qualia_audio/aqa/mos/dnsmos.rs
1//! DNSMOS — non-intrusive (no-reference) learned MOS predictor. **NeedsWeights.**
2//!
3//! DNSMOS (Microsoft, ICASSP 2021) is a *learned* model: a CNN trained on
4//! crowd-sourced ratings predicts a Mean Opinion Score from a single degraded
5//! clip, with no clean reference. There is no closed-form, hand-written way to
6//! produce that number — the score IS the network. Without the trained weights we
7//! cannot compute a MOS, and the project rule is absolute: **never fabricate a
8//! MOS.**
9//!
10//! Therefore this function **fails closed**: with no weights it returns
11//! [`AudioError::BackendUnavailable`]. It does not, under any circumstance, return
12//! an invented number. When weights are supplied the loader is likewise not yet
13//! present, so it also fails closed rather than guessing — surfaced as
14//! `BackendUnavailable` (backend not wired), not as a fake score.
15
16use crate::types::AudioError;
17
18/// Predict a DNSMOS quality score for `signal`.
19///
20/// - `signal`: mono degraded audio (no reference needed).
21/// - `weights`: the trained DNSMOS model weights. `None` (or, currently, any
22/// value) means the learned backend is unavailable.
23///
24/// # Fails closed
25///
26/// Returns [`AudioError::BackendUnavailable`] when `weights` is `None`. A learned
27/// MOS cannot be synthesised without the model, and fabricating one is forbidden.
28/// A future weights loader will replace the `Some(_)` arm; until then it too fails
29/// closed rather than returning a guessed MOS.
30pub fn dnsmos(signal: &[f32], weights: Option<&[u8]>) -> Result<f32, AudioError> {
31 // Reject obviously empty input before considering the backend.
32 if signal.is_empty() {
33 return Err(AudioError::MalformedAudio);
34 }
35
36 match weights {
37 // No model → no MOS. Fail closed; NEVER fabricate a number.
38 None => Err(AudioError::BackendUnavailable),
39 // Weights provided but the learned inference backend is not yet wired.
40 // Still fail closed — do not invent a score from unvalidated bytes.
41 Some(_bytes) => Err(AudioError::BackendUnavailable),
42 }
43}
44
45#[cfg(test)]
46mod tests {
47 use super::*;
48
49 #[test]
50 fn no_weights_fails_closed_never_returns_mos() {
51 let sig = vec![0.1f32, -0.2, 0.3, -0.4, 0.5];
52 let out = dnsmos(&sig, None);
53 assert_eq!(
54 out,
55 Err(AudioError::BackendUnavailable),
56 "DNSMOS with no weights must fail closed, not return a MOS"
57 );
58 // Explicitly assert it is NOT any numeric MOS.
59 assert!(out.is_err());
60 }
61
62 #[test]
63 fn weights_present_still_fails_closed_until_backend_wired() {
64 let sig = vec![0.1f32, 0.2, 0.3];
65 let dummy_weights = [0u8; 8];
66 assert_eq!(
67 dnsmos(&sig, Some(&dummy_weights)),
68 Err(AudioError::BackendUnavailable),
69 "unwired backend must fail closed, not guess a MOS"
70 );
71 }
72
73 #[test]
74 fn empty_signal_is_malformed() {
75 assert_eq!(dnsmos(&[], None), Err(AudioError::MalformedAudio));
76 }
77}