Skip to main content

qualia_audio/features/pitch/
estimate.rs

1//! Shared pitch-estimate type and the numeric core that both YIN variants use,
2//! delegated to [`etalon_signal::pitch`].
3
4/// One fundamental-frequency estimate for a single frame.
5///
6/// `f0_hz == 0.0` denotes an unvoiced / undetected frame (with `confidence`
7/// near zero). Estimates are epistemic proposals, not ground truth.
8#[derive(Debug, Clone, Copy, PartialEq)]
9pub struct PitchEstimate {
10    /// Estimated fundamental frequency in Hz (0.0 = unvoiced).
11    pub f0_hz: f32,
12    /// Voicing confidence in `[0, 1]` (1 = strongly periodic).
13    pub confidence: f32,
14}
15
16impl PitchEstimate {
17    /// The canonical unvoiced estimate.
18    #[inline]
19    pub const fn unvoiced() -> Self {
20        Self {
21            f0_hz: 0.0,
22            confidence: 0.0,
23        }
24    }
25}
26
27/// Convert the raw difference function `diff[0..=max_lag]` into YIN's
28/// cumulative-mean-normalised difference (CMND) **in place**.
29#[inline]
30pub(super) fn cmnd_in_place(diff: &mut [f32], max_lag: usize) {
31    if diff.is_empty() {
32        return;
33    }
34    let last = max_lag.min(diff.len() - 1);
35    etalon_signal::pitch::yin_cmndf_in_place(&mut diff[..=last]);
36}
37
38/// Absolute-threshold lag selection over the CMND `cmnd[min_lag..=max_lag]`.
39#[inline]
40pub(super) fn absolute_threshold(
41    cmnd: &[f32],
42    min_lag: usize,
43    max_lag: usize,
44    threshold: f32,
45) -> usize {
46    etalon_signal::pitch::yin_absolute_threshold(cmnd, min_lag, max_lag, threshold)
47}
48
49/// Parabolic interpolation of the CMND minimum at integer lag `tau`.
50#[inline]
51pub(super) fn parabolic_min(
52    cmnd: &[f32],
53    tau: usize,
54    min_lag: usize,
55    max_lag: usize,
56) -> (f32, f32) {
57    etalon_signal::pitch::yin_parabolic_min(cmnd, tau, min_lag, max_lag)
58}
59
60#[cfg(test)]
61mod tests {
62    use super::*;
63
64    #[test]
65    fn cmnd_sets_dc_to_one() {
66        let mut d = [0.0f32, 4.0, 8.0, 6.0];
67        cmnd_in_place(&mut d, 3);
68        assert_eq!(d[0], 1.0);
69        assert!((d[1] - 1.0).abs() < 1e-6, "{}", d[1]);
70        assert!((d[2] - 1.3333).abs() < 1e-3, "{}", d[2]);
71    }
72
73    #[test]
74    fn threshold_picks_first_dip_below() {
75        let cmnd = [1.0f32, 1.0, 0.9, 0.5, 0.05, 0.2, 0.8];
76        let tau = absolute_threshold(&cmnd, 2, 6, 0.1);
77        assert_eq!(tau, 4);
78    }
79
80    #[test]
81    fn threshold_falls_back_to_global_min() {
82        let cmnd = [1.0f32, 1.0, 0.9, 0.4, 0.6, 0.8];
83        let tau = absolute_threshold(&cmnd, 2, 5, 0.1);
84        assert_eq!(tau, 3, "global min lag");
85    }
86
87    #[test]
88    fn parabolic_recovers_offset_vertex() {
89        let f = |x: f32| (x - 4.3).powi(2) + 0.02;
90        let cmnd: Vec<f32> = (0..8).map(|i| f(i as f32)).collect();
91        let (better, minv) = parabolic_min(&cmnd, 4, 1, 7);
92        assert!((better - 4.3).abs() < 1e-3, "tau={better}");
93        assert!((minv - 0.02).abs() < 1e-3, "minv={minv}");
94    }
95}