Skip to main content

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}