Skip to main content

qualia_audio/features/
stft_stream.rs

1//! Bounded streaming STFT (real radix-2 FFT via `features::fft`; power-of-two frames ≤ 512).
2
3use crate::types::AudioError;
4
5/// Streaming hop STFT with fixed window.
6#[derive(Debug, Clone)]
7pub struct StreamingStft {
8    pub frame_size: usize,
9    pub hop: usize,
10    window: Vec<f32>,
11    ring: Vec<f32>,
12    ring_len: usize,
13    /// Interleaved `[re, im]` FFT scratch (len `2 * frame_size`), reused per frame — no hot-path alloc.
14    scratch: Vec<f32>,
15}
16
17impl StreamingStft {
18    /// Creates a new instance.
19    pub fn new(frame_size: usize, hop: usize) -> Result<Self, AudioError> {
20        if !frame_size.is_power_of_two() || !(4..=512).contains(&frame_size) || hop == 0 {
21            return Err(AudioError::MalformedAudio);
22        }
23        let mut window = vec![0.0f32; frame_size];
24        for i in 0..frame_size {
25            window[i] = 0.5
26                * (1.0
27                    - (core::f32::consts::TAU * i as f32 / (frame_size - 1).max(1) as f32).cos());
28        }
29        Ok(Self {
30            frame_size,
31            hop,
32            window,
33            ring: vec![0.0f32; frame_size * 2],
34            ring_len: 0,
35            scratch: vec![0.0f32; frame_size * 2],
36        })
37    }
38
39    /// Push mono samples; for each completed frame write `n_bins` magnitudes into `out_mags`
40    /// (layout: frame-major, `n_bins` = frame_size/2+1). Returns frames written.
41    pub fn push(
42        &mut self,
43        samples: &[f32],
44        out_mags: &mut [f32],
45        n_bins: usize,
46    ) -> Result<usize, AudioError> {
47        let bins = (self.frame_size / 2 + 1).min(n_bins);
48        let max_frames = out_mags.len() / bins.max(1);
49        let mut written = 0usize;
50        for &s in samples {
51            if self.ring_len < self.ring.len() {
52                self.ring[self.ring_len] = s;
53                self.ring_len += 1;
54            } else {
55                // shift by hop
56                self.ring.copy_within(self.hop.., 0);
57                self.ring_len = self.frame_size;
58                self.ring[self.ring_len - 1] = s;
59            }
60            while self.ring_len >= self.frame_size && written < max_frames {
61                let dest = &mut out_mags[written * bins..(written + 1) * bins];
62                fft_magnitude(
63                    &self.ring[..self.frame_size],
64                    &self.window,
65                    &mut self.scratch,
66                    dest,
67                );
68                // consume hop
69                if self.hop >= self.ring_len {
70                    self.ring_len = 0;
71                } else {
72                    self.ring.copy_within(self.hop..self.ring_len, 0);
73                    self.ring_len -= self.hop;
74                }
75                written += 1;
76            }
77        }
78        Ok(written)
79    }
80
81    /// Resets.
82    pub fn reset(&mut self) {
83        self.ring_len = 0;
84        self.ring.fill(0.0);
85    }
86}
87
88/// One-shot magnitude STFT for a mono buffer (same DFT).
89pub fn magnitude_stft_chunk(
90    samples: &[f32],
91    frame_size: usize,
92    hop: usize,
93    out_mags: &mut [f32],
94    n_bins: usize,
95) -> Result<usize, AudioError> {
96    let mut st = StreamingStft::new(frame_size, hop)?;
97    st.push(samples, out_mags, n_bins)
98}
99
100/// Log-mel spectrogram using the REAL triangular mel filterbank (`features::mel`).
101///
102/// Per frame: real-FFT magnitudes → power → triangular mel bank (0..Nyquist) → natural log.
103/// This replaced the earlier linear-FFT-bin averaging that was mislabelled "log-mel".
104/// Batch convenience path — allocates working buffers once (the zero-heap streaming path is
105/// `StreamingStft` + `features::mel::mel_bands` applied per frame).
106pub fn log_mel_from_mono(
107    samples: &[f32],
108    frame_size: usize,
109    hop: usize,
110    sample_rate: u32,
111    n_mel: usize,
112    out: &mut [f32],
113) -> Result<usize, AudioError> {
114    let n_bins = frame_size / 2 + 1;
115    let max_frames = out.len() / n_mel.max(1);
116    let mut mags = vec![0.0f32; max_frames * n_bins];
117    let n_frames = magnitude_stft_chunk(samples, frame_size, hop, &mut mags, n_bins)?;
118    let n_frames = n_frames.min(max_frames);
119
120    // Real triangular mel filterbank spanning 0..Nyquist, built once.
121    let mut bank = vec![0.0f32; n_mel * n_bins];
122    crate::features::mel::build_mel_bank(
123        n_bins,
124        n_mel,
125        sample_rate as f32,
126        0.0,
127        sample_rate as f32 * 0.5,
128        &mut bank,
129    )?;
130    let mut power = vec![0.0f32; n_bins];
131    for f in 0..n_frames {
132        for b in 0..n_bins {
133            let m = mags[f * n_bins + b];
134            power[b] = m * m;
135        }
136        let dest = &mut out[f * n_mel..(f + 1) * n_mel];
137        crate::features::mel::mel_bands(&power, &bank, n_mel, dest)?;
138        for v in dest.iter_mut() {
139            *v = (*v + 1e-6).ln();
140        }
141    }
142    Ok(n_frames)
143}
144
145/// Windowed magnitude spectrum via the real radix-2 FFT. `scratch` is interleaved `[re, im]`
146/// of length `2 * frame.len()` and is reused across frames (no allocation here).
147fn fft_magnitude(frame: &[f32], window: &[f32], scratch: &mut [f32], out: &mut [f32]) {
148    let n = frame.len();
149    // Pack the windowed real frame into an interleaved complex buffer.
150    for t in 0..n {
151        scratch[2 * t] = frame[t] * window[t];
152        scratch[2 * t + 1] = 0.0;
153    }
154    // n is a validated power of two (StreamingStft::new), so this cannot fail; fail safe anyway.
155    if crate::features::fft::fft_radix2(&mut scratch[..2 * n], false).is_err() {
156        out.iter_mut().for_each(|o| *o = 0.0);
157        return;
158    }
159    let bins = out.len().min(n / 2 + 1);
160    for k in 0..bins {
161        let re = scratch[2 * k];
162        let im = scratch[2 * k + 1];
163        out[k] = (re * re + im * im).sqrt() / n as f32;
164    }
165}
166
167#[cfg(test)]
168mod tests {
169    use super::*;
170
171    #[test]
172    fn sine_has_energy() {
173        let sr = 256usize;
174        let mut s = vec![0.0f32; sr];
175        for i in 0..sr {
176            s[i] = (core::f32::consts::TAU * 4.0 * i as f32 / sr as f32).sin();
177        }
178        let mut mags = vec![0.0f32; 8 * 65];
179        let n = magnitude_stft_chunk(&s, 128, 64, &mut mags, 65).unwrap();
180        assert!(n >= 1);
181        let peak = mags[..65].iter().cloned().fold(0.0f32, f32::max);
182        assert!(peak > 0.01);
183    }
184}