iVoiceTraceX es un binario que captura el tráfico SIP de una red, reconstruye
las llamadas y las muestra en un panel web que trae adentro. En la misma
pantalla hay un softphone, y todo lo que ve una persona lo puede leer un
agente IA por MCP.
📦
Un solo archivo
Sin runtime, sin base de datos y sin librerías de captura. Se copia y se
ejecuta.
🔌
No se mete en la llamada
Escucha en modo pasivo: no es un proxy ni un SBC, así que no agrega un
salto ni puede cortar tráfico.
🤖
Humanos y agentes
El panel y el servidor MCP exponen el mismo catálogo: lo que hace una
persona lo puede hacer un modelo.
Requisitos.
Linux, macOS o Windows. Para capturar hace falta permiso de lectura sobre
la red (CAP_NET_RAW en Linux, root en macOS, Npcap en Windows); el
softphone funciona igual sin ese permiso.
Quickstart
De cero a ver una llamada en el panel, en tres pasos.
1. Pedir el acceso
El instalador llega por correo. Dejás tus datos una vez y te
mandamos el enlace para macOS, Linux, WSL y Windows.
Entrá a https://localhost:8443 y aceptá el certificado
autofirmado. Hacé una llamada: aparece en la lista mientras suena.
Sin PBX a mano.
Podés arrancarlo sin credenciales SIP: el softphone queda deshabilitado y
la captura funciona igual sobre todo el tráfico de la interfaz.
Instalación
El instalador baja el binario, verifica su SHA256 contra el manifiesto
publicado y lo deja en el PATH. No compila nada y no pide dependencias.
Llega por correo.
El mensaje trae la línea para macOS, Linux y WSL, la de Windows
PowerShell y la de Windows CMD. Si lo perdiste, pedilo de nuevo con el
mismo email.
Opciones del instalador
Variable
Qué hace
IVTX_VERSION
Instala una versión concreta en vez de la última.
IVTX_INSTALL_DIR
Dónde dejar el binario. Por defecto /usr/local/bin.
IVTX_NO_CAP
No intentar otorgar CAP_NET_RAW en Linux.
Permiso de captura.
En Linux el instalador intenta otorgar CAP_NET_RAW para que la captura
arranque sin root. Si no pudo, el binario avisa al iniciar y el panel
abre vacío — que es la confusión número uno de la primera corrida.
Por defecto guarda sólo los diálogos de la extensión con la que se
registró. Es lo razonable en una máquina compartida, y se cambia desde el
panel o al arrancar.
bash
# todo el SIP que pase por la interfaz, no sólo lo propio
sudo ivoicetracex -sip-host 192.168.1.100 -sip-user 1001 -sip-pass 'clave' \
-web :8443 -tls -trace-mine=false -debug
El SIP se detecta por contenido, así que no hace falta declarar puertos: un
INVITE en 5080 o en una troncal se captura igual. Una vez que la lista tiene
diálogos:
Calls — la lista de diálogos con su estado, duración y quién los originó.
Flow — el ladder de la llamada, con las flechas RTP junto a la señalización.
RTP / Audio — cada stream con pérdida, jitter y MOS, y el audio para escuchar.
Report — ASR, ACD, PDD y hallazgos sobre todo lo capturado.
Export — un pcap con la señalización y la media, para abrir en Wireshark.
Configuración
Opciones de arranque
Las 42 opciones del binario. Casi todas tienen su variable de entorno, que es como se configuran en Docker o en systemd; las que no la tienen sólo sirven en la línea de comandos.
Teléfono SIP
Opción
Variable
Qué hace
-sip-host
SIP_HOST
Servidor SIP: host o host:puerto.
-sip-user
SIP_USER
Interno o usuario con el que se registra.
-sip-pass
SIP_PASS
Clave del interno.
-sip-transport
SIP_TRANSPORT
Transporte: udp, tcp, tls o ws. Por defecto udp.
-sip-domain
SIP_DOMAIN
Dominio SIP, si difiere del host del servidor.
-codec
CODEC
Códec de la llamada: opus, pcmu o pcma. Se detecta solo si no se indica.
-media-encryption
MEDIA_ENCRYPTION
Cifrado de la media: auto, none, sdes o dtls.
-vm-code
VM_CODE
Código para llamar al buzón de voz. Por defecto *97.
Panel web
Opción
Variable
Qué hace
-web
WEB_ADDR
Dirección donde escucha el panel. Por defecto :8080.
-tls
TLS
HTTPS con certificado autofirmado. Necesario para entrar por IP.
-tls-cert
TLS_CERT
Certificado propio en PEM. Va con -tls-key.
-tls-key
TLS_KEY
Clave privada del certificado.
-gen-cert
—
Escribe un certificado autofirmado en el directorio indicado y termina.
-web-token
WEB_TOKEN
Protege el panel con un token. auto lo genera y lo imprime al arrancar.
-web-rate
WEB_RATE
Intentos de conexión por segundo que se aceptan de un mismo origen. 0 apaga el freno.
-web-burst
WEB_BURST
Intentos seguidos que se toleran antes de que el freno actúe.
-http
—
Nombre viejo de -web. Se mantiene por compatibilidad.
Captura
Opción
Variable
Qué hace
-trace-iface
TRACE_IFACE
Interfaz a escuchar. Vacío = todas.
-trace-port
TRACE_PORT
Puertos a capturar. Vacío = cualquiera, que es lo correcto casi siempre.
-trace-transport
TRACE_TRANSPORT
Restringe a udp o tcp. Restringir esconde tráfico.
-trace-mine
TRACE_MINE
Guarda sólo los diálogos propios. =false captura todo.
-trace-calls
—
Guarda sólo diálogos que empiezan con INVITE.
-trace-spool
TRACE_SPOOL
Dónde va la media capturada. Por defecto en disco; memory la deja en memoria.
-trace-limit
TRACE_LIMIT
Diálogos que se conservan. Por defecto 30000; 0 = sin tope.
-trace-media-mb
TRACE_MEDIA_MB
MiB de media en memoria. Sólo aplica con la media en memoria.
-trace-max-age
TRACE_MAX_AGE
Antigüedad máxima desde la última actividad, p. ej. 48h. 0 = apagado.
-trace-max-disk
TRACE_MAX_DISK
MiB que la media puede ocupar en disco. 0 = apagado.
-trace-purge-every
—
Borra toda la captura cada tanto. Es higiene, no retención.
Conectividad (ICE)
Opción
Variable
Qué hace
-stun
STUN
Servidores STUN que usa el navegador.
-stun-local
STUN_LOCAL
Dirección del STUN propio que levanta el daemon.
-turn
TURN
Servidor TURN, para redes donde el audio directo no pasa.
-turn-user
TURN_USER
Usuario del TURN.
-turn-pass
TURN_PASS
Clave del TURN.
Agentes IA
Opción
Variable
Qué hace
-mcp
—
Abre el canal de control para que un agente se conecte.
-mcp-sock
—
Ruta del canal de control. Por defecto, junto al binario.
-mcp-stdio
—
Corre como puente para el host de IA. No necesita credenciales SIP.
Proceso
Opción
Variable
Qué hace
-debug
DEBUG
Queda en primer plano con logs. Sin esto, en Unix se va al fondo y sin salida.
-color
COLOR
Colores del log: auto, always o never.
-pid-file
—
Archivo del bloqueo de instancia única. Sólo un daemon por máquina.
-env
—
Genera un .env con los valores actuales y termina.
-version
—
Imprime la versión y termina.
-licenses
—
Imprime las licencias de terceros y termina.
Acceso y seguridad
Una captura SIP es material sensible: tiene números, cabeceras y audio. Si
el panel sale de tu equipo, ponele TLS y token.
-web-token auto genera un UUID y lo imprime al arrancar; el enlace con #t=<uuid> entra directo.
-web-rate y -web-burst frenan al que insiste: los intentos se cuentan por IPv4 y por /64 en IPv6, y el bloqueo escala si sigue.
El token exige -tls salvo que escuches en localhost: mandarlo en claro sería peor que no tenerlo.
Con -tls-cert y -tls-key usás tu propio certificado en vez del autofirmado.
Nada sale de tu red.
La captura, el audio y la configuración se quedan en la máquina donde
corre el binario. iPERFEX no recibe ni almacena tráfico, credenciales ni
grabaciones.
Retención
La captura corre de forma permanente, así que está acotada por diseño. Todos
los límites desalojan la misma unidad: el diálogo entero, señalización y
audio juntos — soltar sólo el audio dejaría filas que parecen completas y no
reproducen nada.
Opción
Qué acota
-trace-limit
Diálogos en memoria; al llegar al tope rota el más viejo. Por defecto 30000.
-trace-max-age
Antigüedad desde la última actividad, p. ej. 48h. Garantiza que siempre tenés las últimas N horas.
-trace-max-disk
MiB que el RTP puede ocupar en disco. Es un techo propio, distinto del piso de 5% libre.
-trace-purge-every
Borra toda la captura cada tanto y vuelve a empezar. Es higiene, no retención.
Antigüedad no es borrado periódico.-trace-max-age 48h promete «siempre tengo las últimas 48 h».
-trace-purge-every 48h promete «nada supera las 48 h» y te
deja vacío justo después de disparar. Son promesas opuestas y conviven.
Para dimensionar: 30 000 diálogos, con 3 000 llamadas de un minuto entre
ellos, ocupan unos 78 MiB de RAM y 3,4 GiB de disco.
La captura pasiva necesita ver la red del host y la capability
NET_RAW. Sin --network host el contenedor sólo ve
su propia red virtual, que casi nunca es donde está el SIP.
Usuario del contenedor.
Una capability agregada al contenedor entra en el conjunto bounding,
pero sólo llega al proceso si éste corre como uid 0 o el binario tiene el
bit de fichero. Con una imagen que corre como usuario sin privilegios vas
a ver «SIP capture disabled» pese al --cap-add.
Variables de entorno
Cada variable de la columna Variable de
Opciones de arranque se puede pasar como variable de
entorno: es la forma de configurarlo en Docker y en systemd, donde no hay
línea de comandos donde poner flags. El orden de prioridad es
flags > .env junto al binario > variables de entorno >
valores por defecto.
docker-compose
El mismo arranque, declarado. El volumen es opcional pero conviene: sin
él, la media capturada vive dentro del contenedor y se va con él.
docker-compose.yml
name: ivoicetracex
services:
ivoicetracex:
image: iperfex/ivoicetracex:latest
container_name: ivoicetracex
restart: unless-stopped
# La captura necesita ver la red del host: dentro de una red virtual el SIP
# no pasa por ahi, y el panel abriria siempre vacio.
network_mode: host
cap_add:
- NET_RAW
- NET_ADMIN
# NO es redundante con cap_add. Una capability agregada al contenedor entra
# en el conjunto bounding, pero solo llega al proceso si corre como uid 0.
# Con un usuario sin privilegios el softphone registra y llama perfecto, y
# la traza queda vacia para siempre.
user: "0"
environment:
SIP_HOST: 192.168.1.100
SIP_USER: "1001"
SIP_PASS: tu-clave
WEB_ADDR: ":8443"
TLS: "true"
TRACE_SPOOL: /var/tmp/ivoicetracex
TRACE_LIMIT: "30000"
TRACE_MAX_AGE: 48h
TRACE_MAX_DISK: "8192"
DEBUG: "true"
volumes:
- ivtx-spool:/var/tmp/ivoicetracex
volumes:
ivtx-spool:
bash
docker compose up -d
docker compose logs -f ivoicetracex
El spool se limpia al arrancar.
La media en disco es desborde, no archivo: al iniciar, el directorio se
vacía. El volumen sirve para que no crezca dentro del contenedor, no
para conservar capturas entre reinicios — para eso está la exportación.
Integraciones IA
MCP Server
iVoiceTraceX habla Model Context Protocol: un agente puede
leer la traza, analizar el audio de una llamada y operar el teléfono con las
mismas 32 herramientas que usa el panel.
El daemon abre un canal de control local con -mcp. El host de IA
ejecuta ese mismo binario con -mcp-stdio, que oficia de
puente entre el host y el daemon. El puente no necesita credenciales SIP.
bash
# 1) el daemon, con el socket de control abierto
ivoicetracex -sip-host 192.168.1.100 -sip-user 1001 -sip-pass 'clave' \
-web :8443 -tls -mcp
# 2) el puente que va a ejecutar el host de IA
ivoicetracex -mcp-stdio
Claude Code
Una línea desde la terminal, en el proyecto donde quieras tenerlo:
bash
claude mcp add ivoicetracex -- ivoicetracex -mcp-stdio
Verificá que quedó conectado con /mcp dentro de Claude Code, o
con claude mcp list. Si el socket no está en el lugar por
defecto, agregá -mcp-sock /ruta/mcp.sock al final.
Claude Desktop
Editá claude_desktop_config.json y agregá el servidor. En macOS
está en ~/Library/Application Support/Claude/; en Windows, en
%APPDATA%\Claude\.
MCP es un protocolo abierto: cualquier host que lo hable sirve. La entrada es
siempre la misma — un proceso que se ejecuta y conversa por stdio — así que
en el SDK de Agentes de OpenAI se declara como servidor stdio:
python
from agents import Agent
from agents.mcp import MCPServerStdio
async with MCPServerStdio(
params={"command": "/usr/local/bin/ivoicetracex", "args": ["-mcp-stdio"]},
) as ivtx:
agent = Agent(
name="VoIP analyst",
instructions="Diagnosticá llamadas SIP con las herramientas disponibles.",
mcp_servers=[ivtx],
)
Un solo daemon por máquina.
El puente -mcp-stdio no arranca nada: se conecta al daemon que
ya está corriendo. Si el host de IA no encuentra herramientas, el daemon no
está levantado o no tiene -mcp.
WebMCP
El mismo catálogo, publicado dentro de la página del panel. Un agente
que trabaja sobre el navegador — una extensión, un piloto de pestaña — accede
a las herramientas sin instalar ni configurar nada, usando la sesión que ya
está abierta.
Las herramientas son las mismas 32 del servidor MCP: lo que se puede por un lado se puede por el otro.
Aprovechan la conexión que el panel ya tiene abierta: no hay que exponer ningún puerto ni servicio adicional.
Hereda el acceso de la pestaña: si el panel pidió token, el agente ya pasó por ahí.
Cuándo conviene cada uno: MCP para automatizar sin navegador
—guardias, pipelines, análisis por lote—; WebMCP cuando la
persona ya está mirando el panel y quiere que el agente le explique lo que
tiene delante.
Un ejemplo completo
Un pedido que recorre casi todo el catálogo: hace una llamada, la sostiene,
la corta, baja el audio de las dos direcciones, lo analiza y termina con el
diagnóstico y el pcap. Sirve para conocer la herramienta, y también como
base para automatizar una prueba periódica.
Pegalo tal cual en el host de IA que hayas conectado. El destino y los
tiempos son ejemplos: cambialos por los tuyos.
Prompt · español
Tenés conectado el servidor MCP de iVoiceTraceX. Quiero un recorrido completo, en
pasos visibles: antes de cada herramienta decí en una línea qué vas a hacer y por
qué; después mostrá sólo los números que importan. Nada de explicaciones largas
entre pasos — lo que se tiene que ver es la salida de la herramienta.
NO llames a clear_capture en ningún momento: vacía todo, y esta es una captura en
vivo que quiero conservar.
Hacé esto de punta a punta:
1. PUNTO DE PARTIDA. Llamá a get_status y get_config. Confirmá que el interno
está registrado, y decime el códec y si la traza SIP está encendida. Después
llamá a get_capture_stats y anotá cuántos diálogos ya hay capturados, así después
sabemos cuáles son nuestros.
2. LA LLAMADA. Llamá a place_call con el destino que quieras probar (algo que
atienda: un eco, una locución, un IVR). Enseguida consultá poll_events y seguí
consultando cada ~2 segundos hasta ver la línea activa. Si falla, pará y mostrame
el error tal cual vino.
3. SOSTENERLA. Con la llamada en curso, dejala correr unos 8 segundos para que
haya audio real que analizar. Después mostrá la retención: hold_call, poll_events
para confirmar que el otro extremo la aceptó de verdad, esperá ~3 segundos,
resume_call y poll_events otra vez. Decime cuánto tardó cada transición.
4. CORTAR. Llamá a hang_up y después poll_events una vez más: mostrame el resumen
de la llamada, con duración, códec y cómo terminó.
5. ENCONTRARLA. Llamá a list_calls con only_calls: true y limit: 5. Identificá
NUESTRA llamada — la del destino que marcaste, cuyo origen es AI porque la hiciste
vos — y mostrame su Call-ID, estado, duración y cantidad de mensajes.
6. SEÑALIZACIÓN. Llamá a get_call_flow para ese Call-ID con with_rtp: true.
Resumí el diagrama: cuántos mensajes, la secuencia de métodos y códigos de
respuesta en orden, qué códec se negoció en el SDP, y el tiempo entre el INVITE y
el 200 OK — que es la demora que la persona realmente siente antes de escuchar
algo.
7. EL AUDIO. Del diagrama o de list_calls, tomá los dos identificadores de stream
RTP, uno por dirección. Para CADA uno:
- download_stream_audio: decime la ruta del archivo, su tamaño, la frecuencia
de muestreo y cuántos paquetes se pudieron decodificar.
- analyze_audio: nivel y pico, cuánto del stream es silencio, cuál fue el
silencio más largo, si hay saturación, si se oyen tonos DTMF en el audio, y
los hallazgos en palabras.
- get_audio_envelope con bucket_ms: 100: describí la forma en el tiempo en dos
o tres frases — cuándo arranca el audio, dónde están las partes fuertes, si
hay huecos. No vuelques la serie entera.
8. ANÁLISIS DEL STREAM. Para cada stream llamá a analyze_stream. Primero sin
max_rows, para el resumen: paquetes, esperados, perdidos y el porcentaje de
pérdida, el mínimo/medio/máximo de separación y de jitter, el desvío y la
estimación de MOS. Después llamalo de nuevo sobre UNO solo con max_rows: 20 y
mostrá las primeras filas, para que se vea el detalle paquete por paquete.
9. DIAGNÓSTICO. Llamá a diagnose_call para el Call-ID con bucket_ms: 200. Este es
el cierre: mostrá el veredicto en una línea y después cada hallazgo con el segundo
en que ocurrió, cuánto duró y su gravedad. Si vuelve limpio, decilo sin vueltas —
una llamada sana es un resultado válido.
10. EVIDENCIA. Llamá a get_report acotado a ese Call-ID y decime ASR, ACD, PDD y
la distribución de códigos de respuesta. Después export_capture con
format: "pcap" y callids con nuestro Call-ID, y mostrá la ruta y el tamaño del
archivo.
CERRÁ CON UNA TABLA: Call-ID, duración, códec, pérdida / jitter / MOS por
dirección, el veredicto del diagnóstico, y las rutas de los WAV y del pcap.
Si alguna herramienta devuelve un error, mostralo tal cual y seguí con el resto —
un paso que falla también es información, no un motivo para frenar.
Prompt · English
You have the iVoiceTraceX MCP server connected. I want a complete walkthrough, in
visible steps: before each tool call, say in one short line what you are about to
do and why; after it, show only the numbers that matter. No long explanations
between steps — the tool output is what should be on screen.
Do NOT call clear_capture at any point: it wipes everything, and this is a live
capture I want to keep.
Run this end to end:
1. BASELINE. Call get_status and get_config. Confirm the extension is registered
and report the codec and whether the SIP trace is on. Then call
get_capture_stats and note how many dialogs are already captured, so we can tell
afterwards which ones are ours.
2. PLACE THE CALL. Call place_call with whatever destination you want to test
(something that answers: an echo test, an announcement, an IVR). Immediately poll
with poll_events and keep polling every ~2 seconds until you see the line go
active. If it fails, stop and show me the error verbatim.
3. HOLD THE LINE. Once the call is up, let it run for about 8 seconds so there is
real audio to analyse. Then demonstrate the hold path: hold_call, poll_events to
confirm the far end actually accepted it, wait ~3 seconds, resume_call,
poll_events again. Report how long each transition took.
4. HANG UP. Call hang_up, then poll_events once more and show me the call summary
event: duration, codec and how it ended.
5. FIND THE CALL. Call list_calls with only_calls: true and limit: 5. Identify
OUR call — the one to the destination you dialled, whose origin is AI since you
placed it — and show me its Call-ID, state, duration and message count.
6. SIGNALLING. Call get_call_flow for that Call-ID with with_rtp: true. Summarise
the ladder: how many messages, the sequence of methods and response codes in
order, what codec was negotiated in the SDP, and the delta between the INVITE and
the 200 OK — the post-dial delay a person actually feels before hearing anything.
7. THE AUDIO. From the flow or from list_calls, take the two RTP stream ids, one
per direction. For EACH stream:
- download_stream_audio: report the file path, its size, the sample rate and
how many packets decoded.
- analyze_audio: report level and peak, how much of the stream is silence, the
longest single silence, any clipping, any DTMF tones heard in the audio, and
the findings in plain words.
- get_audio_envelope with bucket_ms: 100: describe the shape over time in two
or three sentences — when audio starts, where the loud parts are, whether
there are gaps. Do not dump the whole series.
8. STREAM ANALYSIS. For each stream, call analyze_stream. First without max_rows
to get the summary: packets, expected, lost and the loss percentage, the
min/mean/max of delta and jitter, the skew, and the MOS estimate. Then call it
again on ONE stream with max_rows: 20 and show the first rows so the
packet-by-packet detail is visible on screen.
9. DIAGNOSIS. Call diagnose_call for the Call-ID with bucket_ms: 200. This is the
finale: show the one-line verdict, then every finding with the second it happened
at, how long it lasted and its severity. If it comes back clean, say so plainly —
a clean call is a valid result.
10. EVIDENCE. Call get_report scoped to that Call-ID and report ASR, ACD, PDD and
the response-code distribution. Then export_capture with format: "pcap" and
callids set to our Call-ID, and show the path and size of the file.
FINISH WITH A SUMMARY TABLE: Call-ID, duration, codec, per-direction loss /
jitter / MOS, the diagnosis verdict, and the paths of the WAV files and the pcap.
If any tool returns an error, show the error verbatim and keep going with the
rest — a failed step is information too, not a reason to stop.
Prompt · Português
Tem o servidor MCP do iVoiceTraceX ligado. Quero um percurso completo, em passos
visíveis: antes de cada ferramenta diga numa linha o que vai fazer e porquê;
depois mostre apenas os números que importam. Nada de explicações longas entre
passos — o que se tem de ver é a saída da ferramenta.
NÃO chame clear_capture em momento algum: esvazia tudo, e esta é uma captura ao
vivo que quero conservar.
Faça isto de ponta a ponta:
1. PONTO DE PARTIDA. Chame get_status e get_config. Confirme que a extensão está
registada e diga-me o codec e se o rastreamento SIP está ligado. Depois chame
get_capture_stats e anote quantos diálogos já estão capturados, para depois
sabermos quais são os nossos.
2. A CHAMADA. Chame place_call com o destino que quiser testar (algo que atenda:
um eco, uma locução, um IVR). De imediato consulte poll_events e continue a
consultar a cada ~2 segundos até ver a linha ativa. Se falhar, pare e mostre-me o
erro tal como veio.
3. SUSTENTÁ-LA. Com a chamada em curso, deixe-a correr cerca de 8 segundos para
haver áudio real que analisar. Depois mostre a retenção: hold_call, poll_events
para confirmar que a outra ponta a aceitou de facto, espere ~3 segundos,
resume_call e poll_events outra vez. Diga-me quanto demorou cada transição.
4. DESLIGAR. Chame hang_up e depois poll_events mais uma vez: mostre-me o resumo
da chamada, com duração, codec e como terminou.
5. ENCONTRÁ-LA. Chame list_calls com only_calls: true e limit: 5. Identifique A
NOSSA chamada — a do destino que marcou, cuja origem é AI porque foi você que a
fez — e mostre-me o Call-ID, estado, duração e número de mensagens.
6. SINALIZAÇÃO. Chame get_call_flow para esse Call-ID com with_rtp: true. Resuma
o diagrama: quantas mensagens, a sequência de métodos e códigos de resposta por
ordem, que codec foi negociado no SDP, e o tempo entre o INVITE e o 200 OK — que
é a demora que a pessoa sente antes de ouvir alguma coisa.
7. O ÁUDIO. Do diagrama ou de list_calls, tome os dois identificadores de stream
RTP, um por direção. Para CADA um:
- download_stream_audio: diga-me o caminho do ficheiro, o tamanho, a
frequência de amostragem e quantos pacotes foi possível descodificar.
- analyze_audio: nível e pico, quanto do stream é silêncio, qual foi o
silêncio mais longo, se há saturação, se se ouvem tons DTMF no áudio, e os
achados por palavras.
- get_audio_envelope com bucket_ms: 100: descreva a forma ao longo do tempo em
duas ou três frases — quando arranca o áudio, onde estão as partes fortes,
se há buracos. Não despeje a série inteira.
8. ANÁLISE DO STREAM. Para cada stream chame analyze_stream. Primeiro sem
max_rows, para o resumo: pacotes, esperados, perdidos e a percentagem de perda, o
mínimo/médio/máximo de separação e de jitter, o desvio e a estimativa de MOS.
Depois chame-o de novo sobre UM só com max_rows: 20 e mostre as primeiras linhas,
para se ver o detalhe pacote a pacote.
9. DIAGNÓSTICO. Chame diagnose_call para o Call-ID com bucket_ms: 200. Este é o
fecho: mostre o veredicto numa linha e depois cada achado com o segundo em que
ocorreu, quanto durou e a sua gravidade. Se vier limpo, diga-o sem rodeios — uma
chamada sã é um resultado válido.
10. EVIDÊNCIA. Chame get_report limitado a esse Call-ID e diga-me ASR, ACD, PDD e
a distribuição de códigos de resposta. Depois export_capture com format: "pcap" e
callids com o nosso Call-ID, e mostre o caminho e o tamanho do ficheiro.
FECHE COM UMA TABELA: Call-ID, duração, codec, perda / jitter / MOS por direção,
o veredicto do diagnóstico, e os caminhos dos WAV e do pcap.
Se alguma ferramenta devolver um erro, mostre-o tal como está e continue com o
resto — um passo que falha também é informação, não um motivo para parar.
Una línea a la vez.
La edición gratuita tiene una sola línea activa: si dejaste el panel con
una llamada en curso, la del ejemplo va a fallar. Cerrala antes de
empezar.
Referencia
Catálogo de herramientas
Las 32 herramientas, una por una: qué hace cada una, qué espera y qué
devuelve. El esquema exacto de los argumentos lo publica el propio
servidor, así que cualquier host los lista al conectarse.
Teléfono
place_call
Qué hace
Llama a un destino: interno, número o dirección SIP.
Qué espera
El destino. Falla si ya hay una llamada en curso.
Qué devuelve
La confirmación de que salió. El progreso —timbrado, atendida, cortada— se sigue con poll_events.
answer_call
Qué hace
Atiende la llamada entrante que está sonando.
Qué espera
Nada.
Qué devuelve
La confirmación. Falla, y lo dice, si no hay ninguna llamada sonando.
reject_call
Qué hace
Rechaza la llamada entrante sin atenderla.
Qué espera
Nada.
Qué devuelve
La confirmación. Falla si no hay ninguna llamada sonando.
hang_up
Qué hace
Corta la llamada activa.
Qué espera
Nada.
Qué devuelve
La confirmación de que la línea quedó libre.
hold_call
Qué hace
Pone la llamada en espera; el conmutador le hace escuchar música de espera al otro extremo.
Qué espera
Nada.
Qué devuelve
La confirmación. La línea sólo figura en espera cuando el otro extremo lo aceptó: si no, falla.
resume_call
Qué hace
Saca la llamada de espera y restablece el audio en las dos direcciones.
Qué espera
Nada.
Qué devuelve
La confirmación de que el audio volvió.
send_dtmf
Qué hace
Manda tonos a la llamada activa, por ejemplo para navegar un IVR.
Qué espera
Los dígitos: 0-9, * y #.
Qué devuelve
La confirmación de que se enviaron.
get_status
Qué hace
Dice cómo está el teléfono ahora mismo.
Qué espera
Nada.
Qué devuelve
Si está registrado, si hay una llamada activa, con qué interno y contra qué servidor, desde cuándo, y el estado de la línea.
get_config
Qué hace
Devuelve la configuración con la que está corriendo el teléfono.
Qué espera
Nada.
Qué devuelve
Códec, transporte, cantidad de líneas, versión, y si la traza SIP y la autenticación están activas.
poll_events
Qué hace
Entrega lo que pasó desde la consulta anterior. Es lo que se llama después de una acción para ver el resultado.
Qué espera
Nada.
Qué devuelve
Los cambios de línea (sonando, discando, activa, en espera), el resultado del registro, avisos de buzón, el resumen al colgar, cambios de códec y errores. Vacía la cola: cada evento se entrega una sola vez.
Traza
list_calls
Qué hace
Lista los diálogos capturados, que es la vista Calls del panel.
Qué espera
Opcional: un tope de filas y si querés sólo llamadas. En una central ocupada el chequeo periódico domina la lista, así que conviene acotar.
Qué devuelve
Una fila por diálogo con todos sus atributos: identificador, origen y destino, método, estado, tiempos y más.
get_call_flow
Qué hace
Devuelve el diagrama de una o varias llamadas: cada mensaje en orden cronológico.
Qué espera
Uno o más identificadores de diálogo, y si querés que también aparezca la media. Juntar varios muestra una llamada completa a través de sus tramos.
Qué devuelve
Los mensajes con su columna, el tiempo transcurrido entre uno y otro, la información de la negociación y, si se pidió, las flechas de la media.
analyze_stream
Qué hace
Mide la calidad de un stream de media tal como llegó por la red.
Qué espera
El identificador del stream. Opcionalmente, cuántas filas de detalle querés.
Qué devuelve
Pérdida de paquetes, estimación de MOS y el resumen mínimo/medio/máximo de separación, jitter y desvío. Por defecto sólo el resumen, con el total de paquetes medidos; pedir filas agrega el detalle paquete por paquete.
get_report
Qué hace
Arma el informe forense sobre lo capturado.
Qué espera
Opcional: los identificadores a los que querés acotarlo. Sin eso, todo lo capturado.
Qué devuelve
Tasa de respuesta, duración media, demora hasta el primer tono, cómo terminaron las llamadas, distribución de códigos, llamadas por minuto, los internos más activos y hallazgos escritos en lenguaje natural.
get_capture_stats
Qué hace
Dice cuánto hay capturado y en qué estado está la captura.
Qué espera
Nada.
Qué devuelve
Cuántos diálogos, llamadas y mensajes hay, abiertos por estado y por método, los códigos de respuesta, los contadores de la captura, y la retención: si está capturando, si se conserva la media, cuánto ocupa y contra qué límites.
export_capture
Qué hace
Exporta lo capturado a un archivo, igual que el botón Export del panel.
Qué espera
El formato: señalización sola, señalización con la media intercalada —reproducible en un analizador— o texto. Opcionalmente, qué diálogos y en qué ruta.
Qué devuelve
La ruta del archivo escrito, su tamaño y un nombre sugerido.
Audio
download_stream_audio
Qué hace
Convierte un stream capturado en un archivo de audio reproducible.
Qué espera
El identificador del stream, que sale de list_calls o de un diagrama pedido con media. Opcionalmente la ruta de salida.
Qué devuelve
La ruta del archivo, su tamaño, la frecuencia de muestreo y cuántos paquetes se pudieron decodificar. Un stream cifrado no se puede decodificar y la respuesta lo dice.
analyze_audio
Qué hace
Describe cómo SUENA un stream capturado. Es el complemento de analyze_stream: aquél mide la red, éste escucha el audio.
Qué espera
El identificador del stream.
Qué devuelve
Nivel y pico, cuánto del stream es silencio y cuál fue el silencio más largo, saturación, corrimiento de continua, tonos oídos en el audio y hallazgos en palabras. Esto es lo que detecta el audio en una sola dirección cuando la red se ve impecable.
get_audio_envelope
Qué hace
Devuelve la FORMA del audio como números, por tramos de tiempo: es lo que el panel dibuja como onda y espectrograma.
Qué espera
El identificador del stream y, si querés, cuánto dura cada tramo.
Qué devuelve
Volumen y balance de graves, voz y agudos en cada tramo. Sirve para ver media que arranca tarde, cortes, quién habló cuándo, un tono de progreso o un zumbido de línea.
diagnose_call
Qué hace
Diagnostica una llamada y dice DÓNDE estuvo el problema. Es la herramienta para cuando alguien reporta «se escuchó mal».
Qué espera
El identificador de la llamada o de un stream. Opcionalmente el tamaño del tramo y cuántas bandas de espectro querés.
Qué devuelve
Hallazgos ubicados en el tiempo —aire muerto, ráfagas de pérdida, picos de jitter, cortes, saturación, zumbido, audio en una sola dirección, códec incompatible, media tardía— cada uno con el segundo en que ocurrió, cuánto duró y el rango de paquetes, para poder ir a buscar la evidencia en el archivo exportado. Además, un veredicto en una línea.
play_audio
Qué hace
Micrófono falso: mete un archivo de audio DENTRO de la llamada activa, como si lo dijera el micrófono.
Qué espera
La ruta del archivo, que tiene que coincidir con el códec de la llamada. Toma el micrófono mientras dura y después lo devuelve. Lo único que rechaza es meterse en una llamada que hizo la persona sentada frente al panel: cortarle la voz a mitad de frase no puede pasar por accidente. Con force lo hace igual.
Qué devuelve
La confirmación de que empezó a reproducirse, o el motivo por el que no.
stop_audio
Qué hace
Corta la reproducción iniciada con play_audio y devuelve el micrófono.
Qué espera
Nada.
Qué devuelve
La confirmación.
start_recording
Qué hace
Parlante falso: graba a disco las DOS direcciones de la llamada activa, en archivos separados.
Qué espera
La ruta base de los archivos.
Qué devuelve
La confirmación de que empezó a grabar, con las rutas donde va a escribir.
stop_recording
Qué hace
Termina la grabación y cierra los archivos.
Qué espera
Nada.
Qué devuelve
Las rutas de los archivos y cuánto duró lo grabado.
get_audio_status
Qué hace
Dice si hay algo reproduciéndose o grabándose ahora mismo.
Qué espera
Nada.
Qué devuelve
Qué se está reproduciendo y con qué códec, si hay una grabación en curso, y quién tiene el micrófono.
Captura
set_capture_running
Qué hace
Enciende o APAGA la captura.
Qué espera
Encendida o apagada. Apagarla deja de ver tráfico para todos los paneles y herramientas a la vez; lo ya capturado se conserva.
Qué devuelve
El estado de la captura, ya actualizado.
set_capture_scope
Qué hace
Cambia si se guarda sólo el tráfico propio o todo el que pase.
Qué espera
El alcance: propio o todo. Sólo afecta a lo que se guarde de acá en adelante.
Qué devuelve
El estado de la captura, ya actualizado.
set_capture_interface
Qué hace
Cambia la interfaz de red que se está escuchando, sin reiniciar.
Qué espera
El nombre de la interfaz. Lo ya capturado no se pierde.
Qué devuelve
El estado de la captura, y el motivo si la interfaz no sirve.
set_capture_filter
Qué hace
Acota la captura a ciertos puertos o a un transporte.
Qué espera
Los puertos y el transporte. Vacío es sin filtro, que es lo correcto casi siempre: restringir esconde tráfico.
Qué devuelve
El estado de la captura, ya actualizado.
set_capture_retention
Qué hace
Ajusta en caliente cuánto se conserva.
Qué espera
El tope de diálogos, el presupuesto de media, si guardar sólo llamadas y cada cuánto borrar todo. Los valores negativos dejan lo que había.
Qué devuelve
El estado de la captura, ya actualizado.
set_rtp_retention
Qué hace
Decide si se conserva la media capturada o sólo se mide al pasar.
Qué espera
Conservar o no. Con esto apagado se siguen midiendo los paquetes, pero no queda audio para escuchar ni descargar, ni detalle paquete por paquete, ni exportación con media. Lo ya guardado se queda.
Qué devuelve
El estado de la captura, ya actualizado.
clear_capture
Qué hace
Vacía lo capturado y empieza de nuevo.
Qué espera
Nada. Es la destructiva: no se puede deshacer.
Qué devuelve
La confirmación. La captura sigue corriendo: se vacía lo guardado, no se apaga nada.
Problemas frecuentes
El panel abre vacío y dice «SIP capture disabled»
Falta el permiso de captura. En Linux, sudo setcap
cap_net_raw,cap_net_admin=eip $(which ivoicetracex) o corré con
sudo. En macOS hace falta root; en Windows, Npcap instalado.
No veo los INVITE de mi troncal
Por defecto sólo se guardan los diálogos propios. Cambiá el alcance a
«Todo el tráfico» desde el panel, o arrancá con
-trace-mine=false. Verificá también la interfaz: con varias
NIC, -trace-iface vacío las escucha todas.
El navegador rechaza el certificado
-tls genera uno autofirmado. Aceptalo una vez, o generá el
tuyo con -gen-cert y usalo con
-tls-cert / -tls-key.
El agente IA no encuentra herramientas
El puente -mcp-stdio se conecta a un daemon que ya tiene que
estar corriendo con -mcp. Si el socket no está en la ruta por
defecto, pasá -mcp-sock en ambos lados.
Se me llena el disco
El RTP va a disco por defecto y se limpia al arrancar, pero mientras corre
crece. Poné un techo con -trace-max-disk y una ventana con
-trace-max-age.