Skip to main content

qualia_audio/models/crepe/
head.rs

1//! CREPE pitch head (P64, fail-closed) — AU-LEARNED.
2//!
3//! `CrepeHead` estimates a fundamental frequency from a single audio frame using learned weights
4//! loaded through the common fail-closed loader. **With no weights it abstains**
5//! (`BackendUnavailable`) — it never returns a fabricated pitch. With a (possibly synthetic/test)
6//! blob present it runs the CPU reference forward pass: a linear projection onto a bank of pitch
7//! bins, an argmax over the bin activations, and the standard CREPE bin→frequency mapping.
8//!
9//! Blob convention: `dims = [num_bins, frame_len]`. `data` is a row-major `num_bins * frame_len`
10//! projection followed by `num_bins` biases. Per bin `act_b = bias_b + Σ_i proj[b,i] * frame[i]`;
11//! the argmax bin maps to a frequency via CREPE's cents grid (bin 0 = `CREPE_CENTS_BASE` cents
12//! above 10 Hz, `CREPE_CENTS_STEP` cents per bin). The forward pass is the hot path and allocates
13//! nothing (streaming argmax over the caller's frame buffer).
14
15use crate::models::loader::{parse_weight_blob, require_weights, WeightBlob, WeightState};
16use crate::types::AudioError;
17
18/// CREPE cents grid: bin 0 sits this many cents above the 10 Hz reference.
19const CREPE_CENTS_BASE: f32 = 1997.379_4;
20/// Cents per pitch bin (CREPE's canonical 20-cent spacing).
21const CREPE_CENTS_STEP: f32 = 20.0;
22/// Reference frequency for the cents grid (Hz).
23const CREPE_REF_HZ: f32 = 10.0;
24
25/// Learned CREPE pitch head. Fail-closed: `Absent` state ⇒ inference abstains.
26#[derive(Debug, Default)]
27pub struct CrepeHead {
28    pub state: WeightState,
29}
30
31impl CrepeHead {
32    /// Construct with no weights — fails closed until [`CrepeHead::load`] succeeds.
33    pub fn new() -> Self {
34        Self {
35            state: WeightState::Absent,
36        }
37    }
38
39    /// Load weights from a P64 blob (cold path).
40    pub fn load(&mut self, bytes: &[u8]) -> Result<(), AudioError> {
41        let blob = parse_weight_blob(bytes)?;
42        validate_shape(&blob)?;
43        self.state = WeightState::Loaded(blob);
44        Ok(())
45    }
46
47    /// Whether a real forward pass is available.
48    pub fn is_ready(&self) -> bool {
49        self.state.is_loaded()
50    }
51
52    /// Estimate fundamental frequency (Hz) from a single `frame`.
53    ///
54    /// - No weights ⇒ `Err(BackendUnavailable)` (abstain; no fabricated pitch).
55    /// - `sample_rate` must be non-zero, else `InvalidParameter`.
56    /// - `frame.len()` must equal the blob's `frame_len`, else `InvalidParameter`.
57    ///
58    /// Returns the argmax-bin frequency. Hot path: no allocation.
59    pub fn infer_pitch(&self, frame: &[f32], sample_rate: u32) -> Result<f32, AudioError> {
60        let blob = require_weights(&self.state)?;
61        if sample_rate == 0 {
62            return Err(AudioError::InvalidParameter);
63        }
64        let (num_bins, frame_len) = shape(blob)?;
65        if frame.len() != frame_len {
66            return Err(AudioError::InvalidParameter);
67        }
68
69        // Streaming argmax over bin activations (zero-heap).
70        let bias_off = num_bins * frame_len;
71        let mut best_bin = 0usize;
72        let mut best_act = f32::NEG_INFINITY;
73        for b in 0..num_bins {
74            let row = b * frame_len;
75            let mut acc = blob.data[bias_off + b];
76            for i in 0..frame_len {
77                acc += blob.data[row + i] * frame[i];
78            }
79            if acc > best_act {
80                best_act = acc;
81                best_bin = b;
82            }
83        }
84
85        Ok(bin_to_hz(best_bin))
86    }
87}
88
89/// CREPE bin → frequency (Hz): `cents = base + step*bin`, `f = ref * 2^(cents/1200)`.
90#[inline]
91fn bin_to_hz(bin: usize) -> f32 {
92    let cents = CREPE_CENTS_BASE + CREPE_CENTS_STEP * bin as f32;
93    CREPE_REF_HZ * (cents / 1200.0 * core::f32::consts::LN_2).exp()
94}
95
96fn shape(blob: &WeightBlob) -> Result<(usize, usize), AudioError> {
97    if blob.dims.len() != 2 {
98        return Err(AudioError::BackendUnavailable);
99    }
100    Ok((blob.dims[0] as usize, blob.dims[1] as usize))
101}
102
103fn validate_shape(blob: &WeightBlob) -> Result<(), AudioError> {
104    let (num_bins, frame_len) = shape(blob)?;
105    if num_bins == 0 || frame_len == 0 {
106        return Err(AudioError::BackendUnavailable);
107    }
108    let need = num_bins * frame_len + num_bins;
109    if blob.data.len() != need {
110        return Err(AudioError::BackendUnavailable);
111    }
112    Ok(())
113}
114
115#[cfg(test)]
116mod tests {
117    use super::*;
118    use crate::models::loader::{make_blob, write_weight_blob};
119
120    // 3 bins, frame_len 2. Bin b fires on a distinct frame pattern.
121    fn synthetic_blob() -> Vec<u8> {
122        let data = vec![
123            // proj rows (bin-major)
124            1.0, 0.0, // bin0 -> feature[0]
125            0.0, 1.0, // bin1 -> feature[1]
126            1.0, 1.0, // bin2 -> both
127            // biases
128            0.0, 0.0, 0.0,
129        ];
130        write_weight_blob(&make_blob(vec![3, 2], data))
131    }
132
133    #[test]
134    fn absent_abstains_never_fabricates() {
135        let head = CrepeHead::new();
136        assert_eq!(
137            head.infer_pitch(&[0.5, 0.5], 16_000),
138            Err(AudioError::BackendUnavailable)
139        );
140    }
141
142    #[test]
143    fn loaded_runs_reference_forward_pass() {
144        let mut head = CrepeHead::new();
145        head.load(&synthetic_blob()).expect("load");
146        assert!(head.is_ready());
147        // frame favours bin1 (feature[1] large) → its mapped frequency.
148        let f = head.infer_pitch(&[0.0, 9.0], 16_000).expect("infer");
149        assert!((f - bin_to_hz(1)).abs() < 1e-3);
150        assert!(f > 0.0);
151    }
152
153    #[test]
154    fn zero_sample_rate_invalid() {
155        let mut head = CrepeHead::new();
156        head.load(&synthetic_blob()).expect("load");
157        assert_eq!(
158            head.infer_pitch(&[0.0, 1.0], 0),
159            Err(AudioError::InvalidParameter)
160        );
161    }
162
163    #[test]
164    fn wrong_frame_len_invalid() {
165        let mut head = CrepeHead::new();
166        head.load(&synthetic_blob()).expect("load");
167        assert_eq!(
168            head.infer_pitch(&[1.0, 2.0, 3.0], 16_000),
169            Err(AudioError::InvalidParameter)
170        );
171    }
172
173    #[test]
174    fn bin_mapping_is_monotonic_and_positive() {
175        // Higher bins map to higher frequencies; all positive.
176        assert!(bin_to_hz(0) > 0.0);
177        assert!(bin_to_hz(10) > bin_to_hz(0));
178    }
179}