Skip to main content

qualia_audio/features/pitch/
vibrato.rs

1//! Detect vibrato — a quasi-periodic modulation of the fundamental — from a
2//! pitch track, by locating the peak of the pitch-contour spectrum.
3//!
4//! The track is converted to a cents deviation about its geometric-mean pitch,
5//! Hann-windowed, and transformed with [`real_fft_magnitude`]. The strongest
6//! bin inside the vibrato band (≈3–12 Hz) gives the rate; its interpolated
7//! magnitude gives the extent (peak-to-peak, in cents); the fraction of contour
8//! power it carries gives a strength in `[0, 1]`.
9//!
10//! Zero-heap: one caller `scratch` buffer holds the windowed cents signal and
11//! the FFT work area; `out_mags` receives the contour magnitude spectrum.
12
13use crate::features::fft::real_fft::real_fft_magnitude;
14use crate::types::AudioError;
15
16/// Vibrato descriptor for a pitch track.
17#[derive(Debug, Clone, Copy, PartialEq)]
18pub struct Vibrato {
19    /// Modulation rate in Hz (0.0 = none detected in band).
20    pub rate_hz: f32,
21    /// Peak-to-peak modulation depth in cents.
22    pub extent_cents: f32,
23    /// Fraction of contour power concentrated at the rate, in `[0, 1]`.
24    pub strength: f32,
25}
26
27impl Vibrato {
28    #[inline]
29    /// None variant.
30    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;
41/// Hann coherent gain (Σw / N).
42const HANN_CG: f32 = 0.5;
43
44/// Minimum `scratch` length for a track of `track_len` samples.
45#[inline]
46pub fn vibrato_scratch_len(track_len: usize) -> usize {
47    3 * fft_len(track_len)
48}
49
50/// Largest power of two ≤ `m` (≥1), the analysis FFT length.
51#[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
63/// Detect vibrato in `track` sampled at `track_rate_hz` frames/second.
64///
65/// - `track`: pitch values (Hz); non-positive entries are treated as unvoiced
66///   and contribute zero deviation.
67/// - `track_rate_hz`: pitch-track frame rate (frames per second), > 0.
68/// - `scratch`: work buffer, at least [`vibrato_scratch_len`] floats.
69/// - `out_mags`: contour magnitude spectrum, at least `fft_len/2 + 1` floats.
70///
71/// Returns a [`Vibrato`]; `rate_hz == 0.0` means no in-band modulation was
72/// found (e.g. a steady or unvoiced track).
73///
74/// # Errors
75/// - [`AudioError::InvalidParameter`] if `track_rate_hz ≤ 0`, the usable length
76///   is below 16, or the track carries no voiced samples.
77/// - [`AudioError::OutputBufferTooSmall`] if `scratch` / `out_mags` are short.
78pub 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    // Geometric-mean reference pitch over voiced samples.
97    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    // Cents deviation about the reference, Hann-windowed.
113    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    // Peak bin in the vibrato band.
137    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    // Parabolic sub-bin refinement of rate and peak magnitude.
149    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    // Extent: |X_peak| ≈ A·N·cg/2 for a windowed sinusoid of amplitude A, so the
157    // peak-to-peak swing is 2A = 4·|X_peak| / (N·cg).
158    let extent_cents = 4.0 * peak_mag / (n as f32 * HANN_CG);
159
160    // Strength: power fraction carried by the peak (and its two neighbours) out
161    // of the whole AC contour spectrum.
162    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/// Parabolic vertex offset and interpolated height for three ordinates centred
187/// on a local maximum. Offset in `(-0.5, 0.5)`.
188#[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    /// Synthesize a pitch track with known vibrato and recover it.
205    fn synth(rate: f32, extent_pp: f32, track_rate: f32, n: usize, f_ref: f32) -> Vec<f32> {
206        let amp = extent_pp * 0.5; // cents amplitude
207        (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; // peak-to-peak cents
221        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        // No modulation → negligible extent (numerical floor only).
241        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}