soniox 2.2.0__tar.gz → 2.3.1__tar.gz

{soniox-2.2.0 → soniox-2.3.1}/CHANGELOG.md

@@ -77,6 +77,28 @@ Examples:
 
 ---
 
+## [2.3.1] - 29 apr 2026
+
+### Changed
+
+- Default TTS model is now `tts-rt-v1` (previously `tts-rt-v1-preview`).
+
+---
+
+## [2.3.0] - 22 apr 2026
+
+### Added
+
+- Text-to-Speech (TTS) support, available on both `SonioxClient` and `AsyncSonioxClient`.
+- REST TTS API via `client.tts`: `generate()` returns audio bytes, `generate_to_file()` writes audio to a path or file-like object. Configurable `voice`, `model`, `language`, `audio_format`, `sample_rate`, and `bitrate`.
+- TTS model listing via `client.tts_models.list()`.
+- Realtime TTS over websocket via `client.realtime.tts.connect(...)`: stream text in with `send_text_chunk` / `send_text_chunks` / `finish`, receive audio with `receive_audio_chunks` or raw events with `receive_events`, plus `cancel`, `pause`, `resume`, and `keep_alive`.
+- Multiplexed realtime TTS via `client.realtime.tts.connect_multi_stream()`: run multiple concurrent TTS streams over a single websocket connection using `open_stream`.
+- New TTS examples for sync and async clients (REST, realtime, and multiplexed realtime).
+- `tts_api_base_url` and `tts_websocket_base_url` client options for overriding TTS endpoints.
+
+---
+
 ## [2.2.0] - 25 feb 2026
 
 ### Added

