rightkit_vad/lib.rs
1//! # rightkit-vad
2//!
3//! Product-neutral voice activity detection. Owns the Silero scorer (loaded
4//! from a caller-supplied ONNX file or embedded bytes; nothing is bundled or
5//! downloaded), the frame protocol, and the span/chunking policy. Owns no
6//! dictation, push-to-talk or command policy: callers decide what a span means.
7//!
8//! Layers, each usable alone:
9//! - [`FrameScorer`]: any per-frame speech-probability source (`Silero` (feature `silero`) or a test double).
10//! - [`SpeechScorer`] (feature `silero`): a constructed scorer that reports its
11//! [`Backend`], with an optional energy fallback when Silero cannot load.
12//! - [`scores_to_spans`]: Silero `get_speech_timestamps`-shaped hysteresis
13//! (`threshold` start, `neg_threshold` end, `min_speech`, `min_silence`,
14//! `pad`, merge).
15//! - [`chunk_spans`]: split/merge spans into decode-sized chunks
16//! (`max_chunk_ms`, `min_chunk_ms`, `merge_gap_ms`).
17//! - [`FrameStream`]: lossless streaming carry. Capture callbacks of any size
18//! in, whole 512-sample frames out; the remainder is retained, never
19//! dropped, because Silero is recurrent. A scorer failure yields `None`
20//! ("unknown"), never silence.
21
22#[cfg(feature = "silero")]
23mod scorer;
24#[cfg(feature = "silero")]
25mod silero;
26mod spans;
27mod stream;
28
29#[cfg(feature = "silero")]
30pub use scorer::{Backend, ScorerBackend, SpeechScorer};
31#[cfg(feature = "silero")]
32pub use silero::{ExecutionProvider, Silero, SileroOptions, Spinning, Warmup};
33pub use spans::{
34 chunk_spans, detect, energy_scores, scores_to_spans, ChunkConfig, ResolvedSpans,
35 RmsCalibration, Span, SpanOptions, VadConfig,
36};
37pub use stream::{FrameStream, FrameVerdicts};
38
39/// Silero v5 16 kHz frame size (32 ms).
40pub const FRAME_SAMPLES: usize = 512;
41/// Frame duration in milliseconds.
42pub const FRAME_MS: u64 = 32;
43/// Required sample rate.
44pub const SAMPLE_RATE: u32 = 16_000;
45
46#[derive(Debug)]
47pub enum Error {
48 Model(String),
49 Input(String),
50}
51
52impl std::fmt::Display for Error {
53 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
54 match self {
55 Error::Model(m) => write!(f, "vad model: {m}"),
56 Error::Input(m) => write!(f, "vad input: {m}"),
57 }
58 }
59}
60impl std::error::Error for Error {}
61pub type Result<T> = std::result::Result<T, Error>;
62
63/// Per-frame speech probability source. Stateful (recurrent) scorers must
64/// honour `reset`.
65pub trait FrameScorer {
66 fn reset(&mut self);
67 /// Probability in `[0,1]` for one 512-sample 16 kHz mono frame.
68 fn score(&mut self, frame: &[f32; FRAME_SAMPLES]) -> Result<f32>;
69}