speaker_helper.client module

Asynchronous client for the Voicebox text-to-speech REST engine.

Module summary

VoiceboxClient is the thin, well-typed layer speaker-helper puts between application code and the Voicebox HTTP API. It hides three awkward details of that API:

Profiles. Every synthesis needs a profile_id. This client creates a preset profile once (idempotently — reusing an existing one) from the engine’s preset voices, preferring a voice whose language matches the target.
Two synthesis paths. POST /generate/stream returns WAV bytes synchronously but refuses to run until the engine model is downloaded; the async POST /generate path does trigger the download. The client streams by default and transparently falls back to the async path (enqueue → poll the SSE status → fetch /audio/{id}) the first time, when the model is absent.
Voice discovery. GET /profiles/presets/{engine} is normalised into typed Voice objects.

httpx and soundfile are imported lazily so importing speaker-helper stays cheap for callers that only need its types.

Usage example

>>> import asyncio
>>> from speaker_helper.config import Settings
>>> from speaker_helper.client import VoiceboxClient
>>> async def demo() -> float:
...     async with VoiceboxClient(Settings.from_mapping({"engine": "kokoro"})) as c:
...         result = await c.synthesize("Bonjour le monde.")
...         return result.duration_s
>>> # asyncio.run(demo())  # requires a running Voicebox

Author

Warith HARCHAOUI — https://linkedin.com/in/warith-harchaoui

class speaker_helper.client.VoiceboxClient(settings)[source]

Bases: object

A typed async client over the Voicebox TTS REST API.

Parameters:: settings (Settings) – Connection and voice configuration. See speaker_helper.config.Settings.

Notes

The client owns an httpx.AsyncClient. Use it as an async context manager (async with) or call aclose() when done. A single client caches the resolved profile_id so repeated syntheses skip the profile bootstrap.

async aclose()[source]

Close the underlying HTTP client and release its connections.

Return type:: None

async clone_voice(name, samples, *, language=None)[source]

Clone a voice from reference samples and use it for synthesis.

Parameters:

name (str) – Profile name for the clone (idempotency key). A matching profile is reused rather than duplicated.
samples (list of VoiceSample) – Reference recordings. Any sample without a reference_text is transcribed with vocal-helper before upload.
language (str or None) – Language of the cloned voice (defaults to the configured language).

Returns:

The cloned profile id (also set as this client’s active profile).

Return type:

str

Raises:

VoiceboxError – On a Voicebox error.

async ensure_profile()[source]

Return a usable profile_id, creating a preset one idempotently.

Returns:: The profile id to pass to synthesis calls.
Return type:: str

Notes

Reuses an existing profile for the resolved preset voice rather than creating a duplicate (Voicebox rejects duplicate names), so a fresh client never fails on the second run. Safe under concurrency via an internal lock.

async health()[source]

Return the Voicebox /health payload.

Returns:: The server health document (backend variant, gpu availability, …).
Return type:: dict
Raises:: VoiceboxError – If the server is unreachable or returns a non-2xx status.

async list_voices(engine=None)[source]

List the preset voices for an engine.

Parameters:: engine (str or None) – Engine id; defaults to the configured engine.
Returns:: The engine and its preset voices (possibly empty).
Return type:: VoiceList

async synthesize(text, *, language=None)[source]

Synthesise text into a single AudioResult.

Parameters:

text (str) – The text to speak. Must be non-empty.
language (str or None) – Override the configured target language for this call.

Returns:

The synthesised WAV plus measured duration and compute time.

Return type:

AudioResult

Raises:

ValueError – If text is empty or whitespace-only.
VoiceboxError – On a Voicebox error or an undecodable response.

Notes

Uses POST /generate/stream (synchronous WAV bytes). The first call for a not-yet-downloaded engine model transparently falls back to the async /generate path, which triggers the download.

exception speaker_helper.client.VoiceboxError[source]

Bases: RuntimeError

Raised when Voicebox returns an error or an unexpected response.