LiveKit docs › Models › STT › Additional models › Soniox

---

# Soniox STT plugin guide

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

Available in:
- [ ] 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 from PyPI:

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

```

### 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).

Set STT options for Soniox using the `params` argument:

```python
from livekit.plugins import soniox

session = AgentSession(
   stt=soniox.STT(
      params=soniox.STTOptions(
         model="stt-rt-v4",
         language_hints=["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
from livekit.plugins import soniox

session = AgentSession(
   stt=soniox.STT(
      params=soniox.STTOptions(
         model="stt-rt-v4",
         language_hints=["en"],
         enable_speaker_diarization=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
from livekit.plugins import soniox

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

```

#### Two-way translation

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

```python
from livekit.plugins import soniox

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

```

When translation is active, the `SpeechData` object in each `SpeechEvent` contains the translated text in the `text` field. The original spoken language and transcription are available in the `source_languages` and `source_texts` fields.

### Parameters

The `soniox.STT` constructor takes an `STTOptions` object as the `params` argument. 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.

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

- **`context`** _(string)_ (optional) - Default: `None`: Free-form text 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).

- **`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.

- **[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-06-07T11:34:11.697Z.
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).