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.")

Author

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

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 the base_url knob.

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: object

The ElevenLabs backend: REST synthesis, model chosen by the mode.

Parameters:

settings (Settings) –

mode picks the model (see MODEL_BY_MODE); voice names an ElevenLabs voice id. The elevenlabs mapping supplies the knobs:

  • api_key — fallback when ELEVENLABS_API_KEY is 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 defaults 0.5 / 0.75 / 0).

  • seed — integer for repeatable takes (default unset).

  • base_url — regional host (default DEFAULT_BASE_URL).

  • timeout_s — HTTP timeout (default 120).

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.

async aclose()[source]

Nothing is held open between calls.

Return type:

None

apply_lexicon(text, language)[source]

Splice lexicon entries the best way this model can read them.

Parameters:
  • text (str) – The text about to be sent.

  • language (str) – Bare language code (entries are language-keyed).

Returns:

/ipa/ for entries with IPA on a model that reads it inline, the respelling otherwise; text unchanged without a lexicon.

Return type:

str

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 voice or elevenlabs.voice_by_lang.

Parameters:
Return type:

str

async health()[source]

Whether a key is configured — without spending a request.

Return type:

dict

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.

Parameters:

engine (str | None)

Return type:

VoiceList

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

Synthesise text through the REST convert endpoint.

Parameters:
  • text (str) – What to say (must be non-empty).

  • language (str or None) – Sent as language_code and used for the lexicon.

  • voice (str or None) – An ElevenLabs voice id; empty picks the per-language default.

  • speed (float) – Clamped to the documented 0.7–1.2.

Raises:
  • ValueError – If text is empty or whitespace-only.

  • RuntimeError – Without an API key, or when the service refuses the call.

Return type:

AudioResult

speaker_helper.backends.elevenlabs.INLINE_IPA_MODELS: frozenset[str] = frozenset({'eleven_v4'})

Models documented as reading /IPA/ inline. eleven_v4_turbo is 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).

speaker_helper.backends.elevenlabs.SAMPLE_RATE_HZ: int = 24000

the suite’s layout rate, no resampling.

Type:

Requested as pcm_24000

speaker_helper.backends.elevenlabs.SPEED_RANGE: tuple[float, float] = (0.7, 1.2)

Documented range of voice_settings.speed.