qualia_audio/features/contours/
predominant.rs1use crate::types::AudioError;
20
21const VOICING_RATIO: f32 = 0.1;
25
26pub 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 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); }
81 let floor = VOICING_RATIO * global_peak;
82
83 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; }
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#[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; const N_BINS: usize = 720; fn semitone_err(a: f32, b: f32) -> f32 {
136 12.0 * (a / b).log2().abs()
137 }
138
139 #[test]
144 fn recovers_stepping_melody_and_abstains() {
145 let melody = [220.0f32, 262.0, 330.0, 0.0]; 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 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; }
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 #[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}