first commit

docs/vad-pause-logs.md

@@ -0,0 +1,193 @@
+# 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:
+
+```text
+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:
+
+```text
+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:
+
+```text
+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:
+
+```text
+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.
+
+```text
+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.
+
+```text
+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.
+
+```text
+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.
+
+```text
+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:
+
+```text
+por que a minha fatura veio mais cara
+```
+
+Exemplo de saida segmentada:
+
+```text
+stt_final | text=porque
+stt_final | text=a minha fatura
+stt_final | text=Veio mais cara
+```
+
+Se isso vier acompanhado de pausas assim:
+
+```text
+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:
+
+```env
+LIVEKIT_VAD_MIN_SILENCE_DURATION_S=0.7
+```
+
+Ele aparece no log como:
+
+```text
+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:
+
+```text
+decision + silence_ms + pause_min_ms
+```
+
+Para impacto na conversa, cruze com:
+
+```text
+stt_final + user_seq + message_id
+```