LiveKit docs › Build Agents › Logic & Structure › Turn detection & interruptions › Turn detector

---

# LiveKit turn detector

> Audio-based end-of-turn detection for voice AI.

## Overview

The LiveKit turn detector improves end-of-turn detection in voice AI apps by adding signals on top of voice activity detection (VAD).

Traditional VAD models are effective at determining the presence or absence of speech, but without understanding the meaning of speech they can provide a poor user experience. For instance, a user might say "I need to think about that for a moment" and then take a long pause. The user has more to say but a VAD-only system interrupts them anyway. A turn detector model can predict that they have more to say and wait for them to finish before responding.

## Audio turn detector

LiveKit's `TurnDetector` is an audio model that encodes user audio directly, capturing both _what_ is said and _how_ it's said. By combining semantic understanding with acoustic cues like intonation, pitch, and rhythm, it reaches state-of-the-art end-of-turn accuracy without relying on a transcript.

The following capture shows two sessions running side by side on the same audio. The text model is tricked by the mid-turn pauses and commits the turn early, while the audio model waits for the true end of turn:

**Turn detection comparison** (interactive timeline, not available in text):

[Listen to the audio sample](https://static.livekit.io/audio/docs/turns/eot-flight-booking.mp3).

- The audio end-of-turn model commits the user's turn at: 6.41s.
- The text (STT-based) end-of-turn model commits the turn at: 2.76s, 4.88s, 6.40s.

Transcript chunks (arrival time → text):

- 2.53s: "Hi. I'd like to book a flight"
- 4.85s: "from Dublin to New York."
- 6.14s: "This Friday."

The detector comes in two versions:

- **`v1`**: the full model, served on LiveKit Inference in every region. Highest accuracy. Included at no extra cost for agents deployed to LiveKit Cloud. For self-hosted agents, usage beyond a monthly development allowance is billed per request on the Ship and Scale plans. On the Build plan, the session falls back to `v1-mini` at the limit by default. To learn more, see [Audio turn detection](https://docs.livekit.io/deploy/admin/quotas-and-limits.md#audio-turn-detection) on the Quotas and limits page.
- **`v1-mini`**: a lightweight version that runs locally on CPU, free to use in any context.

By default, if the full model is unavailable, the session falls back to `v1-mini` for the rest of the session. See [Fallback to the mini model](#audio-fallback).

### Installation

The audio turn detector is built into the Agents SDK: `livekit-agents` 1.6.1 or later for Python, and `@livekit/agents` 1.4.7 or later for Node.js. No separate plugin or extra is required.

### Usage

Initialize your `AgentSession` with `TurnDetector`. `AgentSession` provides the required VAD automatically, and the model is selected based on your environment (see [Default model selection](#audio-default-model)).

**Python**:

```python
from livekit.agents import AgentSession, TurnHandlingOptions, inference

session = AgentSession(
    turn_handling=TurnHandlingOptions(
        turn_detection=inference.TurnDetector(),
    ),
    # ... stt, tts, llm, etc.
)

```

---

**Node.js**:

```typescript
import { inference, voice } from '@livekit/agents';

const session = new voice.AgentSession({
  turnHandling: {
    turnDetection: new inference.TurnDetector(),
  },
  // ... stt, tts, llm, etc.
});

```

To pin a specific version instead of relying on auto-selection, pass `version`:

**Python**:

```python
turn_detection=inference.TurnDetector(version="v1-mini")

```

---

**Node.js**:

```typescript
turnDetection: new inference.TurnDetector({ version: 'v1-mini' }),

```

See the [Voice AI quickstart](https://docs.livekit.io/agents/start/voice-ai.md) for a complete example.

> ℹ️ **Note**
> 
> Some STT models, such as [Deepgram Flux](https://docs.livekit.io/agents/models/stt/deepgram.md), include built-in end-of-turn detection. No special configuration is needed to use them alongside the audio turn detector: the configured turn detector takes precedence, and the session uses end-of-turn signals from the STT only when you set `turn_detection="stt"`.

### Parameters

The following parameters are available on the `TurnDetector` constructor:

- **`version`** _(Literal['v1', 'v1-mini'])_ (optional): Selects the model version. `v1` is the full model served on LiveKit Inference while `v1-mini` runs locally on CPU. When omitted, the version is selected automatically based on your environment. See [Default model selection](#audio-default-model).

- **`unlikely_threshold`** _(float | dict[str, float])_ (optional): Override the model's confidence threshold for ending a turn. Accepts a scalar (applied to every language) or a dict keyed by language code. Unmapped languages keep the calibrated default for the active model. See [Custom thresholds](#audio-custom-thresholds). In Node.js, this parameter is called `unlikelyThreshold`.

- **`local_fallback`** _(bool)_ (optional) - Default: `True`: Controls whether the full `v1` model can fall back to the local `v1-mini` model when requests to LiveKit Inference fail. To learn how errors and timeouts behave either way, see [Fallback to the mini model](#audio-fallback). In Node.js, this parameter is called `localFallback`.

### Endpointing defaults

By default, the session waits between `0.5` and `3.0` seconds after speech to confirm the end of a turn. When you use the audio turn detector, the model provides a confident end-of-turn signal, so the session commits sooner with shorter [endpointing](https://docs.livekit.io/agents/logic/turns.md#endpointing-configuration) delays:

| Option | Default | With audio turn detector |
| --- | --- | --- |
| `min_delay` | `0.5` seconds | `0.3` seconds |
| `max_delay` | `3.0` seconds | `2.5` seconds |

Override either value through [`EndpointingOptions`](https://docs.livekit.io/reference/agents/turn-handling-options.md#endpointingoptions). If the model doesn't return a prediction within about a second, the agent commits the turn anyway, and by default, a timeout on the full `v1` model triggers a [fallback to `v1-mini`](#audio-fallback) for the rest of the session.

The audio turn detector requires VAD, and the VAD's `min_silence_duration` must be at least `0.25` seconds (250 ms). A lower value raises a `ValueError` when the session starts. The Silero VAD default of `0.55` seconds already satisfies this.

### Supported languages

The audio turn detector supports 14 languages: English, Arabic, German, Spanish, French, Hindi, Indonesian, Italian, Japanese, Korean, Dutch, Portuguese, Turkish, and Chinese.

When STT is enabled, the detector uses the language it reports to apply the right per-language threshold. To force a specific language, configure the [STT model](https://docs.livekit.io/agents/models/stt.md) with that language. The `language` parameter accepts any format supported by [`LanguageCode`](https://docs.livekit.io/agents/models/stt.md#language-codes). For example, to set Spanish:

**Python**:

```python
session = AgentSession(
    turn_handling=TurnHandlingOptions(
        turn_detection=inference.TurnDetector(),
    ),
    stt=inference.STT(language="es"),
    # ... tts, llm, etc.
)

```

---

**Node.js**:

```typescript
const session = new voice.AgentSession({
  turnHandling: {
    turnDetection: new inference.TurnDetector(),
  },
  stt: new inference.STT({ language: 'es' }),
  // ... tts, llm, etc.
});

```

When no STT is configured (for example, with a realtime model), the detector defaults to English thresholds.

### Custom thresholds

Each language has a calibrated `unlikely_threshold` that determines how confident the model must be before considering the user's turn complete. Lower values make the detector more eager to respond while higher values make it more patient.

Override the threshold globally with a scalar:

**Python**:

```python
inference.TurnDetector(unlikely_threshold=0.5)

```

---

**Node.js**:

```typescript
new inference.TurnDetector({ unlikelyThreshold: 0.5 });

```

Or override per language (unmapped languages keep the default):

**Python**:

```python
inference.TurnDetector(
    unlikely_threshold={
        "en": 0.5,
        "ja": 0.6,
    }
)

```

---

**Node.js**:

```typescript
new inference.TurnDetector({
  unlikelyThreshold: {
    en: 0.5,
    ja: 0.6,
  },
});

```

The two models ship with different calibrated defaults. When the session falls back from `v1` to `v1-mini` mid-session, your override is rescaled to preserve its relationship to the calibrated defaults of the active model.

### Realtime model usage

Because the audio turn detector doesn't depend on a transcript, you can use it with a realtime model without adding an STT plugin. You still need to disable the realtime model's built-in turn detection so the two systems don't conflict.

**Python**:

```python
from livekit.agents import AgentSession, TurnHandlingOptions, inference
from livekit.plugins import openai

session = AgentSession(
    turn_handling=TurnHandlingOptions(
        turn_detection=inference.TurnDetector(),
    ),
    llm=openai.realtime.RealtimeModel(
        voice="alloy",
        # Disable the model's built-in turn detection to use
        # the LiveKit audio turn detector instead
        turn_detection=None,
    ),
)

```

---

**Node.js**:

```typescript
import { inference, voice } from '@livekit/agents';
import * as openai from '@livekit/agents-plugin-openai';

const session = new voice.AgentSession({
  turnHandling: {
    turnDetection: new inference.TurnDetector(),
  },
  llm: new openai.realtime.RealtimeModel({
    voice: 'alloy',
    // Disable the model's built-in turn detection to use
    // the LiveKit audio turn detector instead
    turnDetection: null,
  }),
});

```

### Default model selection

When you don't set the `version` parameter, the detector picks a version based on your environment:

| Environment | Default version |
| --- | --- |
| Agent deployed to LiveKit Cloud | `v1` (full model) |
| Local development (`dev` mode) with LiveKit Cloud credentials | `v1` (full model) |
| Self-hosted agent in production (`start` command) | `v1-mini` (runs locally) |

To use the full model in a self-hosted agent, or to pin one version in every environment, set `version` explicitly (for example, to `"v1"`). The full model authenticates with your LiveKit Cloud project's API key and secret (`LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET`). Self-hosted or local usage of the full model counts toward a monthly development allowance. To learn more, see [Audio turn detection](https://docs.livekit.io/deploy/admin/quotas-and-limits.md#audio-turn-detection) on the Quotas and limits page.

If you don't pass `turn_detection` to `AgentSession` at all, the session uses a `TurnDetector` by default, unless your LLM is a realtime model that provides its own server-side turn detection.

When `v1-mini` runs (in a self-hosted agent started with `start`, or after a fallback), it uses the CPU of the machine that hosts the agent server. Use compute-optimized instances (such as AWS c6i or c7i) rather than burstable instances (such as AWS t3 or t4g) to avoid inference timeouts from CPU credit limits.

### Fallback to the mini model

When the full `v1` model is active, the detector watches for prediction timeouts and for errors from LiveKit Inference, such as a failed connection or a request rejected because the project reached its usage limit. If either occurs, the session does the following:

1. Logs a warning (once per session).
2. Emits a default probability (`1.0`) for any in-flight prediction so the current turn isn't blocked.
3. Swaps to `v1-mini` for the rest of the session.
4. Rescales any custom `unlikely_threshold` to preserve its relationship to the mini model's calibrated defaults.

The fallback is sticky for the lifetime of the session. The next session starts fresh and attempts the full model again. To turn off the fallback, set `local_fallback=False`, or `localFallback: false` in Node.js. If LiveKit Inference then returns an error or the connection fails, turn detection stops for the rest of the session, and the session ends each user turn after the [endpointing delay](#audio-endpointing). With the fallback turned off, a prediction timeout ends only the current turn, and the next turn uses the full model again.

If `v1-mini` isn't available (for example, the binary failed to load), the detector emits the default probability for each turn and retries on the next turn. The full model is also retried on each new session.

### Local model preloading

To keep sessions from waiting for a model to load on first use, the agent server can load the `v1-mini` weights and the bundled [Silero VAD](https://docs.livekit.io/agents/logic/turns/vad.md) ahead of time. Each SDK loads these models at different times and in different processes:

- In Python on Linux, the agent server loads both models once in a shared parent process, and every job process uses that copy. On macOS, each job process loads only the VAD when it starts, and loads the `v1-mini` weights the first time a session uses them.
- In Node.js, the agent server loads the `v1-mini` weights once in a shared inference process at startup, and every job process sends its predictions to that process. The VAD loads in each job process the first time a session uses it.

Each loaded copy of the `v1-mini` weights takes between about 140 and 250 MB of memory. If your agent never runs `v1-mini`, for example because it sets `version="v1"` with `local_fallback=False` or doesn't use the audio turn detector, you can skip the preload with the `LIVEKIT_AGENTS_PRELOAD_LOCAL_INFERENCE` environment variable:

| Value | Python | Node.js |
| --- | --- | --- |
| `0`, `false`, `no`, or `off` (case-insensitive) | Skips the preload for both models. | Skips the preload for the `v1-mini` weights. |
| Any other value | Preloads both models. On macOS, each job process loads its own copy of the `v1-mini` weights. | Same as not set. |
| Not set | Preloads both models once on Linux. On macOS, preloads only the VAD in each job process. | Preloads the `v1-mini` weights once in the shared inference process. |

If you skip the preload and a session still runs `v1-mini`, the weights load the first time that session uses them. In Python, each job process then loads its own copy. Memory use grows with the number of job processes.

### Benchmarks

LiveKit benchmarks the audio turn detector against other end-of-turn models using [eot-bench](https://github.com/livekit/eot-bench), an open source harness that simulates the live turn-taking decisions a production voice agent makes against natural, task-oriented conversations. See the repository for the current methodology and results.

For a deeper look at the model architecture and evaluation approach, see the [LiveKit blog](https://livekit.com/blog/solving-end-of-turn-detection).

## Text turn detector

> 🔥 **Deprecated**
> 
> The text turn detector is deprecated and slated for removal in version 2.0 of the LiveKit Agents SDK. Use the [audio turn detector](#audio-turn-detector) for new agents. It remains available for cases where you can't use LiveKit Inference and need a fully open-weights, self-contained option, but no longer receives feature work.

The text turn detector is an open-weights language model that adds conversational context as an additional signal to VAD using transcripts from your STT pipeline.

For more general information about the model, read about it on the [LiveKit blog](https://blog.livekit.io/improved-end-of-turn-model-cuts-voice-ai-interruptions-39/).

### Requirements

The text turn detector is designed for use inside an `AgentSession` and also requires an [STT model](https://docs.livekit.io/agents/models/stt.md). If you're using a realtime model, you must include a separate STT model to use this detector.

LiveKit recommends also using the [Silero VAD plugin](https://docs.livekit.io/agents/logic/turns/vad.md) for maximum performance, but you can rely on your STT plugin's endpointing instead if you prefer.

The model is deployed globally on LiveKit Cloud, and agents deployed there automatically use this optimized inference service.

For custom agent deployments, the model runs locally on the CPU in a shared process and requires <`500` MB of RAM. Use compute-optimized instances (such as AWS c6i or c7i) rather than burstable instances (such as AWS t3 or t4g) to avoid inference timeouts due to CPU credit limits.

### Installation

Install the plugin.

**Python**:

Install the plugin from PyPI:

```shell
uv add "livekit-agents[turn-detector]~=1.8"

```

---

**Node.js**:

Install the plugin from npm:

```shell
pnpm install @livekit/agents-plugin-livekit

```

### Usage

Initialize your `AgentSession` with the `MultilingualModel` and an STT model. These examples use LiveKit Inference for STT, but more options [are available](https://docs.livekit.io/agents/models/stt.md).

**Python**:

```python
from livekit.plugins.turn_detector.multilingual import MultilingualModel
from livekit.agents import AgentSession, inference, TurnHandlingOptions

session = AgentSession(
    turn_handling=TurnHandlingOptions(
        turn_detection=MultilingualModel(),
    ),
    stt=inference.STT(language="multi"),
    # ... vad, stt, tts, llm, etc.
)

```

---

**Node.js**:

```typescript
import { voice, inference } from '@livekit/agents';
import * as livekit from '@livekit/agents-plugin-livekit';

const session = new voice.AgentSession({
  stt: new inference.STT({ language: 'multi' }),
  turnHandling: {
    turnDetection: new livekit.turnDetector.MultilingualModel(),
  },
  // ... vad, stt, tts, llm, etc.
});

```

### Parameters

The text turn detector itself has no configuration, but you can configure the following endpointing parameters in the turn handling options passed to the `AgentSession`. To learn more, see [EndpointingOptions](https://docs.livekit.io/reference/agents/turn-handling-options.md#endpointingoptions).

- **`mode`** _(Literal['dynamic', 'fixed'])_ (optional) - Default: `fixed`: Endpointing timing behavior. The endpointing delay is the time the agent waits before terminating the users's turn.

- `"fixed"` - Use the configured `min_delay` and `max_delay` values to determine the endpointing delay.
- `"dynamic"` - Adapt the delay within the `min_delay` and `max_delay` range based on session pause statistics (exponential moving average of between-utterance and between-turn pauses). Suits most conversations.

- **`min_delay`** _(float)_ (optional) - Default: `0.5 seconds`: Minimum time (in seconds) to wait since the last detected speech to declare the user's turn to be complete.

With [dynamic endpointing](https://docs.livekit.io/reference/agents/turn-handling-options.md#dynamic-endpointing), this is the lower bound. The agent might use a longer effective delay when session pause statistics suggest slower turn-taking.

- In VAD mode, this effectively behaves like `max(VAD silence, min_delay)`.
- In STT mode, this is applied _after_ the STT end-of-speech signal, and therefore in addition to the STT provider's endpointing delay.

- **`max_delay`** _(float)_ (optional) - Default: `3.0 seconds`: Maximum time (in seconds) the agent waits before terminating the turn. This prevents the agent from waiting indefinitely for the user to continue speaking.

With [dynamic endpointing](https://docs.livekit.io/reference/agents/turn-handling-options.md#dynamic-endpointing), this is the upper bound. The agent might use a shorter effective delay when session pause statistics suggest faster turn-taking.

- **`alpha`** _(float)_ (optional) - Default: `0.9`: Exponential moving average (EMA) coefficient for [dynamic endpointing](https://docs.livekit.io/reference/agents/turn-handling-options.md#dynamic-endpointing). Higher values give more weight to accumulated history, so the learned delay adapts more slowly. Lower values react faster to recent pauses. Only applies when `mode` is `"dynamic"`.

> ℹ️ **Note**
> 
> When you use the [audio turn detector](https://docs.livekit.io/agents/logic/turns/turn-detector.md#audio-turn-detector), any `min_delay` and `max_delay` values you don't set default to `0.3` and `2.5` seconds instead of `0.5` and `3.0`. The model provides a confident end-of-turn signal, so the agent can commit sooner. See [Endpointing defaults](https://docs.livekit.io/agents/logic/turns/turn-detector.md#audio-endpointing).

> ℹ️ **Time units**
> 
> In Node.js, `min_delay` and `max_delay` are in milliseconds (for example, `500` and `3000`). Python uses seconds (for example, `0.5` and `3.0`).

### Supported languages

The `MultilingualModel` supports English and 13 other languages. The model relies on your [STT model](https://docs.livekit.io/agents/models/stt.md) to report the language of the user's speech. To set the language to a fixed value, configure the STT model with a specific language. The `language` parameter accepts any format supported by [`LanguageCode`](https://docs.livekit.io/agents/models/stt.md#language-codes). For example, to force the model to use Spanish:

**Python**:

```python
session = AgentSession(
    turn_handling=TurnHandlingOptions(
        turn_detection=MultilingualModel(),
    ),
    stt=inference.STT(language="es"),
    # ... vad, stt, tts, llm, etc.
)

```

---

**Node.js**:

```typescript
import { voice, inference } from '@livekit/agents';
import * as livekit from '@livekit/agents-plugin-livekit';

const session = new voice.AgentSession({
  stt: new inference.STT({ language: 'es' }),
  turnHandling: {
    turnDetection: new livekit.turnDetector.MultilingualModel(),
  },
  // ... vad, stt, tts, llm, etc.
});

```

The model currently supports English, Spanish, French, German, Italian, Portuguese, Dutch, Chinese, Japanese, Korean, Indonesian, Turkish, Russian, and Hindi.

### Realtime model usage

Realtime models like the OpenAI Realtime API produce user transcripts after the end of the turn, rather than incrementally while the user speaks. The text turn detector requires live STT results to operate, so you must provide an STT plugin to the `AgentSession` to use it with a realtime model. This incurs extra cost for the STT model.

You must also disable the realtime model's built-in turn detection so it doesn't conflict with the LiveKit turn detector. The following example demonstrates how to do this with the OpenAI Realtime API:

**Python**:

```python
from livekit.agents import AgentSession, TurnHandlingOptions
from livekit.plugins.turn_detector.multilingual import MultilingualModel
from livekit.plugins import deepgram, openai, silero

session = AgentSession(
    turn_handling=TurnHandlingOptions(
        turn_detection=MultilingualModel(),
    ),
    vad=silero.VAD.load(),
    stt=deepgram.STT(),
    # OpenAI Realtime API
    llm=openai.realtime.RealtimeModel(
        voice="alloy",
        # Disable the model's built-in turn detection to use
        # the LiveKit turn detector instead
        turn_detection=None,
        input_audio_transcription=None,  # use Deepgram STT instead
    ),
)

```

---

**Node.js**:

```typescript
import { voice } from '@livekit/agents';
import * as deepgram from '@livekit/agents-plugin-deepgram';
import * as livekit from '@livekit/agents-plugin-livekit';
import * as openai from '@livekit/agents-plugin-openai';
import * as silero from '@livekit/agents-plugin-silero';

const session = new voice.AgentSession({
  turnHandling: {
    turnDetection: new livekit.turnDetector.MultilingualModel(),
  },
  vad: await silero.VAD.load(),
  stt: new deepgram.STT(),
  // OpenAI Realtime API
  llm: new openai.realtime.RealtimeModel({
    voice: 'alloy',
    // Disable the model's built-in turn detection to use
    // the LiveKit turn detector instead
    turnDetection: null,
    inputAudioTranscription: null, // use Deepgram STT instead
  }),
});

```

### Benchmarks

The following data shows the expected performance of the text turn detector model.

#### Runtime performance

The size on disk and typical CPU inference time for the text turn detector model is as follows:

| Model | Base Model | Size on Disk | Per Turn Latency |
| --- | --- | --- | --- |
| Multilingual | [Qwen2.5-0.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct) | 396 MB | ~50-160 ms |

#### Detection accuracy

The following tables show accuracy metrics for the text turn detector model in each supported language.

- **True positive** means the model correctly identifies the user has finished speaking.
- **True negative** means the model correctly identifies the user will continue speaking.

| Language | True Positive Rate | True Negative Rate |
| --- | --- | --- |
| Hindi | 99.4% | 96.30% |
| Korean | 99.3% | 94.50% |
| French | 99.3% | 88.90% |
| Portuguese | 99.4% | 87.40% |
| Indonesian | 99.3% | 89.40% |
| Russian | 99.3% | 88.00% |
| English | 99.3% | 87.00% |
| Chinese | 99.3% | 86.60% |
| Japanese | 99.3% | 88.80% |
| Italian | 99.3% | 85.10% |
| Spanish | 99.3% | 86.00% |
| German | 99.3% | 87.80% |
| Turkish | 99.3% | 87.30% |
| Dutch | 99.3% | 88.10% |

### Resources

The following resources cover the open-weights text turn detector:

- **[Plugin reference](https://docs.livekit.io/reference/python/livekit/plugins/turn_detector/index.html.md)**: Reference for the `livekit-plugins-turn-detector` package.

- **[GitHub repo](https://github.com/livekit/agents/tree/main/livekit-plugins/livekit-plugins-turn-detector)**: View the source or contribute to the text turn detector plugin.

- **[LiveKit Model License](https://huggingface.co/livekit/turn-detector/blob/main/LICENSE)**: LiveKit Model License used for the text turn detector and the `v1-mini` model.

## Additional resources

- **[Audio turn detector deep dive](https://livekit.com/blog/solving-end-of-turn-detection)**: Model architecture, benchmarks, and evaluation methodology on the LiveKit blog.

- **[Evaluation harness](https://github.com/livekit/eot-bench)**: Open source harness for benchmarking end-of-turn models under production endpointing policies.

- **[Evaluation datasets](https://huggingface.co/datasets/livekit/eot-evals)**: Open source English and multilingual end-of-turn test datasets on Hugging Face.

---

This document was rendered at 2026-11-15T12:49:06.443Z.
For the latest version of this document, see [https://docs.livekit.io/agents/logic/turns/turn-detector.md](https://docs.livekit.io/agents/logic/turns/turn-detector.md).

To explore all LiveKit documentation, see [llms.txt](https://docs.livekit.io/llms.txt).