speaker_helper.backends.elevenlabs module
ElevenLabs: the paid cloud cells of the matrix, offline and streaming.
Module summary
The owner’s matrix has two cloud cells — paid, offline and paid, streaming — and ElevenLabs is the service picked for them. This backend covers both with one client, the operating mode choosing the model:
offline →
eleven_v4, “our most emotive, high quality speech synthesis model” (ElevenLabs’ models page, read 2026-11-04);streaming →
eleven_v4_turbo, the same family at ~100 ms median latency.
Both speak French. Audio is requested as pcm_24000 (signed 16-bit
little-endian), the rate every in-tree backend lays out at, so a narration can
mix engines with exact cue times and nothing is resampled.
This is the only backend that sends text off the machine, and it is never
picked by backend: auto: it has no entry in the router’s catalogue, so it
answers only when named (backend: elevenlabs) — a paid service must not be
reached by a default.
The pronunciation lexicon
eleven_v4 reads IPA inline “when wrapped in forward slashes” (ElevenLabs
best-practices page), which is the best tier this backend can offer: entries
with ipa are spliced as /ipa/, deterministically. Every other model —
and every entry without IPA — gets the respelling tier. The backend applies
both itself (LEXICON_TIER = "ipa" tells the Speaker not to respell first,
which would hide the original word from the IPA tier). ElevenLabs’
server-side pronunciation dictionaries are not used: their creation endpoint
could not be read when this was written, and an inline splice needs no
server state.
The streaming cell is served the way every other backend serves it —
stream() pipelines sentence chunks
through synthesize(). ElevenLabs’ WebSocket only pays off when text
arrives token by token, which no surface of this package accepts.
Configuration
The API key comes from ELEVENLABS_API_KEY (preferred: a key in a settings
file ends up in a repository sooner or later) or elevenlabs.api_key.
Usage example
>>> from speaker_helper import Speaker, Settings
>>> # spk = Speaker(Settings.from_mapping({"backend": "elevenlabs", "language": "fr"}))
>>> # await spk.say("Bonjour depuis le nuage.")
- speaker_helper.backends.elevenlabs.DEFAULT_BASE_URL: str = 'https://api.elevenlabs.io'
The REST host; regional hosts (
https://api.eu.residency.elevenlabs.io) go through thebase_urlknob.
- speaker_helper.backends.elevenlabs.DEFAULT_VOICE_ID: str = 'EXAVITQu4vr4xnSDxMaL'
“Sarah”, from ElevenLabs’ premade library, labelled female. Premade voices are multilingual, so one id serves every language until the owner fixes a voice per language (
voice_by_lang) — chosen by ear, which this default has not been.- Type:
Default voice
- class speaker_helper.backends.elevenlabs.ElevenLabsEngine(settings)[source]
Bases:
objectThe ElevenLabs backend: REST synthesis, model chosen by the mode.
- Parameters:
settings (Settings) –
modepicks the model (seeMODEL_BY_MODE);voicenames an ElevenLabs voice id. Theelevenlabsmapping supplies the knobs:api_key— fallback whenELEVENLABS_API_KEYis unset.model— pin a model id regardless of the mode.voice_by_lang—{"fr": "<voice id>", "en": …}, the female voice fixed per language.stability,similarity_boost,style— voice settings (service defaults0.5/0.75/0).seed— integer for repeatable takes (default unset).base_url— regional host (defaultDEFAULT_BASE_URL).timeout_s— HTTP timeout (default120).
- LEXICON_TIER: str = 'ipa'
This backend applies the lexicon itself (inline IPA where the model reads it, respelling elsewhere); the Speaker must not respell first.
- apply_lexicon(text, language)[source]
Splice lexicon entries the best way this model can read them.
- async clone_voice(name, samples, *, language=None)[source]
Refuse: cloning on ElevenLabs uploads a person’s voice to a third party.
That is a decision for whoever owns the recording, taken in their ElevenLabs account; once the voice exists there, its id goes in
voiceorelevenlabs.voice_by_lang.- Parameters:
name (str)
samples (list[VoiceSample])
language (str | None)
- Return type:
- async list_voices(engine=None)[source]
Female voices for the configured language, from the service.
Without a key there is nothing to ask, so the default is listed — it is what would speak.
- async synthesize(text, *, language=None, voice=None, speed=1.0)[source]
Synthesise
textthrough the REST convert endpoint.- Parameters:
- Raises:
ValueError – If
textis empty or whitespace-only.RuntimeError – Without an API key, or when the service refuses the call.
- Return type:
- speaker_helper.backends.elevenlabs.INLINE_IPA_MODELS: frozenset[str] = frozenset({'eleven_v4'})
Models documented as reading
/IPA/inline.eleven_v4_turbois left out until the docs say it does: a slash-wrapped IPA string read aloud literally would be worse than a respelling.
- speaker_helper.backends.elevenlabs.MODEL_BY_MODE: dict[str, str] = {'offline': 'eleven_v4', 'streaming': 'eleven_v4_turbo'}
Model per operating mode (ElevenLabs models page, read 2026-11-04).