> ## Documentation Index
> Fetch the complete documentation index at: https://daily-docs-pr-4892.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Soniox

> Real-time WebSocket text-to-speech service using Soniox's streaming TTS API

## Overview

Soniox provides real-time text-to-speech synthesis using a WebSocket-based streaming API. `SonioxTTSService` streams text incrementally to the Soniox TTS endpoint and receives audio back as base64-encoded chunks. Multiple concurrent streams (up to 5) are multiplexed over a single WebSocket connection, making it efficient for interactive voice applications.

<CardGroup cols={2}>
  <Card title="Soniox TTS API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.soniox.tts.html">
    Pipecat's API methods for Soniox TTS integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-soniox.py">
    Complete example with Soniox STT and TTS
  </Card>

  <Card title="Soniox Documentation" icon="book" href="https://soniox.com/docs/api-reference/tts/websocket-api">
    Official Soniox TTS WebSocket API documentation
  </Card>

  <Card title="Supported Languages" icon="globe" href="https://soniox.com/docs/tts/concepts/languages">
    Browse supported languages (60+)
  </Card>
</CardGroup>

## Installation

To use Soniox TTS, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[soniox]"
```

## Prerequisites

### Soniox Account Setup

Before using Soniox TTS, you need:

1. **Soniox Account**: Sign up at [Soniox Console](https://console.soniox.com)
2. **API Key**: Generate an API key from your console dashboard
3. **Voice Selection**: Choose from available voices

### Required Environment Variables

* `SONIOX_API_KEY`: Your Soniox API key for authentication

## Configuration

<ParamField path="api_key" type="str" required>
  Soniox API key for authentication. Create API keys at [Soniox
  Console](https://console.soniox.com).
</ParamField>

<ParamField path="url" type="str" default="wss://tts-rt.soniox.com/tts-websocket">
  WebSocket endpoint URL for Soniox TTS.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Output sample rate in Hz. Must be one of `{8000, 16000, 24000, 44100, 48000}`
  when using a raw PCM audio format. When `None`, inherits from the pipeline's
  configured sample rate.
</ParamField>

<ParamField path="audio_format" type="str" default="pcm_s16le">
  Output audio format. Defaults to `"pcm_s16le"`, which matches Pipecat's
  downstream audio pipeline.
</ParamField>

<ParamField path="text_aggregation_mode" type="TextAggregationMode" default="TextAggregationMode.SENTENCE">
  Controls how incoming text is aggregated before synthesis. `SENTENCE`
  (default) buffers text until sentence boundaries, producing more natural
  speech. `TOKEN` streams tokens directly for lower latency. Import from
  `pipecat.services.tts_service`.
</ParamField>

<ParamField path="settings" type="SonioxTTSService.Settings" default="None">
  Runtime-configurable settings. See [Settings](#settings) below.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `SonioxTTSService.Settings(...)`. These can be updated mid-conversation with `TTSUpdateSettingsFrame`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter  | Type              | Default       | Description                                                                                                                                                                         |
| ---------- | ----------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`    | `str`             | `tts-rt-v1`   | TTS model identifier. *(Inherited from base settings.)*                                                                                                                             |
| `voice`    | `str`             | `Adrian`      | Voice name (e.g. `"Adrian"`) or the UUID of a cloned voice in the project owning the API key. *(Inherited from base settings.)*                                                     |
| `language` | `Language \| str` | `Language.EN` | Language for synthesis. *(Inherited from base settings.)* See [supported languages](https://soniox.com/docs/tts/concepts/languages).                                                |
| `speed`    | `float \| None`   | `None`        | Speech rate multiplier in the range 0.7-1.3. `None` uses the Soniox server default (1.0). Changing this flushes the current context and starts a new stream with the updated value. |

## Usage

### Basic Setup

```python theme={null}
import os
from pipecat.services.soniox.tts import SonioxTTSService

tts = SonioxTTSService(
    api_key=os.getenv("SONIOX_API_KEY"),
    settings=SonioxTTSService.Settings(
        voice="Maya",
    ),
)
```

### With Custom Voice and Model

```python theme={null}
tts = SonioxTTSService(
    api_key=os.getenv("SONIOX_API_KEY"),
    settings=SonioxTTSService.Settings(
        model="tts-rt-v1",
        voice="Adrian",
        language="en",
    ),
)
```

### With Speech Rate Control

```python theme={null}
tts = SonioxTTSService(
    api_key=os.getenv("SONIOX_API_KEY"),
    settings=SonioxTTSService.Settings(
        voice="Maya",
        speed=1.2,  # 20% faster speech (range: 0.7-1.3)
    ),
)
```

### With Cloned Voice

```python theme={null}
# Use a cloned voice by passing its UUID
tts = SonioxTTSService(
    api_key=os.getenv("SONIOX_API_KEY"),
    settings=SonioxTTSService.Settings(
        voice="a1b2c3d4-e5f6-7890-abcd-ef1234567890",  # UUID of cloned voice
    ),
)
```

### With Custom Sample Rate

```python theme={null}
tts = SonioxTTSService(
    api_key=os.getenv("SONIOX_API_KEY"),
    sample_rate=16000,
    settings=SonioxTTSService.Settings(
        voice="Maya",
    ),
)
```

## Notes

* **WebSocket streaming**: Soniox uses a persistent WebSocket connection for streaming text-in and audio-out, enabling low-latency real-time synthesis.
* **Concurrent streams**: The service supports up to 5 concurrent streams multiplexed over a single WebSocket connection via Pipecat's audio-context mechanism.
* **Sample rates**: When using raw PCM audio formats, the sample rate must be one of `{8000, 16000, 24000, 44100, 48000}`.
* **Keepalive**: The service automatically sends keepalive messages every 20 seconds to prevent Soniox's idle timeout (20-30s).
* **Text aggregation**: Sentence aggregation is enabled by default (`text_aggregation_mode=TextAggregationMode.SENTENCE`). Buffering until sentence boundaries produces more natural speech. Set `text_aggregation_mode=TextAggregationMode.TOKEN` to stream tokens directly for lower latency.
* **Language support**: Soniox supports 60+ languages. See the [language documentation](https://soniox.com/docs/tts/concepts/languages) for the complete list.
* **Word-aligned text frames**: The service emits `TTSTextFrame`s aligned with word timestamps from Soniox, so the LLM context reflects only what was actually spoken at the moment of interruption. This ensures accurate conversation state when the user interrupts mid-sentence.

## Event Handlers

Soniox TTS supports the standard [service connection events](/api-reference/server/events/service-events):

| Event                 | Description                         |
| --------------------- | ----------------------------------- |
| `on_connected`        | Connected to Soniox WebSocket       |
| `on_disconnected`     | Disconnected from Soniox WebSocket  |
| `on_connection_error` | WebSocket connection error occurred |

```python theme={null}
@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Soniox TTS")
```