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_v4offline,eleven_v4_turbostreaming). The only backend that sends text off the machine, soautonever 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'
- speaker_helper.engine.AUTO = 'auto'
Value of
settings.backendmeaning “decide from the operating mode”.
- speaker_helper.engine.MODE_DEPENDENT_BACKENDS: frozenset[str] = frozenset({'auto', 'elevenlabs'})
autoroutes on it,elevenlabspicks 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:
objectA 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
languageandenginelabels and for themockknobs (rtf,chars_per_sec,sample_rate,amplitude,frequency_hz) read viaSettings.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.amplitudeabove 1.0 to deliberately synthesise a clipping signal for testing the anomaly detector.- 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:
name (str)
samples (list[VoiceSample])
language (str | None)
- Return type:
- async synthesize(text, *, language=None, voice=None, speed=1.0)[source]
Synthesise
textinto a deterministic sine-tone WAV.Honouring
speedis what makes this backend worth narrating with: a pace offasthas 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(soresult.rtfreproduces the configured RTF).- Return type:
- Raises:
ValueError – If
textis empty or whitespace-only.
- class speaker_helper.engine.TTSEngine(*args, **kwargs)[source]
Bases:
ProtocolThe 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_checkableletsisinstance(obj, TTSEngine)verify the method names are present (not their signatures) — handy in tests and factories.- async clone_voice(name, samples, *, language=None)[source]
Clone a voice from reference
samplesand return its id.Implementations should be idempotent on
name(reuse an existing clone rather than duplicating). A backend that cannot clone may raiseNotImplementedError.- Parameters:
name (str)
samples (list[VoiceSample])
language (str | None)
- Return type:
- async synthesize(text, *, language=None, voice=None, speed=1.0)[source]
Synthesise
textinto oneAudioResult.voiceandspeedarrived 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:
- speaker_helper.engine.available_backends()[source]
Return the sorted names of all registered backends.
- speaker_helper.engine.create_engine(settings)[source]
Instantiate the backend named by
settings.backend.- Parameters:
settings (Settings) – Configuration; its
backendfield selects the engine."auto"(the default) is resolved from the operating mode first — seeresolve_auto().- Returns:
A ready-to-use engine instance.
- Return type:
- Raises:
ValueError – If
settings.backendnames 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 whatevermodethe configuration was written for: withbackend: autoand the defaultmode: offlineit 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:
settingsitself when the mode is already"streaming"or the backend does not depend on it; otherwise a copy withmode="streaming".- Return type:
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 bycreate_engine().
- Return type:
None
- speaker_helper.engine.resolve_auto(settings)[source]
Return
settingswith 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 plainSpeaker()orspeaker-helper synthused 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: kokoroin a config file means kokoro, whatever the matrix says.