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}