Skip to main content

qualia_core_db/audio/
stft.rs

1//! Real forward STFT over actual audio samples — Hann-windowed framing through the
2//! forge FFT (`crate::wgsl_forge::dispatch::fft_f32`, GPU best-path with `etalon-signal`
3//! CPU FFT/DFT floor).
4//!
5//! This is the genuine forward transform that the cold-path sidecar bake consumes:
6//! [`bake_stft_sidecar_from_samples`] reduces the real magnitude spectrum to
7//! `SPECTRAL_PREVIEW_BINS` and writes it through the same header machinery as the
8//! preview-synthesis bake in [`crate::audio::stft_bake`] — so the sidecar derives
9//! from real audio, not from a parametric preview.
10//!
11//! Heap allocation is fine here: STFT runs at ingest (cold path), never in the
12//! zero-heap U3 hot worklet.
13
14use crate::audio::audio_spectral_sheet::{
15    AudioSpectralSidecarHeader, SIDECAR_KIND_STFT, SPECTRAL_PREVIEW_BINS, SPECTRAL_SIDECAR_MAGIC,
16};
17use crate::audio::stft_bake::StftBakeError;
18use etalon_signal::audio::{hann_window_sample, stft_one_sided_magnitudes_into};
19
20/// Hann window coefficient `w[i] = 0.5*(1 - cos(2π·i/(N-1)))` for a length-`n` frame,
21/// delegated to [`etalon_signal::audio::hann_window_sample`].
22#[inline]
23fn hann(i: usize, n: usize) -> f32 {
24    hann_window_sample(i, n)
25}
26
27/// Real forward STFT over `samples`.
28///
29/// `frame_size` must be a power of two in `[2, 1024]` (the forge FFT's accelerated
30/// window; the CPU DFT floor honours the same size), otherwise
31/// [`StftBakeError::InvalidFrameCount`].
32///
33/// For each frame start `s = 0, hop, 2·hop, …` while `s + frame_size ≤ samples.len()`:
34/// take `samples[s..s+frame_size]`, apply the Hann window, build the interleaved
35/// complex buffer `[re = windowed, im = 0]`, run it through
36/// [`crate::wgsl_forge::dispatch::fft_f32`] (or `etalon_signal::audio::stft_frame_into`
37/// on non-forge builds), and collect the frame's `frame_size` complex bins as `[re, im]`.
38///
39/// Returns one inner `Vec<[f32;2]>` (length `frame_size`) per frame.
40pub fn forward_stft(
41    samples: &[f32],
42    frame_size: usize,
43    hop: usize,
44) -> Result<Vec<Vec<[f32; 2]>>, StftBakeError> {
45    if !frame_size.is_power_of_two() || !(2..=1024).contains(&frame_size) {
46        return Err(StftBakeError::InvalidFrameCount);
47    }
48    if hop == 0 {
49        return Err(StftBakeError::InvalidFrameCount);
50    }
51
52    let mut frames: Vec<Vec<[f32; 2]>> = Vec::new();
53    if samples.len() < frame_size {
54        return Ok(frames);
55    }
56
57    // Reused per-frame interleaved-complex scratch (re, im, re, im, …).
58    let mut interleaved = vec![0.0_f32; frame_size * 2];
59
60    let mut s = 0usize;
61    while s + frame_size <= samples.len() {
62        let win = &samples[s..s + frame_size];
63        for (i, &x) in win.iter().enumerate() {
64            interleaved[2 * i] = x * hann(i, frame_size);
65            interleaved[2 * i + 1] = 0.0;
66        }
67        // Forge FFT (GPU best-path, CPU DFT floor). On any forge error fft_f32
68        // itself falls through to the CPU floor, so this only errors on a bad
69        // (odd) length — which `interleaved` never has.
70        let spectrum = fft_interleaved(&interleaved)?;
71
72        let mut frame = Vec::with_capacity(frame_size);
73        for k in 0..frame_size {
74            frame.push([spectrum[2 * k], spectrum[2 * k + 1]]);
75        }
76        frames.push(frame);
77
78        s += hop;
79    }
80
81    Ok(frames)
82}
83
84/// FFT of one interleaved-complex frame. Uses the forge (GPU best-path with its
85/// own CPU DFT floor) when the `wgsl_forge` module is compiled in; otherwise — on
86/// `wasm32`, or with the `wgsl-forge` feature off — delegates to
87/// [`etalon_signal::dft::dft_interleaved_into`] with the *identical* forward sign
88/// convention (`exp(-2πi·k·j/N)`), so the spectrum is the same transform either way.
89#[inline]
90fn fft_interleaved(interleaved: &[f32]) -> Result<Vec<f32>, StftBakeError> {
91    #[cfg(all(not(target_arch = "wasm32"), feature = "wgsl-forge"))]
92    {
93        crate::wgsl_forge::dispatch::fft_f32(interleaved)
94            .map_err(|_| StftBakeError::InvalidFrameCount)
95    }
96    #[cfg(not(all(not(target_arch = "wasm32"), feature = "wgsl-forge")))]
97    {
98        let mut out = vec![0.0_f32; interleaved.len()];
99        etalon_signal::dft::dft_interleaved_into(interleaved, &mut out)
100            .map_err(|_| StftBakeError::InvalidFrameCount)?;
101        Ok(out)
102    }
103}
104
105/// Per-frame one-sided magnitude spectrum: the first `frame_size/2 + 1` bins
106/// (DC … Nyquist) of `|X[k]| = sqrt(re² + im²)`, delegated to
107/// [`etalon_signal::audio::stft_one_sided_magnitudes_into`].
108pub fn stft_magnitudes(spec: &[Vec<[f32; 2]>]) -> Vec<Vec<f32>> {
109    spec.iter()
110        .map(|frame| {
111            if frame.is_empty() {
112                return Vec::new();
113            }
114            let half = frame.len() / 2 + 1;
115            let mut out = vec![0.0_f32; half];
116            let flat: &[f32] = bytemuck::cast_slice(frame.as_slice());
117            if stft_one_sided_magnitudes_into(flat, &mut out).is_ok() {
118                out
119            } else {
120                frame
121                    .iter()
122                    .take(half)
123                    .map(|&[re, im]| (re * re + im * im).sqrt())
124                    .collect()
125            }
126        })
127        .collect()
128}
129
130/// Reduce a single frame's one-sided magnitude spectrum to `SPECTRAL_PREVIEW_BINS`
131/// by averaging contiguous source bins into each preview bin (group/average).
132fn magnitudes_to_preview(mags: &[f32]) -> [f32; SPECTRAL_PREVIEW_BINS] {
133    let mut out = [0.0_f32; SPECTRAL_PREVIEW_BINS];
134    if mags.is_empty() {
135        return out;
136    }
137    let n = mags.len();
138    for (b, slot) in out.iter_mut().enumerate() {
139        // Even split of [0, n) into SPECTRAL_PREVIEW_BINS contiguous groups.
140        let lo = b * n / SPECTRAL_PREVIEW_BINS;
141        let hi = ((b + 1) * n / SPECTRAL_PREVIEW_BINS).max(lo + 1).min(n);
142        let mut sum = 0.0_f32;
143        let mut cnt = 0u32;
144        for &m in &mags[lo..hi] {
145            sum += m;
146            cnt += 1;
147        }
148        *slot = if cnt > 0 { sum / cnt as f32 } else { 0.0 };
149    }
150    out
151}
152
153/// Bake an STFT sidecar from REAL audio `samples`.
154///
155/// Computes the genuine forward STFT, reduces each frame's one-sided magnitude
156/// spectrum to `SPECTRAL_PREVIEW_BINS` (group/average), and writes the sidecar
157/// through the same [`AudioSpectralSidecarHeader`] machinery as
158/// [`crate::audio::stft_bake::bake_stft_sidecar_from_preview`] — mirroring its
159/// layout exactly (header + `frame_count` × `SPECTRAL_PREVIEW_BINS` f32 raster),
160/// but with `_pad = SIDECAR_KIND_STFT` and frame data derived from real audio.
161///
162/// Returns the number of bytes written into `out`.
163pub fn bake_stft_sidecar_from_samples(
164    samples: &[f32],
165    frame_size: usize,
166    hop: usize,
167    sample_rate: u32,
168    out: &mut [u8],
169) -> Result<usize, StftBakeError> {
170    let spec = forward_stft(samples, frame_size, hop)?;
171    let mags = stft_magnitudes(&spec);
172    let frame_count = mags.len() as u32;
173    if frame_count == 0 || frame_count > 4096 {
174        return Err(StftBakeError::InvalidFrameCount);
175    }
176
177    let header = AudioSpectralSidecarHeader {
178        magic: SPECTRAL_SIDECAR_MAGIC,
179        version: AudioSpectralSidecarHeader::VERSION,
180        _pad: SIDECAR_KIND_STFT,
181        bin_count: SPECTRAL_PREVIEW_BINS as u32,
182        frame_count,
183        sample_rate,
184    };
185    let need = std::mem::size_of::<AudioSpectralSidecarHeader>() + header.payload_bytes();
186    if out.len() < need {
187        return Err(StftBakeError::OutputTooSmall);
188    }
189    out[..std::mem::size_of::<AudioSpectralSidecarHeader>()]
190        .copy_from_slice(bytemuck::bytes_of(&header));
191    let payload_off = std::mem::size_of::<AudioSpectralSidecarHeader>();
192    for (f, frame_mags) in mags.iter().enumerate() {
193        let preview = magnitudes_to_preview(frame_mags);
194        let off = payload_off + f * SPECTRAL_PREVIEW_BINS * 4;
195        out[off..off + SPECTRAL_PREVIEW_BINS * 4].copy_from_slice(bytemuck::cast_slice(&preview));
196    }
197    Ok(need)
198}
199
200#[cfg(test)]
201mod tests {
202    use super::*;
203    use crate::audio::audio_spectral_sheet::parse_sidecar_header;
204
205    /// A pure cosine at bin BIN must place the STFT magnitude peak at bin BIN.
206    /// This also exercises the forge `fft_f32` end-to-end (GPU best-path / CPU floor).
207    #[test]
208    fn cosine_peaks_at_expected_bin() {
209        const FRAME: usize = 64;
210        const BIN: usize = 8;
211        // Three full frames of a pure cosine at exactly `BIN` cycles/frame.
212        let samples: Vec<f32> = (0..FRAME * 3)
213            .map(|i| {
214                (core::f32::consts::TAU * BIN as f32 * (i % FRAME) as f32 / FRAME as f32).cos()
215            })
216            .collect();
217        let spec = forward_stft(&samples, FRAME, FRAME).expect("stft");
218        let mags = stft_magnitudes(&spec);
219        assert!(!mags.is_empty());
220        // Peak bin of the first frame (one-sided spectrum has FRAME/2+1 = 33 bins).
221        let first = &mags[0];
222        let (peak, _) = first
223            .iter()
224            .enumerate()
225            .max_by(|a, b| a.1.partial_cmp(b.1).unwrap())
226            .unwrap();
227        assert!(
228            peak.abs_diff(BIN) <= 1,
229            "expected STFT peak near bin {BIN}, got {peak}"
230        );
231    }
232
233    /// Frame count must equal (len - frame_size)/hop + 1.
234    #[test]
235    fn frame_count_matches_formula() {
236        const FRAME: usize = 64;
237        const HOP: usize = 16;
238        let samples = vec![0.25_f32; 64 * 5 + 7];
239        let spec = forward_stft(&samples, FRAME, HOP).expect("stft");
240        let expected = (samples.len() - FRAME) / HOP + 1;
241        assert_eq!(spec.len(), expected, "frame count mismatch");
242    }
243
244    #[test]
245    fn rejects_non_power_of_two_frame() {
246        let samples = vec![0.0_f32; 256];
247        assert_eq!(
248            forward_stft(&samples, 48, 16),
249            Err(StftBakeError::InvalidFrameCount)
250        );
251        assert_eq!(
252            forward_stft(&samples, 2048, 16),
253            Err(StftBakeError::InvalidFrameCount)
254        );
255    }
256
257    #[test]
258    fn magnitudes_are_one_sided() {
259        const FRAME: usize = 64;
260        let samples = vec![0.1_f32; FRAME * 2];
261        let spec = forward_stft(&samples, FRAME, FRAME).expect("stft");
262        let mags = stft_magnitudes(&spec);
263        assert_eq!(mags[0].len(), FRAME / 2 + 1);
264    }
265
266    #[test]
267    fn bake_from_real_samples_produces_valid_stft_header() {
268        const FRAME: usize = 64;
269        const BIN: usize = 8;
270        let samples: Vec<f32> = (0..FRAME * 4)
271            .map(|i| {
272                (core::f32::consts::TAU * BIN as f32 * (i % FRAME) as f32 / FRAME as f32).cos()
273            })
274            .collect();
275        // Header (20 bytes) + up to 4 frames × 64 bins × 4 bytes.
276        let mut buf = [0u8; 20 + 64 * 4 * 4];
277        let n =
278            bake_stft_sidecar_from_samples(&samples, FRAME, FRAME, 44_100, &mut buf).expect("bake");
279        let h = parse_sidecar_header(&buf).expect("valid header");
280        assert_eq!(h.bin_count, SPECTRAL_PREVIEW_BINS as u32);
281        assert_eq!(h._pad, SIDECAR_KIND_STFT);
282        assert_eq!(h.sample_rate, 44_100);
283        assert!(h.frame_count >= 1);
284        assert_eq!(
285            n,
286            std::mem::size_of::<AudioSpectralSidecarHeader>()
287                + h.frame_count as usize * SPECTRAL_PREVIEW_BINS * 4
288        );
289        // The baked preview carries real energy (cosine is not silence).
290        let payload_off = std::mem::size_of::<AudioSpectralSidecarHeader>();
291        let frame0: &[f32] =
292            bytemuck::cast_slice(&buf[payload_off..payload_off + SPECTRAL_PREVIEW_BINS * 4]);
293        assert!(frame0.iter().any(|&v| v > 0.0), "real STFT energy present");
294    }
295}