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}