Skip to main content

qualia_core_db/audio/qac/profiles/
perceptual.rs

1//! Q06 Mode `0x0105`: Perceptual auditory features (`4 * feature_count` B, `Schema 203`).
2//!
3//! Enforces strict unit/scale separation (`dB-SPL`, `sone`, `LUFS`, `mel`, `MFCC`, ERB/Bark/Gammatone),
4//! explicit filterbank definitions (`centers_hz`, FIR `coefficients`, integration, `reference_pressure_pa`),
5//! ITU-R BS.1770-4/5 gating profiles separate from SPL, non-infinite silence handling, and
6//! raw source / legacy `Q4AU v1/v2` feature preservation (`Schema 209`).
7
8use std::f64::consts::PI;
9
10use crate::audio::audio_spectral_sheet::{
11    parse_sidecar_header, AudioSpectralSidecarHeader, SpectralV2SubHeader,
12    SPECTRAL_V2_SUBHEADER_MAGIC,
13};
14
15use super::envelope::*;
16use super::ray_rir::push_aux_f32_entry;
17use super::types::*;
18
19#[path = "perceptual_helpers.rs"]
20mod perceptual_helpers;
21pub use perceptual_helpers::*;
22
23pub const REFERENCE_PRESSURE_AIR_PA: f64 = 20.0e-6;
24
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum PerceptualScale {
27    LinearEnergy,
28    LogPower,
29    DbSpl,
30    Mel,
31    Mfcc,
32    Sone,
33    Lufs,
34    GammatoneEnergy,
35    ErbEnergy,
36    BarkEnergy,
37}
38
39impl PerceptualScale {
40    pub const fn as_str(self) -> &'static str {
41        match self {
42            Self::LinearEnergy => "linear-energy",
43            Self::LogPower => "log-power",
44            Self::DbSpl => "dB-SPL",
45            Self::Mel => "mel",
46            Self::Mfcc => "MFCC",
47            Self::Sone => "sone",
48            Self::Lufs => "LUFS",
49            Self::GammatoneEnergy => "gammatone-energy",
50            Self::ErbEnergy => "erb-energy",
51            Self::BarkEnergy => "bark-energy",
52        }
53    }
54
55    pub const fn expected_units(self) -> &'static str {
56        match self {
57            Self::DbSpl => "dB-SPL",
58            Self::Sone => "sone",
59            Self::Lufs => "LUFS",
60            Self::Mel => "mel",
61            _ => "1",
62        }
63    }
64
65    pub fn parse(s: &str) -> Result<Self, ProfileError> {
66        match s {
67            "linear-energy" => Ok(Self::LinearEnergy),
68            "log-power" => Ok(Self::LogPower),
69            "dB-SPL" => Ok(Self::DbSpl),
70            "mel" => Ok(Self::Mel),
71            "MFCC" => Ok(Self::Mfcc),
72            "sone" => Ok(Self::Sone),
73            "LUFS" => Ok(Self::Lufs),
74            "gammatone-energy" => Ok(Self::GammatoneEnergy),
75            "erb-energy" => Ok(Self::ErbEnergy),
76            "bark-energy" => Ok(Self::BarkEnergy),
77            _ => Err(ProfileError::InvalidMetadata("perceptual scale")),
78        }
79    }
80}
81
82// ---------------------------------------------------------------------------
83// Auditory scale conversions & FIR Gammatone / BS.1770 / SPL oracles
84// ---------------------------------------------------------------------------
85
86/// Glasberg & Moore (1990) ERB bandwidth in Hz at center frequency `f_hz >= 0`.
87#[inline]
88pub fn erb_bandwidth_hz(f_hz: f64) -> f64 {
89    24.7 * (4.37 * (f_hz / 1000.0) + 1.0)
90}
91
92/// Glasberg & Moore ERB-rate number scale (`Cams`).
93#[inline]
94pub fn hz_to_erb_number(f_hz: f64) -> f64 {
95    21.4 * (4.37e-3 * f_hz + 1.0).log10()
96}
97
98/// Zwicker analytical Bark scale conversion.
99#[inline]
100pub fn hz_to_bark(f_hz: f64) -> f64 {
101    13.0 * (0.00076 * f_hz).atan() + 3.5 * ((f_hz / 7500.0).powi(2)).atan()
102}
103
104/// HTK Mel conversion (`2595 * log10(1 + f / 700)`).
105#[inline]
106pub fn hz_to_mel_htk(f_hz: f64) -> f64 {
107    2595.0 * (1.0 + f_hz / 700.0).log10()
108}
109
110#[inline]
111pub fn mel_to_hz_htk(mel: f64) -> f64 {
112    700.0 * (10.0f64.powf(mel / 2595.0) - 1.0)
113}
114
115/// Synthesizes a unity-peak-gain 4th-order real Gammatone FIR filterbank impulse response
116/// (`h[n]`) at `center_hz` and `sample_rate_hz`.
117pub fn gammatone_fir_impulse(
118    center_hz: f64,
119    sample_rate_hz: f64,
120    taps: usize,
121) -> Result<Vec<f32>, ProfileError> {
122    if !center_hz.is_finite()
123        || !sample_rate_hz.is_finite()
124        || center_hz <= 0.0
125        || center_hz >= 0.5 * sample_rate_hz
126        || taps == 0
127    {
128        return Err(ProfileError::InvalidMetadata("gammatone filter parameters"));
129    }
130    let b = 1.019 * erb_bandwidth_hz(center_hz);
131    let two_pi_b = 2.0 * PI * b;
132    let two_pi_f = 2.0 * PI * center_hz;
133    let mut raw = Vec::with_capacity(taps);
134    for n in 0..taps {
135        let t = (n as f64) / sample_rate_hz;
136        let env = t.powi(3) * (-two_pi_b * t).exp();
137        raw.push(env * (two_pi_f * t).cos());
138    }
139    // Normalize gain so DC-free passband response at center_hz equals 1.0 (DTFT magnitude).
140    let mag_fc = dtft_magnitude(&raw, center_hz / sample_rate_hz);
141    if !mag_fc.is_finite() || mag_fc <= 0.0 {
142        return Err(ProfileError::InvalidMetadata("gammatone normalization"));
143    }
144    Ok(raw.into_iter().map(|v| (v / mag_fc) as f32).collect())
145}
146
147/// Evaluates DTFT magnitude `|sum_n h[n] * exp(-i * 2*pi*nu*n)|` at normalized freq `nu = f/fs`.
148pub fn dtft_magnitude(ir: &[f64], normalized_freq: f64) -> f64 {
149    let mut re = 0.0f64;
150    let mut im = 0.0f64;
151    let w = 2.0 * PI * normalized_freq;
152    for (n, &h) in ir.iter().enumerate() {
153        let ang = w * (n as f64);
154        re += h * ang.cos();
155        im -= h * ang.sin();
156    }
157    (re * re + im * im).sqrt()
158}
159
160/// Exact dB-SPL from finite RMS acoustic pressure `rms_pa >= 0` (`p_ref > 0`).
161/// Returns `Err(SampleStatus::Silence)` on exact zero RMS instead of `-inf`!
162pub fn rms_pa_to_db_spl(rms_pa: f64, reference_pa: f64) -> Result<f64, SampleStatus> {
163    if !rms_pa.is_finite() || rms_pa < 0.0 || !reference_pa.is_finite() || reference_pa <= 0.0 {
164        return Err(SampleStatus::Unknown);
165    }
166    if rms_pa == 0.0 {
167        return Err(SampleStatus::Silence);
168    }
169    Ok(20.0 * (rms_pa / reference_pa).log10())
170}
171
172/// ITU-R BS.1770-4/5 two-stage gated integrated loudness in LUFS (`-70 LKFS` absolute, `-10 LU` relative).
173/// `block_mean_squares` holds `[channel]` mean-square energies per 400 ms gating block.
174pub fn bs1770_integrated_lufs(
175    block_mean_squares: &[&[f64]],
176    channel_weights: &[f64],
177) -> Result<f64, SampleStatus> {
178    if block_mean_squares.is_empty() || channel_weights.is_empty() {
179        return Err(SampleStatus::Silence);
180    }
181    let ch = channel_weights.len();
182    let mut gating_powers = Vec::with_capacity(block_mean_squares.len());
183    for &blk in block_mean_squares {
184        if blk.len() != ch || blk.iter().any(|v| !v.is_finite() || *v < 0.0) {
185            return Err(SampleStatus::Unknown);
186        }
187        let sum_w: f64 = blk.iter().zip(channel_weights).map(|(&z, &g)| g * z).sum();
188        if sum_w <= 0.0 {
189            continue;
190        }
191        let lj = -0.691 + 10.0 * sum_w.log10();
192        if lj > -70.0 {
193            gating_powers.push((lj, blk));
194        }
195    }
196    if gating_powers.is_empty() {
197        return Err(SampleStatus::Silence);
198    }
199    let mut mean_ch = vec![0.0f64; ch];
200    for &(_, blk) in &gating_powers {
201        for (dst, &z) in mean_ch.iter_mut().zip(blk.iter()) {
202            *dst += z;
203        }
204    }
205    let n_abs = gating_powers.len() as f64;
206    let abs_sum: f64 = mean_ch
207        .iter()
208        .zip(channel_weights)
209        .map(|(&m, &g)| g * (m / n_abs))
210        .sum();
211    if abs_sum <= 0.0 {
212        return Err(SampleStatus::Silence);
213    }
214    let gamma_r = -0.691 + 10.0 * abs_sum.log10() - 10.0;
215
216    let mut rel_mean = vec![0.0f64; ch];
217    let mut n_rel = 0usize;
218    for &(lj, blk) in &gating_powers {
219        if lj > gamma_r {
220            for (dst, &z) in rel_mean.iter_mut().zip(blk.iter()) {
221                *dst += z;
222            }
223            n_rel += 1;
224        }
225    }
226    if n_rel == 0 {
227        return Err(SampleStatus::Silence);
228    }
229    let rel_sum: f64 = rel_mean
230        .iter()
231        .zip(channel_weights)
232        .map(|(&m, &g)| g * (m / (n_rel as f64)))
233        .sum();
234    if rel_sum <= 0.0 {
235        return Err(SampleStatus::Silence);
236    }
237    Ok(-0.691 + 10.0 * rel_sum.log10())
238}
239
240/// Descriptor configuration for `mode 0x0105` perceptual feature containers.
241#[derive(Debug, Clone)]
242pub struct PerceptualWriteSpec<'a> {
243    pub algorithm_uri: &'a str,
244    pub algorithm_version: &'a str,
245    pub scale: PerceptualScale,
246    pub feature_count: u32,
247    pub feature_names: &'a str,
248    pub centers_hz: Option<&'a [f32]>,
249    pub filter_coefficients: Option<&'a [f32]>,
250    pub reference_pressure_pa: Option<f64>,
251    pub channel_weights: Option<&'a [f32]>,
252    pub gating_profile: Option<&'a str>,
253    pub frame_rate: RationalRate,
254}
255
256/// Writes canonical QAC v1 `mode 0x0105` perceptual feature stream (`Schema 203` + `205`).
257pub fn write_perceptual_features_qac(
258    frames: &[&[f32]],
259    spec: &PerceptualWriteSpec<'_>,
260    clock: &ClockSpec,
261    provenance: &ProvenanceSpec<'_>,
262    validity_mask: Option<&[u8]>,
263    limits: ProfileLimits,
264) -> Result<Vec<u8>, ProfileError> {
265    if frames.is_empty() || spec.feature_count == 0 {
266        return Err(ProfileError::InvalidPayloadLength);
267    }
268    if spec.scale == PerceptualScale::DbSpl && spec.reference_pressure_pa.is_none() {
269        return Err(ProfileError::InvalidMetadata("dB-SPL requires reference_pressure_pa"));
270    }
271    if spec.scale == PerceptualScale::Lufs
272        && spec.gating_profile.map_or(true, |g| g.is_empty() || g == "none")
273    {
274        return Err(ProfileError::InvalidMetadata("LUFS requires explicit BS.1770 gating_profile"));
275    }
276    if let Some(m) = validity_mask {
277        if m.len() != frames.len() || m.iter().any(|&b| b > 1) {
278            return Err(ProfileError::InvalidValidityBits);
279        }
280    }
281    let width = spec.feature_count as usize;
282    let stride = width * 4;
283    let mut main_payload = vec![0u8; frames.len() * stride];
284    for (idx, row) in frames.iter().enumerate() {
285        if row.len() != width {
286            return Err(ProfileError::InvalidPayloadLength);
287        }
288        let ext_valid = validity_mask.map_or(true, |m| m[idx] != 0);
289        for (c, &v) in row.iter().enumerate() {
290            if !v.is_finite() {
291                return Err(ProfileError::NonFiniteFloat);
292            }
293            require_zero_when_masked(ext_valid, v)?;
294            write_f32_finite(&mut main_payload, idx * stride + c * 4, v)?;
295        }
296    }
297
298    let mut meta = MetadataBuilder::new();
299    meta.push_clock(1, clock)?;
300    meta.push_provenance(3, provenance)?;
301
302    // Canonical directory order on stream_id=1:
303    // Entry 1: mode 0x0105 (desc 6)
304    // Entry 2 (optional mask): mode 0x0106 (desc 7)
305    // Aux entries (desc 8 centers, desc 9 coeffs, desc 10 weights): mode 0x0107
306    let mut next_idx = 2u32;
307    let mask_idx = if validity_mask.is_some() {
308        let idx = next_idx;
309        next_idx += 1;
310        Some(idx)
311    } else {
312        None
313    };
314
315    let mut s203_fields = vec![
316        OwnedField::crit(1, OwnedValue::Utf8(spec.algorithm_uri.to_owned())),
317        OwnedField::crit(2, OwnedValue::Utf8(spec.algorithm_version.to_owned())),
318        OwnedField::crit(3, OwnedValue::U32(vec![spec.feature_count])),
319        OwnedField::crit(4, OwnedValue::Utf8(spec.scale.as_str().to_owned())),
320    ];
321    if let Some(p0) = spec.reference_pressure_pa {
322        s203_fields.push(OwnedField::opt(8, OwnedValue::F64(vec![p0])));
323    }
324    if let Some(gp) = spec.gating_profile {
325        s203_fields.push(OwnedField::opt(10, OwnedValue::Utf8(gp.to_owned())));
326    }
327    if !spec.feature_names.is_empty() {
328        s203_fields.push(OwnedField::opt(11, OwnedValue::Utf8(spec.feature_names.to_owned())));
329    }
330
331    let mut entries = vec![OwnedEntry {
332        mode: MODE_PERCEPTUAL_FEATURES,
333        flags: 3,
334        stream_id: 1,
335        frame_id: 0,
336        start_tick: 0,
337        time_count: frames.len() as u64,
338        spatial_key: 0,
339        record_count: frames.len() as u64,
340        stride: stride as u32,
341        descriptor_id: 6,
342        payload: main_payload,
343    }];
344    if let Some(mb) = validity_mask {
345        entries.push(push_validity_mask_entry(
346            &mut meta,
347            7,
348            3,
349            1,
350            0,
351            frames.len() as u64,
352            mb,
353        )?);
354    }
355
356    if let Some(centers) = spec.centers_hz {
357        s203_fields.push(OwnedField::opt(5, OwnedValue::EntryRefs(vec![next_idx])));
358        next_idx += 1;
359        let mut e = push_aux_f32_entry(&mut meta, 8, 3, "filterbank-centers-hz", "Hz", 1, AuxScalar::F32, centers)?;
360        e.stream_id = 1;
361        entries.push(e);
362    }
363    if let Some(coeffs) = spec.filter_coefficients {
364        s203_fields.push(OwnedField::opt(6, OwnedValue::EntryRefs(vec![next_idx])));
365        next_idx += 1;
366        let mut e = push_aux_f32_entry(&mut meta, 9, 3, "filterbank-coefficients", "1", 1, AuxScalar::F32, coeffs)?;
367        e.stream_id = 1;
368        entries.push(e);
369    }
370    if let Some(cw) = spec.channel_weights {
371        s203_fields.push(OwnedField::opt(9, OwnedValue::EntryRefs(vec![next_idx])));
372        let mut e = push_aux_f32_entry(&mut meta, 10, 3, "loudness-channel-weights", "1", 1, AuxScalar::F32, cw)?;
373        e.stream_id = 1;
374        entries.push(e);
375    }
376
377    meta.push_block(OwnedBlock {
378        id: 4,
379        schema_type: 203,
380        revision: 1,
381        critical: true,
382        fields: s203_fields,
383    })?;
384    let shape = [frames.len() as u64, u64::from(spec.feature_count)];
385    meta.push_model_grid(
386        5,
387        &ModelGridSpec {
388            model_uri: spec.algorithm_uri,
389            model_version: spec.algorithm_version,
390            discretization: Some("frame-feature-vector"),
391            component_offsets_xyz: &[],
392            component_time_offset_num: &[],
393            component_time_offset_den: &[],
394            timestep: Some(spec.frame_rate),
395            tolerance_abs: None,
396            tolerance_rel: None,
397            tensor_shape: &shape,
398            component_names: spec.feature_names,
399        },
400    )?;
401
402    let valid_count = validity_mask.map(|m| m.iter().filter(|&&b| b == 1).count() as u64);
403    let ext = [4u32, 5u32];
404    meta.push_descriptor(
405        6,
406        &DescriptorSpec {
407            clock_id: Some(1),
408            frame_id: None,
409            provenance_id: 3,
410            medium_id: None,
411            transform_id: None,
412            calibration_id: None,
413            quantity: "perceptual-features",
414            units: spec.scale.expected_units(),
415            channels: Some(1),
416            layout: Some("frame-feature"),
417            scalar: Some(AuxScalar::F32),
418            model_uri: "urn:qac:mode:0x0105:v1",
419            sample_rate: Some(spec.frame_rate),
420            valid_record_count: valid_count,
421            validity_mask_entry: mask_idx,
422            source_entries: &[],
423            extension_metadata: &ext,
424        },
425    )?;
426    assemble_qac_v1(&meta, &entries, limits)
427}