Engines and health API
These names are available directly from speechflow and from speechflow.core.
The core owns preparation, operation ordering, cancellation, closure, and common
health. Engine modules implement model loading, synthesis, and resource release.
Use one engine instance on one event loop throughout its lifetime.
Engine contract
prepare() loads and trials the model once after success. A failed preparation
leaves the engine unprepared and allows a later call to retry. The caller chooses
the timeout. async with prepares the engine on entry and closes it on exit.
get(text, model=None, voice=None) collects the complete output into one
AudioData. stream(text, model=None, voice=None) yields AudioData chunks.
Engine-specific options are additional keyword arguments. Model operations on
one engine run one at a time in arrival order. Synthesis requires preparation.
Close a partially consumed stream explicitly, for example with
contextlib.aclosing, so cleanup finishes before reusing the engine.
aclose() cancels pending model operations, waits for work and cleanup to finish,
and releases resources. Repeated closing is safe. A closed instance cannot be
reused. Caller cancellation also waits for the underlying work to finish; the
core does not promise how quickly it stops. Engine closure reports cancelled
operations with EngineClosedError; caller cancellation remains
asyncio.CancelledError. See the error API.
Subclass constructors call super().__init__(). Implement _prepare() to load
resources and run trial inference, _synthesize() to yield audio, and
_release() to return resources. Failed loading cleans up its own partial
resources. Native hooks wait for underlying work to stop before finishing
cancellation cleanup. Each engine module is responsible for producing audio
that meets the AudioData contract.
TTSEngineBase
Bases: ABC
Own preparation, FIFO synthesis, cancellation, and resource lifetime.
Use one instance on one event loop. Modules implement _prepare (load
and trial inference), _synthesize (incremental native synthesis), and
_release (return resources), plus their static capabilities and
immediate voice-list reads. A module whose capabilities declare
voice_listing provides a synchronous list_voices() returning
list[dict[str, str]], one {"name": ..., "kind": ...} per voice.
Native hooks must not finish cancellation
cleanup until their underlying work has actually stopped. Failed loading
cleans its own partial resources; only successful loading is released here.
capabilities
abstractmethod
property
Return the module's immutable static declaration without doing work.
prepare()
async
Load and trial the model once; callers own any timeout.
A prepared engine returns immediately without waiting for synthesis. Concurrent loading requests queue behind the current load. Failures leave the engine unprepared and a later request retries loading.
get(text, model=None, voice=None, **kwargs)
async
Queue synthesis and return all samples after successful completion.
stream(text, model=None, voice=None, **kwargs)
async
Yield output incrementally, holding the model until exhausted or closed.
Close a partially read iterator explicitly (for example with
contextlib.aclosing) so native cleanup finishes before reuse.
aclose()
async
Cancel pending model work, wait for its real end, and release once.
health()
Read local state immediately, including while closing or synthesizing.
_prepare()
abstractmethod
async
Load resources and run trial inference, cleaning failed partial loads.
If cancellation cannot stop loading, wait for its real end. Returning normally records successful loading even when the caller was cancelled.
_synthesize(text, model=None, voice=None, **kwargs)
abstractmethod
Yield native output; finish cleanup only after native inference ends.
A hook may catch cancellation, wait for inference to finish, and yield its final chunk. The parent discards that chunk and closes the source without requesting more output, waiting for the hook's cleanup.
_release()
abstractmethod
async
Return successfully prepared resources, after native work has ended.
Capabilities and voices
EngineCapabilities is an immutable declaration with languages,
auto_language, streaming, voice_listing, voice_cloning, and sample_rate.
When sample_rate is None, the output rate is unknown until the model is loaded.
Use the actual rate carried by each returned AudioData.
A module with voice_listing=True provides a synchronous list_voices() returning
list[dict[str, str]]. Each element has the shape
{"name": <voice name>, "kind": <voice kind>}. A module with
voice_listing=False does not provide this operation. The core base class does
not define it.
EngineCapabilities
dataclass
Static capabilities declared by an engine module.
sample_rate is None when the output rate is unknown until the model
is loaded; each returned AudioData then carries the actual rate.
languages
instance-attribute
auto_language
instance-attribute
streaming
instance-attribute
voice_listing
instance-attribute
voice_cloning
instance-attribute
sample_rate
instance-attribute
__init__(languages, auto_language, streaming, voice_listing, voice_cloning, sample_rate)
Health
Read engine.capabilities and engine.health() synchronously without waiting for
model work. HealthSnapshot carries state (EngineState.UNPREPARED,
EngineState.READY, or EngineState.CLOSED), busy, and
last_progress_monotonic_s. The state values are "unprepared", "ready", and
"closed". These reads remain available after closing.
EngineState
Bases: StrEnum
Preparation and lifetime state of an engine.
UNPREPARED = 'unprepared'
class-attribute
instance-attribute
READY = 'ready'
class-attribute
instance-attribute
CLOSED = 'closed'
class-attribute
instance-attribute
HealthSnapshot
dataclass
An immediate snapshot of the engine's local state.