LiveKit docs › Build Agents › Models › STT › Additional models › Soniox

---

# Soniox STT plugin guide

> How to use the Soniox STT plugin for LiveKit Agents.

Available in:
- [x] Node.js
- [x] Python

## Overview

This plugin allows you to use [Soniox](https://soniox.com/) as an STT provider for your voice agents.

### Installation

Install the plugin:

**Python**:

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

```

---

**Node.js**:

```shell
pnpm add @livekit/agents-plugin-soniox@1.x

```

### Authentication

The Soniox plugin requires an API key from the [Soniox console](https://console.soniox.com/).

Set `SONIOX_API_KEY` in your `.env` file.

### Usage

Use Soniox STT in an `AgentSession` or as a standalone transcription service. For example, you can use this STT in the [Voice AI quickstart](https://docs.livekit.io/agents/start/voice-ai.md).

Configure Soniox STT options when you create the `STT` instance:

**Python**:

```python
from livekit.plugins import soniox

session = AgentSession(
   stt=soniox.STT(
      params=soniox.STTOptions(
         model="stt-rt-v5",
         language_hints=["en"]
      )
   ),
# ... llm, tts, etc.
)

```

---

**Node.js**:

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

const session = new voice.AgentSession({
   stt: new soniox.STT({
      model: 'stt-rt-v4',
      languageHints: ['en'],
   }),
   // ... llm, tts, etc.
});

```

### Speaker diarization

You can enable [speaker diarization](https://soniox.com/docs/stt/concepts/speaker-diarization) so the STT assigns a speaker identifier to each word or segment. When enabled, each token includes a `speaker` field and the STT reports `capabilities.diarization=True`.

The following example enables speaker diarization:

**Python**:

```python
from livekit.plugins import soniox

session = AgentSession(
   stt=soniox.STT(
      params=soniox.STTOptions(
         model="stt-rt-v5",
         language_hints=["en"],
         enable_speaker_diarization=True,
      )
   ),
# ... llm, tts, etc.
)

```

---

**Node.js**:

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

const session = new voice.AgentSession({
   stt: new soniox.STT({
      model: 'stt-rt-v4',
      languageHints: ['en'],
      enableSpeakerDiarization: true,
   }),
   // ... llm, tts, etc.
});

```

You can use `MultiSpeakerAdapter` to detect the primary speaker and format the transcripts by speaker. To learn more, see [Speaker diarization and primary speaker detection](https://docs.livekit.io/agents/models/stt.md#speaker-diarization).

### Realtime translation

To use [realtime translation](https://soniox.com/docs/stt/rt/real-time-translation), pass a `TranslationConfig` to `STTOptions`. Soniox supports two translation modes: one-way and two-way.

#### One-way translation

To translate from any detected language into a single target language, set `type` to `"one_way"` and specify the target language. For example, to translate any spoken language into English:

**Python**:

```python
from livekit.plugins import soniox

session = AgentSession(
   stt=soniox.STT(
      params=soniox.STTOptions(
         model="stt-rt-v5",
         translation=soniox.TranslationConfig(
            type="one_way",
            target_language="en",
         ),
      )
   ),
   # ... llm, tts, etc.
)

```

---

**Node.js**:

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

const session = new voice.AgentSession({
   stt: new soniox.STT({
      model: 'stt-rt-v4',
      translation: {
         type: 'one_way',
         targetLanguage: 'en',
      },
   }),
   // ... llm, tts, etc.
});

```

#### Two-way translation

To translate back and forth between two languages, set `type` to `"two_way"` and specify the two languages. For example, to translate between English and Spanish:

**Python**:

```python
from livekit.plugins import soniox

session = AgentSession(
   stt=soniox.STT(
      params=soniox.STTOptions(
         model="stt-rt-v5",
         translation=soniox.TranslationConfig(
            type="two_way",
            language_a="en",
            language_b="es",
         ),
      )
   ),
   # ... llm, tts, etc.
)

```

---

**Node.js**:

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

const session = new voice.AgentSession({
   stt: new soniox.STT({
      model: 'stt-rt-v4',
      translation: {
         type: 'two_way',
         languageA: 'en',
         languageB: 'es',
      },
   }),
   // ... llm, tts, etc.
});

```

When translation is active, the first `SpeechData` in the `alternatives` list of each `SpeechEvent` (`alternatives[0]`) contains the translated text in the `text` field, and `language` holds the dominant target language.

#### Per-language segments

`SpeechData` splits the transcript by language. `source_languages` lists the language of each spoken segment and `source_texts` holds the matching text. In translation mode, `target_languages` and `target_texts` do the same for the translated output. In Node.js, the fields are `sourceLanguages`, `sourceTexts`, `targetLanguages`, and `targetTexts`.

For example, two-way English and Spanish translation of the spoken phrase `"No hablo español, but I speak English."` produces:

```python
text = "I don't speak Spanish, pero hablo inglés."
source_languages = ["es", "en"]
source_texts = ["No hablo español, ", "but I speak English."]
target_languages = ["en", "es"]
target_texts = ["I don't speak Spanish, ", "pero hablo inglés."]

```

Outside translation mode, `source_languages` and `source_texts` identify the language of each segment in code-switched audio.

### Endpoint detection

Soniox uses [endpoint detection](https://soniox.com/docs/stt/rt/endpoint-detection) to detect when a speech segment has ended and finalize its transcript. It identifies an endpoint as speech followed by enough silence. Finalizing sooner reduces latency, while waiting longer gives the model more context for accuracy. Three options let you tune this tradeoff:

- `max_endpoint_delay_ms` sets the maximum time Soniox waits after speech stops before it finalizes a segment.
- `endpoint_sensitivity` adjusts how readily the model commits an endpoint, where higher values finalize sooner.
- `endpoint_latency_adjustment_level` trades accuracy for lower endpoint latency, where higher values reduce latency.

`endpoint_sensitivity` and `endpoint_latency_adjustment_level` require the `stt-rt-v5` model. Earlier models reject them. `endpoint_sensitivity` is available in Python only.

The following example tunes all three options. Set `model` to `stt-rt-v5` because endpoint-related options require it:

**Python**:

```python
from livekit.plugins import soniox

session = AgentSession(
   stt=soniox.STT(
      params=soniox.STTOptions(
         model="stt-rt-v5",
         max_endpoint_delay_ms=2000,
         endpoint_sensitivity=0.5,
         endpoint_latency_adjustment_level=2,
      )
   ),
# ... llm, tts, etc.
)

```

---

**Node.js**:

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

const session = new voice.AgentSession({
   stt: new soniox.STT({
      model: 'stt-rt-v5',
      maxEndpointDelayMs: 2000,
      endpointLatencyAdjustmentLevel: 2,
   }),
   // ... llm, tts, etc.
});

```

### Parameters

This section describes some of the available options. See the [STTOptions reference](https://docs.livekit.io/reference/python/livekit/plugins/soniox/index.html.md#livekit.plugins.soniox.STTOptions) for a complete list.

In Python, pass these as an `STTOptions` object via the `params` argument. In Node.js, pass them directly to the `STT` constructor using their camelCase names (for example, `languageHints`, `enableSpeakerDiarization`).

- **`model`** _(string)_ (optional): The Soniox STT model to use. Defaults to `stt-rt-v5` in Python and `stt-rt-v4` in Node.js. See [documentation](https://soniox.com/docs/stt/models) for a complete list of supported models.

- **`context`** _(ContextObject | string)_ (optional) - Default: `None`: Free-form text, or a structured `ContextObject`, that provides additional context or vocabulary to bias transcription towards domain-specific terms.

- **`enable_language_identification`** _(boolean)_ (optional) - Default: `true`: When `true`, Soniox attempts to identify the language of the input audio.

- **`enable_speaker_diarization`** _(boolean)_ (optional) - Default: `false`: Set to `True` to enable [speaker diarization](#speaker-diarization).

- **`max_endpoint_delay_ms`** _(int)_ (optional): Maximum delay in milliseconds between when speech stops and Soniox finalizes an endpoint. Range: `500` to `3000`. Defaults to `2000` in Python and `500` in Node.js. See [endpoint detection](#endpoint-detection).

- **`endpoint_sensitivity`** _(float)_ (optional) - Default: `None`: Available in:
- [ ] Node.js
- [x] Python

How readily the model commits an endpoint, from `-1.0` to `1.0`. Higher values finalize sooner. Leave unset to use the Soniox default. Requires the `stt-rt-v5` model. See [endpoint detection](#endpoint-detection).

- **`endpoint_latency_adjustment_level`** _(int)_ (optional) - Default: `None`: How aggressively the model reduces endpoint latency, from `0` to `3`. Higher values reduce latency but can emit more endpoints and slightly reduce accuracy. Leave unset to use the Soniox default. Requires the `stt-rt-v5` model. See [endpoint detection](#endpoint-detection).

- **`translation`** _(TranslationConfig)_ (optional) - Default: `None`: Enable realtime translation. See [realtime translation](#realtime-translation) for details and examples.

## Additional resources

The following resources provide more information about using Soniox with LiveKit Agents.

- **[Python package](https://pypi.org/project/livekit-plugins-soniox/)**: The `livekit-plugins-soniox` package on PyPI.

- **[Node.js package](https://www.npmjs.com/package/@livekit/agents-plugin-soniox)**: The `@livekit/agents-plugin-soniox` package on npm.

- **[Plugin reference](https://docs.livekit.io/reference/python/livekit/plugins/soniox/index.html.md)**: Reference for the Soniox STT plugin.

- **[GitHub repo](https://github.com/livekit/agents/tree/main/livekit-plugins/livekit-plugins-soniox)**: View the source or contribute to the LiveKit Soniox STT plugin.

- **[Soniox docs](https://soniox.com/docs)**: Soniox's full docs site.

- **[Voice AI quickstart](https://docs.livekit.io/agents/start/voice-ai.md)**: Get started with LiveKit Agents and Soniox.

---

This document was rendered at 2026-10-07T16:11:26.740Z.
For the latest version of this document, see [https://docs.livekit.io/agents/models/stt/soniox.md](https://docs.livekit.io/agents/models/stt/soniox.md).

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