espeakng-runtime

A small Python runtime adapter for eSpeak NG phonemization.

The package deliberately does not implement G2P policy for Kokoro, Piper, or any other model. It centralizes the shared eSpeak plumbing:

• executable, shared-library, and data discovery
• optional espeakng-loader integration
• native ctypes execution with process-wide locking
• CLI fallback
• voice enumeration
• IPA phonemization and batching
• exact native clause/terminator output when the loaded library exposes espeak_TextToPhonemesWithTerminator
• explicit runtime diagnostics/capabilities

Layout

This project intentionally uses a flat package layout (no src/ directory):

espeakng_runtime/
tests/
pyproject.toml

Versioning

The version is dynamic and comes from Git tags through setuptools-scm. For source archives without Git metadata, the MVP falls back to 0.1.dev0 so an unpacked zip remains installable.

git tag v0.1.0
python -m build

Install

Use a system eSpeak/eSpeak NG installation:

pip install espeakng-runtime

Or install the optional binary/data loader:

pip install "espeakng-runtime[bundled]"

Quick start

from espeakng_runtime import EspeakRuntime

with EspeakRuntime(mode="auto") as espeak:
    print(espeak.info)
    print(espeak.phonemize("Hello world", voice="en-us"))
    print(espeak.phonemize("Hello world", voice="en-us", separator="_"))
    print(espeak.clauses("Hello, world!", voice="en-us"))

mode is "auto", "native", or "cli". auto prefers a working native library and falls back to the command-line executable.

Voice arguments are caller-facing requests, not necessarily native identifiers. The runtime enumerates the active inventory and resolves language requests such as en-gb to the concrete identifier accepted by the installed eSpeak version. Resolution is cached per runtime instance, and ordinary language requests never select MBROLA voices implicitly. Use an explicit mb/... or mb-... request, or resolve_voice(..., allow_mbrola=True), when MBROLA selection is intended.

The voice argument is a public eSpeak voice/language selector. Native mode first attempts an explicit voice-name lookup and, when that fails and the native API supports it, retries the selector as a language property. This allows common locale selectors such as de-de, en-gb, and fr-fr to behave consistently with the CLI backend. RuntimeInfo.version_tuple exposes the numeric components of the reported eSpeak version, for example (1, 48, 15). Runtime cleanup is deterministic with close() or a context manager. Closing releases the Python runtime ownership; because eSpeak native state is process-global and older releases may be unsafe to terminate/reinitialize repeatedly, the initialized library remains resident for the Python process lifetime. Subsequent compatible runtimes reuse it, while conflicting library or data paths are rejected. Abandoned runtimes release their Python ownership during garbage-collection finalization. For Piper-style exact clause handling, request an exact-capable runtime:

from espeakng_runtime import EspeakRuntime

with EspeakRuntime(mode="auto", prefer_exact_clauses=True) as espeak:
    clauses = espeak.clauses("Hello, world!", voice="en-us", exact=True)

In auto mode, prefer_exact_clauses=True chooses an exact-capable native library when possible and otherwise falls back to CLI best-effort clauses. Calling clauses(..., exact=True) on a non-exact backend raises CapabilityError rather than silently degrading.

Inspect capabilities without initializing eSpeak:

from espeakng_runtime import inspect_espeak

inspection = inspect_espeak(require_exact_clauses=True)
print(inspection.native_available, inspection.cli_available)
for probe in inspection.candidates:
    print(probe.library, probe.loadable, probe.missing_symbols)

Inspection is non-initializing and does not alter process-global native state. In auto mode, a native initialization failure falls back to the CLI and is reported by RuntimeInfo.fallback_code and RuntimeInfo.fallback_reason.

Configuration

Explicit constructor arguments take precedence over environment variables:

• ESPEAKNG_RUNTIME_EXECUTABLE
• ESPEAKNG_RUNTIME_LIBRARY
• ESPEAKNG_RUNTIME_DATA

The library intentionally does not read KokoroG2P/PiperG2P-specific variables; those projects can map their legacy configuration into constructor arguments during migration.

MVP scope

The package returns raw eSpeak output. Model-specific transforms stay in their consumer projects. In particular this MVP does not contain Kokoro phoneme mapping, Piper NFD/phone composition, vowel-cluster merging, lexicons, or G2P routing.