Utterance boundary API
These names are available directly from listenflow. The PCM helpers accept 16 kHz mono raw
PCM in signed 16-bit little-endian or little-endian float32 format. Every chunk must contain whole
samples. Voice thresholds use normalized full-scale amplitude and must be finite float values
between 0.0 and 1.0.
Voice detection and settings
has_voice(chunk, *, input_format, voice_threshold)
UtteranceBoundarySettings
dataclass
silence_threshold_s = 0.8
class-attribute
instance-attribute
voice_threshold = DEFAULT_VOICE_THRESHOLD
class-attribute
instance-attribute
preroll_s = 0.3
class-attribute
instance-attribute
__init__(silence_threshold_s=0.8, voice_threshold=DEFAULT_VOICE_THRESHOLD, preroll_s=0.3)
__post_init__()
Streaming observations
ProvisionalObservation
dataclass
text
instance-attribute
speaker = None
class-attribute
instance-attribute
source_offset_s = None
class-attribute
instance-attribute
__init__(text, speaker=None, source_offset_s=None)
FinalObservation
dataclass
text
instance-attribute
source_offset_s
instance-attribute
speaker = None
class-attribute
instance-attribute
__init__(text, source_offset_s, speaker=None)
UtteranceBoundarySession
dataclass
silence_threshold_s
instance-attribute
voice_threshold
instance-attribute
input_format = EngineInputFormat.PCM_S16LE
class-attribute
instance-attribute
utterance_id = 1
class-attribute
instance-attribute
input_offset_s = 0.0
class-attribute
instance-attribute
last_voice_offset_s = None
class-attribute
instance-attribute
pending_end_ts = None
class-attribute
instance-attribute
in_utterance = False
class-attribute
instance-attribute
emitted_start = False
class-attribute
instance-attribute
emitted_partial = False
class-attribute
instance-attribute
emitted_final = False
class-attribute
instance-attribute
input_finished = False
class-attribute
instance-attribute
last_partial_text = ''
class-attribute
instance-attribute
last_partial_ts_offset_s = None
class-attribute
instance-attribute
last_partial_speaker = None
class-attribute
instance-attribute
has_unfinalized_provisional
property
observe_pcm(chunk)
observe_provisional(observation, *, utterance_id=None)
observe_final(observation, *, utterance_id=None)
finish_input()
finalize_events(*, utterance_id=None)
maybe_end_event(*, utterance_id=None)
Utterance decoding
The decoding callback receives a closed utterance and returns provisional or final observations. Observation offsets use seconds from the start of input audio, including any preroll. The pipeline receives further PCM while decoding and emits events in utterance order.
Normal input completion drains received utterances. Input or decoder failure and early consumer closure cancel the active decode and wait for its cleanup before allowing reuse. Pending decodes and undelivered events are discarded on failure. The first input or decode exception is returned as the original object, even if cleanup fails later.
on_progress optionally receives a synchronous notification after processing a PCM chunk or
completing an utterance decode, including silence and recognition without text. In an engine module,
pass on_progress=self._mark_progress when constructing the pipeline and return its recognition
counters through _health_details(). With the callback, the parent owns the progress timestamp
and the pipeline's last_progress_monotonic_s stays None. A standalone pipeline without the
callback records its own last_progress_monotonic_s. Event delivery does not advance this value.