> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brosbots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wykrywanie tury i timing STT

> Jak platforma decyduje, że rozmówca skończył mówić: VAD, parametry Deepgram (endpointing/utterance_end_ms) i model ML Smart Turn.

Wiedzieć dokładnie, **kiedy rozmówca skończył wypowiedź**, to najtrudniejsza
część agenta głosowego czasu rzeczywistego. Odpowiesz za wcześnie - wchodzisz
w słowo. Za późno - agent brzmi ospale. Platforma łączy **trzy uzupełniające
się warstwy**, żeby robić to dobrze.

## 1. VAD - wykrywanie aktywności głosowej (Silero)

Warstwa transportu przepuszcza każdy fragment audio przez lokalny model
[Silero VAD](https://github.com/snakers4/silero-vad) (ONNX), który dla
każdej ramki odpowiada na proste pytanie:

> *„Czy to mowa, czy cisza?”*

Konfiguracja w `vad_configuration` agenta:

| Parametr | Domyślnie | Znaczenie |
| - | - | - |
| `confidence` | `0.7` | Minimalna pewność modelu, by uznać ramkę za mowę. |
| `start_seconds` | `0.2` | Ile ciągłej mowy oznacza *SPEAKING*. |
| `stop_seconds` | `0.5` | Ile ciągłej ciszy oznacza *QUIET*. |
| `minimum_volume` | `0.6` | Minimalna głośność RMS uznawana za mowę (odcina szum). |

VAD odpowiada za **wykrywanie przerwań** (rozmówca mówi, gdy mówi bot) i jest
bazowym sygnałem dla analizatora tury.

<Note>
  Samo „tak” albo „nie” trwa około 0,2–0,4 s. Przy `start_seconds` równym `0.4`
  (dawna wartość domyślna, wciąż zapisana u agentów utworzonych wcześniej) VAD
  często takiej odpowiedzi nie zauważa i agent reaguje na nią z opóźnieniem.
  Jeśli rozmówcy odpowiadają krótko, ustaw `0.2`. Wyższa wartość ma sens tylko
  na głośnych liniach, gdzie krótkie trzaski przerywają agentowi.
</Note>

W wariancie transkrypcji **Dokładny** (Soniox) to VAD zamyka wypowiedź. Gdy
VAD jej nie zauważy, transkrypcja jest domykana sama po 0,5 s bez nowych
słów, więc krótka odpowiedź nie czeka na kolejne zdanie rozmówcy.

## 2. Parametry streamingu Deepgram

Deepgram (STT po WebSockecie) odbiera audio równolegle z VAD i produkuje dwa
rodzaje transkryptów:

* **Interim** - częściowe, aktualizowane wiele razy na sekundę.
* **Final (`is_final=true`)** - zatwierdzony fragment, już się nie zmieni.

Dwa parametry decydują, kiedy Deepgram „domyka”:

### `endpointing` (ms)

Próg ciszy wyznaczający **granicę frazy** - po jakiej pauzie Deepgram
zatwierdza bieżący transkrypt (`is_final=true`). Niższe wartości = szybsze
zatwierdzanie, ale jedna myśl może rozpaść się na kilka segmentów.

* Zakres: `10–1000` ms
* Domyślnie: `100` ms (szybko)
* Wyższe wartości (300–500 ms) dla rozmówców robiących pauzy w połowie zdania.

### `utterance_end_ms` (ms)

Próg ciszy wyznaczający **koniec całej wypowiedzi** - po jakiej ciszy
Deepgram emituje zdarzenie `UtteranceEnd`, które uruchamia LLM.

* **Minimum: `1000` ms** - *twardy wymóg Deepgram*. Wartości poniżej
  powodują odrzucenie połączenia WebSocket z **HTTP 400** i STT w ogóle się
  nie łączy. Backend automatycznie podbija starsze konfiguracje do 1000.
* Zakres: `1000–5000` ms
* Domyślnie: `1000` ms

## 3. Smart Turn V3 - wykrywanie końca tury przez ML

Same timery ciszy nie wystarczą - ludzie robią pauzy z wielu powodów
(myślą, oddychają, czytają numer), a 1000 ms to w rozmowie wieczność.
**Smart Turn V3** to lokalny model ONNX analizujący **prozodię** wypowiedzi -
intonację, rytm, końcowy kontur wysokości głosu - i zwracający
prawdopodobieństwo, że tura jest skończona.

Po włączeniu w agencie (`smart_turn_enabled: true`):

* po każdej granicy ciszy z VAD segment audio przechodzi przez model,
* model zwraca `{prediction: 0|1, probability: 0..1}`,
* `prediction == 1` → LLM startuje **natychmiast**, często setki ms przed
  timeoutem `utterance_end_ms`,
* `prediction == 0` → pipeline słucha dalej; `utterance_end_ms` działa jako
  siatka bezpieczeństwa.

### Czy `utterance_end_ms` ma znaczenie przy włączonym Smart Turn?

**Tak.** To układ „pasy + szelki”:

| Sytuacja | Co zadziała pierwsze |
| - | - |
| Wyraźny koniec zdania, naturalna intonacja | Smart Turn (\~200–400 ms po ciszy) |
| Niejednoznaczna pauza w środku zdania | Nic - pipeline słucha dalej |
| Koniec wypowiedzi, ale model niepewny | Fallback `utterance_end_ms` (1000 ms) |
| Smart Turn wyłączony | Tylko `utterance_end_ms` (1000 ms) |
| Brak pliku modelu Smart Turn | Ciche przejście na VAD + `utterance_end_ms` |

Obniżenie `utterance_end_ms` poniżej 1000 ms przyspieszyłoby ścieżkę
fallbacku, **ale Deepgram na to nie pozwala**. Chcesz niższych opóźnień -
włącz Smart Turn.

## Gdy rozmówca wchodzi w słowo agentowi

Rozmówca może przerwać agenta w każdej chwili - agent milknie i słucha.
Żeby jednak „mhm” albo „aha” rzucone w trakcie wypowiedzi agenta nie
ucinało mu zdania, w trakcie mowy agenta przerwanie liczy się dopiero od
**dwóch słów** rozmówcy. „Nie, nie” albo „chwila, chwila” przerywa od razu;
pojedyncze potaknięcie agent pomija i mówi dalej. Gdy agent milczy, każde
słowo rozmówcy liczy się jak dotąd.

Próg ustawia suwak **Czułość na przerwanie** w ustawieniach agenta: na
maksimum przerywa każdy dźwięk (także „mhm”, jak dawniej), w środku dwa
słowa, na minimum cztery. Niższa czułość pasuje na głośnych liniach, gdzie
VAD łapie strzępy słów; wyższa, gdy rozmówcy przerywają jednym słowem
(„stop”, „halo”). W API można też podać wprost
`workflow_configurations.interruption_min_words` (`0` = każdy dźwięk).

Krótka odpowiedź poniżej progu nie przepada. Gdy rozmówca rzuci „Tak” na
końcówkę pytania „czy zapisać na wtorek?”, agent nie urywa zdania, ale
zapamiętuje to „Tak” i jeśli skończy mówić w ciągu **1,5 s**, traktuje je
jak zwykłą odpowiedź rozmówcy. Potaknięcie w środku dłuższej wypowiedzi
(agent mówi dalej dłużej niż 1,5 s) nadal jest pomijane. Jeśli zaraz po
krótkim słowie rozmówca mówi dalej i przerywa agenta, oba fragmenty trafiają
do modelu jako jedna wypowiedź. Okno zmienisz przez
`workflow_configurations.short_reply_hold_seconds` (`0` wyłącza, maksimum
`5`); przy suwaku na maksimum nie ma progu, więc nie ma też czego
przechowywać.

## Ile naprawdę czeka rozmówca

W transkrypcji rozmowy, przy każdej odpowiedzi agenta, jest czas z ikoną
stopera: od chwili, gdy rozmówca zamilkł, do pierwszego dźwięku agenta. Składa
się na niego czekanie na koniec wypowiedzi (`stop_seconds`), transkrypcja,
[model LLM](/pl/configurations/llm) i start syntezy mowy. W słuchawce dochodzi
jeszcze opóźnienie sieci telefonicznej, zwykle 0,2–0,4 s, którego platforma
nie mierzy.

Rozmowy sprzed wprowadzenia tego pomiaru pokazują ikonę mózgu i sam czas
namysłu modelu, czyli tylko część tej pauzy.

## Zalecane ustawienia

* **Naturalna rozmowa (zalecane):** Smart Turn WŁ., `utterance_end_ms = 1000`,
  `endpointing = 100`.
* **Dyktowanie numerów / długie pauzy:** Smart Turn WŁ.,
  `utterance_end_ms = 1500–2000`, `endpointing = 300`.
* **Minimalna latencja bez Smart Turn:** `utterance_end_ms = 1000`,
  `endpointing = 100` - sporadyczne wcięcia w słowo możliwe.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.