Skip to main content

qualia_audio/
capability_registry.rs

1//! Capability registry — the honest, machine-readable status of every audio capability.
2//!
3//! This is the single source of truth that the delivery-plan waves update as they land.
4//! Its statuses must match reality (CLAUDE.md §12 completeness / measurement honesty): a row is
5//! `Present` only when there is a real algorithm behind it with a numeric golden test — never a
6//! placeholder wearing the algorithm's name.
7//!
8//! Plan: `docs/plans/audio-algorithms-catalogue-delivery-plan-2026.md` (§6 sketch, §1 corrected baseline).
9//! The MCP `audio_features` tool and the Listen UI honesty chips read from here.
10
11#[path = "capability_registry_helpers.rs"]
12mod capability_registry_helpers;
13pub use capability_registry_helpers::*;
14
15/// Honest lifecycle status of a capability.
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub enum CapabilityStatus {
18    /// Real algorithm with a numeric golden test.
19    Present,
20    /// Exists but coarse / reference-only / mislabelled — not parity.
21    Partial,
22    /// Not implemented (or a placeholder wearing the name — treated as absent).
23    Missing,
24    /// Implemented but behind a Cargo feature that is off in this build.
25    FeatureDisabled,
26    /// Loader/path exists but fails closed until P64 weights are supplied.
27    NeedsWeights,
28}
29
30impl CapabilityStatus {
31    /// Short stable token for UI/MCP/JSON.
32    pub const fn as_str(self) -> &'static str {
33        match self {
34            CapabilityStatus::Present => "Present",
35            CapabilityStatus::Partial => "Partial",
36            CapabilityStatus::Missing => "Missing",
37            CapabilityStatus::FeatureDisabled => "FeatureDisabled",
38            CapabilityStatus::NeedsWeights => "NeedsWeights",
39        }
40    }
41}
42
43/// Broad capability domain (mirrors plan §3).
44#[derive(Debug, Clone, Copy, PartialEq, Eq)]
45pub enum Domain {
46    Io,
47    StandardDsp,
48    Envelope,
49    Filters,
50    Spectral,
51    Pitch,
52    Rhythm,
53    Tonal,
54    Structure,
55    Loudness,
56    Spatial,
57    Separation,
58    Speech,
59    Generative,
60    Aqa,
61    Midi,
62    CrossModal,
63    Sonification,
64}
65
66impl Domain {
67    /// `&str` form.
68    pub const fn as_str(self) -> &'static str {
69        match self {
70            Domain::Io => "io",
71            Domain::StandardDsp => "standard_dsp",
72            Domain::Envelope => "envelope",
73            Domain::Filters => "filters",
74            Domain::Spectral => "spectral",
75            Domain::Pitch => "pitch",
76            Domain::Rhythm => "rhythm",
77            Domain::Tonal => "tonal",
78            Domain::Structure => "structure",
79            Domain::Loudness => "loudness",
80            Domain::Spatial => "spatial",
81            Domain::Separation => "separation",
82            Domain::Speech => "speech",
83            Domain::Generative => "generative",
84            Domain::Aqa => "aqa",
85            Domain::Midi => "midi",
86            Domain::CrossModal => "cross_modal",
87            Domain::Sonification => "sonification",
88        }
89    }
90}
91
92/// One capability row.
93#[derive(Debug, Clone, Copy)]
94pub struct AudioCapability {
95    /// Stable snake_case identifier (e.g. `"mfcc"`, `"pitch_yin"`).
96    pub id: &'static str,
97    pub domain: Domain,
98    pub status: CapabilityStatus,
99    /// True if the hot path is caller-buffered (no per-call heap alloc).
100    pub zero_heap_hot: bool,
101    /// True if it supports streaming/block operation.
102    pub streaming: bool,
103    /// Name of the golden numeric test proving it, or `""` if none yet.
104    pub test_name: &'static str,
105    /// One-line honest note (what it really is / what's missing).
106    pub note: &'static str,
107}
108
109#[allow(unused_imports)]
110use CapabilityStatus::{FeatureDisabled, Missing};
111use CapabilityStatus::{NeedsWeights, Partial, Present};
112use Domain as D;
113
114/// Const constructor keeps the table terse and aligned.
115const fn cap(
116    id: &'static str,
117    domain: Domain,
118    status: CapabilityStatus,
119    zero_heap_hot: bool,
120    streaming: bool,
121    test_name: &'static str,
122    note: &'static str,
123) -> AudioCapability {
124    AudioCapability {
125        id,
126        domain,
127        status,
128        zero_heap_hot,
129        streaming,
130        test_name,
131        note,
132    }
133}
134
135/// The registry. Seeded 2026-07-18 from the plan's corrected §1 baseline.
136/// Waves flip rows to `Present` as real algorithms + golden tests land.
137pub const CAPABILITIES: &[AudioCapability] = &[
138    // ---- I/O -------------------------------------------------------------------------------
139    cap("wav_decode", D::Io, Present, true, false,
140        "wav_roundtrip", "RIFF PCM i16/i32/f32; no 24-bit/extensible"),
141    cap("wav_encode", D::Io, Present, true, false,
142        "wav_roundtrip", "mono i16 encode"),
143    cap("format_convert", D::Io, Present, true, false,
144        "i16_mono_round", "i16/i24/i32/f32 + channel downmix"),
145    cap("resample", D::Io, Present, true, true,
146        "anti_aliasing_downsample_rejects_out_of_band_tone", "windowed-sinc + polyphase, anti-aliased (linear path retained)"),
147    cap("metadata_reader", D::Io, Present, false, false,
148        "reads_inam_title_roundtrip", "RIFF LIST/INFO tags -> provenance pairs"),
149    cap("eqloud_loader", D::Io, Present, false, false,
150        "", "A-weighting equal-loudness + perceptual load"),
151    // ---- Standard DSP ----------------------------------------------------------------------
152    cap("fft", D::StandardDsp, Present, true, false,
153        "peak_bin_matches_cosine_frequency", "real radix-2 FFT + non-pow2 DFT fallback"),
154    cap("window", D::StandardDsp, Present, true, false,
155        "endpoint_zero_centre_one", "Hann/Hamming/Blackman/Blackman-Harris + apply"),
156    cap("framing_ola", D::StandardDsp, Present, true, true,
157        "hann_cola_constant_envelope", "FrameCutter + COLA overlap-add"),
158    cap("istft", D::StandardDsp, Present, true, true,
159        "stft_then_istft_reconstructs_signal", "WOLA ISTFT + Griffin-Lim; MAE<1e-3"),
160    cap("dct", D::StandardDsp, Present, true, false,
161        "dct2_matches_closed_form_reference", "orthonormal DCT-II"),
162    cap("stft", D::StandardDsp, Present, true, true,
163        "sine_has_energy", "real FFT, streaming caller-buffered, frames <=512 pow2"),
164    cap("cqt", D::StandardDsp, Present, true, true,
165        "cqt_stream_440_tone_peaks_at_bin_36", "streaming multi-frame CQT + approximate inverse"),
166    cap("zcr", D::StandardDsp, Present, true, true,
167        "", "real sign-change rate"),
168    cap("energy_rms", D::StandardDsp, Present, true, true,
169        "", "real RMS"),
170    cap("peak_detection", D::StandardDsp, Present, true, false,
171        "golden_three_peaks", "local-max picker + parabolic interp + min-distance"),
172    cap("autocorrelation", D::StandardDsp, Present, true, false,
173        "impulse_train_period", "normalised ACF + cross-correlation"),
174    // ---- Envelope / SFX --------------------------------------------------------------------
175    cap("envelope", D::Envelope, Present, true, true,
176        "tracks_monotonic_decay_of_decaying_sinusoid", "asymmetric-LP follower"),
177    cap("log_attack_time", D::Envelope, Present, true, false,
178        "recovers_hundred_ms_attack", "LogAttackTime over envelope"),
179    cap("temporal_ratios", D::Envelope, Present, true, false,
180        "recovers_peak_fraction", "max/min/tc-to-total, strong decay, SFX"),
181    // ---- Filters ---------------------------------------------------------------------------
182    cap("biquad", D::Filters, Present, true, true,
183        "impulse_response_first_taps_fir", "RBJ cookbook LP/HP/BP/BR/AP"),
184    cap("dc_removal", D::Filters, Present, true, true,
185        "constant_dc_converges_to_zero", "1st-order DC blocker"),
186    cap("smoothing_filters", D::Filters, Present, true, true,
187        "removes_single_impulse_spike", "median / moving-average / max"),
188    // ---- Spectral features -----------------------------------------------------------------
189    cap("mel_bands", D::Spectral, Present, true, true,
190        "tone_lands_in_a_single_band_region", "real triangular HTK mel bank; log_mel re-pointed"),
191    cap("mfcc", D::Spectral, Present, true, true,
192        "c0_dominates_for_single_tone", "mel -> ln -> DCT-II"),
193    cap("bark_erb_gfcc", D::Spectral, Present, true, true,
194        "erb_bandwidth_grows_with_frequency", "Bark/ERB banks + BFCC/GFCC"),
195    cap("spectral_flux", D::Spectral, Present, true, true,
196        "rising_energy_positive_flux", "true per-bin half-wave-rectified flux"),
197    cap("spectral_shape", D::Spectral, Present, true, true,
198        "flat_spectrum_is_unity_and_zero_db", "hfc/rolloff/flatness/contrast/complexity"),
199    cap("spectral_peaks", D::Spectral, Present, true, false,
200        "golden_peak_frequency", "parabolic sub-bin peaks; max-mag-freq"),
201    cap("lpc", D::Spectral, Present, true, false,
202        "recovers_ar2_coefficients", "Levinson-Durbin LPC + reflection"),
203    // ---- Pitch -----------------------------------------------------------------------------
204    cap("pitch_yin", D::Pitch, Present, true, true,
205        "yin_recovers_440hz", "real YIN: CMND+threshold+parabolic; 0.07 cents"),
206    cap("pitch_yin_fft", D::Pitch, Present, true, true,
207        "yin_fft_recovers_440hz", "YinFFT autocorrelation + confidence"),
208    cap("pitch_to_midi", D::Pitch, Present, true, true,
209        "jump_a4_to_b4_yields_two_notes", "hz<->midi + note ON/OFF segmentation; proposals w/ confidence"),
210    cap("pitch_salience", D::Pitch, Present, true, true,
211        "salience_peaks_at_fundamental", "harmonic salience function + peaks"),
212    cap("melody_contours", D::Pitch, Present, false, true,
213        "recovers_stepping_melody_and_abstains", "salience->contours->predominant Melodia-class; abstains"),
214    cap("multipitch", D::Pitch, Present, true, true,
215        "recovers_two_simultaneous_tones", "Klapuri iterative subtraction + multi-voice tracking; abstains"),
216    cap("pitch_crepe", D::Pitch, NeedsWeights, false, true,
217        "absent_abstains_never_fabricates", "P64 loader + fail-closed path built; needs weights"),
218    // ---- Rhythm ----------------------------------------------------------------------------
219    cap("onset_detection", D::Rhythm, Present, true, true,
220        "recovers_known_impulse_pattern", "true spectral-flux onset + adaptive threshold"),
221    cap("tempo", D::Rhythm, Present, true, false,
222        "peaks_at_true_tempo", "autocorrelation tempogram"),
223    cap("beat_tracking", D::Rhythm, Present, false, true,
224        "recovers_120_bpm", "comb-filter beat tracker + BPM histogram"),
225    // ---- Tonal -----------------------------------------------------------------------------
226    cap("chroma", D::Tonal, Present, true, true,
227        "golden_c_major_triad_peaks_at_c_e_g", "real HPCP (log2 pitch-class), parameterised tuning"),
228    cap("hpcp_key_chord", D::Tonal, Present, true, true,
229        "c_major_profile_returns_c_major", "HPCP + tuning + K-S key + chord; abstains"),
230    // ---- Structure -------------------------------------------------------------------------
231    cap("structure_segments", D::Structure, Present, true, false,
232        "golden_boundary_at_midpoint", "SSM + Foote novelty segmentation"),
233    // ---- Loudness --------------------------------------------------------------------------
234    cap("loudness_r128", D::Loudness, Present, true, true,
235        "integrated_lufs_minus20dbfs_sine", "BS.1770/EBU R128 integrated/momentary/short-term + LRA; -19.99 LUFS"),
236    cap("replay_gain", D::Loudness, Present, true, false,
237        "", "ReplayGain 2.0 (-18 LUFS target)"),
238    cap("dynamics_stats", D::Loudness, Present, true, true,
239        "sine_crest_is_root_two", "crest factor + moments + dyn complexity"),
240    // ---- Spatial ---------------------------------------------------------------------------
241    cap("hrtf_binaural", D::Spatial, Partial, true, true,
242        "", "analytic + synth HRIR; no measured KEMAR"),
243    cap("reverb", D::Spatial, Present, true, true,
244        "impulse_produces_bounded_decaying_tail", "Schroeder + FDN reverb + stereo mux/width; zero-alloc process"),
245    // ---- Separation ------------------------------------------------------------------------
246    cap("source_separation", D::Separation, Present, true, false,
247        "band_mask_isolates_that_band", "classical spectral masking (real); learned demucs = NeedsWeights"),
248    // ---- Speech ----------------------------------------------------------------------------
249    cap("vad_segment", D::Speech, Present, true, true,
250        "one_segment_covers_the_burst_not_the_silence", "multi-feature VAD (energy+flatness+ZCR) + hangover; silence stays unvoiced"),
251    cap("speech_asr", D::Speech, NeedsWeights, false, true,
252        "absent_abstains_never_fabricates", "P64 CTC loader + fail-closed greedy decode; needs HA6 model"),
253    // ---- Generative ------------------------------------------------------------------------
254    cap("vocoder", D::Generative, NeedsWeights, false, true,
255        "", "HiFi-GAN/BigVGAN via P64+Forge"),
256    cap("audio_tokens", D::Generative, Present, true, true,
257        "centroid_sum_round_trips_exactly", "RVQ + FSQ quantizer ABI (real codebook math)"),
258    cap("tts", D::Generative, NeedsWeights, false, true,
259        "", "2-sine placeholder; consent-gated"),
260    // ---- AQA -------------------------------------------------------------------------------
261    cap("aqa_intrusive", D::Aqa, Present, true, false,
262        "identical_signals_hit_clamped_maximum", "seg-SNR + log-spectral distance + PESQ-subset (pure Rust)"),
263    cap("aqa_mos", D::Aqa, NeedsWeights, false, false,
264        "no_weights_fails_closed_never_returns_mos", "DNSMOS/NISQA loader fails closed; never fabricates MOS"),
265    // ---- MIDI ------------------------------------------------------------------------------
266    cap("midi_message", D::Midi, Present, true, true,
267        "golden_running_status_two_note_ons", "MIDI 1.0 model + running-status stream parse"),
268    cap("midi_ump", D::Midi, Present, true, true,
269        "golden_ump32_note_on_roundtrip", "MIDI 2.0 UMP + 7↔16 scaling + MIDI-CI skeleton"),
270    cap("midi_smf", D::Midi, Present, false, false,
271        "round_trip_structure_and_bytes", "Standard MIDI File 0/1/2 I/O + tempo map"),
272    cap("midi_sequencer", D::Midi, Present, true, true,
273        "golden_480_ticks_is_half_second_at_120bpm", "PPQ transport/tracks/quantize + clock/MTC/MMC + MPE"),
274    cap("midi_tuning", D::Midi, Present, true, false,
275        "tuning_parse_pythagorean_ratio_fifth_is_exactly_three_halves", "Scala .scl/.kbm + MTS; non-12-TET; alloc-free lookup"),
276    cap("midi_synth", D::Midi, Present, true, true,
277        "full_pool_then_one_more_steals_oldest", "voice allocator + ADSR + osc voices; zero-alloc render"),
278    cap("midi_instrument", D::Midi, Present, false, false,
279        "golden_first_region", "SFZ/SF2/DLS loaders + licence-provenance resolver; ships NO content"),
280    cap("midi_bridge", D::Midi, Present, true, true,
281        "golden_note_on_round_trip", "MIDI<->SonicToken, pitch_midi->sequencer, SMF provenance"),
282    // ---- Cross-modal / sonification (already real) -----------------------------------------
283    cap("cross_modal_clock", D::CrossModal, Present, true, false,
284        "", "shared media clock; overlap != cause"),
285    cap("sonify", D::Sonification, Present, true, true,
286        "", "parametric event sonifier (U3 hear)"),
287];