Skip to main content

qualia_audio/features/contours/
predominant.rs

1//! Top-level predominant-F0-per-frame melody line (mono melody from poly input).
2//!
3//! Given a stream of per-frame pitch-salience curves (from
4//! [`crate::features::salience::pitch_salience`]), emit one fundamental frequency
5//! per frame: the pitch of the frame's strongest salience ridge, refined to
6//! sub-bin resolution, **provided** that ridge is salient enough to be voiced.
7//! Frames whose peak salience falls below a data-driven voicing floor **abstain**
8//! (`out_f0 = 0.0`) rather than guess.
9//!
10//! ASSUMPTION (declared): this collapses each frame to a single F0 — a
11//! **monophonic melody** reading of possibly polyphonic input. The output is an
12//! epistemic *proposal* for the predominant voice, not an assertion that only one
13//! pitch sounds. Callers needing all voices should use the salience peaks /
14//! contour tracker directly.
15//!
16//! Zero-heap hot path: reads a caller-owned flat salience buffer and writes into
17//! a caller-owned `out_f0`; allocates nothing.
18
19use crate::types::AudioError;
20
21/// Fraction of the global peak salience below which a frame is treated as
22/// unvoiced (abstains). Melodia uses a salience-distribution threshold; this is
23/// a simple, honest analogue driven by the loudest ridge in the excerpt.
24const VOICING_RATIO: f32 = 0.1;
25
26/// Estimate the predominant fundamental frequency of each frame.
27///
28/// `salience_frames` is a flat row-major buffer of shape `n_frames × n_bins`
29/// (`salience_frames[f * n_bins + b]`) on the logarithmic grid where bin `b` is
30/// `f_min_hz * 2^(b / (12 * bins_per_semitone))`. For each frame the strongest
31/// bin is found, parabolically refined, and converted to Hz; frames whose peak
32/// salience is below `VOICING_RATIO` of the whole excerpt's peak salience abstain
33/// with `out_f0 = 0.0`.
34///
35/// Returns the number of **voiced** frames (non-zero `out_f0`).
36///
37/// # Errors
38/// - [`AudioError::InvalidParameter`] if `n_bins < 3`, `f_min_hz` /
39///   `bins_per_semitone` are not positive finite, or
40///   `salience_frames.len() < n_frames * n_bins`.
41/// - [`AudioError::OutputBufferTooSmall`] if `out_f0.len() < n_frames`.
42pub fn predominant_melody(
43    salience_frames: &[f32],
44    n_frames: usize,
45    n_bins: usize,
46    f_min_hz: f32,
47    bins_per_semitone: f32,
48    out_f0: &mut [f32],
49) -> Result<usize, AudioError> {
50    if n_bins < 3
51        || !(f_min_hz.is_finite() && f_min_hz > 0.0)
52        || !(bins_per_semitone.is_finite() && bins_per_semitone > 0.0)
53        || salience_frames.len() < n_frames.saturating_mul(n_bins)
54    {
55        return Err(AudioError::InvalidParameter);
56    }
57    if out_f0.len() < n_frames {
58        return Err(AudioError::OutputBufferTooSmall);
59    }
60    for v in out_f0.iter_mut().take(n_frames) {
61        *v = 0.0;
62    }
63    if n_frames == 0 {
64        return Ok(0);
65    }
66
67    // First pass: global peak salience → voicing floor.
68    let mut global_peak = 0.0f32;
69    for f in 0..n_frames {
70        let row = f * n_bins;
71        for b in 0..n_bins {
72            let s = salience_frames[row + b];
73            if s > global_peak {
74                global_peak = s;
75            }
76        }
77    }
78    if global_peak <= 0.0 {
79        return Ok(0); // wholly silent excerpt → abstain everywhere
80    }
81    let floor = VOICING_RATIO * global_peak;
82
83    // Second pass: per-frame argmax + parabolic refine + voicing decision.
84    let mut voiced = 0usize;
85    for f in 0..n_frames {
86        let row = f * n_bins;
87        let mut bi = 0usize;
88        let mut bv = salience_frames[row];
89        for b in 1..n_bins {
90            let s = salience_frames[row + b];
91            if s > bv {
92                bv = s;
93                bi = b;
94            }
95        }
96        if bv <= floor {
97            continue; // abstain: not salient enough to commit to a pitch
98        }
99        let refined = parabolic_bin(salience_frames, row, bi, n_bins);
100        let f0 = f_min_hz * (refined / (12.0 * bins_per_semitone)).exp2();
101        out_f0[f] = f0;
102        voiced += 1;
103    }
104    Ok(voiced)
105}
106
107/// Sub-bin refinement of the salience maximum at bin `bi` via a 3-point
108/// parabola; returns the fractional bin. Boundary maxima fall back to `bi`.
109#[inline]
110fn parabolic_bin(sal: &[f32], row: usize, bi: usize, n_bins: usize) -> f32 {
111    if bi == 0 || bi + 1 >= n_bins {
112        return bi as f32;
113    }
114    let ym1 = sal[row + bi - 1];
115    let y0 = sal[row + bi];
116    let yp1 = sal[row + bi + 1];
117    let denom = ym1 - 2.0 * y0 + yp1;
118    if denom == 0.0 || !denom.is_finite() {
119        return bi as f32;
120    }
121    let off = (0.5 * (ym1 - yp1) / denom).clamp(-0.5, 0.5);
122    bi as f32 + off
123}
124
125#[cfg(test)]
126mod tests {
127    use super::*;
128    use crate::features::salience::pitch_salience;
129
130    const F_MIN: f32 = 55.0;
131    const BPS: f32 = 10.0; // 10 cents/bin
132    const N_BINS: usize = 720; // 6 octaves
133
134    /// Ratio of two frequencies expressed in semitones.
135    fn semitone_err(a: f32, b: f32) -> f32 {
136        12.0 * (a / b).log2().abs()
137    }
138
139    /// GOLDEN end-to-end: a melody stepping 220 → 262 → 330 Hz across three
140    /// voiced frames (built as real harmonic-salience frames via `pitch_salience`)
141    /// plus one silent frame. `predominant_melody` recovers each f0 to within a
142    /// semitone and abstains on the silent frame.
143    #[test]
144    fn recovers_stepping_melody_and_abstains() {
145        let melody = [220.0f32, 262.0, 330.0, 0.0]; // last = silent
146        let n_frames = melody.len();
147        let mut frames = vec![0.0f32; n_frames * N_BINS];
148        let mut frame_buf = vec![0.0f32; N_BINS];
149
150        for (f, &f0) in melody.iter().enumerate() {
151            if f0 > 0.0 {
152                // Three harmonics for a tone at f0.
153                let pf = [f0, 2.0 * f0, 3.0 * f0];
154                let pm = [1.0f32, 0.6, 0.4];
155                pitch_salience(&pf, &pm, 3, F_MIN, BPS, N_BINS, &mut frame_buf).expect("salience");
156            } else {
157                for s in frame_buf.iter_mut() {
158                    *s = 0.0; // silent frame
159                }
160            }
161            frames[f * N_BINS..(f + 1) * N_BINS].copy_from_slice(&frame_buf);
162        }
163
164        let mut f0_out = vec![0.0f32; n_frames];
165        let voiced =
166            predominant_melody(&frames, n_frames, N_BINS, F_MIN, BPS, &mut f0_out).expect("melody");
167
168        assert_eq!(voiced, 3, "three voiced frames, one abstained");
169        for (f, &want) in melody.iter().enumerate() {
170            if want > 0.0 {
171                let err = semitone_err(f0_out[f], want);
172                assert!(
173                    err < 1.0,
174                    "frame {f}: recovered {} Hz vs {} Hz = {:.3} semitones",
175                    f0_out[f],
176                    want,
177                    err
178                );
179            } else {
180                assert_eq!(f0_out[f], 0.0, "silent frame must abstain");
181            }
182        }
183    }
184
185    /// A wholly silent excerpt abstains on every frame.
186    #[test]
187    fn all_silent_abstains() {
188        let n_frames = 4usize;
189        let frames = vec![0.0f32; n_frames * N_BINS];
190        let mut f0_out = vec![9.0f32; n_frames];
191        let voiced =
192            predominant_melody(&frames, n_frames, N_BINS, F_MIN, BPS, &mut f0_out).expect("melody");
193        assert_eq!(voiced, 0);
194        assert!(f0_out.iter().all(|&v| v == 0.0));
195    }
196
197    #[test]
198    fn rejects_bad_params() {
199        let frames = vec![0.0f32; 10];
200        let mut f0 = [0.0f32; 2];
201        assert_eq!(
202            predominant_melody(&frames, 2, 2, F_MIN, BPS, &mut f0),
203            Err(AudioError::InvalidParameter)
204        );
205        assert_eq!(
206            predominant_melody(&frames, 2, 5, 0.0, BPS, &mut f0),
207            Err(AudioError::InvalidParameter)
208        );
209    }
210
211    #[test]
212    fn rejects_small_output() {
213        let frames = vec![0.0f32; 3 * 8];
214        let mut f0 = [0.0f32; 2];
215        assert_eq!(
216            predominant_melody(&frames, 3, 8, F_MIN, BPS, &mut f0),
217            Err(AudioError::OutputBufferTooSmall)
218        );
219    }
220}