docs(live-stt): semantic end-of-turn feature page

chapters/live-stt/features/end-of-turn.mdx

@@ -0,0 +1,76 @@
+---
+title: "Semantic end-of-turn"
+description: "Finalize a turn when the speaker has actually finished, not just when they go quiet"
+---
+
+Semantic end-of-turn detection decides that a speaker has finished their turn based on **what they said**, not only on how long they stayed silent. It runs on top of the usual [endpointing](https://docs.gladia.io/chapters/live-stt/features/endpointing) and lets the API hold a turn open through natural mid-sentence pauses, then finalize as soon as the thought is complete.
+
+It is designed for conversational, turn-taking use cases — voice agents, IVR, live assistants — where cutting a speaker off on a brief hesitation ("I'd like… uh… a coffee, please") feels broken.
+
+### Endpointing vs end-of-turn
+
+Both answer the same question — *has this turn finished?* — but they look at different signals.
+
+**Endpointing** is **time-based**. It waits for a fixed amount of *silence* and, once that silence passes, closes the turn. It is simple and predictable, but silence is only a proxy for "finished": a speaker who pauses to think looks exactly like a speaker who is done. Set the window short and you cut people off mid-thought; set it long and every turn feels sluggish.
+
+**End-of-turn** is **meaning-based**. A model listens to the content of the turn and judges whether the speaker has actually reached the end of what they were saying. A pause in the middle of a sentence no longer forces a cut — the turn stays open until the utterance is genuinely complete, or a safety limit is reached.
+
+The two are complementary, not exclusive: endpointing remains the silence-based safety net, and end-of-turn adds a layer of semantic judgment on top of it.
+
+| | Endpointing | Semantic end-of-turn |
+|---|---|---|
+| Decides on | Duration of silence | Whether the thought is complete |
+| Mid-sentence pause | May cut the speaker off | Held open until the turn is complete |
+| Best for | Simple, predictable segmenting | Natural turn-taking (voice agents, IVR) |
+| Tuning | One silence window | Sensitivity + safety guard |
+
+In short: **endpointing asks "has it been quiet long enough?"; end-of-turn asks "has the speaker actually finished?"**
+
+### How to enable it
+
+Add an `end_of_turn` object to your live configuration. Omit it and the session uses endpointing only (unchanged behaviour).
+
+```json
+{
+  "end_of_turn": {
+    "threshold": 0.5,
+    "max_wait_secs": 8
+  }
+}
+```
+
+### Parameters
+
+**threshold** \
+Definition: how confident the model must be that the turn is complete before finalizing it. Higher = the model waits until it is more certain the speaker is done.
+- Default: 0.5
+- Range: 0 to 1
+
+Effect:
+- Lower value = finalizes more eagerly (snappier turn-taking, but more likely to close on a natural pause).
+- Higher value = waits for stronger evidence the turn is over (fewer premature cuts, slightly higher latency).
+
+**emission_threshold** \
+Definition: the confidence at which the `speech_turn_end` event is sent to your client, independent of the value that finalizes the utterance. Lets you surface an early "the speaker is wrapping up" signal to drive your UI or agent while keeping finalization conservative.
+- Default: follows `threshold`
+- Range: 0 to 1
+
+**max_wait_secs** \
+Definition: a safety limit. If the model never declares the turn complete, the utterance is finalized anyway once this much speech has elapsed, so a turn can never hang.
+- Default: 8
+- Range: 1 to 30
+
+**probe_base_ms** \
+Definition: how often the model checks, while the speaker is still talking, whether the turn is wrapping up. This is what lets partial transcripts speed up as the end approaches.
+- Default: 900
+- Range: 100 to 5000
+
+Effect:
+- Lower value = more responsive turn-taking and lower latency to the final transcript, but a higher chance of finalizing on a brief mid-sentence pause.
+- Higher value = more conservative, less likely to cut the speaker off.
+- Keep the default unless you have a specific reason to change it; going near the minimum is not recommended for general use.
+
+### Choosing between them
+
+- **Meetings, lectures, captioning** — endpointing alone is usually enough; you want complete, clean segments and cadence matters less.
+- **Voice agents, IVR, live assistants** — enable end-of-turn for natural turn-taking that survives hesitations, and tune `threshold` for how eagerly the agent should take its turn.

chapters/live-stt/features/endpointing.mdx

@@ -1,35 +1,35 @@
 ---
 title: "Endpointing"
 description: "What's endpointing and how it works"
 ---
 
 Endpointing is the mechanism Gladia uses in live transcription to decide when a speaker has "finished" an utterance, so the API can close that utterance and emit a final transcript segment.
 
 In practice, endpointing answers the question: "How much silence should we wait before we consider the sentence (or turn) complete?"
 
 ### Why endpointing matters
 
 Endpointing is one of the main knobs that controls the tradeoff between:
 - **Latency (speed)**: how quickly you get final utterances
 - **Completeness**: whether you avoid cutting someone off mid-thought
 - **Chunking quality**: whether utterances align well with natural turns or sentences
 
 Lower endpointing values feel "snappier" (great for voice agents), while higher values tend to produce cleaner, more complete segments (great for meetings and lectures).
 
 ### How it works conceptually
 
 During a live session, Gladia continuously analyzes the incoming audio stream and: 
 1. Detects speech activity on each channel (voice activity detection)
 2. Groups speech into an "utterance" while speech is ongoing
 3. When it observes silence lasting at least endpointing seconds, it considers the utterance finished and closes it (finalizes it).
 4. The AI model is then used to transcribe the final result of the utterance.
 5. If speech never pauses long enough, Gladia still has a safety mechanism to close the utterance (*maximum_duration_without_endpointing*, see next section)
 
 You can also subscribe to speech activity messages to know when speech [starts](https://docs.gladia.io/api-reference/v2/live/callback/speech-start) and [ends](https://docs.gladia.io/api-reference/v2/live/callback/speech-end) (useful to drive UI or agent turn-taking)
 
 ### The 2 key parameters
 
 **endpointing (seconds)** \
 Definition: the duration of silence that closes the current utterance.
 - Default: 0.05
 - Range: 0.01 to 10
@@ -38,10 +38,16 @@
 - Smaller value = closes utterances faster, but can split sentences if the speaker hesitates briefly.
 - Larger value = waits longer before finalizing, which improves segment completeness but increases latency.
 
 **maximum_duration_without_endpointing (seconds)**
 
 Definition: maximum amount of time Gladia will keep an utterance open without detecting endpointing silence. If that limit is reached, the utterance is considered finished anyway.
 - Default: 5
 - Range: 5 to 60
 
 Why it exists: it prevents extremely long, never-ending utterances (for example: constant background noise, a speaker who never pauses, or long monologues), which is important for downstream UX and processing stability.
+
+### Endpointing vs end-of-turn
+
+Endpointing is **time-based**: it closes a turn after a fixed amount of silence. That makes it simple and predictable, but silence is only a proxy for "finished" — a speaker who pauses to think looks the same as one who is done, so a short window can cut people off mid-thought.
+
+[Semantic end-of-turn](https://docs.gladia.io/chapters/live-stt/features/end-of-turn) is **meaning-based**: a model judges whether the speaker has actually reached the end of their turn, so a natural mid-sentence pause no longer forces a cut. The two work together — endpointing stays the silence-based safety net, and end-of-turn adds semantic judgment on top. For natural turn-taking (voice agents, IVR), enable end-of-turn; for simple, predictable segmenting, endpointing alone is enough.

docs.json

@@ -53,6 +53,7 @@
                   "chapters/live-stt/quickstart",
                   "chapters/live-stt/audio-intelligence",
                   "chapters/live-stt/features/endpointing",
+                  "chapters/live-stt/features/end-of-turn",
                   "chapters/live-stt/features/partial-transcripts",
                   "chapters/live-stt/recommended-parameters"
                 ]