soniox 2.3.2__tar.gz → 2.4.0__tar.gz

soniox-2.4.0/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run *)",
+      "Bash(just test *)",
+      "Bash(/home/miha/workspace/soniox_python_sdk/.venv/bin/python *)",
+      "Bash(git apply *)",
+      "Bash(git add *)",
+      "Bash(sed -n '110,140p' tests/unit/test_client.py)",
+      "Bash(sed -n '85,120p' tests/unit/test_async_client.py)",
+      "Bash(/tmp/soniox-v240-test/.venv/bin/python -u test_schema_sync.py)",
+      "Bash(awk '/^class Transcription\\\\b/,/^class [A-Z]/' src/soniox/types/api.py)"
+    ]
+  }
+}

soniox-2.4.0/.gitignore

@@ -0,0 +1,15 @@
+dist
+build
+__pycache__
+generated-docs
+
+# Virtualenv
+.venv
+
+# Test / coverage artifacts
+.coverage
+.pytest_cache
+htmlcov
+
+# Local audio scratch
+*.wav

{soniox-2.3.2 → soniox-2.4.0}/CHANGELOG.md

@@ -21,12 +21,12 @@ The format is inspired by Keep a Changelog and this project follows Semantic Ver
 
 Use the following categories when adding entries:
 
-- **Added** — new features or capabilities.
-- **Changed** — updates to existing functionality.
-- **Deprecated** — features that will be removed soon.
-- **Removed** — features removed in this version.
-- **Fixed** — bug fixes.
-- **Security** — vulnerability fixes.
+- **Added** - new features or capabilities.
+- **Changed** - updates to existing functionality.
+- **Deprecated** - features that will be removed soon.
+- **Removed** - features removed in this version.
+- **Fixed** - bug fixes.
+- **Security** - vulnerability fixes.
 
 ---
 
@@ -53,9 +53,9 @@ This project follows Semantic Versioning:
 
 Examples:
 
-- `1.0.0` — stable API
-- `1.1.0` — new features added
-- `1.1.1` — bug fixes only
+- `1.0.0` - stable API
+- `1.1.0` - new features added
+- `1.1.1` - bug fixes only
 
 ---
 
@@ -77,6 +77,31 @@ Examples:
 
 ---
 
+## [2.4.0] - 13 may 2026
+
+### Added
+
+- `client.files.count()` and `client.stt.count()` endpoints (and async variants) returning the total count of files and transcriptions.
+- `client.usage_logs.list()` and `list_all()` (and async variants) for retrieving per-request usage logs over a time window.
+- `client.concurrency_limits.get()` (and async variant) returning current and configured concurrency limits for realtime STT and TTS, scoped to project and organization.
+- `TtsVoice.description` and `TtsVoice.gender` (`"male" | "female" | "neutral"`) fields, exposing richer voice metadata from the server. Enables programmatic voice filtering.
+- `RealtimeSTTAudioFormat`, `RealtimeSTTHeaderFormat`, `RealtimeSTTRawFormat` literal types covering the 30 audio formats accepted by realtime STT.
+- `py.typed` marker (PEP 561): downstream type-checkers now consume the SDK's inline type annotations.
+- `StructuredContext.general` and `StructuredContext.translation_terms` now accept a plain dict in addition to the typed item lists.
+- `finalize: bool = True` keyword-only parameter on realtime STT `pause()` (sync and async). When `False`, pause without emitting a finalize.
+- `TtsModel.languages` field listing the languages supported by the model. Defaults to an empty list for backward compatibility with direct construction.
+- `Language` type exported from `soniox.types` (previously only reachable via `soniox.types.api`).
+- `ApiError.more_info` field - optional URL pointing to documentation for resolving an error.
+- `Model.supports_max_endpoint_delay` flag indicating whether a model supports the `max_endpoint_delay_ms` option.
+- Internal test suite (pytest + respx + polyfactory) covering REST, realtime websocket, schema drift, and sync/async parity. Not shipped to users; runnable via `just test`.
+
+### Changed
+
+- `RealtimeSTTConfig.audio_format` is now typed as a Literal union instead of bare `str`. Passing an unrecognized value raises at validation time instead of failing on the wire.
+- Raw realtime STT audio formats (`pcm_*`, `mulaw`, `alaw`) now require `sample_rate` and `num_channels` on `RealtimeSTTConfig`. Previously these were silently accepted client-side and rejected by the server.
+
+---
+
 ## [2.3.2] - 4 may 2026
 
 ### Added

