Skip to main content

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}