1use 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#[inline]
88pub fn erb_bandwidth_hz(f_hz: f64) -> f64 {
89 24.7 * (4.37 * (f_hz / 1000.0) + 1.0)
90}
91
92#[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#[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#[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
115pub 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 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
147pub 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
160pub 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
172pub 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#[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
256pub 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 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}