Skip to main content

qualia_audio/models/separation/
learned.rs

1//! Learned (demucs / open-unmix / band-split RNN class) source separation — **fail-closed stub**.
2//!
3//! A learned separator estimates per-source masks (or waveforms) from a neural network whose
4//! weights are not present in this build. Per the project's honesty rule, this module must never
5//! fabricate stems: with no weights loaded there is no faithful separation to return, so the only
6//! correct behaviour is to abstain. [`separate_learned`] therefore always returns
7//! [`AudioError::BackendUnavailable`] (the `NeedsWeights` signal).
8//!
9//! When real weights are wired (a P64 head, gated on the principal per ADR 007 / delivery plan
10//! Waves 7–8), this stub is replaced by the actual inference path. Until then, callers get an
11//! explicit, honest failure rather than plausible-looking noise. For weight-free separation use
12//! the classical masking in [`crate::models::separation::apply_soft_mask`].
13
14use crate::types::AudioError;
15
16/// Attempt learned, demucs-class source separation of a mixture magnitude spectrum into
17/// `n_stems` stems written contiguously into `out_stems` (`n_stems × mixture_mag.len()`).
18///
19/// **Always fails closed.** No weights are bundled, so this returns
20/// [`AudioError::BackendUnavailable`] without touching `out_stems` — it never fabricates stems.
21///
22/// # Errors
23/// Always [`AudioError::BackendUnavailable`] (NeedsWeights).
24pub fn separate_learned(
25    mixture_mag: &[f32],
26    n_stems: usize,
27    out_stems: &mut [f32],
28) -> Result<usize, AudioError> {
29    // Bind the parameters so the signature is honest about what a real backend would consume,
30    // and so the stub cannot silently write partial output.
31    let _ = (mixture_mag, n_stems, &out_stems);
32    Err(AudioError::BackendUnavailable)
33}
34
35#[cfg(test)]
36mod tests {
37    use super::*;
38
39    #[test]
40    fn always_fails_closed_with_backend_unavailable() {
41        let mix = [1.0f32, 2.0, 3.0];
42        let mut out = [0.0f32; 6]; // room for 2 stems
43        let r = separate_learned(&mix, 2, &mut out);
44        assert_eq!(r, Err(AudioError::BackendUnavailable));
45    }
46
47    #[test]
48    fn never_writes_fabricated_stems() {
49        let mix = [1.0f32, 2.0, 3.0];
50        let mut out = [7.0f32; 6];
51        let _ = separate_learned(&mix, 2, &mut out);
52        // Output buffer untouched — no invented audio.
53        assert!(
54            out.iter().all(|&x| x == 7.0),
55            "stub must not fabricate stems"
56        );
57    }
58}