> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/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/tts/api-reference/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-preview` | TTS model identifier. *(Inherited from base settings.)*                                                                              |
| `voice`    | `str`             | `Adrian`            | Voice identifier. *(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). |

## 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-preview",
        voice="Adrian",
        language="en",
    ),
)
```

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

## 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")
```