Skip to main content

qualia_audio/
music.rs

1//! Swarm M — foundational music features (assumptions declared).
2
3use crate::features::frame_energy;
4use crate::hash::q_hash;
5
6/// Declared analysis assumptions (never implicit universal truth).
7#[derive(Debug, Clone, Copy)]
8pub struct MusicAssumptions {
9    /// Equal temperament 12-tone — set false if unknown.
10    pub assumes_12tet: bool,
11    pub assumes_4_4: bool,
12    pub tuning_a4_hz: f32,
13}
14
15impl Default for MusicAssumptions {
16    fn default() -> Self {
17        Self {
18            assumes_12tet: false,
19            assumes_4_4: false,
20            tuning_a4_hz: 440.0,
21        }
22    }
23}
24
25#[derive(Debug, Clone, Copy)]
26pub struct OnsetEvent {
27    pub frame: u64,
28    pub strength: f32,
29}
30
31#[derive(Debug, Clone, Copy)]
32pub struct PitchEstimate {
33    pub frame: u64,
34    pub f0_hz: f32,
35    pub confidence: f32,
36}
37
38/// Spectral flux style onset detection on mono frames.
39pub fn detect_onsets(
40    mono: &[f32],
41    frame_len: usize,
42    hop: usize,
43    threshold: f32,
44    out: &mut [OnsetEvent],
45) -> usize {
46    if frame_len == 0 || hop == 0 || mono.len() < frame_len {
47        return 0;
48    }
49    let mut prev = 0.0f32;
50    let mut w = 0usize;
51    let mut i = 0usize;
52    while i + frame_len <= mono.len() && w < out.len() {
53        let e = frame_energy(&mono[i..i + frame_len]);
54        let flux = (e - prev).max(0.0);
55        if flux > threshold {
56            out[w] = OnsetEvent {
57                frame: i as u64,
58                strength: flux,
59            };
60            w += 1;
61        }
62        prev = e;
63        i += hop;
64    }
65    w
66}
67
68/// F0 for one frame via the real YIN estimator (CMND + absolute threshold +
69/// parabolic interpolation) in `features::pitch`. Replaced the earlier coarse
70/// integer-lag argmin. Allocates a per-call difference-function scratch (this is
71/// the batch convenience path; the zero-heap path is `features::pitch::yin_pitch`
72/// with a caller-owned scratch).
73pub fn estimate_f0_hz(frame: &[f32], sample_rate: u32, min_hz: f32, max_hz: f32) -> PitchEstimate {
74    let unvoiced = PitchEstimate {
75        frame: 0,
76        f0_hz: 0.0,
77        confidence: 0.0,
78    };
79    if frame.len() < 32 || sample_rate == 0 {
80        return unvoiced;
81    }
82    let mut scratch = vec![0.0f32; frame.len()];
83    match crate::features::pitch::yin_pitch(
84        frame,
85        sample_rate as f32,
86        min_hz,
87        max_hz,
88        0.15,
89        &mut scratch,
90    ) {
91        Ok(est) => PitchEstimate {
92            frame: 0,
93            f0_hz: est.f0_hz,
94            confidence: est.confidence,
95        },
96        Err(_) => unvoiced,
97    }
98}
99
100/// Chroma-like 12-bin energy from log-mel (only if assumes_12tet).
101pub fn chroma12_from_mel(
102    mel: &[f32],
103    n_mel: usize,
104    out: &mut [f32; 12],
105    assumptions: MusicAssumptions,
106) {
107    out.fill(0.0);
108    if !assumptions.assumes_12tet || n_mel == 0 {
109        return; // abstain — leave zeros
110    }
111    for (i, &v) in mel.iter().enumerate() {
112        let pc = i % 12;
113        out[pc] += v.max(0.0);
114    }
115}
116
117/// Music-class onset.
118pub fn music_class_onset() -> u64 {
119    q_hash("https://ns.webizen.org/q42/music/onset")
120}
121
122/// Estimated tempo from inter-onset intervals (reference; not a production beat tracker).
123#[derive(Debug, Clone, Copy)]
124pub struct TempoEstimate {
125    pub bpm: f32,
126    pub confidence: f32,
127    pub n_onsets_used: u32,
128}
129
130/// Estimates tempo from onsets.
131pub fn estimate_tempo_from_onsets(
132    onsets: &[OnsetEvent],
133    sample_rate: u32,
134    assumptions: MusicAssumptions,
135) -> TempoEstimate {
136    if sample_rate == 0 || onsets.len() < 2 {
137        return TempoEstimate {
138            bpm: 0.0,
139            confidence: 0.0,
140            n_onsets_used: 0,
141        };
142    }
143    let mut intervals = [0.0f32; 64];
144    let mut n_iv = 0usize;
145    for w in onsets.windows(2) {
146        if n_iv >= intervals.len() {
147            break;
148        }
149        let df = w[1].frame.saturating_sub(w[0].frame) as f32;
150        if df > 1.0 {
151            intervals[n_iv] = df / sample_rate as f32;
152            n_iv += 1;
153        }
154    }
155    if n_iv == 0 {
156        return TempoEstimate {
157            bpm: 0.0,
158            confidence: 0.0,
159            n_onsets_used: onsets.len() as u32,
160        };
161    }
162    // Median interval
163    let mut sorted = intervals[..n_iv].to_vec();
164    sorted.sort_by(|a, b| a.partial_cmp(b).unwrap_or(core::cmp::Ordering::Equal));
165    let med = sorted[n_iv / 2].max(1e-4);
166    let mut bpm = 60.0 / med;
167    // Fold into 60–180 if 4/4 assumed
168    if assumptions.assumes_4_4 {
169        while bpm < 60.0 {
170            bpm *= 2.0;
171        }
172        while bpm > 180.0 {
173            bpm *= 0.5;
174        }
175    }
176    let conf = ((n_iv as f32) / 8.0).clamp(0.05, 0.9);
177    TempoEstimate {
178        bpm,
179        confidence: conf,
180        n_onsets_used: onsets.len() as u32,
181    }
182}
183
184/// Coarse structure segment (energy-change boundaries).
185#[derive(Debug, Clone, Copy)]
186pub struct StructureSegment {
187    pub start_frame: u64,
188    pub end_frame: u64,
189    pub mean_energy: f32,
190    pub label_hash: u64,
191}
192
193/// Split mono into up to `out.len()` energy-based segments (proposal only).
194pub fn propose_structure_segments(
195    mono: &[f32],
196    frame_len: usize,
197    hop: usize,
198    out: &mut [StructureSegment],
199) -> usize {
200    if frame_len == 0 || hop == 0 || mono.len() < frame_len || out.is_empty() {
201        return 0;
202    }
203    let mut energies = [0.0f32; 256];
204    let mut n_e = 0usize;
205    let mut i = 0usize;
206    while i + frame_len <= mono.len() && n_e < energies.len() {
207        energies[n_e] = frame_energy(&mono[i..i + frame_len]);
208        n_e += 1;
209        i += hop;
210    }
211    if n_e == 0 {
212        return 0;
213    }
214    let mean: f32 = energies[..n_e].iter().sum::<f32>() / n_e as f32;
215    let thr = mean * 0.5;
216    let mut w = 0usize;
217    let mut seg_start = 0usize;
218    let mut in_high = energies[0] >= thr;
219    for e_i in 1..n_e {
220        let high = energies[e_i] >= thr;
221        if high != in_high {
222            if w < out.len() {
223                let start_f = (seg_start * hop) as u64;
224                let end_f = (e_i * hop) as u64;
225                let me: f32 =
226                    energies[seg_start..e_i].iter().sum::<f32>() / (e_i - seg_start).max(1) as f32;
227                out[w] = StructureSegment {
228                    start_frame: start_f,
229                    end_frame: end_f,
230                    mean_energy: me,
231                    label_hash: if in_high {
232                        q_hash("https://ns.webizen.org/q42/music/segment/active")
233                    } else {
234                        q_hash("https://ns.webizen.org/q42/music/segment/sparse")
235                    },
236                };
237                w += 1;
238            }
239            seg_start = e_i;
240            in_high = high;
241        }
242    }
243    if w < out.len() {
244        out[w] = StructureSegment {
245            start_frame: (seg_start * hop) as u64,
246            end_frame: mono.len() as u64,
247            mean_energy: energies[seg_start..n_e].iter().sum::<f32>()
248                / (n_e - seg_start).max(1) as f32,
249            label_hash: q_hash("https://ns.webizen.org/q42/music/segment/tail"),
250        };
251        w += 1;
252    }
253    w
254}
255
256/// Pitch track over successive frames (caller-buffered).
257pub fn track_pitch(
258    mono: &[f32],
259    sample_rate: u32,
260    frame_len: usize,
261    hop: usize,
262    out: &mut [PitchEstimate],
263) -> usize {
264    if frame_len == 0 || hop == 0 {
265        return 0;
266    }
267    let mut w = 0usize;
268    let mut i = 0usize;
269    while i + frame_len <= mono.len() && w < out.len() {
270        let mut pe = estimate_f0_hz(&mono[i..i + frame_len], sample_rate, 80.0, 800.0);
271        pe.frame = i as u64;
272        out[w] = pe;
273        w += 1;
274        i += hop;
275    }
276    w
277}
278
279#[cfg(test)]
280mod tests {
281    use super::*;
282
283    #[test]
284    fn onset_on_impulse() {
285        let mut s = vec![0.0f32; 2048];
286        s[1000] = 1.0;
287        let mut out = [OnsetEvent {
288            frame: 0,
289            strength: 0.0,
290        }; 8];
291        let n = detect_onsets(&s, 256, 128, 0.01, &mut out);
292        assert!(n >= 1);
293    }
294
295    #[test]
296    fn chroma_abstains_without_12tet() {
297        let mel = [1.0f32; 24];
298        let mut c = [0.0f32; 12];
299        chroma12_from_mel(&mel, 24, &mut c, MusicAssumptions::default());
300        assert!(c.iter().all(|&x| x == 0.0));
301    }
302
303    #[test]
304    fn tempo_from_regular_onsets() {
305        let sr = 16000u32;
306        // ~120 BPM → 0.5s between onsets
307        let hop = (sr as f32 * 0.5) as u64;
308        let onsets: Vec<OnsetEvent> = (0..8)
309            .map(|i| OnsetEvent {
310                frame: i * hop,
311                strength: 1.0,
312            })
313            .collect();
314        let t = estimate_tempo_from_onsets(
315            &onsets,
316            sr,
317            MusicAssumptions {
318                assumes_4_4: true,
319                ..Default::default()
320            },
321        );
322        assert!(t.bpm > 100.0 && t.bpm < 140.0, "bpm={}", t.bpm);
323        assert!(t.confidence > 0.0);
324    }
325
326    #[test]
327    fn structure_emits_segments() {
328        let mut s = vec![0.01f32; 4096];
329        for x in s[1024..2048].iter_mut() {
330            *x = 0.5;
331        }
332        let mut out = [StructureSegment {
333            start_frame: 0,
334            end_frame: 0,
335            mean_energy: 0.0,
336            label_hash: 0,
337        }; 8];
338        let n = propose_structure_segments(&s, 256, 128, &mut out);
339        assert!(n >= 1);
340    }
341}