tia_regional_xai_tts_pool/docs/vad-pause-logs.md

VAD pause logs

Este documento resume como analisar pausas de fala do usuario nos logs locais do agente LiveKit.

Onde procurar

Os logs por chamada ficam em logs/.

O arquivo costuma trazer os identificadores principais logo no inicio:

CALL_START | room=dev-room-75a205ec | protocol=PRT-20260409-0001 | session_id=hf05d7c2-1a1a-42e9-8651-ccd6351faff4 | bridge=ws-bridge-dev-2755fb53

Use principalmente:

• room: identifica a sala LiveKit e permite cruzar com timeline/<room>.jsonl.
• session_id: identifica a conversa/sessao.
• message_id: identifica cada turno de usuario ou resposta do agente.
• user_seq: sequencia de falas finais do usuario.

Evento principal: vad_user_pause

vad_user_pause indica que o wrapper de VAD registrou uma pausa relevante na fala do usuario.

Exemplo:

FLOW | step=vad_user_pause | decision=end_of_speech | silence_ms=704 | pause_min_ms=700 | speech_duration_ms=896 | min_interrupt_ms=1600 | eligible=False | probability=0.000 | raw_speech_ms=0 | raw_silence_ms=0

Campos essenciais:

Campo	Como usar
decision	Tipo de pausa detectada. end_of_speech e o principal para segmentacao real. pause_threshold_reached e um alerta intermediario.
silence_ms	Silencio observado pelo VAD, em milissegundos. E o campo mais importante para pausa.
pause_min_ms	Minimo de silencio necessario para fechar a fala. Vem de LIVEKIT_VAD_MIN_SILENCE_DURATION_S.
speech_duration_ms	Duracao do trecho de fala fechado pelo VAD. Trechos muito baixos indicam fala picotada.
min_interrupt_ms	Minimo de fala para considerar interrupcao do bot. Nao e o limite de pausa.
eligible	Se a fala passou de min_interrupt_ms. Mais util para barge-in do que para pausa.
probability	Probabilidade de fala no frame atual. Ajuda a entender ruido/atividade fraca.
raw_speech_ms	Acumulo bruto usado pelo VAD para detectar inicio de fala.
raw_silence_ms	Acumulo bruto usado pelo VAD para detectar silencio.

Como interpretar pausas

Pausa que fechou fala

Priorize decision=end_of_speech.

Exemplo:

decision=end_of_speech | silence_ms=704 | pause_min_ms=700 | speech_duration_ms=896

Leitura:

• o VAD fechou o trecho apos observar 704ms de silencio;
• o minimo configurado era 700ms;
• como passou apenas 4ms do minimo, a configuracao esta bem sensivel;
• se isso acontece varias vezes durante uma frase natural, a fala esta sendo segmentada cedo demais.

Alerta intermediario

decision=pause_threshold_reached significa que o silencio passou do limite minimo antes do fechamento final.

Exemplo:

decision=pause_threshold_reached | silence_ms=960 | pause_min_ms=700 | speech_duration_ms=0 | raw_speech_ms=32

Esse evento deve ser lido com cuidado quando:

• speech_duration_ms=0;
• raw_speech_ms e muito baixo, como 32;
• silence_ms e muito alto, como dezenas de segundos.

Nesses casos, pode ser artefato de estado acumulado ou ruido antes de uma fala real. Para confirmar impacto na conversa, cruze com stt_final.

Eventos auxiliares

vad_speech_start

Indica inicio de fala detectado pelo VAD.

FLOW | step=vad_speech_start | speech_duration_ms=128 | min_interrupt_ms=1600

Use para ver quando o sistema saiu de listening para speaking.

vad_speech_end

Indica fechamento do trecho de fala.

FLOW | step=vad_speech_end | decision=too_short | speech_duration_ms=896 | eligible=False | silence_ms=704 | pause_min_ms=700

Use junto com vad_user_pause. Se speech_duration_ms for baixo varias vezes, a fala pode estar sendo picotada.

vad_interrupt_check

Indica que a fala atingiu duracao suficiente para interrupcao do bot.

FLOW | step=vad_interrupt_check | decision=eligible_by_duration | speech_duration_ms=1600 | min_interrupt_ms=1600

Esse evento ajuda mais a analisar barge-in/interrupcao do bot do que pausa final de fala.

stt_final

Mostra o texto final enviado como turno de usuario.

FLOW | step=stt_final | message_id=12345678-1234-4234-9234-123456789abc | user_seq=3 | text=Veio mais cara

Use este evento para validar o efeito real da segmentacao. Se uma frase natural virou varios stt_final, o VAD/STT segmentou demais.

Checklist de analise

1. Encontre o CALL_START e anote room, session_id e protocol.
2. Filtre os eventos vad_user_pause.
3. Priorize decision=end_of_speech.
4. Compare silence_ms com pause_min_ms.
5. Verifique se speech_duration_ms esta muito baixo.
6. Cruze com os stt_final seguintes.
7. Se uma frase esperada virou varias mensagens curtas, a segmentacao esta agressiva.

Sinais de segmentacao agressiva

Exemplo de fala esperada:

por que a minha fatura veio mais cara

Exemplo de saida segmentada:

stt_final | text=porque
stt_final | text=a minha fatura
stt_final | text=Veio mais cara

Se isso vier acompanhado de pausas assim:

vad_user_pause | decision=end_of_speech | silence_ms=704 | pause_min_ms=700

provavelmente o limite de pausa esta fechando a fala cedo demais.

Parametro de ajuste

O limite principal e:

LIVEKIT_VAD_MIN_SILENCE_DURATION_S=0.7

Ele aparece no log como:

pause_min_ms=700

Aumentar esse valor tende a juntar mais frases, porque o VAD espera mais silencio antes de encerrar a fala. O custo e aumentar a latencia percebida: o agente demora um pouco mais para responder depois que o usuario termina.

Valores para teste manual:

• 0.85: ajuste conservador.
• 1.0: tende a reduzir mais a segmentacao.
• 1.2: pode ajudar em fala pausada, mas pode deixar a conversa lenta.

Regra pratica

Para pausa, olhe primeiro:

decision + silence_ms + pause_min_ms

Para impacto na conversa, cruze com:

stt_final + user_seq + message_id