Expand description
§native-whisperx
Reusable workflow library for composing moritzbrantner-* transcription,
alignment, diarization, and transcript crates into a WhisperX-style pipeline.
This crate owns workflow configuration and output writing. The reusable audio,
text, model-runtime, and speaker primitives remain in rust-packages.
§Release Role
native-whisperx is the library crate for Workflow Composition APIs. It is
published before native-whisperx-cli. After that manual release order, Cargo
users install the CLI package with:
cargo install native-whisperx-cliThe installed terminal command is native-whisperx.
§Workflow Surface
The crate composes native transcription, default wav2vec2 alignment, optional speaker diarization, optional segment-level post-ASR translation, and output writing. The user-facing parity target is the Python WhisperX CLI. Delegated features remain delegated where the repository has not yet replaced them with a Rust-Native Parity path.
Default json output is WhisperX JSON. Use native-json through the CLI when
you need the Rust transcript contract shape.
Installing the CLI package does not make transcription resources available. Model bundles, cache entries, CUDA, Python WhisperX compatibility resources, and gated Hugging Face assets are resolved by the invoked workflow. Delegated Feature paths remain delegated until separate Rust-Native Parity work replaces them.
§Feature Flags
| Feature | Purpose |
|---|---|
native | Native Candle Whisper and wav2vec2 alignment composition. Enabled by default. |
translation | Helsinki-NLP OPUS-MT/Marian post-ASR segment translation and the curated planning/runtime surface. Enabled by default. |
cuda | CUDA-backed Candle execution for hosts with a local CUDA toolchain. |
media-decode | FFmpeg-backed finite non-WAV media/container decode through the audio I/O crate. Enabled by default. |
diarization | Heuristic speaker diarization composition. |
onnx-diarization | Explicit ONNX speaker embedding diarization path. |
pyannote-diarization | Native pyannote community diarization bundle path. Enabled by default for Automatic Workflow Selection, with runtime resources resolved lazily. |
silero-vad | Explicit Silero ONNX VAD path. |
pyannote-vad | Native pyannote ONNX VAD path. Enabled by default for Automatic Workflow Selection, with runtime resources resolved lazily. |
whisperx-compat | External Python WhisperX command compatibility and parity checks. |
Default library and CLI packaging includes translation plus the pyannote VAD
and pyannote diarization code paths required by automatic native --diarize.
Enabling the translation code does not start translation or resolve a model:
TranslationConfig::default() remains disabled, and resources are accessed
only when a configured workflow uses them. Default builds do not bundle models
or eagerly access Hugging Face credentials, ONNX Runtime dynamic-library
configuration, CUDA, Python WhisperX, or parity resources.
Builds using --no-default-features remain supported and translation-free.
Minimal embedding applications can explicitly enable only translation or the
other feature rows they need.
§Translation Planning and Immutable Results
CuratedLanguage contains English (en), German (de), French (fr),
Spanish (es), Italian (it), Portuguese (pt), Dutch (nl), and Polish
(pl). TranslationPlan::new and TranslationPlan::from_language_codes
choose a deterministic plan for every distinct ordered pair. A validated model
pair produces TranslationPlanProvenance::Direct; otherwise the plan records
two ordered legs through English as
TranslationPlanProvenance::PivotTranslation.
translate_transcription borrows an existing
TranscriptionPipelineResponse and returns a separate
TranslatedTranscriptionResult. The source response is never mutated, so its
text, detected language, segment boundaries, word and character timings,
diagnostics, and metadata remain available even when translation fails. The
translated result keeps segment timing and ordered model provenance separately;
source-language word and character alignments are not copied onto target text.
Use translate_transcription_with_control for progress and cooperative
cancellation at translation-leg and segment boundaries.
TranslationConfig is a library-owned type, independent from CLI argument
types. model_bundle selects an explicit local bundle. model_dir selects an
application-owned model/cache root, and model_cache_only is a hard
no-download control: missing assets fail model resolution. CLI flags map into
this type, but embedding applications configure it directly.
§Finite Media Inputs
Default builds include finite media decode support. WAV files continue to use the native WAV reader path. Non-WAV finite media files route through the FFmpeg-backed media decode path when the required runtime tools are installed.
The guaranteed finite input set is wav, mp3, m4a, aac, flac, ogg,
opus, mp4, mov, mkv, and webm. Other FFmpeg-decodable files may work
on a best-effort basis, but they are not part of the guaranteed support set.
Video files are transcribed from the selected/default audio track only; video
frames are not analyzed.
Builds using --no-default-features do not implicitly include finite non-WAV
media decode. Enable media-decode explicitly for minimal builds that still
need FFmpeg-backed media/container input support.
§Finite Progress and Cancellation
run_with_observer and run_many_with_observer emit the ordered
Transcription Progress Stream while preserving their existing non-cancellable
return types. Embedding applications that need cooperative cancellation use
run_with_control or run_many_with_control with a cloneable
CancellationHandle; another thread may call cancel(), and Workflow
Composition stops at the next safe phase boundary. Cancellation is a typed
outcome and does not emit a generic failure. A cancelled Multi-Input
Transcription Run retains completed reports and identifies inputs that were not
finished.
TranscriptionProgressEvent is now #[non_exhaustive] because model
resolution/download and direct or Pivot Translation leg facts extend the
stream. Existing consumers that exhaustively matched the enum must add a
wildcard arm. Existing run, run_with_observer, run_many, and
run_many_with_observer calls remain available and use an uncancelled control
internally.
§Live Progress and Cancellation
LiveTranscriptionProgressObserver receives operational session, Near-Live
Window, model resolution/download/load/reuse, completion, failure, and
cancellation facts. It is intentionally separate from LiveTranscriptEvent:
progress is telemetry, while Live Transcript Events remain the JSONL transcript
output contract.
Pass the same cloneable CancellationHandle to
LivePcmIngestionSession::ingest_reader_with_control to cancel before the next
Near-Live Window. Cancellation retains already stable final events, discards
unstable partial text, emits LiveTranscriptionProgressEvent::Cancelled, and
ends the transcript stream with LiveSessionEndReason::Cancelled. Existing
ingest_reader, ingest_reader_with_event_sink, and
ingest_reader_with_observer entry points remain available and use an
uncancelled handle internally.
§Exhaustive Enum Migration
Version 0.1.14 adds LiveSessionEndReason::Cancelled; existing exhaustive
matches over LiveSessionEndReason must add that arm. The new
TranscriptionProgressEvent and LiveTranscriptionProgressEvent contracts are
#[non_exhaustive]; downstream matches must include a wildcard arm so future
progress facts remain source compatible. Prefer an explicit Cancelled arm
before the wildcard when cancellation changes application state.
§Documentation
The canonical public API documentation target is https://docs.rs/native-whisperx. Repository release and model-resource setup details are in https://github.com/moritzbrantner/native-whisperx.
Structs§
- Alignment
Config - AsrConfig
- Automatic
Workflow Selection - Automatic
Workflow Selection Decision - Cancellation
Handle - Cloneable cooperative cancellation shared by finite and live workflows.
- Diarization
Config - Expected
Output Comparison - Expected
Output File - External
Whisperx Config - Finite
Cancellation - Details about the safe finite-workflow boundary where cancellation won.
- Live
AsrSegment Candidate - Live
Final Transcript Segment - Live
Partial Segment - Live
Partial Transcript - Live
PcmIngestion Report - Live
PcmIngestion Session - Live
PcmWindow - Live
Session Ended - Live
Session Started - Live
Transcript Error - Live
Window - Live
Window Planner - Live
Window Processing Error - Live
Window State - Live
Window Transcript Observation - Live
Windowing Config - Native
Whisperx Config - Native
Whisperx Report - Native
Workflow Selection Report - Noop
Live Transcription Progress Observer - Noop
Transcription Progress Observer - Output
Config - Output
File - Parity
Comparison - Parity
Comparison Config - Parity
Config - Parity
Fixture Case - Parity
Fixture Case Report - Parity
Fixture Suite - Parity
Fixture Suite Report - Parity
Multi Input Fixture Case - Parity
Preflight Case Report - Parity
Preflight Report - Parity
Report - Parity
Tolerance - Resolved
Speaker Directory - Selected
Diarization Model Report - Selected
VadReport - Speaker
Correction Range - Speaker
Correction Report - Speaker
Correction Request - Speaker
Directory Selection - Speaker
Directory State - Speaker
Library State - Speaker
Library Validation - Speaker
Profile Edit - Speaker
Profile State - Speaker
Profile Summary - Speaker
Trace - Speaker
Trace Error - Speaker
Trace File - Speaker
Trace Rebuild Report - Speaker
Trace Rebuild Stats - Speaker
Trace Span - Speaker
Trace Speaker - Speaker
Trace State - Subtitle
Config - Transcript
Segment Contract - Transcription
Contract - Transcription
Pipeline Request - Request for an audio/video-to-text transcription pipeline.
- Transcription
Pipeline Response - Response from a transcription pipeline.
- Translated
Transcription Result - A translated transcript kept separate from its source pipeline response.
- Translation
Config - Library-owned controls for post-ASR translation model resolution.
- Translation
Leg - One ordered OPUS-MT model invocation in a translation plan.
- Translation
Model Error - A typed failure reported by a
SegmentTranslationProvider. - Translation
Plan - A deterministic direct or Pivot Translation plan.
- Unfinished
Transcription - Input not completed by a cancelled Multi-Input Transcription Run.
- VadConfig
- Whisperx
Decode Config
Enums§
- Alignment
Interpolation Method - Timestamp interpolation behavior for missing alignment spans.
- AsrProvider
- Assignment
Policy - Automatic
Workflow Selection Resource - Config
Selection - Curated
Language - A language supported by the curated native translation registry.
- Device
Preference - Expected
Transcript Target - Finite
Transcription Outcome - Typed result of a cancellable single-input finite workflow.
- Input
Source - Live
Session EndReason - Live
Transcript Event - Live
Transcription Progress Event - One ordered progress observation from a Live Feed Transcription session.
- Live
Windowing Error - Model
Resource Source - Multi
Input Transcription Outcome - Typed result of a cancellable Multi-Input Transcription Run.
- Native
Whisperx Error - Output
Comparison Mode - Output
Format - Resolved
Speaker Directory Scope - Segment
Resolution - Speaker
Directory Scope - Speaker
Directory State Scope - Speaker
Library Validation Status - Speaker
Trace Speaker Kind - Speaker
Trace State Status - Transcription
Progress Event - One ordered observation in the finite Transcription Progress Stream.
- Transcription
Progress Task - Transcription
Task - Translated
Transcription Outcome - Typed result of translating an immutable transcription with cooperative control.
- Translation
Error - A typed failure while executing an already validated translation plan.
- Translation
Plan Error - Validation failures returned before any translation model is resolved.
- Translation
Plan Provenance - Whether a plan uses one direct model or composes two legs through English.
- VadMethod
Constants§
- GLOBAL_
SPEAKER_ DIRECTORY_ APP - GLOBAL_
SPEAKER_ DIRECTORY_ NAME - LIVE_
PCM_ SAMPLE_ RATE - LOCAL_
SPEAKER_ DIRECTORY - SPEAKER_
LIBRARY_ FILE - SPEAKER_
TRACE_ FILE
Traits§
- Live
PcmWindow Processor - Live
Transcription Progress Observer - Segment
Translation Provider - A boundary that executes one planned model leg for one transcript segment.
- Transcription
Progress Observer
Functions§
- build_
transcription_ request - compare_
with_ whisperx - correct_
speaker - delete_
speaker_ profile - global_
speaker_ directory - import_
whisperx_ json - list_
speaker_ profiles - live_
transcript_ events_ to_ jsonl - local_
speaker_ directory - read_
speaker_ directory_ state - rebuild_
speaker_ trace - reject_
draft_ speaker_ profile_ creation - resolve_
automatic_ workflow_ selection - resolve_
speaker_ directory - run
- run_
live_ asr_ window - run_
live_ asr_ window_ with_ observer - Runs one bounded native ASR Near-Live Window with operational progress.
- run_
many - run_
many_ reusing_ native_ provider - run_
many_ with_ control - Runs a Multi-Input Transcription Run with progress and cooperative control.
- run_
many_ with_ observer - run_
parity_ fixture_ suite - run_
parity_ preflight - run_
with_ control - Runs one finite Workflow Composition with progress and cooperative control.
- run_
with_ observer - speaker_
library_ path - speaker_
trace_ path - translate_
transcription - Executes a plan without taking ownership of or mutating the source result.
- translate_
transcription_ with_ control - Executes direct or Pivot Translation with ordered leg progress and cancellation.
- update_
speaker_ profile - validate_
speaker_ library - validate_
speaker_ library_ file - write_
outputs