Skip to main content

qualia_audio/features/vad/
frame_vad.rs

1//! Per-frame voice-activity decision from a fusion of three cheap, orthogonal
2//! cues:
3//!
4//! 1. **Energy above an adaptive noise floor** — the primary gate. Activity
5//!    requires the frame RMS to clear the (caller-supplied) noise floor by a
6//!    margin; the size of the margin, in dB, sets the confidence.
7//! 2. **Spectral flatness** — tonal/harmonic content (low flatness) is
8//!    structured signal; a flat (white-ish) spectrum is noise-like. This
9//!    *raises confidence* for structured frames but never vetoes a clearly
10//!    above-floor frame, so a genuine noise burst is still reported as active.
11//! 3. **Zero-crossing rate** — a coarse spectral-tilt proxy; voiced/percussive
12//!    content sits in a plausible mid range, extreme values are down-weighted.
13//!
14//! EPISTEMIC RULE: the output is a *proposal*, not ground truth. A frame at or
15//! below the noise floor is returned unvoiced with zero confidence — **silence
16//! is never forced into "speech"**. Confidence is fused so that the energy gate
17//! dominates and the spectral/temporal cues only modulate a frame that has
18//! already cleared the floor.
19//!
20//! Zero-heap hot path: spectral flatness is computed through an in-place FFT
21//! over fixed **stack** scratch buffers (no allocation). Frames whose length is
22//! not a power of two, or longer than [`MAX_VAD_FFT`], skip the spectral cue and
23//! fall back to a neutral tonality — the energy gate still applies.
24
25use crate::features::energy::{frame_energy, frame_zcr};
26use crate::features::fft::real_fft_magnitude;
27use crate::features::spectral::spectral_flatness_db;
28
29/// Largest frame length (samples) for which the stack-buffered spectral-flatness
30/// cue is computed. Covers the usual 256/512/1024-sample VAD frames; longer
31/// frames fall back to the energy+ZCR decision with neutral tonality.
32pub const MAX_VAD_FFT: usize = 1024;
33
34/// SNR (dB) at which a frame *starts* to count as active above the floor.
35const ONSET_DB: f32 = 3.0;
36/// SNR (dB) at which energy confidence saturates to 1.0.
37const FULL_DB: f32 = 15.0;
38/// Confidence below which a frame is declared unvoiced by [`frame_is_voiced`].
39const VOICE_DECISION: f32 = 0.5;
40/// Floor of the structure multiplier: even a perfectly flat (noise-like) but
41/// clearly above-floor frame keeps this fraction of its energy confidence, so
42/// noise bursts are still detected as activity.
43const STRUCT_FLOOR: f32 = 0.6;
44/// Guards against a zero/unknown floor being read as "everything is voiced".
45const FLOOR_EPS: f32 = 1e-7;
46/// ZCR value treated as most plausible for voiced/structured content.
47const ZCR_CENTER: f32 = 0.15;
48/// Half-width of the plausible ZCR band.
49const ZCR_SPREAD: f32 = 0.4;
50
51/// Binary voiced/unvoiced proposal for one frame.
52///
53/// Convenience wrapper over [`frame_voicing_score`]: `true` iff the fused
54/// confidence reaches the decision threshold. `noise_floor` is the adaptive
55/// floor (e.g. from [`crate::features::vad::noise_floor_min_stat`]); a frame at
56/// or below it is always unvoiced.
57pub fn frame_is_voiced(frame: &[f32], noise_floor: f32) -> bool {
58    frame_voicing_score(frame, noise_floor) >= VOICE_DECISION
59}
60
61/// Fused voice-activity **confidence** in `[0, 1]` for one frame.
62///
63/// `0.0` means "at/below the noise floor" (silence — never voiced). Values grow
64/// with how far the frame clears the floor (energy cue) and are scaled up by
65/// spectral structure (low flatness) and a plausible zero-crossing rate. This is
66/// the scored variant; [`frame_is_voiced`] thresholds it.
67///
68/// Zero-heap: uses fixed stack scratch for the optional FFT cue.
69pub fn frame_voicing_score(frame: &[f32], noise_floor: f32) -> f32 {
70    if frame.len() < 2 {
71        return 0.0;
72    }
73    let floor = noise_floor.max(FLOOR_EPS);
74    let e = frame_energy(frame);
75    // Epistemic guard: at or below the estimated floor is silence, not speech.
76    if !(e > floor) {
77        return 0.0;
78    }
79
80    // Energy confidence from headroom over the floor, in dB.
81    let snr_db = 20.0 * (e / floor).log10();
82    let energy_conf = ((snr_db - ONSET_DB) / (FULL_DB - ONSET_DB)).clamp(0.0, 1.0);
83    if energy_conf <= 0.0 {
84        // Above the floor but within the onset margin: treat as not (yet) voiced.
85        return 0.0;
86    }
87
88    // Spectral structure: tonality = 1 - flatness (falls back to neutral 0.5).
89    let tonality = match frame_tonality(frame) {
90        Some(t) => t,
91        None => 0.5,
92    };
93
94    // Temporal plausibility from ZCR: peaks near ZCR_CENTER, decays outward.
95    let z = frame_zcr(frame);
96    let zcr_plaus = (1.0 - (z - ZCR_CENTER).abs() / ZCR_SPREAD).clamp(0.0, 1.0);
97
98    let structure = 0.7 * tonality + 0.3 * zcr_plaus;
99    let score = energy_conf * (STRUCT_FLOOR + (1.0 - STRUCT_FLOOR) * structure);
100    score.clamp(0.0, 1.0)
101}
102
103/// Tonality in `[0, 1]` (`1 - spectral_flatness`) via a stack-buffered FFT.
104///
105/// Returns `None` when the spectral cue is unavailable (frame length not a power
106/// of two, longer than [`MAX_VAD_FFT`], or an FFT/flatness error) so the caller
107/// can fall back to a neutral value. Zero-heap: fixed-size stack scratch.
108fn frame_tonality(frame: &[f32]) -> Option<f32> {
109    let n = frame.len();
110    if n < 2 || n > MAX_VAD_FFT || !n.is_power_of_two() {
111        return None;
112    }
113    let bins = n / 2 + 1;
114    let mut scratch = [0.0f32; 2 * MAX_VAD_FFT];
115    let mut mags = [0.0f32; MAX_VAD_FFT / 2 + 1];
116    real_fft_magnitude(frame, &mut scratch[..2 * n], &mut mags[..bins]).ok()?;
117    // Nudge off exact zeros so flatness reflects the true peakiness rather than
118    // collapsing to 0 on a single empty bin.
119    for m in mags[..bins].iter_mut() {
120        *m += 1e-9;
121    }
122    let flat = spectral_flatness_db(&mags[..bins], false).ok()?;
123    Some((1.0 - flat).clamp(0.0, 1.0))
124}
125
126#[cfg(test)]
127mod tests {
128    use super::*;
129    use core::f32::consts::TAU;
130
131    fn tone(n: usize, freq: f32, sr: f32, amp: f32) -> Vec<f32> {
132        (0..n)
133            .map(|i| amp * (TAU * freq * i as f32 / sr).sin())
134            .collect()
135    }
136
137    #[test]
138    fn silent_frame_is_unvoiced() {
139        let frame = [0.0f32; 512];
140        assert!(!frame_is_voiced(&frame, 0.0));
141        assert_eq!(frame_voicing_score(&frame, 0.0), 0.0);
142        // Also unvoiced against a nonzero floor.
143        assert!(!frame_is_voiced(&frame, 0.01));
144    }
145
146    #[test]
147    fn strong_tone_above_floor_is_voiced() {
148        let frame = tone(512, 440.0, 16_000.0, 0.5);
149        let score = frame_voicing_score(&frame, 0.001);
150        assert!(score >= VOICE_DECISION, "tone score={score}");
151        assert!(frame_is_voiced(&frame, 0.001));
152        assert!(score <= 1.0);
153    }
154
155    #[test]
156    fn quiet_tone_at_floor_stays_unvoiced() {
157        // Tone energy sits essentially at the floor → within onset margin → unvoiced.
158        let frame = tone(512, 440.0, 16_000.0, 0.5);
159        let e = frame_energy(&frame);
160        assert!(
161            !frame_is_voiced(&frame, e),
162            "must not force a floor-level frame voiced"
163        );
164        assert_eq!(frame_voicing_score(&frame, e), 0.0);
165    }
166
167    #[test]
168    fn noise_burst_above_floor_is_still_voiced() {
169        // Pseudo-random noise well above the floor: flat spectrum, but activity.
170        let mut state = 0x1234_5678u32;
171        let frame: Vec<f32> = (0..512)
172            .map(|_| {
173                state = state.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
174                ((state >> 8) as f32 / 8_388_608.0) - 1.0 // ~[-1,1)
175            })
176            .collect();
177        assert!(
178            frame_is_voiced(&frame, 0.001),
179            "noise burst should be detected as active"
180        );
181    }
182
183    #[test]
184    fn confidence_grows_with_headroom() {
185        let frame = tone(512, 440.0, 16_000.0, 0.5);
186        let near = frame_voicing_score(&frame, 0.05); // little headroom
187        let far = frame_voicing_score(&frame, 0.0005); // lots of headroom
188        assert!(far >= near, "far={far} near={near}");
189    }
190
191    #[test]
192    fn tonality_available_for_power_of_two() {
193        let frame = tone(512, 440.0, 16_000.0, 0.5);
194        let t = frame_tonality(&frame).expect("tonality for power-of-two frame");
195        assert!(
196            t > 0.5,
197            "a pure tone should read as strongly tonal, got {t}"
198        );
199    }
200
201    #[test]
202    fn tonality_none_for_non_power_of_two() {
203        let frame = tone(500, 440.0, 16_000.0, 0.5);
204        assert!(frame_tonality(&frame).is_none());
205    }
206}