{soniox-2.2.0 → soniox-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soniox
-Version: 2.2.0
+Version: 2.3.1
 Summary: The official Python SDK for the Soniox API (STT, REST)
 Project-URL: Homepage, https://sonoix.com
 Project-URL: Documentation, https://soniox.com/docs
@@ -37,8 +37,10 @@ Description-Content-Type: text/markdown
 
 # Soniox Python SDK
 
-The SDK exposes two clients: `SonioxClient` (sync) and `AsyncSonioxClient`. Client can hit every Soniox REST endpoint or open a real-time websocket session, so you can focus on building features instead of dealing with boilerplate.
-Auth, file uploads, transcription polling, webhook helpers, and real-time stream helpers all live in one typed package.
+The SDK exposes two clients: `SonioxClient` (sync) and `AsyncSonioxClient` (async). Each client supports:
+- STT over REST (`client.stt`) and realtime WebSocket (`client.realtime.stt`)
+- TTS over REST (`client.tts`) and realtime WebSocket (`client.realtime.tts`)
+- auth, file uploads, model listing, webhooks, and typed request/response models
 
 ## Install
 
@@ -51,9 +53,9 @@ export SONIOX_API_KEY=<your-key>
 
 Get your API key from the [Soniox Console](https://console.soniox.com) and inject it once per shell session. Both clients read `SONIOX_API_KEY` by default, but you can override it per-client if needed.
 
-## Quick run (rest + real-time)
+## Quick run (STT + TTS, REST + realtime)
 
-1. **REST transcription**: copy this snippet or run [`examples/soniox_client/api_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/api_example.py).
+1. **REST STT transcription**: copy this snippet or run [`examples/soniox_client/api_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/api_example.py).
 
 ```python
 from soniox import SonioxClient
@@ -67,7 +69,29 @@ client.stt.wait(transcription.id, timeout_sec=60)
 print(client.stt.get_transcript(transcription.id).text[:200])
 ```
 
-2. **Real-time streaming**: the real-time helpers mirror the sync rest sample—open `client.realtime.stt.connect`, call `session.send_byte_chunk` or `session.send_bytes`, then iterate `session.receive_events()` to render tokens. example:
+2. **REST TTS generation**: convert text to an audio file.
+
+```python
+from soniox import SonioxClient
+from soniox.utils import output_file_for_audio_format
+
+client = SonioxClient()
+output_file = output_file_for_audio_format("wav", "tts_sync_output")
+written = client.tts.generate_to_file(
+    output_file,
+    text="Hello from Soniox Python SDK Text-to-Speech.",
+    model="tts-rt-v1",
+    language="en",
+    voice="Adrian",
+    audio_format="wav",
+)
+print(f"Wrote {written} bytes to {output_file.resolve()}")
+client.close()
+```
+
+Run the full example at [`examples/soniox_client/tts_api_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/tts_api_example.py) or async version at [`examples/async_soniox_client/tts_api_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/async_soniox_client/tts_api_example.py).
+
+3. **Realtime STT streaming**: open `client.realtime.stt.connect`, call `session.send_byte_chunk` or `session.send_bytes`, then iterate `session.receive_events()` to render tokens:
 
 ```python
 from soniox import SonioxClient
@@ -96,15 +120,46 @@ def realtime():
 realtime()
 ```
 
-see [`examples/soniox_client/realtime_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/realtime_example.py) for the full flow.
+See [`examples/soniox_client/realtime_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/realtime_example.py) for the full flow.
+
+4. **Realtime TTS streaming**: send text chunks and read generated audio chunks from the session.
+
+```python
+from uuid import uuid4
+
+from soniox import SonioxClient
+from soniox.types import RealtimeTTSConfig
+
+client = SonioxClient()
+config = RealtimeTTSConfig(
+    stream_id=f"sync-{uuid4()}",
+    model="tts-rt-v1",
+    language="en",
+    voice="Adrian",
+    audio_format="wav",
+)
+
+audio_chunks: list[bytes] = []
+with client.realtime.tts.connect(config=config) as session:
+    session.keep_alive()
+    session.send_text_chunks(
+        ["Hello from realtime TTS. ", "This is the final chunk."],
+        text_end=True,
+    )
+    for chunk in session.receive_audio_chunks():
+        audio_chunks.append(chunk)
+
+print(f"Collected {sum(len(c) for c in audio_chunks)} bytes of audio")
+```
+
+Run the full example at [`examples/soniox_client/tts_realtime_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/tts_realtime_example.py) or async version at [`examples/async_soniox_client/tts_realtime_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/async_soniox_client/tts_realtime_example.py).
 
 ## Repository layout
 
 - `src/soniox/` – sdk code (clients, http namespaces, real-time/session helpers, types, utils).
-- `examples/soniox_client` & `examples/async_soniox_client` – runnable rest + real-time flows for sync and async.
+- `examples/soniox_client` & `examples/async_soniox_client` – runnable STT and TTS examples for sync and async clients.
 - `docs/` – markdown outputs (e.g., `docs/python-sdk.md`) that come from `pydoc-markdown`.
 - `assets/` – sample audio referenced by the examples.
-- `tests/` – pytest narratives that describe the public behavior.
 
 ## Development
 

soniox-2.3.1/README.md

@@ -0,0 +1,149 @@
+# Soniox Python SDK
+
+The SDK exposes two clients: `SonioxClient` (sync) and `AsyncSonioxClient` (async). Each client supports:
+- STT over REST (`client.stt`) and realtime WebSocket (`client.realtime.stt`)
+- TTS over REST (`client.tts`) and realtime WebSocket (`client.realtime.tts`)
+- auth, file uploads, model listing, webhooks, and typed request/response models
+
+## Install
+
+```bash
+pip install soniox
+# or if using uv
+uv add soniox
+export SONIOX_API_KEY=<your-key>
+```
+
+Get your API key from the [Soniox Console](https://console.soniox.com) and inject it once per shell session. Both clients read `SONIOX_API_KEY` by default, but you can override it per-client if needed.
+
+## Quick run (STT + TTS, REST + realtime)
+
+1. **REST STT transcription**: copy this snippet or run [`examples/soniox_client/api_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/api_example.py).
+
+```python
+from soniox import SonioxClient
+
+client = SonioxClient()
+transcription = client.stt.transcribe(
+    audio_url="https://soniox.com/media/examples/coffee_shop.mp3",
+    client_reference_id="docs-quick-start",
+)
+client.stt.wait(transcription.id, timeout_sec=60)
+print(client.stt.get_transcript(transcription.id).text[:200])
+```
+
+2. **REST TTS generation**: convert text to an audio file.
+
+```python
+from soniox import SonioxClient
+from soniox.utils import output_file_for_audio_format
+
+client = SonioxClient()
+output_file = output_file_for_audio_format("wav", "tts_sync_output")
+written = client.tts.generate_to_file(
+    output_file,
+    text="Hello from Soniox Python SDK Text-to-Speech.",
+    model="tts-rt-v1",
+    language="en",
+    voice="Adrian",
+    audio_format="wav",
+)
+print(f"Wrote {written} bytes to {output_file.resolve()}")
+client.close()
+```
+
+Run the full example at [`examples/soniox_client/tts_api_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/tts_api_example.py) or async version at [`examples/async_soniox_client/tts_api_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/async_soniox_client/tts_api_example.py).
+
+3. **Realtime STT streaming**: open `client.realtime.stt.connect`, call `session.send_byte_chunk` or `session.send_bytes`, then iterate `session.receive_events()` to render tokens:
+
+```python
+from soniox import SonioxClient
+from soniox.types import RealtimeSTTConfig, Token
+from soniox.utils import render_tokens, throttle_audio, start_audio_thread
+
+DEMO_FILE = "path_to_your_audio_file"
+
+client = SonioxClient()
+config = RealtimeSTTConfig(model="stt-rt-v4", audio_format="mp3")
+final_tokens: list[Token] = []
+non_final_tokens: list[Token] = []
+
+def realtime():
+    with client.realtime.stt.connect(config=config) as session:
+        start_audio_thread(session, throttle_audio(DEMO_FILE, delay_seconds=0.1))
+        for event in session.receive_events():
+            for token in event.tokens:
+                if token.is_final:
+                    final_tokens.append(token)
+                else:
+                    non_final_tokens.append(token)
+            print(render_tokens(final_tokens, non_final_tokens))
+            non_final_tokens.clear()
+
+realtime()
+```
+
+See [`examples/soniox_client/realtime_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/realtime_example.py) for the full flow.
+
+4. **Realtime TTS streaming**: send text chunks and read generated audio chunks from the session.
+
+```python
+from uuid import uuid4
+
+from soniox import SonioxClient
+from soniox.types import RealtimeTTSConfig
+
+client = SonioxClient()
+config = RealtimeTTSConfig(
+    stream_id=f"sync-{uuid4()}",
+    model="tts-rt-v1",
+    language="en",
+    voice="Adrian",
+    audio_format="wav",
+)
+
+audio_chunks: list[bytes] = []
+with client.realtime.tts.connect(config=config) as session:
+    session.keep_alive()
+    session.send_text_chunks(
+        ["Hello from realtime TTS. ", "This is the final chunk."],
+        text_end=True,
+    )
+    for chunk in session.receive_audio_chunks():
+        audio_chunks.append(chunk)
+
+print(f"Collected {sum(len(c) for c in audio_chunks)} bytes of audio")
+```
+
+Run the full example at [`examples/soniox_client/tts_realtime_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/tts_realtime_example.py) or async version at [`examples/async_soniox_client/tts_realtime_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/async_soniox_client/tts_realtime_example.py).
+
+## Repository layout
+
+- `src/soniox/` – sdk code (clients, http namespaces, real-time/session helpers, types, utils).
+- `examples/soniox_client` & `examples/async_soniox_client` – runnable STT and TTS examples for sync and async clients.
+- `docs/` – markdown outputs (e.g., `docs/python-sdk.md`) that come from `pydoc-markdown`.
+- `assets/` – sample audio referenced by the examples.
+
+## Development
+
+```bash
+uv install --with dev
+```
+
+This pulls in `ruff`, `pyright`, `pytest`, etc., so you can lint, type-check, test, and regenerate docs locally.
+
+## Docs
+
+```bash
+source .venv/bin/activate
+python3 scripts/generate_docs.py
+```
+
+Docs are output to `/docs` directory.
+
+## Resources
+
+- [soniox.com/docs](https://soniox.com/docs/stt/SDKs/python-SDK) – official Soniox documentation.
+- [GitHub repo](https://github.com/soniox/soniox-python) – source, examples, and scripts.
+- [PyPI](https://pypi.org/project/soniox/)
+- Support: `support@soniox.com`.

{soniox-2.2.0 → soniox-2.3.1}/docs/async_client.md

@@ -1,7 +1,7 @@
 ---
 title: "Async Client"
 description: "Soniox Python SDK - Async Client Reference"
-keywords: "AsyncSonioxClient, AsyncFilesAPI, AsyncSttAPI, AsyncModelsAPI, AsyncAuthAPI, AsyncSonioxWebhooksAPI"
+keywords: "AsyncSonioxClient, AsyncFilesAPI, AsyncSttAPI, AsyncTtsAPI, AsyncTtsModelsAPI, AsyncModelsAPI, AsyncAuthAPI, AsyncSonioxWebhooksAPI"
 ---
 
 ---
@@ -15,7 +15,7 @@ Asynchronous Soniox REST client exposing HTTP and realtime helpers.
 ### Constructor
 
 ```python
-AsyncSonioxClient(api_key: str | None = None, api_base_url: str | None = None, websocket_base_url: str | None = None, timeout_sec: float | None = None, webhook_secret: str | None = None, webhook_signature_header: str | None = None, **client_kwargs: Any)
+AsyncSonioxClient(api_key: str | None = None, api_base_url: str | None = None, websocket_base_url: str | None = None, tts_api_base_url: str | None = None, tts_websocket_base_url: str | None = None, timeout_sec: float | None = None, webhook_secret: str | None = None, webhook_signature_header: str | None = None, **client_kwargs: Any)
 ```
 
 **Parameters**
@@ -25,6 +25,8 @@ AsyncSonioxClient(api_key: str | None = None, api_base_url: str | None = None, w
 | `api_key` | `str \| None` | API key used for authentication. |
 | `api_base_url` | `str \| None` | Base URL for Soniox REST API requests. |
 | `websocket_base_url` | `str \| None` | Base URL for Soniox realtime WebSocket endpoint. |
+| `tts_api_base_url` | `str \| None` | Base URL for Soniox Text-to-Speech REST API requests. |
+| `tts_websocket_base_url` | `str \| None` | Base URL for Soniox Text-to-Speech realtime WebSocket endpoint. |
 | `timeout_sec` | `float \| None` | Maximum wait time in seconds. |
 | `webhook_secret` | `str \| None` | Webhook secret used for signature verification. |
 | `webhook_signature_header` | `str \| None` | Webhook signature header name. |
@@ -42,7 +44,9 @@ AsyncSonioxClient(api_key: str | None = None, api_base_url: str | None = None, w
 | ------ | ------ | ------ |
 | `files` | `AsyncFilesAPI` | List of uploaded files. |
 | `stt` | `AsyncSttAPI` | Speech-to-text API namespace. |
-| `models` | `AsyncModelsAPI` | List of all available models. |
+| `tts` | `AsyncTtsAPI` | Text-to-Speech API namespace |
+| `models` | `AsyncModelsAPI` | List of available Text-to-Speech models. |
+| `tts_models` | `AsyncTtsModelsAPI` | - |
 | `auth` | `AsyncAuthAPI` | Authentication API namespace. |
 | `webhooks` | `AsyncSonioxWebhooksAPI` | Webhook utilities API namespace. |
 | `realtime` | `AsyncRealtimeAPI` | Entrypoint for async realtime helpers on AsyncSonioxClient. |
@@ -929,6 +933,135 @@ Optionally deletes the transcription and uploaded file after completion.
 
 ---
 
+## AsyncTtsAPI
+
+<a id="asyncttsapi-constructor"></a>
+
+### Constructor
+
+```python
+AsyncTtsAPI(client: AsyncSonioxClient)
+```
+
+**Parameters**
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `client` | `AsyncSonioxClient` | Soniox client instance. |
+
+**Returns**
+
+`None`
+
+<a id="asyncttsapi-generate"></a>
+
+### generate()
+
+```python
+generate(*, text: str, voice: str, model: str = DEFAULT_MODEL, language: str = DEFAULT_LANGUAGE, audio_format: TtsAudioFormat = DEFAULT_AUDIO_FORMAT, sample_rate: TtsSampleRate | None = None, bitrate: TtsBitrate | None = None, config: CreateTtsConfig | None = None) -> bytes
+```
+
+Generate speech audio from text and return raw audio bytes.
+
+Performs a POST request to the TTS REST endpoint.
+
+**Parameters**
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `text` | `str` | Longer free-form background text, prior interaction history, reference documents, or meeting notes. |
+| `voice` | `str` | Voice identifier to generate speech audio with. |
+| `model` | `str` | Speech-to-text model to use. |
+| `language` | `str` | Language code for Text-to-Speech (e.g., "en"). |
+| `audio_format` | `TtsAudioFormat` | Audio format for realtime transcription. |
+| `sample_rate` | `TtsSampleRate \| None` | Audio sample rate in Hz. |
+| `bitrate` | `TtsBitrate \| None` | Output bitrate in bits-per-second for compressed formats. |
+| `config` | `CreateTtsConfig \| None` | Configuration options for this operation. |
+
+**Returns**
+
+`bytes`
+
+**Raises**
+
+- `SonioxAPIError` When the API returns an error.
+
+***
+
+<a id="asyncttsapi-generate_to_file"></a>
+
+### generate_to_file()
+
+```python
+generate_to_file(output: BinaryIO | Path | str, *, text: str, voice: str = DEFAULT_VOICE, model: str = DEFAULT_MODEL, language: str = DEFAULT_LANGUAGE, audio_format: TtsAudioFormat = DEFAULT_AUDIO_FORMAT, sample_rate: TtsSampleRate | None = None, bitrate: TtsBitrate | None = None, config: CreateTtsConfig | None = None) -> int
+```
+
+Generate speech audio from text and write the audio bytes to a file-like output.
+
+**Parameters**
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `output` | `BinaryIO \| Path \| str` | - |
+| `text` | `str` | Longer free-form background text, prior interaction history, reference documents, or meeting notes. |
+| `voice` | `str` | Voice identifier to generate speech audio with. |
+| `model` | `str` | Speech-to-text model to use. |
+| `language` | `str` | Language code for Text-to-Speech (e.g., "en"). |
+| `audio_format` | `TtsAudioFormat` | Audio format for realtime transcription. |
+| `sample_rate` | `TtsSampleRate \| None` | Audio sample rate in Hz. |
+| `bitrate` | `TtsBitrate \| None` | Output bitrate in bits-per-second for compressed formats. |
+| `config` | `CreateTtsConfig \| None` | Configuration options for this operation. |
+
+**Returns**
+
+`int`
+
+Number of bytes written.
+
+---
+
+## AsyncTtsModelsAPI
+
+<a id="asyncttsmodelsapi-constructor"></a>
+
+### Constructor
+
+```python
+AsyncTtsModelsAPI(client: AsyncSonioxClient)
+```
+
+**Parameters**
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `client` | `AsyncSonioxClient` | Soniox client instance. |
+
+**Returns**
+
+`None`
+
+<a id="asyncttsmodelsapi-list"></a>
+
+### list()
+
+```python
+list() -> GetTtsModelsResponse
+```
+
+List available Text-to-Speech models.
+
+Performs a GET request to ``/tts-models``.
+
+**Returns**
+
+`GetTtsModelsResponse`
+
+**Raises**
+
+- `SonioxAPIError` When the API returns an error.
+
+---
+
 ## AsyncModelsAPI
 
 <a id="asyncmodelsapi-constructor"></a>