Engines and health API
These names are available directly from listenflow. An engine module implements the native
hooks; the core owns preparation, operation ordering, cancellation, closure, and common health.
Use one engine instance on one event loop. The application interprets capabilities and health
and chooses readiness, recovery, and timeout policy.
Engine contract
prepare() loads and trials the model, retries after failure, and does nothing after success.
Recognition starts on the first read; a concurrent stream raises EngineStateError. Model
operations wait in arrival order. aclose() cancels active and waiting operations, waits for native
cleanup, and releases resources once. A closed engine cannot be reused. async with prepares on
entry and closes on exit, including exceptional exit.
Close a stream explicitly with its aclose() or contextlib.aclosing when stopping early.
Consumer cancellation remains asyncio.CancelledError; engine closure produces EngineClosedError.
Capabilities and health can be read while model operations run and after closure.
To collect final transcripts from complete PCM audio, use the core function
transcribe(engine, pcm). The caller prepares and closes the engine.
Subclass constructors call super().__init__(). _load() and _release() are asynchronous;
_recognize() returns an asynchronous iterator. A failed load cleans up its own partial resources.
Hooks map native errors into the error hierarchy and chain their causes. Cancelled hooks wait for
native work to actually finish. _health_details() returns recognition fields only, without
state, busy, or last_progress_monotonic_s. _mark_progress() records PCM processing and
utterance decode completion. Pass it as on_progress when constructing an UtteranceDecodePipeline
to give the parent sole ownership of the timestamp.
STTEngineBase
Bases: ABC
Shared preparation, recognition, closure, and health behavior.
Use one engine instance on one event loop. Modules implement the hooks, map native errors into STTError subclasses, and finish native work before returning from a cancelled hook. Failed loads clean up their own resources.
capabilities
abstractmethod
property
Return the module's immutable, static capability declaration.
prepare()
async
Load and trial the model once; retry after an unsuccessful load.
stream(pcm_chunks)
Start recognition on the first read and keep its slot through cleanup.
The returned iterator supports aclose(). Close it explicitly when stopping before the end, or use contextlib.aclosing around the iterator.
aclose()
async
Cancel operations, wait for their cleanup, and release resources once.
health()
Return held values immediately, including after closure.
_load()
abstractmethod
async
Load resources and run a trial inference; clean up a failed load.
_release()
abstractmethod
async
Return resources created by a successful load.
_recognize(pcm_chunks)
abstractmethod
Recognize PCM; cancellation and iterator closure must finish native work.
_health_details()
Return recognition fields only, without the three shared health fields.
_mark_progress()
Record a processed PCM chunk or completed utterance decode.
Errors
Engine errors inherit from STTError and the meaning's standard Python error. EngineClosedError
is an EngineStateError. Native errors are chained as causes. Release failure is an InferenceError
reported only by the first aclose(). Standalone helpers keep their standard validation errors.
errors
Errors shared by recognition engines and their callers.
STTError
Bases: Exception
Base class for recognition engine errors.
ConfigurationError
Bases: STTError, ValueError
An engine setting or input value is invalid.
EngineStateError
Bases: STTError, RuntimeError
The engine cannot accept an operation in its current state.
EngineClosedError
Bases: EngineStateError
The engine is closed or has cancelled an operation while closing.
InferenceError
Bases: STTError, RuntimeError
An engine operation failed at runtime.
EnvironmentUnavailableError
Bases: STTError, RuntimeError
The environment lacks a runtime component or device the engine needs.
ModuleNotInstalledError
Bases: STTError, ImportError
The requested engine module is not installed.
Capabilities
languages is an immutable set of accepted language codes. Empty means the engine has no language
argument and makes no language declaration. auto_language states whether None requests language
detection. The declaration also keeps the recognition transport, input format, partial mode,
finalization modes, timestamp detail, and diarization fields.
EngineCapabilities
dataclass
transport
instance-attribute
input_format
instance-attribute
partial_mode
instance-attribute
finalization
instance-attribute
timestamp_detail
instance-attribute
diarization
instance-attribute
languages
instance-attribute
auto_language
instance-attribute
__init__(transport, input_format, partial_mode, finalization, timestamp_detail, diarization, languages, auto_language)
__post_init__()
EngineTransport
Bases: StrEnum
IN_PROCESS = 'in_process'
class-attribute
instance-attribute
WEBSOCKET = 'websocket'
class-attribute
instance-attribute
GRPC = 'grpc'
class-attribute
instance-attribute
HTTP_UTTERANCE = 'http_utterance'
class-attribute
instance-attribute
EngineInputFormat
Bases: StrEnum
PCM_S16LE = 'pcm_s16le'
class-attribute
instance-attribute
PCM_F32 = 'pcm_f32'
class-attribute
instance-attribute
BASE64_PCM16 = 'base64_pcm16'
class-attribute
instance-attribute
WAV_PCM_S16LE = 'wav_pcm_s16le'
class-attribute
instance-attribute
PartialMode
Bases: StrEnum
REPLACE = 'replace'
class-attribute
instance-attribute
APPEND = 'append'
class-attribute
instance-attribute
COMMIT_ONLY = 'commit_only'
class-attribute
instance-attribute
NONE = 'none'
class-attribute
instance-attribute
FinalizationMode
Bases: StrEnum
ENGINE_SEGMENT = 'engine_segment'
class-attribute
instance-attribute
ENGINE_ENDPOINT = 'engine_endpoint'
class-attribute
instance-attribute
CLIENT_FLUSH = 'client_flush'
class-attribute
instance-attribute
LOCAL_VAD = 'local_vad'
class-attribute
instance-attribute
TimestampDetail
Bases: StrEnum
NONE = 'none'
class-attribute
instance-attribute
SEGMENT = 'segment'
class-attribute
instance-attribute
WORD = 'word'
class-attribute
instance-attribute
TOKEN = 'token'
class-attribute
instance-attribute
SAMPLE_OFFSET = 'sample_offset'
class-attribute
instance-attribute
DiarizationMode
Bases: StrEnum
NONE = 'none'
class-attribute
instance-attribute
SEGMENT_LABEL = 'segment_label'
class-attribute
instance-attribute
WORD_LABEL = 'word_label'
class-attribute
instance-attribute
MUTABLE_SPANS = 'mutable_spans'
class-attribute
instance-attribute
Health
state stays UNPREPARED while loading and after failure, becomes READY after success, and is
CLOSED once closing starts. busy describes a running model operation, including stream cleanup;
waiting calls alone do not make it true. last_progress_monotonic_s is a time.monotonic() timestamp
or None before progress. PCM processing and utterance decode completion update it, including
silence and recognition without text. Consumer event reads do not update it.
Recognition fields are processed_pcm_chunks, emitted_events, bias_application,
decoding_utterance_id, and pending_decode_utterances. Health reads held values without I/O,
inference, or waiting for the model operation lock.
EngineState
Bases: StrEnum
The engine's preparation and closure state.