Skip to main content

qualia_core_db/audio/qac/profiles/
hrir_helpers.rs

1//! Auxiliary vector/scalar array entry pushers, legacy Q4AU v3 validation, and lossless migration.
2
3use crate::audio::audio_spectral_sheet_v3::{
4    parse_v3_header, Q4AuHeaderV3, SofaHrirEntry, Q4AU_V3_HEADER_BYTES, SOFA_DEFAULT_FIR_TAPS,
5};
6
7use super::*;
8
9pub(crate) fn push_aux_f32_vec3_entry(
10    meta: &mut MetadataBuilder,
11    desc_id: u32,
12    prov_id: u32,
13    qty: &str,
14    units: &str,
15    vecs: &[[f32; 3]],
16) -> Result<OwnedEntry, ProfileError> {
17    let mut payload = vec![0u8; vecs.len() * 12];
18    for (i, v) in vecs.iter().enumerate() {
19        write_f32_slice(&mut payload, i * 12, v)?;
20    }
21    meta.push_descriptor(
22        desc_id,
23        &DescriptorSpec {
24            clock_id: None,
25            frame_id: None,
26            provenance_id: prov_id,
27            medium_id: None,
28            transform_id: None,
29            calibration_id: None,
30            quantity: qty,
31            units,
32            channels: Some(3),
33            layout: Some("record-component"),
34            scalar: Some(AuxScalar::F32),
35            model_uri: "urn:qac:mode:0x0107:v1",
36            sample_rate: None,
37            valid_record_count: None,
38            validity_mask_entry: None,
39            source_entries: &[],
40            extension_metadata: &[],
41        },
42    )?;
43    Ok(OwnedEntry {
44        mode: MODE_AUX_ARRAY,
45        flags: 1,
46        stream_id: 0,
47        frame_id: 0,
48        start_tick: 0,
49        time_count: 0,
50        spatial_key: 0,
51        record_count: vecs.len() as u64,
52        stride: 12,
53        descriptor_id: desc_id,
54        payload,
55    })
56}
57
58pub(crate) fn push_aux_f64_scalar_entry(
59    meta: &mut MetadataBuilder,
60    desc_id: u32,
61    prov_id: u32,
62    qty: &str,
63    units: &str,
64    vals: &[f64],
65) -> Result<OwnedEntry, ProfileError> {
66    let mut payload = vec![0u8; vals.len() * 8];
67    for (i, &v) in vals.iter().enumerate() {
68        let f = require_finite_f64(v)?;
69        payload[i * 8..(i + 1) * 8].copy_from_slice(&f.to_le_bytes());
70    }
71    meta.push_descriptor(
72        desc_id,
73        &DescriptorSpec {
74            clock_id: None,
75            frame_id: None,
76            provenance_id: prov_id,
77            medium_id: None,
78            transform_id: None,
79            calibration_id: None,
80            quantity: qty,
81            units,
82            channels: Some(1),
83            layout: Some("record-component"),
84            scalar: Some(AuxScalar::F64),
85            model_uri: "urn:qac:mode:0x0107:v1",
86            sample_rate: None,
87            valid_record_count: None,
88            validity_mask_entry: None,
89            source_entries: &[],
90            extension_metadata: &[],
91        },
92    )?;
93    Ok(OwnedEntry {
94        mode: MODE_AUX_ARRAY,
95        flags: 1,
96        stream_id: 0,
97        frame_id: 0,
98        start_tick: 0,
99        time_count: 0,
100        spatial_key: 0,
101        record_count: vals.len() as u64,
102        stride: 8,
103        descriptor_id: desc_id,
104        payload,
105    })
106}
107
108// ---------------------------------------------------------------------------
109// Legacy Q4AU v3 SOFA 64-tap validation & lossless migration
110// ---------------------------------------------------------------------------
111
112/// Strictly validated `Q4AU v3` legacy container parsed without assuming pointer alignment.
113pub struct ValidatedLegacyQ4auV3 {
114    pub header: Q4AuHeaderV3,
115    pub sofa_entries: Vec<SofaHrirEntry>,
116}
117
118/// Parses and validates a legacy `Q4AU v3` file, rejecting truncation, overlap,
119/// tap count mismatch, non-finite floats, and WASM32 multiplication overflow.
120pub fn parse_legacy_q4au_v3(bytes: &[u8]) -> Result<ValidatedLegacyQ4auV3, ProfileError> {
121    let header = parse_v3_header(bytes)
122        .ok_or(ProfileError::LegacyFormat("invalid Q4AU v3 magic/version/header CRC"))?;
123    if header.sample_rate == 0 {
124        return Err(ProfileError::LegacyFormat("Q4AU v3 sample_rate must be > 0"));
125    }
126    let ch = header.hoa_channel_count();
127    let spectral_bytes = (header.bin_count as usize)
128        .checked_mul(header.frame_count as usize)
129        .and_then(|v| v.checked_mul(ch))
130        .and_then(|v| v.checked_mul(4))
131        .ok_or(ProfileError::Overflow)?;
132    let spectral_end = Q4AU_V3_HEADER_BYTES
133        .checked_add(spectral_bytes)
134        .ok_or(ProfileError::Overflow)?;
135    if bytes.len() < spectral_end {
136        return Err(ProfileError::LegacyFormat("Q4AU v3 truncated spectral payload"));
137    }
138    let dir_count = usize::try_from(header.sofa_direction_count).map_err(|_| ProfileError::Overflow)?;
139    let mut sofa_entries = Vec::new();
140    if dir_count > 0 {
141        if header.sofa_fir_taps as usize != SOFA_DEFAULT_FIR_TAPS {
142            return Err(ProfileError::LegacyFormat("Q4AU v3 sofa_fir_taps disagrees with 64-tap layout"));
143        }
144        let sofa_start = usize::try_from(header.sofa_block_offset).map_err(|_| ProfileError::Overflow)?;
145        if sofa_start < spectral_end {
146            return Err(ProfileError::LegacyFormat("Q4AU v3 SOFA block overlaps header/spectral payload"));
147        }
148        let entry_size = std::mem::size_of::<SofaHrirEntry>();
149        let sofa_len = dir_count.checked_mul(entry_size).ok_or(ProfileError::Overflow)?;
150        let sofa_end = sofa_start.checked_add(sofa_len).ok_or(ProfileError::Overflow)?;
151        if bytes.len() < sofa_end {
152            return Err(ProfileError::LegacyFormat("Q4AU v3 truncated SOFA table"));
153        }
154        sofa_entries.reserve(dir_count);
155        for i in 0..dir_count {
156            let off = sofa_start + i * entry_size;
157            let e = bytemuck::pod_read_unaligned::<SofaHrirEntry>(&bytes[off..off + entry_size]);
158            if !e.azimuth_deg.is_finite()
159                || !e.elevation_deg.is_finite()
160                || !e.itd_samples.is_finite()
161                || e.left_fir.iter().any(|v| !v.is_finite())
162                || e.right_fir.iter().any(|v| !v.is_finite())
163            {
164                return Err(ProfileError::NonFiniteFloat);
165            }
166            sofa_entries.push(e);
167        }
168    }
169    Ok(ValidatedLegacyQ4auV3 {
170        header,
171        sofa_entries,
172    })
173}
174
175/// Losslessly migrates a `Q4AU v3` 64-tap SOFA HRIR table to QAC v1 (`mode 0x0103`),
176/// preserving bit-exact original taps, per-ear ITD offsets, spherical directions,
177/// and exact unparsed original bytes (`mode 0x0104` + `Schema 209`).
178pub fn migrate_legacy_q4au_v3_hrir(
179    legacy_bytes: &[u8],
180    limits: ProfileLimits,
181) -> Result<Vec<u8>, ProfileError> {
182    let parsed = parse_legacy_q4au_v3(legacy_bytes)?;
183    if parsed.sofa_entries.is_empty() {
184        return Err(ProfileError::LegacyFormat("Q4AU v3 has no SOFA HRIR entries"));
185    }
186    let orig_digest: [u8; 32] = *blake3::hash(legacy_bytes).as_bytes();
187    let n = parsed.sofa_entries.len();
188    let mut impulses = Vec::with_capacity(n * 2 * SOFA_DEFAULT_FIR_TAPS);
189    let mut source_pos = Vec::with_capacity(n);
190    let mut delays = Vec::with_capacity(n * 2);
191
192    for e in &parsed.sofa_entries {
193        impulses.extend_from_slice(&e.left_fir);
194        impulses.extend_from_slice(&e.right_fir);
195        let az = f64::from(e.azimuth_deg).to_radians();
196        let el = f64::from(e.elevation_deg).to_radians();
197        source_pos.push([
198            (el.cos() * az.cos()) as f32,
199            (el.cos() * az.sin()) as f32,
200            el.sin() as f32,
201        ]);
202        delays.push(f64::from(e.itd_samples));
203        delays.push(0.0);
204    }
205
206    let mut payload = vec![0u8; impulses.len() * 4];
207    write_f32_slice(&mut payload, 0, &impulses)?;
208
209    let mut meta = MetadataBuilder::new();
210    meta.push_frame(2, &FrameSpec::local_default())?;
211    let digests = [orig_digest];
212    meta.push_provenance(
213        3,
214        &ProvenanceSpec {
215            role: 2, // derived
216            source_digests: &digests,
217            algorithm: Some("urn:qac:migration:q4au-v3-hrir"),
218            algorithm_version: Some("1"),
219            instrument_uri: None,
220            authority_receipt_digest: None,
221            lineage: Some("migrated from Q4AU v3 preserving exact 64-tap FIR and unparsed original"),
222        },
223    )?;
224    meta.push_provenance(
225        8,
226        &ProvenanceSpec {
227            role: 4, // opaque-preserved
228            source_digests: &[],
229            algorithm: None,
230            algorithm_version: None,
231            instrument_uri: None,
232            authority_receipt_digest: None,
233            lineage: Some("unparsed original Q4AU v3 container"),
234        },
235    )?;
236
237    let impulse_rate = RationalRate::new(u64::from(parsed.header.sample_rate), 1)?;
238    let mut s204_fields = vec![
239        OwnedField::crit(1, OwnedValue::Utf8("HRIR".to_owned())),
240        OwnedField::opt(6, OwnedValue::EntryRefs(vec![3])),
241        OwnedField::opt(7, OwnedValue::EntryRefs(vec![4])),
242        OwnedField::crit(8, OwnedValue::U32(vec![SOFA_DEFAULT_FIR_TAPS as u32])),
243        OwnedField::crit(9, OwnedValue::U32(vec![2])),
244        OwnedField::crit(10, OwnedValue::U32(vec![n as u32])),
245        OwnedField::opt(11, OwnedValue::EntryRefs(vec![2])),
246        OwnedField::opt(12, OwnedValue::Utf8("SimpleFreeFieldHRIR".to_owned())),
247        OwnedField::opt(13, OwnedValue::MetadataRefs(vec![2])),
248        OwnedField::crit(17, OwnedValue::U64(vec![impulse_rate.num])),
249        OwnedField::crit(18, OwnedValue::U64(vec![impulse_rate.den])),
250        OwnedField::crit(19, OwnedValue::Utf8(LEGACY_DELAY_REFERENCE.to_owned())),
251    ];
252    let _ = &mut s204_fields;
253    meta.push_block(OwnedBlock {
254        id: 4,
255        schema_type: 204,
256        revision: 1,
257        critical: true,
258        fields: s204_fields,
259    })?;
260
261    let shape = [n as u64, 2, SOFA_DEFAULT_FIR_TAPS as u64];
262    meta.push_model_grid(
263        5,
264        &ModelGridSpec {
265            model_uri: "urn:qac:model:q4au-v3-hrir:v1",
266            model_version: "1",
267            discretization: Some("discrete-fir-taps"),
268            component_offsets_xyz: &[],
269            component_time_offset_num: &[],
270            component_time_offset_den: &[],
271            timestep: None,
272            tolerance_abs: None,
273            tolerance_rel: None,
274            tensor_shape: &shape,
275            component_names: "left_fir,right_fir",
276        },
277    )?;
278
279    // Schema 209 LegacyRetention linking Entry 2 (0x0104 opaque original bytes).
280    meta.push_block(OwnedBlock {
281        id: 7,
282        schema_type: 209,
283        revision: 1,
284        critical: true,
285        fields: vec![
286            OwnedField::crit(1, OwnedValue::Utf8("Q4AU".to_owned())),
287            OwnedField::crit(2, OwnedValue::U32(vec![3])),
288            OwnedField::crit(3, OwnedValue::EntryRefs(vec![2])),
289            OwnedField::crit(4, OwnedValue::Bytes(orig_digest.to_vec())),
290            OwnedField::crit(5, OwnedValue::Utf8("urn:qac:migration:q4au-v3-hrir".to_owned())),
291            OwnedField::crit(6, OwnedValue::Utf8("1".to_owned())),
292            OwnedField::opt(
293                7,
294                OwnedValue::Utf8("sample_rate,sofa_direction_count,azimuth_deg,elevation_deg,itd_samples,left_fir,right_fir".to_owned()),
295            ),
296            OwnedField::opt(
297                8,
298                OwnedValue::Utf8("unknown_excitation_origin_delay_ref".to_owned()),
299            ),
300        ],
301    })?;
302
303    let ext = [4u32, 5u32, 7u32];
304    meta.push_descriptor(
305        6,
306        &DescriptorSpec {
307            clock_id: None,
308            frame_id: Some(2),
309            provenance_id: 3,
310            medium_id: None,
311            transform_id: None,
312            calibration_id: None,
313            quantity: "hrir-impulse-response",
314            units: "1",
315            channels: Some(2),
316            layout: Some("measurement-receiver-tap"),
317            scalar: Some(AuxScalar::F32),
318            model_uri: "urn:qac:mode:0x0103:v1",
319            sample_rate: None,
320            valid_record_count: None,
321            validity_mask_entry: None,
322            source_entries: &[2],
323            extension_metadata: &ext,
324        },
325    )?;
326
327    meta.push_descriptor(
328        9,
329        &DescriptorSpec {
330            clock_id: None,
331            frame_id: None,
332            provenance_id: 8,
333            medium_id: None,
334            transform_id: None,
335            calibration_id: None,
336            quantity: "opaque-original",
337            units: "1",
338            channels: Some(1),
339            layout: Some("byte"),
340            scalar: Some(AuxScalar::U8),
341            model_uri: "urn:qac:mode:0x0104:opaque-original:v1",
342            sample_rate: None,
343            valid_record_count: None,
344            validity_mask_entry: None,
345            source_entries: &[],
346            extension_metadata: &[],
347        },
348    )?;
349
350    let e_src_pos = push_aux_f32_vec3_entry(&mut meta, 10, 8, "source-positions", "1", &source_pos)?;
351    let e_delays = push_aux_f64_scalar_entry(&mut meta, 11, 8, "delays-samples", "1", &delays)?;
352
353    // Canonical directory order: stream_id=0, modes 0x0103 < 0x0104 < 0x0107 (desc 10 < desc 11).
354    let entries = vec![
355        OwnedEntry {
356            mode: MODE_HRIR_IMPULSE,
357            flags: 1,
358            stream_id: 0,
359            frame_id: 2,
360            start_tick: 0,
361            time_count: 0,
362            spatial_key: 0,
363            record_count: (n * 2) as u64,
364            stride: (SOFA_DEFAULT_FIR_TAPS as u32) * 4,
365            descriptor_id: 6,
366            payload,
367        },
368        OwnedEntry {
369            mode: MODE_OPAQUE_SOURCE,
370            flags: 1,
371            stream_id: 0,
372            frame_id: 0,
373            start_tick: 0,
374            time_count: 0,
375            spatial_key: 0,
376            record_count: legacy_bytes.len() as u64,
377            stride: 1,
378            descriptor_id: 9,
379            payload: legacy_bytes.to_vec(),
380        },
381        e_src_pos,
382        e_delays,
383    ];
384    assemble_qac_v1(&meta, &entries, limits)
385}