Skip to main content

qualia_audio/features/cqt_stream/
spectrogram.rs

1//! Streaming multi-frame CQT magnitude spectrogram (AU-CQT-STREAM).
2//!
3//! Hops a fixed-length analysis window across a mono signal, calling the
4//! single-frame [`crate::features::cqt::forward_cqt_mono`] kernel per frame and
5//! writing a row-major `[n_frames × n_bins]` magnitude spectrogram into a
6//! caller-provided buffer.
7//!
8//! Zero-heap hot path: this function performs no allocation. Each frame is a
9//! borrowed sub-slice of `signal`, and each frame's CQT magnitudes are written
10//! directly into the matching row of the caller's `out` buffer. The per-frame
11//! kernel itself uses only stack scalars.
12
13use crate::features::cqt::forward_cqt_mono;
14use crate::types::AudioError;
15
16/// Number of hopped frames that fit in `signal_len` given `frame_len`/`hop`.
17///
18/// A frame is counted only if it lies fully within the signal, i.e. the last
19/// sample it reads (`start + frame_len - 1`) is in range. Returns 0 when the
20/// signal is shorter than a single frame.
21fn frame_count(signal_len: usize, frame_len: usize, hop: usize) -> usize {
22    if frame_len == 0 || hop == 0 || signal_len < frame_len {
23        return 0;
24    }
25    1 + (signal_len - frame_len) / hop
26}
27
28/// Compute a streaming CQT magnitude spectrogram over `signal`.
29///
30/// The window of length `frame_len` is advanced by `hop` samples per frame;
31/// for each frame the constant-Q magnitudes (`n_bins` bins, geometrically
32/// spaced from `f_min` at `bins_per_octave`) are computed with
33/// [`forward_cqt_mono`] and stored row-major into `out` as
34/// `out[frame * n_bins + bin]`.
35///
36/// Returns the number of frames written. `out` must hold at least
37/// `n_frames * n_bins` values, where `n_frames` follows the hop math
38/// (`1 + (signal.len() - frame_len) / hop`, or 0 if the signal is too short).
39///
40/// # Errors
41/// - [`AudioError::InvalidParameter`] if `hop == 0`, `frame_len == 0`,
42///   `n_bins == 0`, `bins_per_octave == 0`, `sample_rate <= 0`, or `f_min <= 0`.
43/// - [`AudioError::OutputBufferTooSmall`] if `out` cannot hold the spectrogram.
44#[allow(clippy::too_many_arguments)]
45pub fn cqt_spectrogram(
46    signal: &[f32],
47    sample_rate: f32,
48    f_min: f32,
49    bins_per_octave: usize,
50    n_bins: usize,
51    hop: usize,
52    frame_len: usize,
53    out: &mut [f32],
54) -> Result<usize, AudioError> {
55    if hop == 0
56        || frame_len == 0
57        || n_bins == 0
58        || bins_per_octave == 0
59        || sample_rate <= 0.0
60        || f_min <= 0.0
61    {
62        return Err(AudioError::InvalidParameter);
63    }
64
65    let n_frames = frame_count(signal.len(), frame_len, hop);
66    let needed = n_frames.saturating_mul(n_bins);
67    if out.len() < needed {
68        return Err(AudioError::OutputBufferTooSmall);
69    }
70
71    for f in 0..n_frames {
72        let start = f * hop;
73        let frame = &signal[start..start + frame_len];
74        let row = &mut out[f * n_bins..(f + 1) * n_bins];
75        forward_cqt_mono(frame, sample_rate, f_min, bins_per_octave, n_bins, row)?;
76    }
77
78    Ok(n_frames)
79}
80
81#[cfg(test)]
82mod tests {
83    use super::*;
84
85    fn tone(freq: f32, sr: f32, n: usize) -> Vec<f32> {
86        (0..n)
87            .map(|i| (core::f32::consts::TAU * freq * i as f32 / sr).sin())
88            .collect()
89    }
90
91    #[test]
92    fn cqt_stream_frame_count_matches_hop_math() {
93        // 8192 samples, frame 4096, hop 2048 -> 1 + (8192-4096)/2048 = 3.
94        assert_eq!(frame_count(8192, 4096, 2048), 3);
95        // Exactly one frame.
96        assert_eq!(frame_count(4096, 4096, 2048), 1);
97        // Signal shorter than a frame -> zero frames.
98        assert_eq!(frame_count(4000, 4096, 2048), 0);
99        // Non-integer trailing frame is dropped (fully-in-range rule).
100        assert_eq!(frame_count(9000, 4096, 2048), 3);
101    }
102
103    #[test]
104    fn cqt_stream_440_tone_peaks_at_bin_36() {
105        let sr = 16000.0f32;
106        let n = 8192usize;
107        let frame_len = 4096usize;
108        let hop = 2048usize;
109        let f_min = 55.0f32;
110        let bpo = 12usize;
111        let n_bins = 48usize; // covers 4 octaves; 440 Hz -> bin 36.
112
113        let s = tone(440.0, sr, n);
114
115        // Expected bin index: 12 * log2(440/55) = 36.
116        let expected_bin = (bpo as f32 * (440.0f32 / f_min).log2()).round() as usize;
117        assert_eq!(expected_bin, 36);
118
119        let n_frames_expected = 1 + (n - frame_len) / hop; // 3
120        let mut out = vec![0.0f32; n_frames_expected * n_bins];
121
122        let n_frames =
123            cqt_spectrogram(&s, sr, f_min, bpo, n_bins, hop, frame_len, &mut out).unwrap();
124        assert_eq!(n_frames, 3, "frame count must match hop math");
125
126        // Per-frame the max-magnitude bin must be 36.
127        for f in 0..n_frames {
128            let row = &out[f * n_bins..(f + 1) * n_bins];
129            let mut best = 0usize;
130            let mut best_v = row[0];
131            for (k, &v) in row.iter().enumerate() {
132                if v > best_v {
133                    best_v = v;
134                    best = k;
135                }
136            }
137            assert_eq!(best, 36, "frame {f} peak bin should be 36 (440 Hz)");
138        }
139
140        // Summed energy across frames also peaks at bin 36.
141        let mut summed = vec![0.0f32; n_bins];
142        for f in 0..n_frames {
143            for k in 0..n_bins {
144                summed[k] += out[f * n_bins + k];
145            }
146        }
147        let mut best = 0usize;
148        for k in 1..n_bins {
149            if summed[k] > summed[best] {
150                best = k;
151            }
152        }
153        assert_eq!(best, 36, "summed-energy peak bin should be 36");
154    }
155
156    #[test]
157    fn cqt_stream_short_signal_zero_frames() {
158        let sr = 16000.0f32;
159        let s = tone(440.0, sr, 1000);
160        let mut out = [0.0f32; 48];
161        let n = cqt_spectrogram(&s, sr, 55.0, 12, 48, 2048, 4096, &mut out).unwrap();
162        assert_eq!(n, 0);
163    }
164
165    #[test]
166    fn cqt_stream_rejects_bad_params_and_small_out() {
167        let s = tone(440.0, 16000.0, 8192);
168        // hop == 0.
169        assert!(matches!(
170            cqt_spectrogram(&s, 16000.0, 55.0, 12, 48, 0, 4096, &mut [0.0; 48]),
171            Err(AudioError::InvalidParameter)
172        ));
173        // Output too small (needs 3*48 = 144).
174        let mut small = [0.0f32; 100];
175        assert!(matches!(
176            cqt_spectrogram(&s, 16000.0, 55.0, 12, 48, 2048, 4096, &mut small),
177            Err(AudioError::OutputBufferTooSmall)
178        ));
179    }
180}