Skip to content

vox-speech API Reference (generated)

Crate: vox-speech · Version: 0.6.0 · Target: Library (lib.rs)

Vox speech-to-text (Oratio) — transcript refinement, routing and Sherpa-ONNX STT; Candle Whisper lives in vox-plugin-speech

Oratio — Vox speech-to-text and transcript refinement.

STT runs through Sherpa-ONNX in-process (stt-sherpa) or Candle Whisper in the oratio plugin (vox-plugin-speech), which hosts register through [backend_dispatch::register_whisper_transcriber]. Audio file decoding needs the audio-decode feature; without it only .txt / .md passthrough is available.

FeatureDefault / Enables
audio-decodedep:symphonia, dep:rubato
clouddep:vox-populi, dep:tokio, dep:vox-http-client, dep:async-trait, dep:reqwest
compiler-rerankdep:vox-compiler
defaultcompiler-rerank
servedep:axum, axum/multipart, dep:tokio
stt-sherpadep:sherpa-onnx, dep:hf-hub, audio-decode
DependencyKind
vox-compilerNormal
vox-configNormal
vox-http-clientNormal
vox-populiNormal
vox-secretsNormal
ModuleDescription
acoustic_preprocess—
ast_mapper—
contextual_bias—
backend_dispatch—
backends—
eval—
eval_srt—
failure_taxonomy—
refine—
routing—
session—
speaker_profile—
speech_intent—
speech_lexicon—
speech_normalize—
speech_policy—
streaming_partialEnv-tunable stabilization thresholds for future streaming decoders; offline transcribe_path ignores this.
subtitle—
tieringPolicy helpers (escalation hint, cache keys) for hosts — not required for file-based STT.
trace—
traits—
transcript_rerank—
vad—
serve—
FunctionDescription
candle_backend_status_jsonJSON status for the in-process Candle backend — always {"stt_candle": false}: Candle Whisper runs in the oratio plugin (vox-plugin-speech).
Dependency Topology, diagram 111 nodes, 10 edges: vox-speech → vox-compiler; vox-speech → vox-config; vox-speech → vox-http-client; vox-speech → vox-populi; vox-speech → vox-secrets; vox-gui → vox-speech; vox-integration-tests → vox-speech; vox-ml-cli → vox-speech; vox-orchestrator → vox-speech; vox-orchestrator-mcp → vox-speechvox-speechvox-compilervox-configvox-http-clientvox-populivox-secretsvox-guivox-integration-testsvox-ml-clivox-orchestratorvox-orchestrator-mcp
Diagram source
graph {
direction: right
node vox_speech: "vox-speech"
node vox_compiler: "vox-compiler"
vox_speech -> vox_compiler
node vox_config: "vox-config"
vox_speech -> vox_config
node vox_http_client: "vox-http-client"
vox_speech -> vox_http_client
node vox_populi: "vox-populi"
vox_speech -> vox_populi
node vox_secrets: "vox-secrets"
vox_speech -> vox_secrets
node vox_gui: "vox-gui"
vox_gui -> vox_speech
node vox_integration_tests: "vox-integration-tests"
vox_integration_tests -> vox_speech
node vox_ml_cli: "vox-ml-cli"
vox_ml_cli -> vox_speech
node vox_orchestrator: "vox-orchestrator"
vox_orchestrator -> vox_speech
node vox_orchestrator_mcp: "vox-orchestrator-mcp"
vox_orchestrator_mcp -> vox_speech
}
Consumer CrateRole
vox-guiDirect workspace dependent
vox-integration-testsDirect workspace dependent
vox-ml-cliDirect workspace dependent
vox-orchestratorDirect workspace dependent
vox-orchestrator-mcpDirect workspace dependent
KindSymbolSignatureSourceDescription
fncandle_backend_status_jsonpub fn candle_backend_status_json() -> serde_json::Valuecrates/vox-speech/src/lib.rs#L71-L73JSON status for the in-process Candle backend — always {"stt_candle": false}: Candle Whisper runs in the oratio plugin (vox-plugin-speech).
structacoustic_preprocess::AcousticPreprocessDiagnosticspub struct AcousticPreprocessDiagnosticscrates/vox-speech/src/acoustic_preprocess.rs#L11-L26What ran in [preprocess_audio_pcm_f32_reported].
fnacoustic_preprocess::preprocess_audio_pcm_f32_reportedpub fn preprocess_audio_pcm_f32_reported(crates/vox-speech/src/acoustic_preprocess.rs#L59Preprocess PCM f32 mono (typ. -1..=1) with diagnostics; respects max_extra_ms wall budget.
fnacoustic_preprocess::preprocess_audio_pcm_f32pub fn preprocess_audio_pcm_f32(samples: &[f32], max_extra_ms: u64) -> Vec<f32>crates/vox-speech/src/acoustic_preprocess.rs#L152-L154When local denoise is unavailable or mode is none, returns samples unchanged (or scaled for peak mode). max_extra_ms caps wall time: if exceeded, returns the original buffer.
structast_mapper::AstTargetpub struct AstTargetcrates/vox-speech/src/ast_mapper.rs#L7-L14An AST-aware target that Vox Oratio can map to in the IDE.
fnast_mapper::map_to_ast_targetpub fn map_to_ast_target(crates/vox-speech/src/ast_mapper.rs#L18Simple heuristic to extract AST targets from transcript (Phase 1C MVP).
typebackend_dispatch::ExternalWhisperTranscribepub type ExternalWhisperTranscribe =crates/vox-speech/src/backend_dispatch.rs#L15Whisper transcriber supplied by the host: the SpeechToText::transcribe contract of the oratio plugin (vox-plugin-speech). Takes mono f32 little-endian PCM bytes and a {"sample_rate", "language"} config JSON; returns {"text", "segments"} JSON. vox-speech cannot reach vox-plugin-host itself, so hosts that can (vox-gui, vox-ml-cli’s vox oratio) register one with [register_whisper_transcriber].
fnbackend_dispatch::register_whisper_transcriberpub fn register_whisper_transcriber(f: ExternalWhisperTranscribe)crates/vox-speech/src/backend_dispatch.rs#L23-L28Register the host’s Whisper transcriber and drop the cached backend so the next transcription rebuilds with it.
fnbackend_dispatch::has_registered_whisper_transcriberpub fn has_registered_whisper_transcriber() -> boolcrates/vox-speech/src/backend_dispatch.rs#L31-L33Whether a host registered a Whisper transcriber.
fnbackend_dispatch::whisper_backendpub fn whisper_backend() -> anyhow::Result<Box<dyn AsrBackend>>crates/vox-speech/src/backend_dispatch.rs#L93-L102The Whisper backend: the host-registered transcriber, or an actionable error when none is registered.
fnbackend_dispatch::create_backendpub fn create_backend() -> anyhow::Result<Box<dyn AsrBackend>>crates/vox-speech/src/backend_dispatch.rs#L116-L168Instantiate the configured STT backend. # Env - VOX_ORATIO_BACKEND=auto (default) — picks Sherpa if compiled in, else Whisper - VOX_ORATIO_BACKEND=whisper — always Whisper ([whisper_backend]) - VOX_ORATIO_BACKEND=sherpa — always Sherpa (returns error if feature not compiled)
fnbackend_dispatch::invalidate_cachepub fn invalidate_cache()crates/vox-speech/src/backend_dispatch.rs#L201-L206Clear the cached backend so the next call to [with_cached_backend] reconstructs it via create_backend(), re-reading VOX_ORATIO_BACKEND. Needed because changing the backend setting (e.g. via the GUI’s Settings panel) only updates the env var / secret resolution the next create_backend() call reads — without this, a Settings change would update the displayed value but silently keep using the previously constructed (now stale) engine for the rest of the process’s life, since with_cached_backend has no other way to know the setting changed.
fnbackend_dispatch::with_cached_backendpub fn with_cached_backend<F, R>(f: F) -> anyhow::Result<R>crates/vox-speech/src/backend_dispatch.rs#L214Run f against the cached ASR backend, constructing it on first successful call. Safe to call from multiple threads: the backend is constructed at most once (barring a failed attempt, which is retried on the next call). The lock is released before f runs, so concurrent transcriptions don’t serialize on each other — only on the one-time construction.
fncontextual_bias::bias_hit_scorepub fn bias_hit_score(text: &str, phrases: &[String]) -> u32crates/vox-speech/src/contextual_bias.rs#L9-L31Count overlapping case-insensitive substring hits for phrases in text.
fncontextual_bias::merge_bias_phrasespub fn merge_bias_phrases(crates/vox-speech/src/contextual_bias.rs#L35Merge lexicon-derived bias strings with extra (e.g. session hotwords), dedupe, longest-first, cap max_phrases.
fncontextual_bias::parse_hotword_csvpub fn parse_hotword_csv(raw: &str) -> Vec<String>crates/vox-speech/src/contextual_bias.rs#L59-L65Parse comma-separated session hotwords from env-style strings.
fneval::tokenize_wordspub fn tokenize_words(s: &str) -> Vec<String>crates/vox-speech/src/eval.rs#L5-L11Normalize s into lowercase word tokens (whitespace split).
fneval::word_error_ratepub fn word_error_rate(reference: &str, hypothesis: &str) -> f64crates/vox-speech/src/eval.rs#L19-L30Word error rate over whitespace-delimited tokens (case-insensitive). Uses Levenshtein distance at the token level. Returns 0.0 when both strings are empty after tokenization; if the reference is empty but the hypothesis is not, returns 1.0.
fneval::char_error_ratepub fn char_error_rate(reference: &str, hypothesis: &str) -> f64crates/vox-speech/src/eval.rs#L37-L48Character error rate over non-whitespace Unicode scalar values. If both sides are empty after stripping whitespace, returns 0.0. If reference is empty and hypothesis is not, returns 1.0.
fneval::symbol_error_ratepub fn symbol_error_rate(reference: &str, hypothesis: &str) -> f64crates/vox-speech/src/eval.rs#L53-L81Symbol error rate for code-domain evaluation. Only considers tokens that look like identifiers [a-zA-Z_][a-zA-Z0-9_]*.
fneval_srt::mean_timing_offset_mspub fn mean_timing_offset_ms(expected: &[TimedSegment], actual: &[TimedSegment]) -> f32crates/vox-speech/src/eval_srt.rs#L10-L37Compute the mean absolute timing error (in milliseconds) between predicted and expected subtitle blocks. This is a simplified “TER” (Timing Error Rate) based on matching blocks by text similarity, then computing differences. For a production metric, you would want dynamic time warping (DTW) against the target audio, but this serves as a baseline proxy using ground-truth subtitles.
enumfailure_taxonomy::SpeechFailureCategorypub enum SpeechFailureCategorycrates/vox-speech/src/failure_taxonomy.rs#L8-L21High-level failure bucket for ASR → LLM → compiler pipelines.
fnfailure_taxonomy::as_strpub fn as_str(self) -> &'static strcrates/vox-speech/src/failure_taxonomy.rs#L26-L35Stable string label for logs and KPI JSON.
enumrefine::DomainModepub enum DomainModecrates/vox-speech/src/refine/mod.rs#L16-L22Specialization domain for STT rules.
enumrefine::OratioCorrectionProfilepub enum OratioCorrectionProfilecrates/vox-speech/src/refine/mod.rs#L27-L35Correction strictness profile for transcript refinement.
structrefine::CorrectionContextpub struct CorrectionContextcrates/vox-speech/src/refine/mod.rs#L39-L54Runtime context for refinement and spelling correction.
fnrefine::from_runtimepub fn from_runtime(crates/vox-speech/src/refine/mod.rs#L59Build context using resolved runtime refine tunables.
structrefine::CorrectionTracepub struct CorrectionTracecrates/vox-speech/src/refine/mod.rs#L77-L86Trace item for one correction decision.
structrefine::RefineOutputpub struct RefineOutputcrates/vox-speech/src/refine/mod.rs#L90-L97Output of transcript refinement.
fnrefine::refine_transcriptpub fn refine_transcript(raw: &str, ctx: &CorrectionContext) -> RefineOutputcrates/vox-speech/src/refine/mod.rs#L101-L103Run deterministic refinement and spelling correction.
structrouting::IdeContextpub struct IdeContextcrates/vox-speech/src/routing.rs#L16-L25IDE context for grounding speech commands in the current workspace state.
enumrouting::RouteModepub enum RouteModecrates/vox-speech/src/routing.rs#L276-L288Route modes for transcript-driven execution.
structrouting::RouteResponsepub struct RouteResponsecrates/vox-speech/src/routing.rs#L292-L301Route response envelope shared by CLI and MCP.
fnrouting::route_transcript_with_optionspub fn route_transcript_with_options(crates/vox-speech/src/routing.rs#L305Route with explicit confidence + runtime policy (CLI / MCP parity).
fnrouting::route_transcriptpub fn route_transcript(mode: RouteMode, session_id: &str, transcript: &str) -> RouteResponsecrates/vox-speech/src/routing.rs#L536-L545Back-compat wrapper: uses [crate::runtime_config::resolved_runtime_config] and assumes saturated transcript confidence (callers pre-gating tool mode should prefer [route_transcript_with_options]).
fnserve::run_serve_workerpub async fn run_serve_worker(port: u16) -> anyhow::Result<()>crates/vox-speech/src/serve.rs#L11-L23Serve POST /transcribe (multipart file of f32 LE PCM, optional sample_rate and language) on 127.0.0.1:port, transcribing through the Whisper backend selection.
enumsession::CaptureStatepub enum CaptureStatecrates/vox-speech/src/session.rs#L16-L27Capture/session lifecycle state.
enumsession::OratioDeadlineTaxonomypub enum OratioDeadlineTaxonomycrates/vox-speech/src/session.rs#L32-L41Machine-readable timeout / deadline taxonomy for diagnostics (CLI + MCP).
structsession::DeadlineDiagnosticspub struct DeadlineDiagnosticscrates/vox-speech/src/session.rs#L45-L54Structured deadline diagnostics (phase + elapsed + limits).
structsession::OratioSessionConfigpub struct OratioSessionConfigcrates/vox-speech/src/session.rs#L58-L75Config shared across CLI and MCP sessionized transcription flows.
structsession::OratioTimingspub struct OratioTimingscrates/vox-speech/src/session.rs#L95-L108Timing diagnostics for one session run.
structsession::OratioSessionResultpub struct OratioSessionResultcrates/vox-speech/src/session.rs#L112-L140Sessionized output returned to CLI and MCP callers.
fnsession::session_config_with_runtimepub fn session_config_with_runtime(crates/vox-speech/src/session.rs#L157Merge session config with runtime defaults for deadlines not explicitly set.
fnsession::transcribe_path_sessionpub fn transcribe_path_session(crates/vox-speech/src/session.rs#L175Run an end-to-end transcription session from a provided file path.
fnsession::transcribe_path_session_with_runtimepub fn transcribe_path_session_with_runtime(crates/vox-speech/src/session.rs#L184Like [transcribe_path_session] but uses a caller-provided resolved runtime snapshot (tests / MCP).