qualia_audio/features/pitch/
vibrato.rs1use crate::features::fft::real_fft::real_fft_magnitude;
14use crate::types::AudioError;
15
16#[derive(Debug, Clone, Copy, PartialEq)]
18pub struct Vibrato {
19 pub rate_hz: f32,
21 pub extent_cents: f32,
23 pub strength: f32,
25}
26
27impl Vibrato {
28 #[inline]
29 pub const fn none() -> Self {
31 Self {
32 rate_hz: 0.0,
33 extent_cents: 0.0,
34 strength: 0.0,
35 }
36 }
37}
38
39const MIN_VIBRATO_HZ: f32 = 3.0;
40const MAX_VIBRATO_HZ: f32 = 12.0;
41const HANN_CG: f32 = 0.5;
43
44#[inline]
46pub fn vibrato_scratch_len(track_len: usize) -> usize {
47 3 * fft_len(track_len)
48}
49
50#[inline]
52fn fft_len(m: usize) -> usize {
53 if m < 1 {
54 return 1;
55 }
56 let mut n = 1usize;
57 while n * 2 <= m {
58 n *= 2;
59 }
60 n
61}
62
63pub fn detect_vibrato(
79 track: &[f32],
80 track_rate_hz: f32,
81 scratch: &mut [f32],
82 out_mags: &mut [f32],
83) -> Result<Vibrato, AudioError> {
84 if !(track_rate_hz.is_finite() && track_rate_hz > 0.0) {
85 return Err(AudioError::InvalidParameter);
86 }
87 let n = fft_len(track.len());
88 if n < 16 {
89 return Err(AudioError::InvalidParameter);
90 }
91 let bins = n / 2 + 1;
92 if scratch.len() < 3 * n || out_mags.len() < bins {
93 return Err(AudioError::OutputBufferTooSmall);
94 }
95
96 let mut ln_sum = 0.0f64;
98 let mut voiced = 0usize;
99 for &f in &track[..n] {
100 if f > 0.0 {
101 ln_sum += (f as f64).ln();
102 voiced += 1;
103 }
104 }
105 if voiced == 0 {
106 return Err(AudioError::InvalidParameter);
107 }
108 let ref_ln = ln_sum / voiced as f64;
109
110 let (cw, fft_scratch) = scratch.split_at_mut(n);
111
112 for i in 0..n {
114 let f = track[i];
115 let dev = if f > 0.0 {
116 (1200.0 / core::f64::consts::LN_2 * ((f as f64).ln() - ref_ln)) as f32
117 } else {
118 0.0
119 };
120 let hann = 0.5 - 0.5 * (core::f32::consts::TAU * i as f32 / (n - 1) as f32).cos();
121 cw[i] = dev * hann;
122 }
123
124 real_fft_magnitude(cw, fft_scratch, &mut out_mags[..bins])?;
125
126 let bin_hz = track_rate_hz / n as f32;
127 if bin_hz <= 0.0 {
128 return Ok(Vibrato::none());
129 }
130 let lo = ((MIN_VIBRATO_HZ / bin_hz).floor() as usize).max(1);
131 let hi = ((MAX_VIBRATO_HZ / bin_hz).ceil() as usize).min(bins - 1);
132 if lo > hi {
133 return Ok(Vibrato::none());
134 }
135
136 let peak = (lo..=hi).fold(lo, |best, k| {
138 if out_mags[k] > out_mags[best] {
139 k
140 } else {
141 best
142 }
143 });
144 if out_mags[peak] <= 0.0 {
145 return Ok(Vibrato::none());
146 }
147
148 let (offset, peak_mag) = if peak >= 1 && peak + 1 < bins {
150 parabolic(out_mags[peak - 1], out_mags[peak], out_mags[peak + 1])
151 } else {
152 (0.0, out_mags[peak])
153 };
154 let rate_hz = (peak as f32 + offset) * bin_hz;
155
156 let extent_cents = 4.0 * peak_mag / (n as f32 * HANN_CG);
159
160 let total_pow: f64 = out_mags[1..bins]
163 .iter()
164 .map(|&m| (m as f64) * (m as f64))
165 .sum();
166 let mut peak_pow = (out_mags[peak] as f64).powi(2);
167 if peak >= 1 {
168 peak_pow += (out_mags[peak - 1] as f64).powi(2);
169 }
170 if peak + 1 < bins {
171 peak_pow += (out_mags[peak + 1] as f64).powi(2);
172 }
173 let strength = if total_pow > 0.0 {
174 (peak_pow / total_pow).clamp(0.0, 1.0) as f32
175 } else {
176 0.0
177 };
178
179 Ok(Vibrato {
180 rate_hz,
181 extent_cents,
182 strength,
183 })
184}
185
186#[inline]
189fn parabolic(ym1: f32, y0: f32, yp1: f32) -> (f32, f32) {
190 let denom = ym1 - 2.0 * y0 + yp1;
191 if denom.abs() <= f32::EPSILON || !denom.is_finite() {
192 return (0.0, y0);
193 }
194 let off = (0.5 * (ym1 - yp1) / denom).clamp(-0.5, 0.5);
195 let peak = y0 - 0.25 * (ym1 - yp1) * off;
196 (off, peak)
197}
198
199#[cfg(test)]
200mod tests {
201 use super::*;
202 use core::f32::consts::TAU;
203
204 fn synth(rate: f32, extent_pp: f32, track_rate: f32, n: usize, f_ref: f32) -> Vec<f32> {
206 let amp = extent_pp * 0.5; (0..n)
208 .map(|i| {
209 let phase = TAU * rate * i as f32 / track_rate;
210 let cents = amp * phase.sin();
211 f_ref * 2f32.powf(cents / 1200.0)
212 })
213 .collect()
214 }
215
216 #[test]
217 fn recovers_rate_and_extent() {
218 let track_rate = 100.0f32;
219 let rate = 6.0f32;
220 let extent = 60.0f32; let track = synth(rate, extent, track_rate, 512, 440.0);
222 let mut scratch = vec![0.0f32; vibrato_scratch_len(512)];
223 let mut mags = vec![0.0f32; 512 / 2 + 1];
224 let v = detect_vibrato(&track, track_rate, &mut scratch, &mut mags).expect("vibrato");
225 assert!((v.rate_hz - rate).abs() < 0.5, "rate={}", v.rate_hz);
226 assert!(
227 (v.extent_cents - extent).abs() < 15.0,
228 "extent={}",
229 v.extent_cents
230 );
231 assert!(v.strength > 0.5, "strength={}", v.strength);
232 }
233
234 #[test]
235 fn steady_pitch_has_low_strength() {
236 let track = vec![330.0f32; 512];
237 let mut scratch = vec![0.0f32; vibrato_scratch_len(512)];
238 let mut mags = vec![0.0f32; 512 / 2 + 1];
239 let v = detect_vibrato(&track, 100.0, &mut scratch, &mut mags).expect("vibrato");
240 assert!(v.extent_cents < 1.0, "extent={}", v.extent_cents);
242 }
243
244 #[test]
245 fn different_rate_recovered() {
246 let track_rate = 100.0f32;
247 let rate = 5.0f32;
248 let track = synth(rate, 40.0, track_rate, 1024, 220.0);
249 let mut scratch = vec![0.0f32; vibrato_scratch_len(1024)];
250 let mut mags = vec![0.0f32; 1024 / 2 + 1];
251 let v = detect_vibrato(&track, track_rate, &mut scratch, &mut mags).expect("vibrato");
252 assert!((v.rate_hz - rate).abs() < 0.4, "rate={}", v.rate_hz);
253 }
254
255 #[test]
256 fn rejects_unvoiced_track() {
257 let track = vec![0.0f32; 64];
258 let mut scratch = vec![0.0f32; vibrato_scratch_len(64)];
259 let mut mags = vec![0.0f32; 64 / 2 + 1];
260 assert_eq!(
261 detect_vibrato(&track, 100.0, &mut scratch, &mut mags),
262 Err(AudioError::InvalidParameter)
263 );
264 }
265
266 #[test]
267 fn rejects_bad_rate() {
268 let track = vec![440.0f32; 64];
269 let mut scratch = vec![0.0f32; vibrato_scratch_len(64)];
270 let mut mags = vec![0.0f32; 64 / 2 + 1];
271 assert_eq!(
272 detect_vibrato(&track, 0.0, &mut scratch, &mut mags),
273 Err(AudioError::InvalidParameter)
274 );
275 }
276}