Soniox
Text-to-SpeechReal-time API

Streams

Run multiple concurrent Text-to-Speech streams over a single WebSocket connection using stream_id.

Overview

A single WebSocket connection can host up to 5 concurrent streams, each an independent Text-to-Speech generation identified by a unique stream_id. This lets you serve multiple users, voices, or languages from one connection without reopening a socket per request.

Multiple streams are useful when you need to:

  • Generate speech for multiple users or conversations over one connection.
  • Produce audio in different voices or languages simultaneously.
  • Reduce connection overhead by reusing a single WebSocket instead of opening one per request.

Each stream has its own lifecycle: it is started with a config message, receives its own text chunks, and produces its own audio output. Streams are fully isolated — an error in one stream does not affect the others.

Core rules

  • Start each stream with a config message that includes a unique stream_id. See the WebSocket API reference for the full payload.
  • Use the same stream_id for all text chunks belonging to that stream.
  • You can run up to 5 active streams per connection.
  • A stream error does not terminate other streams on the same connection.
  • Keep the WebSocket connection alive with keepalive messages between streams. Keepalive does not keep a stream open: send text continuously and close each stream with text_end: true.
  • A stream can be canceled at any time.

Starting multiple streams

Send a config message for each stream before sending text for that stream. Stream configs are independent — each one picks its own voice, language, and audio output settings.

Example: two streams on one connection

Stream A config (English, voice Adrian):

{
  "model": "tts-rt-v2",
  "language": "en",
  "voice": "Adrian",
  "audio_format": "pcm_s16le",
  "sample_rate": 24000,
  "stream_id": "stream-A"
}

Stream B config (Italian, voice Adrian) — same connection, different stream_id, any other fields may differ too:

{
  "model": "tts-rt-v2",
  "language": "it",
  "voice": "Adrian",
  "audio_format": "pcm_s16le",
  "sample_rate": 24000,
  "stream_id": "stream-B"
}

Important: Always send a stream's config message before sending any text for that stream.

After configuring, send text chunks with the matching stream_id. You can interleave chunks across streams freely — only the stream_id field determines routing:

{"text": "This audio belongs to stream A.", "text_end": false, "stream_id": "stream-A"}
{"text": "Questo audio appartiene allo stream B.", "text_end": false, "stream_id": "stream-B"}

Route messages by stream ID

The server sends audio for all active streams over the same connection. Use the stream_id field to route each incoming message to the correct output:

  1. Inspect stream_id on every incoming message.
  2. Route audio chunks to the matching output buffer or player.
  3. Track termination state separately for each stream.
  4. Mark a stream as finished only after receiving terminated: true for that stream_id.

Audio message:

{
  "audio": "<base64-audio-bytes>",
  "audio_end": false,
  "stream_id": "stream-A"
}

Termination message:

{
  "terminated": true,
  "stream_id": "stream-A"
}

Error isolation

  • Stream-level error — The server returns an error message for that stream_id, followed by a terminated: true event. Other streams on the connection continue normally.
  • Validation or malformed-message error — An incoming message was malformed or invalid (bad JSON, missing fields, unknown stream_id, duplicate start). The server returns an error response but does not send a terminated event, because no stream was actually running. The connection stays open for other valid streams and messages.
  • Connection-level failure — If the WebSocket itself closes (network failure, server error), all active streams on that connection end immediately.

For the full list of error codes and messages, see the WebSocket API reference.

Code example

Prerequisite: Complete the steps in Get started.

See on GitHub: soniox_sdk_realtime.py.

import argparse
import os
import threading
import time
from pathlib import Path
from uuid import uuid4

from soniox import SonioxClient
from soniox.errors import SonioxRealtimeError
from soniox.types import RealtimeTTSConfig
from soniox.utils import output_file_for_audio_format

VALID_SAMPLE_RATES = [8000, 16000, 24000, 44100, 48000]
VALID_BITRATES = [32000, 64000, 96000, 128000, 192000, 256000, 320000]
VALID_AUDIO_FORMATS = [
    "pcm_f32le",
    "pcm_s16le",
    "pcm_mulaw",
    "pcm_alaw",
    "wav",
    "aac",
    "mp3",
    "opus",
    "flac",
]

DEFAULT_LINES = [
    "Welcome to Soniox real-time Text-to-Speech. ",
    "As text is streamed in, audio streams back in parallel with high accuracy, ",
    "so your application can start playing speech ",
    "within milliseconds of the first word.",
]


def get_config(
    model: str,
    language: str,
    voice: str,
    audio_format: str,
    sample_rate: int | None,
    bitrate: int | None,
    stream_id: str | None,
) -> RealtimeTTSConfig:
    config = RealtimeTTSConfig(
        # Stream id for this realtime TTS session.
        # If omitted, a random id is generated.
        stream_id=stream_id or f"tts-{uuid4()}",
        #
        # Select the model to use.
        # See: docs.soniox.com/tts/models
        model=model,
        #
        # Set the language of the input text.
        # See: docs.soniox.com/tts/concepts/supported-languages
        language=language,
        #
        # Select the voice to use.
        # See: docs.soniox.com/tts/concepts/voices
        voice=voice,
        #
        # Set output audio format and optional encoding parameters.
        # See: docs.soniox.com/api-reference/tts/websocket-api
        audio_format=audio_format,
        sample_rate=sample_rate,
        bitrate=bitrate,
    )

    return config


