Faster-whisper API
All four classes below are exported from listenflow.faster_whisper. The module
also exports __version__, the distribution version. It exports no standalone
public functions.
Engine
Supply an absolute OfflineModelDirectorySource and a positive cpu_threads
value. The defaults request model label small, language en, device cpu,
compute type int8, and beam size 1. The label does not locate or verify
weights. Configuration types and ranges and metadata language support are checked
at construction; upstream decides runtime compatibility.
The constructor also accepts max_new_tokens, repetition_penalty,
no_repeat_ngram_size, initial_prompt, word_timestamps, silence_mitigation,
boundary_settings, and input_format. Decoding limits with upstream defaults
are omitted from the faster-whisper call unless changed. Audio must be 16 kHz mono
PCM, with whole samples in the configured signed 16-bit little-endian or
little-endian float32 format.
prepare() loads the offline model and drains the full packaged synthetic utterance
(1.36 seconds) before publishing readiness. A successful preparation is reused; an unsuccessful attempt
leaves no published partial model or status. stream() requires preparation and
returns an asynchronous transcript iterator. Consume only one stream per instance
and close the iterator explicitly when stopping early. Cancellation and closure
wait for uninterruptible native transcription to finish before returning.
aclose() cancels active operations, waits for native work, and releases the model.
Closure is idempotent and permanent. async with engine prepares on entry and
closes on exit. Use an instance on one event loop.
capabilities.languages is the accepted metadata language-code set, and
auto_language indicates detection for multilingual vocabularies when
language=None. input_format is the configured PCM format. health() supplies
state, busy, last_progress_monotonic_s, lifetime PCM/event counters, current
and pending decoding, and session prompt evidence; preparation warm-up does not
advance public progress. Health is readable after closure. runtime_status()
raises EngineStateError until preparation succeeds, including after a failed
attempt, then returns an immutable readback of that load.
After closure, capabilities and input_format keep returning their values;
runtime_status() raises EngineClosedError once closure starts, including while
native work is still finishing.
Configuration and PCM failures use listenflow.ConfigurationError; state and
closure failures use EngineStateError and EngineClosedError. Upstream failures
use InferenceError, identifiable missing native/CUDA components use
EnvironmentUnavailableError, and a missing runtime uses ModuleNotInstalledError.
These core errors retain native and upstream exceptions as their cause.
FasterWhisperEngine
Bases: STTEngineBase
capabilities
property
input_format
property
__init__(*, model_source, cpu_threads, model='small', language='en', device='cpu', compute_type='int8', beam_size=1, max_new_tokens=None, repetition_penalty=1.0, no_repeat_ngram_size=0, initial_prompt=None, word_timestamps=False, silence_mitigation=FasterWhisperSilenceMitigation(), boundary_settings=UtteranceBoundarySettings(), input_format=EngineInputFormat.PCM_S16LE)
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.
runtime_status()
Return the prepared runtime snapshot, rejecting unprepared or closed engines.
__aenter__()
async
__aexit__(exc_type, exc_value, traceback)
async
Silence mitigation
This immutable configuration controls VAD and silence-related transcription
options. The same caller-selected values reach warm-up and utterance decoding.
Thresholds must be in the inclusive range 0.0 to 1.0, silence duration must be
a nonnegative integer, and an enabled hallucination-silence threshold must be
finite and positive. Boolean fields require boolean values.
The hallucination-silence threshold is disabled by default. faster-whisper uses it
only when the engine is constructed with word_timestamps=True; set both to skip
long silences before likely hallucinated segments.
FasterWhisperSilenceMitigation
dataclass
vad_filter = True
class-attribute
instance-attribute
vad_threshold = 0.65
class-attribute
instance-attribute
vad_min_silence_duration_ms = 500
class-attribute
instance-attribute
no_speech_threshold = 0.75
class-attribute
instance-attribute
condition_on_previous_text = False
class-attribute
instance-attribute
hallucination_silence_threshold_s = None
class-attribute
instance-attribute
Seconds of silence to skip before a likely hallucinated segment.
faster-whisper reads this threshold only when the engine's word_timestamps
is True; with word_timestamps=False it has no effect. None disables it.
__init__(vad_filter=True, vad_threshold=0.65, vad_min_silence_duration_ms=500, no_speech_threshold=0.75, condition_on_previous_text=False, hallucination_silence_threshold_s=None)
Runtime status
The immutable status records the configured model label and absolute directory, requested device, compute type and CPU threads, effective device, device indices and compute type, and faster-whisper and CTranslate2 versions. It is a fixed post-load snapshot and does not perform live health or compatibility checks.
FasterWhisperRuntimeStatus
dataclass
model_label
instance-attribute
model_directory_path
instance-attribute
requested_device
instance-attribute
effective_device
instance-attribute
device_index
instance-attribute
requested_compute_type
instance-attribute
effective_compute_type
instance-attribute
requested_cpu_threads
instance-attribute
faster_whisper_version
instance-attribute
ctranslate2_version
instance-attribute
cuda
instance-attribute
__init__(model_label, model_directory_path, requested_device, effective_device, device_index, requested_compute_type, effective_compute_type, requested_cpu_threads, faster_whisper_version, ctranslate2_version, cuda)
The optional CUDA status is present only when the loaded model's effective device
is CUDA. Its distribution versions are None when the corresponding installation
metadata is absent.