Skip to main content

qualia_audio/features/vad/
segmenter.rs

1//! Segment a mono signal into voiced regions with hysteresis and hangover.
2//!
3//! A raw per-frame decision ([`crate::features::vad::frame_is_voiced`]) chatters
4//! at speech onsets/offsets and on brief dropouts (stops, glottal gaps). This
5//! module turns the frame-level proposal stream into stable `[start, end)`
6//! frame-index segments using two duration guards:
7//!
8//! - **min-speech (onset debounce):** a run of voiced frames must reach a
9//!   minimum length before a segment *opens*, rejecting isolated spurious
10//!   frames.
11//! - **min-silence (hangover):** once open, a segment only *closes* after a
12//!   sustained run of unvoiced frames, so a short dropout inside speech does not
13//!   split it.
14//!
15//! The noise floor is adaptive and streamed online: a fixed **stack** ring of
16//! the most recent per-frame energies feeds
17//! [`crate::features::vad::noise_floor_min_stat`], so the floor tracks the quiet
18//! frames without any heap allocation.
19//!
20//! EPISTEMIC RULE: output segments are *proposals*. Frames at or below the
21//! adaptive floor stay unvoiced — silence is never coerced into a segment.
22
23use crate::features::energy::frame_energy;
24use crate::features::vad::frame_vad::frame_is_voiced;
25use crate::features::vad::noise_estimate::noise_floor_min_stat;
26use crate::types::AudioError;
27
28/// Trailing frames used by the online minimum-statistics noise floor.
29const NOISE_WIN: usize = 64;
30/// Minimum voiced-run duration (ms) to open a segment (onset debounce).
31const MIN_SPEECH_MS: u32 = 32;
32/// Minimum unvoiced-run duration (ms) to close a segment (hangover).
33const MIN_SILENCE_MS: u32 = 120;
34
35/// Convert a duration in milliseconds to a frame count for the given `hop` and
36/// `sample_rate`, clamped to at least one frame.
37fn ms_to_frames(ms: u32, hop: usize, sample_rate: u32) -> usize {
38    if hop == 0 || sample_rate == 0 {
39        return 1;
40    }
41    let frames = (ms as u64 * sample_rate as u64) / (1000u64 * hop as u64);
42    (frames as usize).max(1)
43}
44
45/// Detect voiced segments in `signal`, writing `[start_frame, end_frame)` index
46/// pairs into `out_segments`.
47///
48/// - `signal`: mono samples in `[-1, 1]` (or any linear scale).
49/// - `frame_len`: analysis window length in samples (power-of-two enables the
50///   spectral-flatness cue; see [`crate::features::vad::frame_voicing_score`]).
51/// - `hop`: advance between frame starts in samples.
52/// - `sample_rate`: used only to convert the hysteresis durations to frames.
53/// - `out_segments`: caller-owned output; each entry is `(start_frame, end_frame)`
54///   with `end` exclusive, in frame-index units.
55///
56/// Returns the number of segments written.
57///
58/// # Errors
59/// - [`AudioError::InvalidParameter`] if `frame_len` or `hop` is zero.
60/// - [`AudioError::OutputBufferTooSmall`] if there are more segments than
61///   `out_segments` can hold (segments written so far are left in place).
62///
63/// Zero-heap: a single streaming pass over `signal`; the only working state is a
64/// fixed stack ring for the adaptive noise floor.
65pub fn segment_voiced(
66    signal: &[f32],
67    frame_len: usize,
68    hop: usize,
69    sample_rate: u32,
70    out_segments: &mut [(u32, u32)],
71) -> Result<usize, AudioError> {
72    if frame_len == 0 || hop == 0 {
73        return Err(AudioError::InvalidParameter);
74    }
75
76    let num_frames = if signal.len() < frame_len {
77        0
78    } else {
79        (signal.len() - frame_len) / hop + 1
80    };
81
82    let min_speech = ms_to_frames(MIN_SPEECH_MS, hop, sample_rate);
83    let min_silence = ms_to_frames(MIN_SILENCE_MS, hop, sample_rate);
84
85    // Online minimum-statistics noise floor over a fixed stack ring.
86    let mut ring = [0.0f32; NOISE_WIN];
87    let mut ring_len = 0usize; // number of valid entries (saturates at NOISE_WIN)
88    let mut ring_pos = 0usize; // next write index
89
90    // Hysteresis state machine.
91    let mut in_speech = false;
92    let mut seg_start = 0usize;
93    let mut voiced_run = 0usize; // consecutive voiced frames while in silence
94    let mut silence_run = 0usize; // consecutive unvoiced frames while in speech
95    let mut count = 0usize;
96
97    for f in 0..num_frames {
98        let s = f * hop;
99        let frame = &signal[s..s + frame_len];
100
101        // Update the adaptive floor from recent energies (this frame included so
102        // a lone loud frame cannot depress the floor).
103        let e = frame_energy(frame);
104        ring[ring_pos] = e;
105        ring_pos = (ring_pos + 1) % NOISE_WIN;
106        if ring_len < NOISE_WIN {
107            ring_len += 1;
108        }
109        let floor = noise_floor_min_stat(&ring[..ring_len], NOISE_WIN);
110
111        let voiced = frame_is_voiced(frame, floor);
112
113        if in_speech {
114            if voiced {
115                silence_run = 0;
116            } else {
117                silence_run += 1;
118                if silence_run >= min_silence {
119                    // Segment ended at the last voiced frame: current frame `f`
120                    // is the `silence_run`-th unvoiced frame, so the last voiced
121                    // frame was `f - silence_run`; end is exclusive.
122                    let end = (f - silence_run + 1) as u32;
123                    write_segment(out_segments, &mut count, seg_start as u32, end)?;
124                    in_speech = false;
125                    silence_run = 0;
126                    voiced_run = 0;
127                }
128            }
129        } else if voiced {
130            voiced_run += 1;
131            if voiced_run >= min_speech {
132                in_speech = true;
133                // The run began `voiced_run - 1` frames before the current one.
134                seg_start = f - (voiced_run - 1);
135                voiced_run = 0;
136                silence_run = 0;
137            }
138        } else {
139            voiced_run = 0;
140        }
141    }
142
143    // Flush an open segment at end-of-signal (closes at the last frame).
144    if in_speech {
145        write_segment(
146            out_segments,
147            &mut count,
148            seg_start as u32,
149            num_frames as u32,
150        )?;
151    }
152
153    Ok(count)
154}
155
156/// Append one `[start, end)` segment, guarding output capacity.
157fn write_segment(
158    out: &mut [(u32, u32)],
159    count: &mut usize,
160    start: u32,
161    end: u32,
162) -> Result<(), AudioError> {
163    if *count >= out.len() {
164        return Err(AudioError::OutputBufferTooSmall);
165    }
166    out[*count] = (start, end);
167    *count += 1;
168    Ok(())
169}
170
171#[cfg(test)]
172mod tests {
173    use super::*;
174    use core::f32::consts::TAU;
175
176    const SR: u32 = 16_000;
177    const FRAME: usize = 512;
178    const HOP: usize = 256;
179
180    /// Build silence · tone-burst · silence. Returns (signal, tone_start_sample,
181    /// tone_end_sample).
182    fn build_burst(lead: usize, burst: usize, trail: usize) -> (Vec<f32>, usize, usize) {
183        let mut sig = vec![0.0f32; lead + burst + trail];
184        for i in 0..burst {
185            let t = i as f32 / SR as f32;
186            sig[lead + i] = 0.5 * (TAU * 440.0 * t).sin();
187        }
188        (sig, lead, lead + burst)
189    }
190
191    fn frames_for(len: usize) -> usize {
192        if len < FRAME {
193            0
194        } else {
195            (len - FRAME) / HOP + 1
196        }
197    }
198
199    #[test]
200    fn one_segment_covers_the_burst_not_the_silence() {
201        let (sig, tstart, tend) = build_burst(3000, 6000, 3000);
202        let n_frames = frames_for(sig.len());
203        let mut segs = [(0u32, 0u32); 8];
204        let c = segment_voiced(&sig, FRAME, HOP, SR, &mut segs).expect("segment");
205
206        assert_eq!(
207            c,
208            1,
209            "expected exactly one voiced segment, got {c}: {:?}",
210            &segs[..c]
211        );
212        let (start, end) = segs[0];
213
214        // Expected onset/offset in frame indices (a frame at sample s spans
215        // [s, s+FRAME)). Allow a few frames of tolerance for the analysis window
216        // straddling the boundaries and the onset/hangover guards.
217        let onset_frame = (tstart / HOP) as u32;
218        let offset_frame = (tend / HOP) as u32;
219
220        assert!(
221            start >= 5 && start <= onset_frame + 3,
222            "start {start} should exclude lead silence and be near onset {onset_frame}"
223        );
224        assert!(
225            end >= offset_frame - 3 && end < n_frames as u32,
226            "end {end} should reach offset {offset_frame} and exclude trailing silence (n={n_frames})"
227        );
228        // The burst body is inside the segment; lead/trail silence frames are not.
229        assert!(
230            start < onset_frame + 2 && end > offset_frame - 2,
231            "segment must cover the burst"
232        );
233        assert!(
234            start > 2,
235            "early silence frame 2 must be outside the segment"
236        );
237    }
238
239    #[test]
240    fn one_frame_dropout_does_not_split_segment() {
241        let (mut sig, tstart, tend) = build_burst(3000, 6000, 3000);
242        // Zero one full frame's worth in the middle of the burst → a single
243        // silent frame. The hangover must bridge it.
244        let mid = tstart + (tend - tstart) / 2;
245        for x in sig[mid..mid + FRAME].iter_mut() {
246            *x = 0.0;
247        }
248        let mut segs = [(0u32, 0u32); 8];
249        let c = segment_voiced(&sig, FRAME, HOP, SR, &mut segs).expect("segment");
250        assert_eq!(
251            c,
252            1,
253            "a 1-frame dropout must not split the burst, got {c}: {:?}",
254            &segs[..c]
255        );
256    }
257
258    #[test]
259    fn pure_silence_yields_no_segments() {
260        let sig = vec![0.0f32; 12_000];
261        let mut segs = [(0u32, 0u32); 8];
262        let c = segment_voiced(&sig, FRAME, HOP, SR, &mut segs).expect("segment");
263        assert_eq!(c, 0, "silence must not be forced into a voiced segment");
264    }
265
266    #[test]
267    fn rejects_zero_params() {
268        let sig = vec![0.0f32; 1000];
269        let mut segs = [(0u32, 0u32); 4];
270        assert_eq!(
271            segment_voiced(&sig, 0, HOP, SR, &mut segs),
272            Err(AudioError::InvalidParameter)
273        );
274        assert_eq!(
275            segment_voiced(&sig, FRAME, 0, SR, &mut segs),
276            Err(AudioError::InvalidParameter)
277        );
278    }
279
280    #[test]
281    fn full_output_buffer_reports_too_small() {
282        // Two separated bursts, but room for only one segment.
283        let mut sig = vec![0.0f32; 3000];
284        let (b1, _, _) = build_burst(0, 4000, 3000);
285        sig.extend_from_slice(&b1);
286        let (b2, _, _) = build_burst(0, 4000, 3000);
287        sig.extend_from_slice(&b2);
288        let mut segs = [(0u32, 0u32); 1];
289        let r = segment_voiced(&sig, FRAME, HOP, SR, &mut segs);
290        assert_eq!(r, Err(AudioError::OutputBufferTooSmall));
291    }
292
293    #[test]
294    fn signal_shorter_than_frame_is_empty() {
295        let sig = vec![0.5f32; FRAME - 1];
296        let mut segs = [(0u32, 0u32); 4];
297        assert_eq!(segment_voiced(&sig, FRAME, HOP, SR, &mut segs), Ok(0));
298    }
299}