speaker_helper.engine module

Backend-agnostic text-to-speech engine interface and registry.

Module summary

speaker-helper’s value is a small, typed façade over a local TTS engine. The concrete engine is deliberately an implementation detail: the rest of the package — Speaker, the REST API, the CLI, the evaluation layer — talks only to the TTSEngine protocol defined here. Swapping or adding a backend is therefore a local change: write a class with four coroutines and register it.

Eight backends ship in-tree. None is “the default” on its own: backend="auto" resolves from the operating mode (offline → chatterbox, Turbo for English; streaming → kokoro — see resolve_auto()).

  • kokoro — in this process, no server, 54 built-in voices.

  • openvoice, chatterbox — cloning, from a reference recording.

  • kyutai — native French (and English) from Kyutai’s 1.6B model; voices picked from a published embedding bank rather than cloned.

  • audio8 — Edge0’s realism-tuned 0.6B cloner (MLX, Apple Silicon), always conditioned on a reference — the bundled female one by default.

  • qwen3tts — Qwen3-TTS 0.6B through the same MLX cloning contract; the closest clone measured here, at the edge of real time.

  • elevenlabs — the paid cloud cells (eleven_v4 offline, eleven_v4_turbo streaming). The only backend that sends text off the machine, so auto never picks it.

  • mock — MockEngine, a deterministic, dependency-light synthesiser that needs no server and no model. It makes the test suite and the evaluation layer runnable in CI, and it proves the abstraction: the same code paths drive any backend, narration included.

Another used to ship — a REST client for a desktop application on a fixed port. It was removed once the default ran in-process: an engine you have to install, launch and keep alive, to do what a 300 MB file does here, is not a second option but a second way to fail.

create_engine() dispatches on settings.backend. Third parties can add their own backend at runtime with register_backend().

Usage example

>>> from speaker_helper.config import Settings
>>> from speaker_helper.engine import create_engine
>>> eng = create_engine(Settings.from_mapping({"backend": "mock"}))
>>> type(eng).__name__
'MockEngine'

Author

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

speaker_helper.engine.AUTO = 'auto'

Value of settings.backend meaning “decide from the operating mode”.

speaker_helper.engine.MODE_DEPENDENT_BACKENDS: frozenset[str] = frozenset({'auto', 'elevenlabs'})

auto routes on it, elevenlabs picks its model from it. Every other backend is the same engine in both modes, so a streaming call can reuse it as is.

Type:

Backends whose engine depends on settings.mode

class speaker_helper.engine.MockEngine(settings)[source]

Bases: object

A deterministic, serverless TTS backend for tests and evaluation.

It produces a real (decodable) WAV whose duration is proportional to the input length at a fixed speaking rate, and reports a compute time derived from a configured real-time factor. No audio model runs and no network call is made, so behaviour is reproducible and fast — ideal for CI, for exercising the evaluation layer’s anomaly checks, and for proving that engine-agnostic code paths work against any backend.

Parameters:

settings (Settings) – Used for language and engine labels and for the mock knobs (rtf, chars_per_sec, sample_rate, amplitude, frequency_hz) read via Settings.mock.

Notes

The audio is a quiet sine tone (not silence) so evaluation’s “empty audio” and “clipping” checks see a realistic, non-degenerate signal. Set mock.amplitude above 1.0 to deliberately synthesise a clipping signal for testing the anomaly detector.

async aclose()[source]

No-op: the mock holds no resources.

Return type:

None

amplitude: float
chars_per_sec: float
async clone_voice(name, samples, *, language=None)[source]

Pretend to clone a voice; return a deterministic id (no audio model).

Validates that at least one sample is provided (matching the real engine’s contract) but performs no synthesis-model work, so cloning is testable without a server.

Parameters:
Return type:

str

frequency_hz: float
async health()[source]

Return a static healthy document identifying the mock backend.

Return type:

dict

async list_voices(engine=None)[source]

Return a small fixed set of fake voices for engine.

Parameters:

engine (str | None)

Return type:

VoiceList

rtf: float
sample_rate: int
async synthesize(text, *, language=None, voice=None, speed=1.0)[source]

Synthesise text into a deterministic sine-tone WAV.

Honouring speed is what makes this backend worth narrating with: a pace of fast has to shorten the audio, or the cues it produces are not the ones a real engine would produce and the timeline tests pass against a shape nothing ships.

