speaker_helper.config module

Configuration for speaker-helper.

Module summary

speaker-helper reads a small, typed configuration describing where the Voicebox engine lives and which voice / language / mode to use. Values come from (in increasing precedence) dataclass defaults, an optional settings.yaml, and SPEAKER_HELPER_* environment variables. Strings spelled ${VAR} inside the YAML are expanded from the environment at load time so hosts and secrets never sit in a committed file.

See settings.yaml.example and speaker_config.json.example at the repository root for a documented template.

Usage example

>>> from speaker_helper.config import Settings
>>> s = Settings.from_yaml_text("voicebox: {port: 17600}\nlanguage: fr")
>>> s.voicebox.port
17600
>>> s.base_url
'http://127.0.0.1:17600'

Author

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

class speaker_helper.config.Settings(voicebox=<factory>, backend='voicebox', engine='kokoro', voice_id='', language='fr', normalize=True, mode='offline', first_chunk_sentences=1, mock=<factory>, clone=<factory>)[source]

Bases: object

Top-level speaker-helper configuration.

Parameters:

voicebox (VoiceboxConfig) – Connection details for the Voicebox engine.
backend (str) – Which TTS backend to drive: "voicebox" (the real engine, default) or "mock" (deterministic, serverless — used by tests and the evaluation layer). The backend is an implementation detail; the rest of the package talks only to the TTSEngine protocol. See speaker_helper.engine.available_backends().
engine (str) – Backend-specific engine/model id. For Voicebox, kokoro is fast enough for real-time on CPU.
voice_id (str) – Preset voice id. Empty (default) means “auto-pick a voice whose language matches language”.
language (str) – ISO-639-1 target language (e.g. "fr").
normalize (bool) – Ask Voicebox to loudness-normalise the output.
mode (str) – "offline" or "streaming".
first_chunk_sentences (int) – Streaming only: sentences in the first emitted chunk (1 → lowest TTFA).
mock (dict[str, Any])
clone (dict[str, Any])

Notes

Precedence, lowest to highest: dataclass defaults → settings.yaml → SPEAKER_HELPER_* environment variables.

backend: str = 'voicebox'

property base_url: str: Return the Voicebox base URL, e.g. http://127.0.0.1:17600.

clone: dict[str, Any]

engine: str = 'kokoro'

first_chunk_sentences: int = 1

classmethod from_mapping(mapping)[source]

Build settings from a plain mapping (unknown keys ignored).

Parameters:: mapping (dict or None) – Nested mapping mirroring the dataclass fields.
Returns:: The populated settings, with environment overrides applied.
Return type:: Settings

classmethod from_yaml_text(text)[source]

Build settings from a YAML document string.

Parameters:: text (str) – YAML source.
Returns:: The populated settings.
Return type:: Settings

language: str = 'fr'

classmethod load(path=None)[source]

Load settings from a YAML file if present, else defaults + env.

Parameters:: path (str or Path or None) – Path to a settings.yaml. When None, ./settings.yaml is used if it exists; otherwise dataclass defaults apply. Environment overrides are always applied last.
Returns:: The populated settings.
Return type:: Settings

mock: dict[str, Any]

mode: str = 'offline'

normalize: bool = True

voice_id: str = ''

voicebox: VoiceboxConfig

class speaker_helper.config.VoiceboxConfig(host='127.0.0.1', port=17493, timeout_s=300.0, max_retries=2, retry_backoff_s=0.5)[source]

Bases: object

Where the Voicebox REST service lives.

Parameters:

host (str) – Hostname or IP of the Voicebox server. Default 127.0.0.1.
port (int) – TCP port. Voicebox’s native default is 17493; the bundled docker-compose maps the container to 17600 on the host.
timeout_s (float) – Per-request timeout in seconds. The first synthesis of a new engine pays a model download, so keep this generous.
max_retries (int) – How many times to retry a request that fails on a transient error (network/transport error or a 5xx from the engine). 0 disables retries. Client errors (4xx) are never retried.
retry_backoff_s (float) – Base delay for exponential backoff between retries: attempt k waits retry_backoff_s * 2**(k-1) seconds.

host: str = '127.0.0.1'

max_retries: int = 2

port: int = 17493

retry_backoff_s: float = 0.5

timeout_s: float = 300.0