qualia_audio/features/cqt_stream/
inverse.rs1use crate::types::AudioError;
21
22fn 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
31fn 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#[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 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 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 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 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 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 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 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}