Skip to main content

qualia_audio/features/cqt_stream/
inverse.rs

1//! Approximate inverse CQT: time-domain reconstruction from a CQT magnitude
2//! spectrogram (AU-CQT-STREAM).
3//!
4//! This is an **approximate, magnitude-only overlap-add reconstruction**, not
5//! an exact inverse. A true inverse CQT requires the complex (phase-bearing)
6//! transform and a dual frame; here only per-bin magnitudes are available. We
7//! resynthesise each bin as a pure sinusoid at that bin's centre frequency,
8//! scaled by its magnitude, and overlap-add the windowed frame contributions.
9//!
10//! Phase is taken from the **absolute** output sample index `n` (not reset
11//! per frame), so overlapping frames add coherently and a steady tone
12//! reconstructs as a clean sinusoid at the bin centre frequency. Amplitude is
13//! only approximate (a Hann analysis-synthesis window is applied without
14//! gain-normalising the overlap), which is sufficient for pitch/frequency
15//! reconstruction but does not recover exact levels.
16//!
17//! Caller-buffered: the reconstruction is written into `out`; no heap
18//! allocation is performed.
19
20use crate::types::AudioError;
21
22/// Length of the reconstructed signal for a hopped spectrogram.
23fn reconstruction_len(n_frames: usize, frame_len: usize, hop: usize) -> usize {
24    if n_frames == 0 {
25        0
26    } else {
27        (n_frames - 1) * hop + frame_len
28    }
29}
30
31/// Hann window value at sample `j` of a `len`-sample window.
32fn hann(j: usize, len: usize) -> f32 {
33    if len <= 1 {
34        1.0
35    } else {
36        0.5 * (1.0 - (core::f32::consts::TAU * j as f32 / (len - 1) as f32).cos())
37    }
38}
39
40/// Approximate inverse CQT via magnitude-weighted sinusoidal overlap-add.
41///
42/// `spectrogram` is a row-major `[n_frames × n_bins]` magnitude matrix (as
43/// produced by [`super::spectrogram::cqt_spectrogram`]). Each bin `k` maps to
44/// centre frequency `f_min * 2^(k / bins_per_octave)`. The reconstruction sums,
45/// for every frame and bin, `mag * hann * sin(2π f_k n / sr)` into the output at
46/// absolute sample index `n`, with frames placed `hop` samples apart.
47///
48/// Returns the number of samples written:
49/// `(n_frames - 1) * hop + frame_len` (0 if `n_frames == 0`). `out` is fully
50/// overwritten in `[0, len)` (accumulation starts from zero).
51///
52/// # Errors
53/// - [`AudioError::InvalidParameter`] if `hop == 0`, `frame_len == 0`,
54///   `n_bins == 0`, `bins_per_octave == 0`, `sample_rate <= 0`, or `f_min <= 0`.
55/// - [`AudioError::MalformedAudio`] if `spectrogram` is smaller than
56///   `n_frames * n_bins`.
57/// - [`AudioError::OutputBufferTooSmall`] if `out` is smaller than `len`.
58#[allow(clippy::too_many_arguments)]
59pub fn inverse_cqt(
60    spectrogram: &[f32],
61    n_frames: usize,
62    n_bins: usize,
63    sample_rate: f32,
64    f_min: f32,
65    bins_per_octave: usize,
66    hop: usize,
67    frame_len: usize,
68    out: &mut [f32],
69) -> Result<usize, AudioError> {
70    if hop == 0
71        || frame_len == 0
72        || n_bins == 0
73        || bins_per_octave == 0
74        || sample_rate <= 0.0
75        || f_min <= 0.0
76    {
77        return Err(AudioError::InvalidParameter);
78    }
79    if spectrogram.len() < n_frames.saturating_mul(n_bins) {
80        return Err(AudioError::MalformedAudio);
81    }
82    let len = reconstruction_len(n_frames, frame_len, hop);
83    if out.len() < len {
84        return Err(AudioError::OutputBufferTooSmall);
85    }
86    if len == 0 {
87        return Ok(0);
88    }
89
90    out[..len].fill(0.0);
91
92    for f in 0..n_frames {
93        let base = f * hop;
94        let row = &spectrogram[f * n_bins..(f + 1) * n_bins];
95        for (k, &mag) in row.iter().enumerate() {
96            if mag == 0.0 {
97                continue;
98            }
99            let f_k = f_min * 2.0_f32.powf(k as f32 / bins_per_octave as f32);
100            let omega = core::f32::consts::TAU * f_k / sample_rate;
101            for j in 0..frame_len {
102                let n = base + j;
103                let w = hann(j, frame_len);
104                out[n] += mag * w * (omega * n as f32).sin();
105            }
106        }
107    }
108
109    Ok(len)
110}
111
112#[cfg(test)]
113mod tests {
114    use super::*;
115
116    /// Estimate dominant frequency (Hz) of `sig` via zero-crossing rate.
117    /// crossings ≈ 2 * cycles, so f ≈ crossings / (2 * duration_seconds).
118    fn dominant_freq_zc(sig: &[f32], sr: f32) -> f32 {
119        let mut crossings = 0usize;
120        for w in sig.windows(2) {
121            if (w[0] <= 0.0 && w[1] > 0.0) || (w[0] > 0.0 && w[1] <= 0.0) {
122                crossings += 1;
123            }
124        }
125        let duration = sig.len() as f32 / sr;
126        crossings as f32 / (2.0 * duration)
127    }
128
129    #[test]
130    fn inverse_single_bin_reconstructs_440hz() {
131        let sr = 16000.0f32;
132        let f_min = 55.0f32;
133        let bpo = 12usize;
134        let n_bins = 48usize;
135        let hop = 2048usize;
136        let frame_len = 4096usize;
137        let n_frames = 3usize;
138
139        // Bin 36 -> 55 * 2^3 = 440 Hz.
140        let bin = 36usize;
141        let f_k = f_min * 2.0f32.powf(bin as f32 / bpo as f32);
142        assert!((f_k - 440.0).abs() < 1e-3, "bin 36 centre = {f_k} Hz");
143
144        // Single active bin across all frames.
145        let mut spec = vec![0.0f32; n_frames * n_bins];
146        for f in 0..n_frames {
147            spec[f * n_bins + bin] = 1.0;
148        }
149
150        let len = reconstruction_len(n_frames, frame_len, hop);
151        let mut out = vec![0.0f32; len];
152        let written = inverse_cqt(
153            &spec, n_frames, n_bins, sr, f_min, bpo, hop, frame_len, &mut out,
154        )
155        .unwrap();
156        assert_eq!(written, len);
157        assert_eq!(len, (n_frames - 1) * hop + frame_len);
158
159        // Measure reconstructed dominant frequency on the coherent central
160        // region (avoid the tapered ends where Hann attenuates the signal).
161        let lo = frame_len / 2;
162        let hi = len - frame_len / 2;
163        let f_est = dominant_freq_zc(&out[lo..hi], sr);
164        assert!(
165            (f_est - 440.0).abs() < 440.0 * 0.03,
166            "reconstructed dominant freq {f_est} Hz should be ~440 Hz"
167        );
168    }
169
170    #[test]
171    fn inverse_zero_frames_writes_nothing() {
172        let sr = 16000.0f32;
173        let mut out = [0.0f32; 16];
174        let n = inverse_cqt(&[], 0, 48, sr, 55.0, 12, 2048, 4096, &mut out).unwrap();
175        assert_eq!(n, 0);
176    }
177
178    #[test]
179    fn inverse_rejects_bad_params_and_buffers() {
180        let spec = [0.0f32; 48];
181        // hop == 0.
182        assert!(matches!(
183            inverse_cqt(&spec, 1, 48, 16000.0, 55.0, 12, 0, 4096, &mut [0.0; 4096]),
184            Err(AudioError::InvalidParameter)
185        ));
186        // Spectrogram too small (needs 2*48 = 96).
187        assert!(matches!(
188            inverse_cqt(
189                &spec,
190                2,
191                48,
192                16000.0,
193                55.0,
194                12,
195                2048,
196                4096,
197                &mut [0.0; 6144]
198            ),
199            Err(AudioError::MalformedAudio)
200        ));
201        // Output too small (needs 4096).
202        assert!(matches!(
203            inverse_cqt(&spec, 1, 48, 16000.0, 55.0, 12, 2048, 4096, &mut [0.0; 100]),
204            Err(AudioError::OutputBufferTooSmall)
205        ));
206    }
207}