API reference

Types

espeakng_runtime.Mode

alias of Literal[‘auto’, ‘native’, ‘cli’]

The Mode type constrains backend selection. Use 'auto' to prefer native with CLI fallback, 'native' to require the ctypes backend, or 'cli' to force the subprocess backend.

Runtime

class espeakng_runtime.EspeakRuntime(*, mode: Literal['auto', 'native', 'cli'] = 'auto', executable: str | None = None, library: str | None = None, data: str | None = None, timeout: float | None = None, prefer_exact_clauses: bool = False)[source]

Bases: object

Resolve and own one eSpeak backend.

Native calls are serialized process-wide because eSpeak’s public API uses global state, including the currently selected voice.

property info: RuntimeInfo

property native_probes: tuple[LibraryProbe, ...]

Probes from native library selection during construction.

Returns an empty tuple for CLI mode. Does not perform additional discovery when read.

resolve_voice(voice: str, *, allow_mbrola: bool = False) → Voice[source]

Resolve a caller voice request to a concrete eSpeak voice.

phonemize(text: str, *, voice: str, separator: str | None = None, use_tie: bool = False, tie_char: str = '͡') → str[source]

phonemize_many(texts: Sequence[str], *, voice: str, separator: str | None = None, use_tie: bool = False, tie_char: str = '͡') → list[str][source]

clauses(text: str, *, voice: str, exact: bool = False) → list[Clause][source]

list_voices(filter_name: str | None = None) → list[Voice][source]

close() → None[source]

EspeakRuntime.resolve_voice(voice, allow_mbrola=False) returns the concrete Voice selected from the active eSpeak inventory. Language-style requests such as en-gb are resolved consistently for native and CLI backends. Normal requests exclude MBROLA entries unless allow_mbrola=True; explicit mb/… and mb-… requests are accepted.

RuntimeInfo.version_tuple contains the first numeric version sequence from RuntimeInfo.version, or () when no version is reported.

EspeakRuntime.native_probes returns the LibraryProbe records from native library selection during construction. For mode=”cli”, this is an empty tuple. Use runtime.info for the selected backend details and runtime.native_probes for what was considered during native selection.

espeakng_runtime.inspect_espeak(*, executable: str | None = None, library: str | None = None, data: str | None = None, require_exact_clauses: bool = False) → EspeakInspection[source]

Inspect eSpeak candidates without initializing the native library.

Data models

class espeakng_runtime.RuntimeInfo(requested_mode: Literal['auto', 'native', 'cli'], implementation: Literal['native', 'cli'], executable: str | None = None, library: str | None = None, data: str | None = None, source: str | None = None, version: str | None = None, exact_clause_api: bool = False, phoneme_output_api: Literal['cli', 'native-trace', 'native-translation'] | None = None, phoneme_parity: Literal['exact', 'best-effort'] | None = None, parity: Literal['exact', 'best-effort'] = 'best-effort', fallback_reason: str | None = None, fallback_code: Literal['native-unavailable', 'native-load-error', 'exact-clause-api-unavailable', 'native-init-failed'] | None = None)[source]

Bases: object

Resolved backend and capability information.

requested_mode: Literal['auto', 'native', 'cli']

implementation: Literal['native', 'cli']

executable: str | None

library: str | None

data: str | None

source: str | None

version: str | None

exact_clause_api: bool

phoneme_output_api: Literal['cli', 'native-trace', 'native-translation'] | None

phoneme_parity: Literal['exact', 'best-effort'] | None

parity: Literal['exact', 'best-effort']

fallback_reason: str | None

fallback_code: Literal['native-unavailable', 'native-load-error', 'exact-clause-api-unavailable', 'native-init-failed'] | None

property version_tuple: tuple[int, ...]

Return the numeric components of the reported version.

class espeakng_runtime.Clause(phonemes: str, terminator: str | None = None, terminator_code: int | None = None, sentence_end: bool = False)[source]

Bases: object

A phonemized clause plus its source terminator.

phonemes: str

terminator: str | None

terminator_code: int | None

sentence_end: bool

class espeakng_runtime.EspeakInspection(executable: str | None, cli_available: bool, require_exact_clauses: bool, selected_library: str | None, selected_source: str | None, selected_data: str | None, candidates: tuple[LibraryProbe, ...] = ())[source]

Bases: object

Non-initializing eSpeak capability and candidate inspection.

executable: str | None

cli_available: bool

require_exact_clauses: bool

selected_library: str | None

selected_source: str | None

selected_data: str | None

candidates: tuple[LibraryProbe, ...]

property native_available: bool

property exact_native_available: bool

property trace_native_available: bool

True when the selected native library exposes the phoneme trace API.

class espeakng_runtime.LibraryCandidate(library: 'str', source: 'str', data: 'str | None' = None, explicit: 'bool' = False)[source]

Bases: object

library: str

source: str

data: str | None

explicit: bool

class espeakng_runtime.LibraryProbe(library: 'str', source: 'str', data: 'str | None', loadable: 'bool', exact_clause_api: 'bool', phoneme_trace_api: 'bool' = False, error: 'str | None' = None, missing_symbols: 'tuple[str, ...]' = ())[source]

Bases: object

library: str

source: str

data: str | None

loadable: bool

exact_clause_api: bool

phoneme_trace_api: bool

error: str | None

missing_symbols: tuple[str, ...]

class espeakng_runtime.Voice(name: str, language: str, identifier: str, gender: int = 0, age: int = 0)[source]

Bases: object

An eSpeak voice entry.

name: str

language: str

identifier: str

gender: int

age: int

Errors

Public exceptions for espeakng-runtime.

exception espeakng_runtime.errors.EspeakError[source]

Bases: RuntimeError

Base class for runtime errors.

exception espeakng_runtime.errors.EspeakUnavailableError[source]

Bases: EspeakError

Raised when no requested eSpeak backend can be initialized.

exception espeakng_runtime.errors.EspeakConflictError[source]

Bases: EspeakError

Raised when incompatible native eSpeak configurations share a process.

exception espeakng_runtime.errors.PhonemizationError[source]

Bases: EspeakError

Raised when eSpeak fails while phonemizing text.

exception espeakng_runtime.errors.VoiceNotFoundError[source]

Bases: PhonemizationError

Raised when eSpeak cannot select a requested voice.

exception espeakng_runtime.errors.CapabilityError[source]

Bases: EspeakError

Raised when the active backend lacks a requested capability.