Skip to main content

qualia_audio/models/separation/
mask.rs

1//! Classical spectral masking for source separation. Given a mixture magnitude spectrum and a
2//! per-bin soft mask (each element in `[0, 1]`), the separated stem magnitude is the
3//! element-wise product `stem = mixture ⊙ mask`. This is the algorithmic core of ideal-ratio /
4//! Wiener-style masking; it invents nothing — it only re-weights energy the mixture already
5//! contains. Learned mask *estimation* (a demucs/openunmix network) is a separate,
6//! `NeedsWeights` concern (see `learned.rs`).
7//!
8//! Zero-heap: the caller supplies both the mask and the output buffer.
9
10use crate::types::AudioError;
11
12/// Apply a per-bin soft mask to a mixture magnitude spectrum: `out[k] = mixture_mag[k] * mask[k]`.
13///
14/// - `mixture_mag`: mixture magnitudes (any length `N`).
15/// - `mask`: `N` weights, each expected in `[0, 1]` (all-ones passes the mixture through,
16///   all-zeros yields silence). Values outside `[0, 1]` are applied as-is (caller's choice).
17/// - `out`: at least `N` floats; bins `0..N` are written.
18///
19/// # Errors
20/// - [`AudioError::InvalidParameter`] if `mask.len() != mixture_mag.len()`.
21/// - [`AudioError::OutputBufferTooSmall`] if `out` is shorter than `mixture_mag`.
22pub fn apply_soft_mask(
23    mixture_mag: &[f32],
24    mask: &[f32],
25    out: &mut [f32],
26) -> Result<(), AudioError> {
27    if mask.len() != mixture_mag.len() {
28        return Err(AudioError::InvalidParameter);
29    }
30    if out.len() < mixture_mag.len() {
31        return Err(AudioError::OutputBufferTooSmall);
32    }
33    for (o, (&m, &g)) in out.iter_mut().zip(mixture_mag.iter().zip(mask.iter())) {
34        *o = m * g;
35    }
36    Ok(())
37}
38
39/// Derive a **binary** mask from two reference magnitude spectra (the "ideal binary mask" when
40/// the references are the true stems): bin `k` is assigned to the target (`1.0`) when the target
41/// reference has at least as much magnitude there as the other reference, else `0.0`.
42///
43/// Equivalent to thresholding the ratio `target / (target + other)` at `0.5`, but computed by
44/// direct comparison to avoid a divide (and the `0/0` case). Zero-heap.
45///
46/// - `target_ref`, `other_ref`: reference magnitudes, equal length `N`.
47/// - `out_mask`: at least `N` floats; each written as `0.0` or `1.0`.
48///
49/// # Errors
50/// - [`AudioError::InvalidParameter`] if the two references differ in length.
51/// - [`AudioError::OutputBufferTooSmall`] if `out_mask` is shorter than the references.
52pub fn binary_mask_from_ratio(
53    target_ref: &[f32],
54    other_ref: &[f32],
55    out_mask: &mut [f32],
56) -> Result<(), AudioError> {
57    if target_ref.len() != other_ref.len() {
58        return Err(AudioError::InvalidParameter);
59    }
60    if out_mask.len() < target_ref.len() {
61        return Err(AudioError::OutputBufferTooSmall);
62    }
63    for (o, (&t, &n)) in out_mask
64        .iter_mut()
65        .zip(target_ref.iter().zip(other_ref.iter()))
66    {
67        *o = if t >= n { 1.0 } else { 0.0 };
68    }
69    Ok(())
70}
71
72#[cfg(test)]
73mod tests {
74    use super::*;
75
76    #[test]
77    fn all_ones_mask_passes_mixture_unchanged() {
78        let mix = [0.5f32, 1.0, 2.0, 0.25];
79        let mask = [1.0f32; 4];
80        let mut out = [0.0f32; 4];
81        apply_soft_mask(&mix, &mask, &mut out).expect("mask");
82        assert_eq!(out, mix);
83    }
84
85    #[test]
86    fn all_zeros_mask_yields_silence() {
87        let mix = [0.5f32, 1.0, 2.0, 0.25];
88        let mask = [0.0f32; 4];
89        let mut out = [9.0f32; 4];
90        apply_soft_mask(&mix, &mask, &mut out).expect("mask");
91        assert_eq!(out, [0.0, 0.0, 0.0, 0.0]);
92    }
93
94    #[test]
95    fn band_mask_isolates_that_band() {
96        // Keep only bins 1..3 (a mid band); zero the rest.
97        let mix = [1.0f32, 2.0, 3.0, 4.0, 5.0];
98        let mask = [0.0f32, 1.0, 1.0, 0.0, 0.0];
99        let mut out = [0.0f32; 5];
100        apply_soft_mask(&mix, &mask, &mut out).expect("mask");
101        assert_eq!(out, [0.0, 2.0, 3.0, 0.0, 0.0]);
102    }
103
104    #[test]
105    fn soft_mask_scales_energy() {
106        let mix = [4.0f32, 8.0];
107        let mask = [0.25f32, 0.5];
108        let mut out = [0.0f32; 2];
109        apply_soft_mask(&mix, &mask, &mut out).expect("mask");
110        assert_eq!(out, [1.0, 4.0]);
111    }
112
113    #[test]
114    fn binary_mask_assigns_dominant_bins() {
115        let target = [1.0f32, 0.2, 0.5, 0.0];
116        let other = [0.5f32, 0.8, 0.5, 0.1];
117        let mut mask = [0.0f32; 4];
118        binary_mask_from_ratio(&target, &other, &mut mask).expect("mask");
119        // t>=other: bin0 (1>=0.5), bin2 (0.5>=0.5). bin1 (0.2<0.8), bin3 (0<0.1).
120        assert_eq!(mask, [1.0, 0.0, 1.0, 0.0]);
121    }
122
123    #[test]
124    fn binary_then_apply_extracts_target_bins() {
125        let target = [3.0f32, 0.1, 2.0];
126        let other = [1.0f32, 0.9, 0.5];
127        let mix = [4.0f32, 1.0, 2.5]; // = target + other
128        let mut mask = [0.0f32; 3];
129        binary_mask_from_ratio(&target, &other, &mut mask).expect("mask");
130        let mut out = [0.0f32; 3];
131        apply_soft_mask(&mix, &mask, &mut out).expect("apply");
132        // target dominant in bins 0 and 2 -> keep mixture there, drop bin 1.
133        assert_eq!(out, [4.0, 0.0, 2.5]);
134    }
135
136    #[test]
137    fn rejects_length_mismatch_and_short_output() {
138        let mix = [1.0f32, 2.0];
139        let mask = [1.0f32];
140        let mut out = [0.0f32; 2];
141        assert_eq!(
142            apply_soft_mask(&mix, &mask, &mut out),
143            Err(AudioError::InvalidParameter)
144        );
145        let mask2 = [1.0f32, 1.0];
146        let mut small = [0.0f32; 1];
147        assert_eq!(
148            apply_soft_mask(&mix, &mask2, &mut small),
149            Err(AudioError::OutputBufferTooSmall)
150        );
151    }
152}