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

# Turn Detection

> Understand when a user is truly finished speaking with semantic turn-detection models.

Timing matters. VAD detects silence; turn detection reads meaning so your agent knows when to respond and when to keep listening.

## Echo Turn Detector

Zero Runtime's turn detector is **Echo**, a server-hosted model passed to your `Pipeline` as the `turn_detector`. It is exposed through the **Zero Runtime Inference Gateway** via the unified `TurnDetector` class (`model="echo-small"` or `model="echo-large"`). No model is downloaded or loaded on your machine; authentication requires `ZRT_AUTH_TOKEN`. Choose `echo-small` for speed or `echo-large` for accuracy.

<Note>
  VAD detects **that** speech is happening; the turn detector decides **when** the turn is over.
</Note>

### How It Works

As the user speaks, VAD detects the speech and STT produces a transcript. After each user utterance, the latest transcript is sent to the Inference Gateway, where the selected Echo model (`echo-small` or `echo-large`) classifies the turn into one of four states:

| State         | Meaning                                                             |
| :------------ | :------------------------------------------------------------------ |
| `Complete`    | The user has finished their turn.                                   |
| `Incomplete`  | The user is still mid-sentence or not finished yet.                 |
| `Backchannel` | A short acknowledgement (e.g. "uh-huh", "okay okay").               |
| `Wait`        | The user wants the agent to hold (e.g. "wait a minute", "hold on"). |

### Models

Both models share the same four-state classification; they differ only in the latency/accuracy trade-off:

| Provider     | Model Name | Model ID     |
| :----------- | :--------- | :----------- |
| Zero Runtime | Echo Small | `echo-small` |
| Zero Runtime | Echo Large | `echo-large` |

* **`model="echo-small"`**: the lowest-latency model, optimized for the fastest possible turn detection. Best when responsiveness matters most.
* **`model="echo-large"`**: a higher-accuracy model that trades a little latency for better classification. Best when accuracy matters more than raw speed.

### Supported Languages

Both `echo-small` and `echo-large` support 12 languages: English, Hindi, Gujarati, Marathi, Tamil, Telugu, Urdu, Bengali, French, German, Italian, and Spanish.

### Usage

Set your auth token, then construct `TurnDetector` with the `echo-small` or `echo-large` model:

<CodeGroup>
  ```python Python theme={null}
  # Set ZRT_AUTH_TOKEN in your environment.

  from zrt.plugins import TurnDetector

  # Fastest, lowest latency
  turn_detector = TurnDetector(model="echo-small")

  # Higher accuracy
  turn_detector = TurnDetector(model="echo-large")
  ```
</CodeGroup>

### Performance

Benchmarked on the [TURNS2K](https://huggingface.co/datasets/latishab/turns-2k) dataset against a leading third-party turn-detection model, referred to here as **Baseline**. Each sample is labeled **Complete** (the user has finished speaking) or **Incomplete** (the user is still speaking).

| Metric              | Echo-Small | Echo-Large | Baseline |
| :------------------ | :--------- | :--------- | :------- |
| Accuracy            | 93.60%     | 96.20%     | 61.13%   |
| Recall (Complete)   | 97.31%     | 96.50%     | 32.83%   |
| Specificity         | 88.91%     | 95.81%     | 96.83%   |
| F1 Score (Complete) | 0.9443     | 0.9659     | 0.4851   |

<Note>
  Results are measured on the benchmark dataset described above, on samples labeled Complete or Incomplete. Performance may vary depending on language, deployment configuration, user behavior, and application requirements.
</Note>

### Choosing a Model

| Model          | Latency | Accuracy | Best For                          |
| :------------- | :------ | :------- | :-------------------------------- |
| **Echo Small** | Lowest  | High     | Lowest-latency, responsive agents |
| **Echo Large** | Low     | Highest  | Highest accuracy                  |

## End-of-Utterance Handling

End-of-Utterance (EOU) handling decides when the pipeline treats the user as finished speaking. In `ADAPTIVE` mode, the wait timeout adjusts based on confidence scores, so the agent waits longer when the user is hesitant and responds faster when intent is clear.

Configure it with `EOUConfig` in your pipeline options:

<CodeGroup>
  ```python Python theme={null}
  from zrt import Pipeline, EOUConfig

  pipeline = Pipeline(
      # ... other config
      eou_config=EOUConfig(
          mode="ADAPTIVE",
          min_max_speech_wait_timeout=[0.5, 0.8]
      )
  )
  ```
</CodeGroup>

| Parameter                     | Type                        | Default      | Description                                         |
| :---------------------------- | :-------------------------- | :----------- | :-------------------------------------------------- |
| `mode`                        | `"DEFAULT"` \| `"ADAPTIVE"` | `"DEFAULT"`  | `ADAPTIVE` uses LLM confidence to adjust wait time. |
| `min_max_speech_wait_timeout` | `[float, float]`            | `[0.5, 0.8]` | Min and max wait time in seconds after speech ends. |

### How the modes behave

* `DEFAULT`: Fixed wait within your min–max range. For clear utterances you respond near the minimum; for hesitations you wait near the maximum.
* `ADAPTIVE`: The wait scales with confidence. Low confidence (hesitation) increases wait; high confidence shortens it, always clamped to your min–max.

## What's Next

<CardGroup cols={2}>
  <Card title="VAD and Interruptions" icon="waveform-lines" href="/build/turn-detection-and-interruptions/vad-and-interruptions">
    Pair turn detection with Silero VAD.
  </Card>

  <Card title="De-noise" icon="headphones" href="/build/turn-detection-and-interruptions/denoise">
    Feed the detector cleaner input audio.
  </Card>
</CardGroup>

## References

<Tabs>
  <Tab title="Python">
    #### Examples

    <CardGroup cols={2}>
      <Card title="Cascade Basic" icon="github" href="https://github.com/ZeroRuntimeAI/zrt-python-sdk-examples/blob/main/features/basic_cascade.py">
        Voice agent with a turn detector configured.
      </Card>
    </CardGroup>

    #### SDK Reference

    <CardGroup cols={2}>
      <Card title="End of Utterance" icon="book" href="/api-reference/python/core/errors-and-config#eouconfig">
        `End of Utterance` in the Python API reference.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>