{soniox-2.3.2 → soniox-2.4.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: soniox
-Version: 2.3.2
+Version: 2.4.0
 Summary: The official Python SDK for the Soniox API (STT, REST)
-Project-URL: Homepage, https://sonoix.com
+Project-URL: Homepage, https://soniox.com
 Project-URL: Documentation, https://soniox.com/docs
 Project-URL: Repository, https://github.com/soniox/soniox-python
 Author-email: Soniox <support@soniox.com>
@@ -31,13 +31,20 @@ Requires-Dist: pydantic>2
 Requires-Dist: websockets>11.0
 Provides-Extra: dev
 Requires-Dist: griffe>=1.15.0; extra == 'dev'
-Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: polyfactory>=2.15.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.409; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.1; extra == 'dev'
 Requires-Dist: ruff>=0.0.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # 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
@@ -53,20 +60,23 @@ 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.
 
+> **Avoid Python 3.13.6** - it has a regression in `ssl` that hangs realtime STT/TTS (CPython issue [#137583](https://github.com/python/cpython/issues/137583)). Use any other 3.10-3.13.x.
+
 ## 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).
+1. **REST STT transcription**: transcribe a local file end-to-end in one call. Full example: [`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",
+transcript = client.stt.transcribe_and_wait_with_tokens(
+    file="path/to/audio.mp3",                # local file
+    # audio_url="https://example.com/audio.mp3",  # or remote URL
+    delete_after=True,                        # auto-cleanup file + transcription
 )
-client.stt.wait(transcription.id, timeout_sec=60)
-print(client.stt.get_transcript(transcription.id).text[:200])
+print(transcript.text)
+client.close()
 ```
 
 2. **REST TTS generation**: convert text to an audio file.
@@ -118,17 +128,19 @@ def realtime():
             non_final_tokens.clear()
 
 realtime()
+client.close()
 ```
 
 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.
+4. **Realtime TTS streaming**: send text chunks and write audio to a file as it arrives.
 
 ```python
 from uuid import uuid4
 
 from soniox import SonioxClient
 from soniox.types import RealtimeTTSConfig
+from soniox.utils import output_file_for_audio_format
 
 client = SonioxClient()
 config = RealtimeTTSConfig(
@@ -139,17 +151,18 @@ config = RealtimeTTSConfig(
     audio_format="wav",
 )
 
-audio_chunks: list[bytes] = []
-with client.realtime.tts.connect(config=config) as session:
-    session.keep_alive()
+output_file = output_file_for_audio_format("wav", "tts_realtime_output")
+bytes_written = 0
+with client.realtime.tts.connect(config=config) as session, output_file.open("wb") as f:
     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)
+        f.write(chunk)
+        bytes_written += len(chunk)
 
-print(f"Collected {sum(len(c) for c in audio_chunks)} bytes of audio")
+print(f"Wrote {bytes_written} bytes to {output_file.resolve()}")
 ```
 
 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).

{soniox-2.3.2 → soniox-2.4.0}/README.md

@@ -1,6 +1,7 @@
 # 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
@@ -16,20 +17,23 @@ 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.
 
+> **Avoid Python 3.13.6** - it has a regression in `ssl` that hangs realtime STT/TTS (CPython issue [#137583](https://github.com/python/cpython/issues/137583)). Use any other 3.10-3.13.x.
+
 ## 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).
+1. **REST STT transcription**: transcribe a local file end-to-end in one call. Full example: [`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",
+transcript = client.stt.transcribe_and_wait_with_tokens(
+    file="path/to/audio.mp3",                # local file
+    # audio_url="https://example.com/audio.mp3",  # or remote URL
+    delete_after=True,                        # auto-cleanup file + transcription
 )
-client.stt.wait(transcription.id, timeout_sec=60)
-print(client.stt.get_transcript(transcription.id).text[:200])
+print(transcript.text)
+client.close()
 ```
 
 2. **REST TTS generation**: convert text to an audio file.
@@ -81,17 +85,19 @@ def realtime():
             non_final_tokens.clear()
 
 realtime()
+client.close()
 ```
 
 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.
+4. **Realtime TTS streaming**: send text chunks and write audio to a file as it arrives.
 
 ```python
 from uuid import uuid4
 
 from soniox import SonioxClient
 from soniox.types import RealtimeTTSConfig
+from soniox.utils import output_file_for_audio_format
 
 client = SonioxClient()
 config = RealtimeTTSConfig(
@@ -102,17 +108,18 @@ config = RealtimeTTSConfig(
     audio_format="wav",
 )
 
-audio_chunks: list[bytes] = []
-with client.realtime.tts.connect(config=config) as session:
-    session.keep_alive()
+output_file = output_file_for_audio_format("wav", "tts_realtime_output")
+bytes_written = 0
+with client.realtime.tts.connect(config=config) as session, output_file.open("wb") as f:
     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)
+        f.write(chunk)
+        bytes_written += len(chunk)
 
-print(f"Collected {sum(len(c) for c in audio_chunks)} bytes of audio")
+print(f"Wrote {bytes_written} bytes to {output_file.resolve()}")
 ```
 
 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).

{soniox-2.3.2 → soniox-2.4.0}/docs/async_client.md

@@ -47,6 +47,8 @@ AsyncSonioxClient(api_key: str | None = None, api_base_url: str | None = None, w
 | `tts` | `AsyncTtsAPI` | Text-to-Speech API namespace |
 | `models` | `AsyncModelsAPI` | List of available Text-to-Speech models. |
 | `tts_models` | `AsyncTtsModelsAPI` | - |
+| `usage_logs` | `AsyncUsageLogsAPI` | Per-request usage log entries ordered by end_time. |
+| `concurrency_limits` | `AsyncConcurrencyLimitsAPI` | - |
 | `auth` | `AsyncAuthAPI` | Authentication API namespace. |
 | `webhooks` | `AsyncSonioxWebhooksAPI` | Webhook utilities API namespace. |
 | `realtime` | `AsyncRealtimeAPI` | Entrypoint for async realtime helpers on AsyncSonioxClient. |
@@ -143,6 +145,28 @@ Performs a GET request to ``/files`` with optional pagination.
 
 ***
 
+<a id="asyncfilesapi-count"></a>
+
+### count()
+
+```python
+count() -> GetFilesCountResponse
+```
+
+Return a breakdown of uploaded file counts.
+
+Performs a GET request to ``/files/count``.
+
+**Returns**
+
+`GetFilesCountResponse`
+
+**Raises**
+
+- `SonioxAPIError` When the API returns an error.
+
+***
+
 <a id="asyncfilesapi-list_all"></a>
 
 ### list_all()
@@ -390,6 +414,28 @@ Performs a GET request to ``/transcriptions`` with optional pagination.
 
 ***
 
+<a id="asyncsttapi-count"></a>
+
+### count()
+
+```python
+count() -> GetTranscriptionsCountResponse
+```
+
+Return a breakdown of transcription counts.
+
+Performs a GET request to ``/transcriptions/count``.
+
+**Returns**
+
+`GetTranscriptionsCountResponse`
+
+**Raises**
+
+- `SonioxAPIError` When the API returns an error.
+
+***
+
 <a id="asyncsttapi-list_all"></a>
 
 ### list_all()

{soniox-2.3.2 → soniox-2.4.0}/docs/realtime_client.md

@@ -184,10 +184,12 @@ is established when entering the context manager.
 close() -> None
 ```
 
-Gracefully close the realtime session.
+Close the realtime session and release the WebSocket.
 
-Sends a final empty message to signal end-of-stream, then closes
-the WebSocket connection. Calling this method multiple times is safe.
+Signals end-of-audio to the server and clears the underlying
+connection. Subsequent calls are no-ops.
+
+Called automatically when exiting the context manager.
 
 **Returns**
 
@@ -234,17 +236,18 @@ send_bytes(chunks: bytes | Iterator[bytes], *, finish: bool = True) -> None
 
 Send audio data to the realtime stream.
 
-This method accepts either a single bytes object or an iterator
-yielding audio chunks. When an iterator is provided, a FINISH
-control message is sent automatically after all chunks have
-been transmitted.
+Accepts either a single bytes object or an iterator yielding byte
+chunks (e.g. from `throttle_audio`). If `finish=True` (the default),
+an end-of-audio signal is sent after the last chunk; pass
+`finish=False` when you intend to send more audio later in the
+same session.
 
 **Parameters**
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `chunks` | `bytes \| Iterator[bytes]` | Audio data as raw bytes or an iterator of byte chunks. |
-| `finish` | `bool` | Whether to send a finish signal after streaming completes. |
+| `chunks` | `bytes \| Iterator[bytes]` | Raw bytes or an iterator of byte chunks. |
+| `finish` | `bool` | If True (default), signal end-of-audio after the last chunk. |
 
 **Returns**
 
@@ -289,7 +292,11 @@ end-of-audio or requesting finalization.
 finish() -> None
 ```
 
-Signal that no more audio will be sent for this session.
+Signal end-of-audio.
+
+The server finalizes any pending tokens and closes the
+connection. Continue iterating `receive_events()` to consume
+the remaining tokens.
 
 **Returns**
 
@@ -441,7 +448,7 @@ Receive realtime events and dispatch them to a handler callback.
 ### pause()
 
 ```python
-pause() -> None
+pause(*, finalize: bool = True) -> None
 ```
 
 Pause the session, suppressing outgoing audio and starting a
@@ -454,6 +461,12 @@ timing out the session.
 
 Calling `pause` on an already-paused session is a no-op.
 
+**Parameters**
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `finalize` | `bool` | If True (default), call `finalize()` before pausing. |
+
 **Returns**
 
 `None`
@@ -1246,10 +1259,12 @@ is established when entering the async context manager.
 close() -> None
 ```
 
-Gracefully close the realtime session.
+Close the realtime session and release the WebSocket.
 
-Sends a final empty message to signal end-of-stream, then closes
-the WebSocket connection. Calling this method multiple times is safe.
+Signals end-of-audio to the server and clears the underlying
+connection. Subsequent calls are no-ops.
+
+Called automatically when exiting the async context manager.
 
 **Returns**
 
@@ -1296,17 +1311,18 @@ send_bytes(chunks: bytes | AsyncIterator[bytes], *, finish: bool = True) -> None
 
 Send audio data to the realtime stream.
 
-This method accepts either a single bytes object or an iterator
-yielding audio chunks. When an iterator is provided, a
-FINISH control message is sent automatically after all chunks
-have been transmitted.
+Accepts either a single bytes object or an async iterator yielding
+byte chunks (e.g. from `throttle_audio_async`). If `finish=True`
+(the default), an end-of-audio signal is sent after the last chunk;
+pass `finish=False` when you intend to send more audio later in the
+same session.
 
 **Parameters**
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `chunks` | `bytes \| AsyncIterator[bytes]` | Audio data as raw bytes or an iterator of byte chunks. |
-| `finish` | `bool` | Whether to send a finish signal after streaming completes. |
+| `chunks` | `bytes \| AsyncIterator[bytes]` | Raw bytes or an async iterator of byte chunks. |
+| `finish` | `bool` | If True (default), signal end-of-audio after the last chunk. |
 
 **Returns**
 
@@ -1351,7 +1367,11 @@ end-of-audio or requesting finalization.
 finish() -> None
 ```
 
-Signal that no more audio will be sent for this session.
+Signal end-of-audio.
+
+The server finalizes any pending tokens and closes the
+connection. Continue iterating `receive_events()` to consume
+the remaining tokens.
 
 **Returns**
 
@@ -1503,7 +1523,7 @@ Receive realtime events and dispatch them to a handler callback.
 ### pause()
 
 ```python
-pause() -> None
+pause(*, finalize: bool = True) -> None
 ```
 
 Pause the session, suppressing outgoing audio and starting a
@@ -1516,6 +1536,12 @@ timing out the session.
 
 Calling `pause` on an already-paused session is a no-op.
 
+**Parameters**
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `finalize` | `bool` | If True (default), call `finalize()` before pausing. |
+
 **Returns**
 
 `None`