Parameters:
  • text (str) – Text to “speak” (must be non-empty). Only its length drives the output duration; content is not spoken.

  • language (str or None) – Override the configured language label on the result.

  • voice (str or None) – Reported back on the result; nothing here varies with it.

  • speed (float) – Divides the duration, the way a faster reading would.

Returns:

A decodable WAV plus duration and a compute time equal to duration * rtf (so result.rtf reproduces the configured RTF).

Return type:

AudioResult

Raises:

ValueError – If text is empty or whitespace-only.

class speaker_helper.engine.TTSEngine(*args, **kwargs)[source]

Bases: Protocol

The minimal surface every speaker-helper backend must provide.

A backend is any object exposing these four coroutines. Everything else in the package is written against this protocol, never against a concrete engine, so the backend stays swappable.

Notes

@runtime_checkable lets isinstance(obj, TTSEngine) verify the method names are present (not their signatures) — handy in tests and factories.

async aclose()[source]

Release any held resources (HTTP clients, handles, …).

Return type:

None

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

Clone a voice from reference samples and return its id.

Implementations should be idempotent on name (reuse an existing clone rather than duplicating). A backend that cannot clone may raise NotImplementedError.

Parameters:
Return type:

str

async health()[source]

Return a backend health document (must include a status key).

Return type:

dict

async list_voices(engine=None)[source]

List preset voices for an engine (or the configured one).

Parameters:

engine (str | None)

Return type:

VoiceList

async synthesize(text, *, language=None, voice=None, speed=1.0)[source]

Synthesise text into one AudioResult.

voice and speed arrived with narration, where a document picks a voice once and varies the pace block by block. They are keyword-only and both have defaults, so a backend written against the original two-argument signature still satisfies this protocol — narrate() offers them and withdraws them when the backend does not declare them.

Parameters:
Return type:

AudioResult

speaker_helper.engine.available_backends()[source]

Return the sorted names of all registered backends.

Return type:

list[str]

speaker_helper.engine.create_engine(settings)[source]

Instantiate the backend named by settings.backend.

Parameters:

settings (Settings) – Configuration; its backend field selects the engine. "auto" (the default) is resolved from the operating mode first — see resolve_auto().

Returns:

A ready-to-use engine instance.

Return type:

TTSEngine

Raises:

ValueError – If settings.backend names no registered backend.

speaker_helper.engine.for_streaming(settings)[source]

The settings a streaming call should run with.

A streaming request (synth --stream, POST /synth/stream) is the streaming cell of the matrix whatever mode the configuration was written for: with backend: auto and the default mode: offline it would otherwise stream through chatterbox, two to five times slower than real time, and ElevenLabs would use its offline model.

Parameters:

settings (Settings) – The configured settings.

Returns:

settings itself when the mode is already "streaming" or the backend does not depend on it; otherwise a copy with mode="streaming".

Return type:

Settings

Examples

>>> for_streaming(Settings.from_mapping({"backend": "auto"})).mode
'streaming'
>>> s = Settings.from_mapping({"backend": "kokoro"})
>>> for_streaming(s) is s
True
speaker_helper.engine.register_backend(name, factory)[source]

Register (or override) a backend factory under name.

Parameters:
  • name (str) – Backend identifier used in settings.backend (case-insensitive).

  • factory (callable) – Settings -> TTSEngine. Called lazily by create_engine().

Return type:

None

speaker_helper.engine.resolve_auto(settings)[source]

Return settings with an "auto" backend/engine decided by mode.

The project’s operating matrix is {offline, streaming} × {local-free, paid-cloud}, and the owner has settled the two local-free cells: offline goes to chatterbox in every language, streaming stays on kokoro for now. That matrix already lives in speaker_helper.router, so this resolves through the router rather than hard-coding a second copy that could drift from it — the French ratification, the per-language priors and the printed justification all come along for free.

Before this existed, the router’s answer only reached callers who asked for it (route, Speaker.from_route()), while a plain Speaker() or speaker-helper synth used the configured backend — which defaulted to kokoro. “Offline French uses chatterbox” was therefore true of the router and false of the default path. This closes that gap.

An explicitly configured backend is never touched: backend: kokoro in a config file means kokoro, whatever the matrix says.

Parameters:

settings (Settings) – Configuration, possibly carrying backend="auto".

Returns:

The same object when nothing was "auto"; otherwise a copy with backend and engine resolved.

Return type:

Settings