Skip to main content

qualia_audio/features/salience/
salience_function.rs

1//! Harmonic pitch-salience function over a cent/bin grid (Melodia-class).
2//!
3//! Given the spectral peaks of one frame `(peak_freqs, peak_mags)`, accumulate a
4//! **pitch-salience curve** onto a logarithmic (constant-cents) frequency grid.
5//! Each spectral peak at frequency `f_i` is treated as the possible `h`-th
6//! harmonic of a fundamental `f0 = f_i / h` for `h = 1..N_HARMONICS`, so it casts
7//! a weighted vote onto the salience bin of every such candidate fundamental. A
8//! fundamental that actually generated a harmonic series therefore collects votes
9//! from all of its harmonics and dominates the curve.
10//!
11//! EPISTEMIC NOTE: the salience curve is a *proposal* about where pitched energy
12//! plausibly sits; it commits to no monophonic/polyphonic reading — a polyphonic
13//! frame yields several salient ridges. Downstream selection
14//! (`predominant`/`melodia`) is where a mono-vs-poly assumption is declared.
15//!
16//! Zero-heap hot path: the caller owns `out_salience` (length ≥ `n_bins`); the
17//! function clears and fills it in place and allocates nothing.
18
19use crate::types::AudioError;
20
21/// Number of harmonics each spectral peak votes through (peak = h-th harmonic).
22const N_HARMONICS: usize = 20;
23/// Geometric harmonic-weight decay `α^(h-1)` (higher harmonics vote weaker).
24const HARMONIC_ALPHA: f32 = 0.8;
25
26/// Accumulate a harmonic pitch-salience curve from the frame's spectral peaks.
27///
28/// The salience grid is logarithmic: bin `b` is the pitch
29/// `f_min_hz * 2^(b / (12 * bins_per_semitone))`, i.e. a constant
30/// `100 / bins_per_semitone` cents per bin. A peak at `f_i` with magnitude `m_i`
31/// contributes, for each harmonic number `h`, to the candidate fundamental
32/// `f0 = f_i / h`: the vote `m_i * HARMONIC_ALPHA^(h-1)` is spread over the grid
33/// bins within one semitone of `f0` with a `cos²` window (zero at ±1 semitone),
34/// which softens grid quantisation without smearing across notes.
35///
36/// - `peak_freqs` / `peak_mags`: the frame's spectral peaks (Hz, linear
37///   magnitude), as produced by [`crate::features::peaks::spectral_peaks()`]. Only
38///   the first `n_peaks` entries are read.
39/// - `f_min_hz`: frequency of salience bin 0 (the low edge of the pitch range).
40/// - `bins_per_semitone`: grid resolution (e.g. `10.0` → 10 cents per bin).
41/// - `n_bins`: number of salience bins to fill.
42/// - `out_salience`: caller buffer, cleared then filled in `[0, n_bins)`.
43///
44/// # Errors
45/// - [`AudioError::InvalidParameter`] if `f_min_hz`, `bins_per_semitone` are not
46///   positive finite values.
47/// - [`AudioError::OutputBufferTooSmall`] if `out_salience.len() < n_bins`.
48pub fn pitch_salience(
49    peak_freqs: &[f32],
50    peak_mags: &[f32],
51    n_peaks: usize,
52    f_min_hz: f32,
53    bins_per_semitone: f32,
54    n_bins: usize,
55    out_salience: &mut [f32],
56) -> Result<(), AudioError> {
57    if !(f_min_hz.is_finite()
58        && f_min_hz > 0.0
59        && bins_per_semitone.is_finite()
60        && bins_per_semitone > 0.0)
61    {
62        return Err(AudioError::InvalidParameter);
63    }
64    if out_salience.len() < n_bins {
65        return Err(AudioError::OutputBufferTooSmall);
66    }
67    // Clear the active range (caller buffer may be reused across frames).
68    for s in out_salience.iter_mut().take(n_bins) {
69        *s = 0.0;
70    }
71    if n_bins == 0 {
72        return Ok(());
73    }
74
75    let cap = peak_freqs.len().min(peak_mags.len()).min(n_peaks);
76
77    for i in 0..cap {
78        let f = peak_freqs[i];
79        let m = peak_mags[i];
80        if !(f.is_finite() && f > 0.0 && m.is_finite() && m > 0.0) {
81            continue;
82        }
83        let mut hw = 1.0f32; // HARMONIC_ALPHA^(h-1)
84        for h in 1..=N_HARMONICS {
85            let f0 = f / h as f32;
86            if f0 < f_min_hz {
87                break; // f0 only decreases as h grows → no further in-range candidates
88            }
89            // Fractional grid position of this candidate fundamental.
90            let b_center = 12.0 * bins_per_semitone * (f0 / f_min_hz).log2();
91            let lo = (b_center - bins_per_semitone).ceil();
92            let hi = (b_center + bins_per_semitone).floor();
93            if hi < 0.0 || lo >= n_bins as f32 {
94                hw *= HARMONIC_ALPHA;
95                continue;
96            }
97            let b0 = lo.max(0.0) as usize;
98            let b1 = (hi.min((n_bins - 1) as f32)) as usize;
99            for b in b0..=b1 {
100                // Distance in semitones from the candidate fundamental.
101                let d_semi = (b as f32 - b_center) / bins_per_semitone;
102                if d_semi.abs() >= 1.0 {
103                    continue;
104                }
105                let c = (d_semi * core::f32::consts::FRAC_PI_2).cos();
106                let w = c * c; // cos² window, 1 at centre → 0 at ±1 semitone
107                out_salience[b] += m * hw * w;
108            }
109            hw *= HARMONIC_ALPHA;
110        }
111    }
112    Ok(())
113}
114
115#[cfg(test)]
116mod tests {
117    use super::*;
118
119    /// Convert a fundamental frequency to its (fractional) salience bin.
120    fn hz_to_bin(f: f32, f_min: f32, bps: f32) -> f32 {
121        12.0 * bps * (f / f_min).log2()
122    }
123
124    /// Index of the maximum over `[0, n)`.
125    fn argmax(s: &[f32], n: usize) -> usize {
126        let mut bi = 0usize;
127        let mut bv = s[0];
128        for i in 1..n {
129            if s[i] > bv {
130                bv = s[i];
131                bi = i;
132            }
133        }
134        bi
135    }
136
137    /// GOLDEN: a harmonic tone at 220 Hz (peaks at 220/440/660) must produce a
138    /// salience curve whose global maximum sits at 220 Hz's bin — the harmonics
139    /// all vote onto the true fundamental.
140    #[test]
141    fn salience_peaks_at_fundamental() {
142        let f_min = 55.0f32;
143        let bps = 10.0f32; // 10 cents/bin
144        let n_bins = 720usize; // 6 octaves
145        let f0 = 220.0f32;
146        let peak_freqs = [f0, 2.0 * f0, 3.0 * f0];
147        let peak_mags = [1.0f32, 0.6, 0.4];
148        let mut sal = vec![0.0f32; n_bins];
149        pitch_salience(&peak_freqs, &peak_mags, 3, f_min, bps, n_bins, &mut sal).expect("salience");
150
151        let want = hz_to_bin(f0, f_min, bps).round() as usize; // 240
152        let got = argmax(&sal, n_bins);
153        assert_eq!(want, 240, "expected fundamental bin math");
154        assert!(
155            (got as i32 - want as i32).abs() <= 1,
156            "peak bin={got} want≈{want}"
157        );
158        // The fundamental collects all three harmonics → strictly the strongest.
159        let f2bin = hz_to_bin(2.0 * f0, f_min, bps).round() as usize;
160        assert!(
161            sal[got] > sal[f2bin],
162            "fundamental {} !> octave {}",
163            sal[got],
164            sal[f2bin]
165        );
166    }
167
168    #[test]
169    fn rejects_bad_params() {
170        let mut sal = [0.0f32; 4];
171        assert_eq!(
172            pitch_salience(&[100.0], &[1.0], 1, 0.0, 10.0, 4, &mut sal),
173            Err(AudioError::InvalidParameter)
174        );
175        assert_eq!(
176            pitch_salience(&[100.0], &[1.0], 1, 55.0, 0.0, 4, &mut sal),
177            Err(AudioError::InvalidParameter)
178        );
179    }
180
181    #[test]
182    fn rejects_small_buffer() {
183        let mut sal = [0.0f32; 3];
184        assert_eq!(
185            pitch_salience(&[100.0], &[1.0], 1, 55.0, 10.0, 8, &mut sal),
186            Err(AudioError::OutputBufferTooSmall)
187        );
188    }
189
190    /// A silent frame (no peaks) leaves an all-zero salience curve.
191    #[test]
192    fn silent_frame_is_zero() {
193        let mut sal = vec![9.0f32; 32];
194        pitch_salience(&[], &[], 0, 55.0, 10.0, 32, &mut sal).expect("ok");
195        assert!(sal.iter().all(|&v| v == 0.0));
196    }
197}