qualia_core_db/audio/
stft.rs1use 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#[inline]
23fn hann(i: usize, n: usize) -> f32 {
24 hann_window_sample(i, n)
25}
26
27pub 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 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 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#[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
105pub 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
130fn 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 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
153pub 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 #[test]
208 fn cosine_peaks_at_expected_bin() {
209 const FRAME: usize = 64;
210 const BIN: usize = 8;
211 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 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 #[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 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 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}