Skip to main content

qualia_core_db/audio/qac/profiles/
hrir.rs

1//! Q05 Mode `0x0103`: HRIR / RIR FIR taps (`taps * 4` B) & legacy Q4AU v3 SOFA preservation.
2//!
3//! Strictly separates impulse sample rate (`Schema 204` keys 17/18) from measurement acquisition
4//! cadence (`Schema 3` keys 13/14), applies explicit per-receiver delays once relative to excitation
5//! origin, and performs lossless Q4AU v3 -> QAC v1 migration retaining unparsed original bytes (`Schema 209`).
6
7use super::envelope::*;
8use super::types::*;
9
10#[path = "hrir_helpers.rs"]
11mod hrir_helpers;
12pub use hrir_helpers::*;
13
14/// Static or temporally indexed HRIR/RIR payload specification.
15#[derive(Debug, Clone)]
16pub struct HrirWriteSpec<'a> {
17    pub representation: &'a str, // "HRIR" or "RIR"
18    pub taps: u32,
19    pub receivers: u32,
20    pub measurements: u32,
21    pub impulse_sample_rate: RationalRate,
22    pub delay_reference: &'a str,
23    pub sofa_convention: Option<&'a str>,
24    pub units: &'a str,
25    pub delays_samples: Option<&'a [f64]>,
26    pub source_positions_xyz: Option<&'a [[f32; 3]]>,
27    pub receiver_positions_xyz: Option<&'a [[f32; 3]]>,
28    /// Present ONLY when measurements form a uniform time series (distinct from `impulse_sample_rate`).
29    pub measurement_cadence: Option<(&'a ClockSpec, RationalRate)>,
30}
31
32/// Zero-heap borrowed view over verified `0x0103` FIR tap records (`[measurement][receiver][tap]`).
33pub struct HrirChunkView<'a> {
34    bytes: &'a [u8],
35    taps: usize,
36    receivers: usize,
37    measurements: usize,
38    mask: Option<&'a [u8]>,
39}
40
41impl<'a> HrirChunkView<'a> {
42    pub fn taps(&self) -> usize {
43        self.taps
44    }
45
46    pub fn receivers(&self) -> usize {
47        self.receivers
48    }
49
50    pub fn measurements(&self) -> usize {
51        self.measurements
52    }
53
54    pub fn record_count(&self) -> usize {
55        self.measurements * self.receivers
56    }
57
58    /// Reads exact FIR taps for `(measurement, receiver)` into caller buffer `out_taps[..taps]`.
59    pub fn read_impulse(
60        &self,
61        measurement: usize,
62        receiver: usize,
63        out_taps: &mut [f32],
64    ) -> Result<(), ProfileError> {
65        if measurement >= self.measurements || receiver >= self.receivers {
66            return Err(ProfileError::OutOfBoundsIndex("hrir measurement/receiver"));
67        }
68        if out_taps.len() != self.taps {
69            return Err(ProfileError::InvalidPayloadLength);
70        }
71        let rec_idx = measurement * self.receivers + receiver;
72        let stride = self.taps.checked_mul(4).ok_or(ProfileError::Overflow)?;
73        let start = rec_idx.checked_mul(stride).ok_or(ProfileError::Overflow)?;
74        let end = start.checked_add(stride).ok_or(ProfileError::Overflow)?;
75        let slice = self
76            .bytes
77            .get(start..end)
78            .ok_or(ProfileError::OutOfBoundsIndex("hrir slice"))?;
79        let ext_valid = self.mask.map_or(true, |m| m[rec_idx] != 0);
80        for (i, dst) in out_taps.iter_mut().enumerate() {
81            let v = read_f32_finite(slice, i * 4)?;
82            require_zero_when_masked(ext_valid, v)?;
83            *dst = v;
84        }
85        Ok(())
86    }
87}
88
89/// Exact tap arrival time in seconds relative to excitation origin:
90/// `(delay_samples + tap_index) * (impulse_rate_den / impulse_rate_num)`. Applied ONCE.
91pub fn tap_time_seconds(
92    delay_samples: f64,
93    tap_index: u32,
94    impulse_sample_rate: RationalRate,
95) -> Result<f64, ProfileError> {
96    if !delay_samples.is_finite() {
97        return Err(ProfileError::NonFiniteFloat);
98    }
99    let dt = (impulse_sample_rate.den as f64) / (impulse_sample_rate.num as f64);
100    Ok((delay_samples + f64::from(tap_index)) * dt)
101}
102
103/// Exact fractional-delay impulse interpolation oracle (`y(t)` at fractional sample `idx_f`).
104pub fn sample_delayed_impulse(taps: &[f32], delay_samples: f64, sample_idx: f64) -> f64 {
105    let shifted = sample_idx - delay_samples;
106    if shifted < 0.0 || shifted > (taps.len().saturating_sub(1)) as f64 {
107        return 0.0;
108    }
109    let i0 = shifted.floor() as usize;
110    let frac = shifted - (i0 as f64);
111    if i0 + 1 < taps.len() {
112        (1.0 - frac) * f64::from(taps[i0]) + frac * f64::from(taps[i0 + 1])
113    } else {
114        f64::from(taps[i0])
115    }
116}
117
118/// Exact discrete FIR convolution for one receiver response (applying optional `delay_samples` once).
119pub fn convolve_hrir(input: &[f32], taps: &[f32], out: &mut [f32]) -> Result<(), ProfileError> {
120    if out.len() != input.len() {
121        return Err(ProfileError::InvalidPayloadLength);
122    }
123    for (n, slot) in out.iter_mut().enumerate() {
124        let mut acc = 0.0f64;
125        for (k, &h) in taps.iter().enumerate() {
126            if n >= k {
127                acc += f64::from(input[n - k]) * f64::from(h);
128            }
129        }
130        *slot = acc as f32;
131    }
132    Ok(())
133}
134
135/// Writes canonical QAC v1 `mode 0x0103` HRIR/RIR container (plus optional delays & positions `0x0107`).
136pub fn write_hrir_qac(
137    impulses: &[f32],
138    spec: &HrirWriteSpec<'_>,
139    frame: &FrameSpec<'_>,
140    provenance: &ProvenanceSpec<'_>,
141    limits: ProfileLimits,
142) -> Result<Vec<u8>, ProfileError> {
143    if spec.representation != "HRIR" && spec.representation != "RIR" {
144        return Err(ProfileError::InvalidMetadata("representation must be HRIR or RIR"));
145    }
146    if spec.delay_reference != BASE_DELAY_REFERENCE && spec.delay_reference != LEGACY_DELAY_REFERENCE {
147        return Err(ProfileError::InvalidMetadata("invalid delay_reference"));
148    }
149    if spec.taps == 0 || spec.receivers == 0 || spec.measurements == 0 {
150        return Err(ProfileError::InvalidMetadata("taps/receivers/measurements must be > 0"));
151    }
152    if spec.taps > limits.max_taps || spec.receivers > limits.max_channels {
153        return Err(ProfileError::LimitExceeded);
154    }
155    let rec_count = u64::from(spec.measurements)
156        .checked_mul(u64::from(spec.receivers))
157        .ok_or(ProfileError::Overflow)?;
158    let expected_floats = rec_count
159        .checked_mul(u64::from(spec.taps))
160        .ok_or(ProfileError::Overflow)?;
161    if impulses.len() as u64 != expected_floats {
162        return Err(ProfileError::InvalidPayloadLength);
163    }
164    let stride = spec.taps.checked_mul(4).ok_or(ProfileError::Overflow)?;
165    let mut main_payload = vec![0u8; impulses.len() * 4];
166    write_f32_slice(&mut main_payload, 0, impulses)?;
167
168    let mut meta = MetadataBuilder::new();
169    let has_time = spec.measurement_cadence.is_some();
170    if let Some((clk, _)) = spec.measurement_cadence {
171        meta.push_clock(1, clk)?;
172    }
173    meta.push_frame(2, frame)?;
174    meta.push_provenance(3, provenance)?;
175
176    let mut entries = Vec::new();
177    let stream_id = if has_time { 1 } else { 0 };
178    let main_flags = if has_time { 3 } else { 1 };
179    let main_desc_id = 6u32;
180
181    // Canonical directory order: (stream_id, start_tick, spatial_key, mode, descriptor_id).
182    // Main entry uses mode 0x0103; auxiliary geometry/delays use mode 0x0107 at stream_id=0 or stream_id=main
183    // so 0x0103 < 0x0107 cleanly orders Main as Entry 1 and Aux arrays as Entry 2+.
184    let mut s204_fields = vec![
185        OwnedField::crit(1, OwnedValue::Utf8(spec.representation.to_owned())),
186        OwnedField::crit(8, OwnedValue::U32(vec![spec.taps])),
187        OwnedField::crit(9, OwnedValue::U32(vec![spec.receivers])),
188        OwnedField::crit(10, OwnedValue::U32(vec![spec.measurements])),
189        OwnedField::opt(13, OwnedValue::MetadataRefs(vec![2])),
190        OwnedField::crit(17, OwnedValue::U64(vec![spec.impulse_sample_rate.num])),
191        OwnedField::crit(18, OwnedValue::U64(vec![spec.impulse_sample_rate.den])),
192        OwnedField::crit(19, OwnedValue::Utf8(spec.delay_reference.to_owned())),
193    ];
194    if let Some(conv) = spec.sofa_convention {
195        validate_identifier_str(conv, "sofa_convention")?;
196        s204_fields.push(OwnedField::opt(12, OwnedValue::Utf8(conv.to_owned())));
197    }
198
199    let mut aux_desc_id = 7u32;
200    let mut next_entry_idx = 2u32;
201    let mut aux_entries = Vec::new();
202
203    if let Some(rx_pos) = spec.receiver_positions_xyz {
204        if rx_pos.len() != spec.receivers as usize {
205            return Err(ProfileError::InvalidPayloadLength);
206        }
207        let e = push_aux_f32_vec3_entry(&mut meta, aux_desc_id, 3, "receiver-positions", "m", rx_pos)?;
208        s204_fields.push(OwnedField::opt(5, OwnedValue::EntryRefs(vec![next_entry_idx])));
209        aux_entries.push(e);
210        aux_desc_id += 1;
211        next_entry_idx += 1;
212    }
213    if let Some(tx_pos) = spec.source_positions_xyz {
214        if tx_pos.len() != spec.measurements as usize {
215            return Err(ProfileError::InvalidPayloadLength);
216        }
217        let e = push_aux_f32_vec3_entry(&mut meta, aux_desc_id, 3, "source-positions", "m", tx_pos)?;
218        s204_fields.push(OwnedField::opt(6, OwnedValue::EntryRefs(vec![next_entry_idx])));
219        aux_entries.push(e);
220        aux_desc_id += 1;
221        next_entry_idx += 1;
222    }
223    if let Some(delays) = spec.delays_samples {
224        if delays.len() as u64 != rec_count {
225            return Err(ProfileError::InvalidPayloadLength);
226        }
227        let e = push_aux_f64_scalar_entry(&mut meta, aux_desc_id, 3, "delays-samples", "1", delays)?;
228        s204_fields.push(OwnedField::opt(7, OwnedValue::EntryRefs(vec![next_entry_idx])));
229        aux_entries.push(e);
230    }
231
232    meta.push_block(OwnedBlock {
233        id: 4,
234        schema_type: 204,
235        revision: 1,
236        critical: true,
237        fields: s204_fields,
238    })?;
239
240    let shape = [
241        u64::from(spec.measurements),
242        u64::from(spec.receivers),
243        u64::from(spec.taps),
244    ];
245    meta.push_model_grid(
246        5,
247        &ModelGridSpec {
248            model_uri: "urn:qac:model:hrir-fir:v1",
249            model_version: "1",
250            discretization: Some("discrete-fir-taps"),
251            component_offsets_xyz: &[],
252            component_time_offset_num: &[],
253            component_time_offset_den: &[],
254            timestep: None,
255            tolerance_abs: None,
256            tolerance_rel: None,
257            tensor_shape: &shape,
258            component_names: "hrir_tap",
259        },
260    )?;
261
262    let ext = [4u32, 5u32];
263    let (clock_id, sample_rate) = if let Some((_, rate)) = spec.measurement_cadence {
264        (Some(1), Some(rate))
265    } else {
266        (None, None)
267    };
268    meta.push_descriptor(
269        main_desc_id,
270        &DescriptorSpec {
271            clock_id,
272            frame_id: Some(2),
273            provenance_id: 3,
274            medium_id: None,
275            transform_id: None,
276            calibration_id: None,
277            quantity: "impulse-response",
278            units: spec.units,
279            channels: Some(spec.receivers),
280            layout: Some("measurement-receiver-tap"),
281            scalar: Some(AuxScalar::F32),
282            model_uri: "urn:qac:mode:0x0103:v1",
283            sample_rate,
284            valid_record_count: None,
285            validity_mask_entry: None,
286            source_entries: &[],
287            extension_metadata: &ext,
288        },
289    )?;
290
291    entries.push(OwnedEntry {
292        mode: MODE_HRIR_IMPULSE,
293        flags: main_flags,
294        stream_id,
295        frame_id: 2,
296        start_tick: 0,
297        time_count: if has_time { u64::from(spec.measurements) } else { 0 },
298        spatial_key: 0,
299        record_count: rec_count,
300        stride,
301        descriptor_id: main_desc_id,
302        payload: main_payload,
303    });
304    // Note: if stream_id == 1 on main entry, place aux at stream_id = 1 too? No: static aux at stream_id=0
305    // sorts BEFORE stream_id=1! So when has_time==true, aux at stream_id=0 comes first!
306    // Reorder cleanly if has_time==true by putting aux at stream_id=1 so main (0x0103) precedes aux (0x0107).
307    for mut aux in aux_entries {
308        aux.stream_id = stream_id;
309        entries.push(aux);
310    }
311    assemble_qac_v1(&meta, &entries, limits)
312}
313
314pub struct HrirDocumentView<'a> {
315    pub chunk: HrirChunkView<'a>,
316    pub representation: &'a str,
317    pub impulse_sample_rate: RationalRate,
318    pub delay_reference: &'a str,
319    pub delays_samples: Option<Vec<f64>>,
320    pub legacy_original_bytes: Option<&'a [u8]>,
321}
322
323/// Opens and fully validates `mode 0x0103` HRIR/RIR entry + optional delays & legacy origin.
324pub fn read_hrir_qac<'a>(
325    bytes: &'a [u8],
326    entry_index: u32,
327    limits: ProfileLimits,
328) -> Result<HrirDocumentView<'a>, ProfileError> {
329    let env = AdmittedEnvelope::open_alloc(bytes, limits)?;
330    let e = env.entry(entry_index)?;
331    if e.mode() != MODE_HRIR_IMPULSE {
332        return Err(ProfileError::InvalidMode(e.mode()));
333    }
334    let desc = env.descriptor_for_entry(e)?;
335    let s204 = env
336        .extension_block(desc, 204)?
337        .ok_or(ProfileError::MissingRequiredSchema(204))?;
338    let repr = field_str(field_req(s204, 1)?)?;
339    if repr != "HRIR" && repr != "RIR" {
340        return Err(ProfileError::InvalidMetadata("Schema 204 representation must be HRIR or RIR"));
341    }
342    let taps = field_u32(field_req(s204, 8)?)?;
343    let receivers = field_u32(field_req(s204, 9)?)?;
344    let measurements = field_u32(field_req(s204, 10)?)?;
345    if taps == 0 || receivers == 0 || measurements == 0 || taps > limits.max_taps {
346        return Err(ProfileError::InvalidMetadata("invalid HRIR dimensions"));
347    }
348    let impulse_sample_rate = RationalRate::new(
349        field_u64(field_req(s204, 17)?)?,
350        field_u64(field_req(s204, 18)?)?,
351    )?;
352    let delay_reference = field_str(field_req(s204, 19)?)?;
353    if delay_reference == LEGACY_DELAY_REFERENCE && env.extension_block(desc, 209)?.is_none() {
354        return Err(ProfileError::MissingRequiredSchema(209));
355    }
356    let expected_rec = u64::from(measurements)
357        .checked_mul(u64::from(receivers))
358        .ok_or(ProfileError::Overflow)?;
359    let expected_stride = taps.checked_mul(4).ok_or(ProfileError::Overflow)?;
360    if e.record_count() != expected_rec || e.stride() != expected_stride {
361        return Err(ProfileError::InvalidStride {
362            expected: expected_stride,
363            actual: e.stride(),
364        });
365    }
366    let payload = env.verify_chunk(entry_index)?;
367    let mask = env.read_validity_mask(desc, expected_rec)?;
368
369    let delays_samples = if let Some(df) = field_opt(s204, 7) {
370        let d_idx = field_u32(df)?;
371        let d_bytes = env.verify_chunk(d_idx)?;
372        if d_bytes.len() as u64 != expected_rec * 8 {
373            return Err(ProfileError::InvalidPayloadLength);
374        }
375        let mut out = Vec::with_capacity(expected_rec as usize);
376        for c in d_bytes.chunks_exact(8) {
377            let v = f64::from_le_bytes([c[0], c[1], c[2], c[3], c[4], c[5], c[6], c[7]]);
378            out.push(require_finite_f64(v)?);
379        }
380        Some(out)
381    } else {
382        None
383    };
384
385    let legacy_original_bytes = if let Some(s209) = env.extension_block(desc, 209)? {
386        let orig_idx = field_u32(field_req(s209, 3)?)?;
387        let orig_digest = field_bytes32(field_req(s209, 4)?)?;
388        let orig_bytes = env.verify_chunk(orig_idx)?;
389        if blake3::hash(orig_bytes).as_bytes() != &orig_digest {
390            return Err(ProfileError::LegacyFormat("Schema 209 original_digest mismatch"));
391        }
392        Some(orig_bytes)
393    } else {
394        None
395    };
396
397    let chunk = HrirChunkView {
398        bytes: payload,
399        taps: taps as usize,
400        receivers: receivers as usize,
401        measurements: measurements as usize,
402        mask,
403    };
404    let mut tmp = vec![0.0f32; taps as usize];
405    for m in 0..measurements as usize {
406        for r in 0..receivers as usize {
407            chunk.read_impulse(m, r, &mut tmp)?;
408        }
409    }
410    Ok(HrirDocumentView {
411        chunk,
412        representation: repr,
413        impulse_sample_rate,
414        delay_reference,
415        delays_samples,
416        legacy_original_bytes,
417    })
418}