speaker_helper.config module

Configuration for speaker-helper.

Module summary

speaker-helper reads a small, typed configuration describing where the backend reads, 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("backend: kokoro\nlanguage: fr\nvoice: ff_siwis")
>>> s.backend, s.voice
('kokoro', 'ff_siwis')

Author

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

class speaker_helper.config.Settings(backend='kokoro', engine='kokoro', voice='', voice_sample='', 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:

  • backend (str) – Which TTS backend to drive. "kokoro" (default) runs in this process and needs no server; "openvoice" and "chatterbox" clone a voice from a recording; "mock" is deterministic and serverless, for 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) – A label carried on results, for callers that record which model produced what. It does not select the backend; backend does.

  • voice (str) – Which built-in voice reads. Empty (default) means “read the text, detect the language, and pick the voice that speaks it” — which is not a convenience: the detected language is what the phonemiser works from, and French read as English is not French in an American accent, it is an American spelling the words out.

  • voice_sample (str) – Path to a reference recording, for the cloning backends. Kokoro refuses one rather than ignoring it.

  • voice_id (str) – Deprecated spelling of voice, kept because configuration files in the wild use it. voice wins when both are set.

  • language (str) – ISO-639-1 target language (e.g. "fr").

  • normalize (bool) – Loudness-normalise the output where the backend can.

  • mode (str) – "offline" or "streaming".

  • first_chunk_sentences (int) – Streaming only: sentences in the first emitted chunk (1 → lowest time-to-first-audio, which is the number a conversation feels).

  • mock (dict[str, Any])

  • clone (dict[str, Any])

Notes

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

backend: str = 'kokoro'
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: str = ''
voice_id: str = ''
voice_sample: str = ''