qualia_audio/features/contours/melodia.rs
1//! Predominant-melody contour selection (Melodia-class).
2//!
3//! After tracking (`contour_tracking`), a frame may be covered by several
4//! competing contours. Melodia's melody stage chooses the contour that is both
5//! **salient** (loud, harmonically strong) and **smooth** (low pitch variance —
6//! melodies move stepwise, not erratically), rejecting octave-jumping or noisy
7//! candidates.
8//!
9//! This selects, among a set of candidate contours summarised by their mean
10//! salience and their pitch variance, the index of the predominant-melody
11//! contour. It encodes an explicitly **monophonic** reading: exactly one melody
12//! line is chosen. In genuinely polyphonic material that assumption is a
13//! *proposal*, not a claim that only one voice exists.
14//!
15//! Zero-heap: reads two caller slices, returns an index; allocates nothing.
16
17use crate::types::AudioError;
18
19/// Choose the predominant-melody contour among `n` candidates.
20///
21/// Each candidate `i` is summarised by `mean_salience[i]` (higher = stronger)
22/// and `pitch_variance[i]` in squared bins (higher = more erratic pitch). The
23/// selection score normalises both across the candidate set and combines them:
24///
25/// ```text
26/// score(i) = salience_weight * (salience[i] / max_salience)
27/// + (1 - salience_weight) * (1 - variance[i] / max_variance)
28/// ```
29///
30/// so a candidate is preferred when it is loud *and* smooth. The index of the
31/// highest score is returned (ties resolve to the lowest index).
32///
33/// - `salience_weight`: relative importance of salience vs. smoothness, in
34/// `[0, 1]`. `1.0` selects purely on salience; `0.0` purely on smoothness.
35///
36/// # Errors
37/// - [`AudioError::InvalidParameter`] if `n == 0`, either slice is shorter than
38/// `n`, `salience_weight` is not a finite value in `[0, 1]`, or any summarised
39/// value is non-finite / negative.
40pub fn select_melody_contour(
41 mean_salience: &[f32],
42 pitch_variance: &[f32],
43 n: usize,
44 salience_weight: f32,
45) -> Result<usize, AudioError> {
46 if n == 0
47 || mean_salience.len() < n
48 || pitch_variance.len() < n
49 || !salience_weight.is_finite()
50 || !(0.0..=1.0).contains(&salience_weight)
51 {
52 return Err(AudioError::InvalidParameter);
53 }
54
55 let mut max_sal = 0.0f32;
56 let mut max_var = 0.0f32;
57 for i in 0..n {
58 let s = mean_salience[i];
59 let v = pitch_variance[i];
60 if !(s.is_finite() && s >= 0.0 && v.is_finite() && v >= 0.0) {
61 return Err(AudioError::InvalidParameter);
62 }
63 if s > max_sal {
64 max_sal = s;
65 }
66 if v > max_var {
67 max_var = v;
68 }
69 }
70
71 let mut best_i = 0usize;
72 let mut best_score = f32::NEG_INFINITY;
73 for i in 0..n {
74 // Normalise; guard degenerate (all-equal) sets.
75 let s_norm = if max_sal > 0.0 {
76 mean_salience[i] / max_sal
77 } else {
78 0.0
79 };
80 let smoothness = if max_var > 0.0 {
81 1.0 - pitch_variance[i] / max_var
82 } else {
83 1.0 // all equally smooth
84 };
85 let score = salience_weight * s_norm + (1.0 - salience_weight) * smoothness;
86 if score > best_score {
87 best_score = score;
88 best_i = i;
89 }
90 }
91 Ok(best_i)
92}
93
94#[cfg(test)]
95mod tests {
96 use super::*;
97
98 /// With equal weight, a loud-but-erratic contour loses to a slightly quieter
99 /// but far smoother one — the melody heuristic favours smooth pitch.
100 #[test]
101 fn prefers_smooth_over_erratic() {
102 // idx0: loud (1.0) but very erratic (var 100). idx1: medium (0.85) smooth (var 1).
103 let sal = [1.0f32, 0.85];
104 let var = [100.0f32, 1.0];
105 let i = select_melody_contour(&sal, &var, 2, 0.5).expect("select");
106 assert_eq!(i, 1, "smooth medium-salience contour is the melody");
107 }
108
109 /// Pure-salience weight ignores smoothness and takes the loudest.
110 #[test]
111 fn salience_only_takes_loudest() {
112 let sal = [0.3f32, 0.9, 0.5];
113 let var = [1.0f32, 50.0, 2.0];
114 let i = select_melody_contour(&sal, &var, 3, 1.0).expect("select");
115 assert_eq!(i, 1);
116 }
117
118 /// Pure-smoothness weight takes the lowest-variance contour.
119 #[test]
120 fn smoothness_only_takes_flattest() {
121 let sal = [0.9f32, 0.2, 0.5];
122 let var = [40.0f32, 0.5, 10.0];
123 let i = select_melody_contour(&sal, &var, 3, 0.0).expect("select");
124 assert_eq!(i, 1);
125 }
126
127 #[test]
128 fn rejects_bad_params() {
129 assert_eq!(
130 select_melody_contour(&[], &[], 0, 0.5),
131 Err(AudioError::InvalidParameter)
132 );
133 assert_eq!(
134 select_melody_contour(&[1.0], &[1.0], 1, 2.0),
135 Err(AudioError::InvalidParameter)
136 );
137 }
138}