def run_session(
    client: SonioxClient,
    lines: list[str],
    model: str,
    language: str,
    voice: str,
    audio_format: str,
    sample_rate: int | None,
    bitrate: int | None,
    stream_id: str | None,
    output_path: str | None,
) -> None:
    # Build a realtime Text-to-Speech session configuration.
    config = get_config(
        model=model,
        language=language,
        voice=voice,
        audio_format=audio_format,
        sample_rate=sample_rate,
        bitrate=bitrate,
        stream_id=stream_id,
    )
    sanitized_lines = [line.strip() for line in lines if line.strip()]
    if not sanitized_lines:
        raise ValueError("Text is empty after parsing.")

    destination = (
        Path(output_path)
        if output_path
        else output_file_for_audio_format(audio_format, "tts_realtime")
    )
    print("Connecting to Soniox...")
    audio_chunks: list[bytes] = []
    try:
        with client.realtime.tts.connect(config=config) as session:
            print("Session started.")
            send_errors: list[Exception] = []

            def send_worker() -> None:
                try:
                    for line in sanitized_lines:
                        session.send_text_chunk(line, text_end=False)
                        time.sleep(0.1)
                    session.finish()
                except Exception as exc:
                    send_errors.append(exc)

            threading.Thread(target=send_worker, daemon=True).start()
            # Receive streamed audio chunks from the websocket.
            for audio_chunk in session.receive_audio_chunks():
                audio_chunks.append(audio_chunk)
            if send_errors:
                raise RuntimeError(f"Failed to send realtime text: {send_errors[0]}")
            print("Session finished.")
    finally:
        audio = b"".join(audio_chunks)
        if audio:
            destination.write_bytes(audio)
            print(f"Wrote {len(audio)} bytes to {destination.resolve()}")
        else:
            print("No audio file was written.")


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--line",
        action="append",
        default=None,
        help="Line to send to realtime TTS (repeat --line for multiple lines).",
    )
    parser.add_argument("--model", default="tts-rt-v2")
    parser.add_argument("--language", default="en")
    parser.add_argument("--voice", default="Adrian")
    parser.add_argument("--audio_format", default="wav")
    parser.add_argument("--sample_rate", type=int)
    parser.add_argument("--bitrate", type=int)
    parser.add_argument("--stream_id", help="Optional stream id.")
    parser.add_argument(
        "--output_path",
        help="Optional output file path. If omitted, a timestamped path is generated.",
    )
    args = parser.parse_args()

    if args.audio_format not in VALID_AUDIO_FORMATS:
        raise ValueError(f"audio_format must be one of {VALID_AUDIO_FORMATS}")
    if args.sample_rate is not None and args.sample_rate not in VALID_SAMPLE_RATES:
        raise ValueError(f"sample_rate must be None or one of {VALID_SAMPLE_RATES}")
    if args.bitrate is not None and args.bitrate not in VALID_BITRATES:
        raise ValueError(f"bitrate must be None or one of {VALID_BITRATES}")

    api_key = os.environ.get("SONIOX_API_KEY")
    if not api_key:
        raise RuntimeError(
            "Missing SONIOX_API_KEY.\n"
            "1. Get your API key at https://console.soniox.com\n"
            "2. Run: export SONIOX_API_KEY=<YOUR_API_KEY>"
        )

    client = SonioxClient(api_key=api_key)

    try:
        run_session(
            client=client,
            lines=args.line or DEFAULT_LINES,
            model=args.model,
            language=args.language,
            voice=args.voice,
            audio_format=args.audio_format,
            sample_rate=args.sample_rate,
            bitrate=args.bitrate,
            stream_id=args.stream_id,
            output_path=args.output_path,
        )
    except SonioxRealtimeError as exc:
        print("Soniox realtime error:", exc)
    finally:
        client.close()


if __name__ == "__main__":
    main()

Terminal
# Generate speech with default settings (wav output)
python soniox_sdk_realtime.py --line "Hello from Soniox realtime Text-to-Speech."

# Generate raw PCM output
python soniox_sdk_realtime.py --audio_format pcm_s16le --sample_rate 24000 --output_path tts-output.pcm

Real-time generation

Learn how to generate speech in real time with the Soniox Text-to-Speech WebSocket API, including configuration, streaming, responses, and errors.

Stream termination

Learn how to terminate a stream and handle finalization and errors in the Soniox Text-to-Speech WebSocket API.

On this page

Overview
Core rules
Starting multiple streams
Example: two streams on one connection
Route messages by stream ID
Error isolation
Code example