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}