# 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
```