Skip to main content

qualia_core_db/audio/qac/profiles/
perceptual_helpers.rs

1//! Helper types and migration loaders for Q06 Mode `0x0105` perceptual features.
2
3use super::*;
4
5/// Zero-heap borrowed view over verified `0x0105` perceptual feature vectors.
6pub struct PerceptualChunkView<'a> {
7    bytes: &'a [u8],
8    feature_count: usize,
9    mask: Option<&'a [u8]>,
10}
11
12impl<'a> PerceptualChunkView<'a> {
13    pub fn frame_count(&self) -> usize {
14        self.bytes.len() / (self.feature_count * 4)
15    }
16
17    pub fn feature_count(&self) -> usize {
18        self.feature_count
19    }
20
21    pub fn read_frame(&self, index: usize, out: &mut [f32]) -> Result<(), ProfileError> {
22        if out.len() != self.feature_count {
23            return Err(ProfileError::InvalidPayloadLength);
24        }
25        let stride = self.feature_count * 4;
26        let start = index.checked_mul(stride).ok_or(ProfileError::Overflow)?;
27        let end = start.checked_add(stride).ok_or(ProfileError::Overflow)?;
28        let slice = self
29            .bytes
30            .get(start..end)
31            .ok_or(ProfileError::OutOfBoundsIndex("perceptual frame"))?;
32        let ext_valid = self.mask.map_or(true, |m| m[index] != 0);
33        for (i, dst) in out.iter_mut().enumerate() {
34            let v = read_f32_finite(slice, i * 4)?;
35            require_zero_when_masked(ext_valid, v)?;
36            *dst = v;
37        }
38        Ok(())
39    }
40}
41
42pub struct PerceptualDocumentView<'a> {
43    pub chunk: PerceptualChunkView<'a>,
44    pub scale: PerceptualScale,
45    pub reference_pressure_pa: Option<f64>,
46    pub gating_profile: Option<&'a str>,
47    pub centers_hz: Option<Vec<f32>>,
48    pub filter_coefficients: Option<Vec<f32>>,
49    pub channel_weights: Option<Vec<f32>>,
50    pub units: &'a str,
51}
52
53pub fn read_perceptual_features_qac<'a>(
54    bytes: &'a [u8],
55    entry_index: u32,
56    limits: ProfileLimits,
57) -> Result<PerceptualDocumentView<'a>, ProfileError> {
58    let env = AdmittedEnvelope::open_alloc(bytes, limits)?;
59    let e = env.entry(entry_index)?;
60    if e.mode() != MODE_PERCEPTUAL_FEATURES {
61        return Err(ProfileError::InvalidMode(e.mode()));
62    }
63    let desc = env.descriptor_for_entry(e)?;
64    let s203 = env
65        .extension_block(desc, 203)?
66        .ok_or(ProfileError::MissingRequiredSchema(203))?;
67    let bands = field_u32(field_req(s203, 3)?)?;
68    let scale = PerceptualScale::parse(field_str(field_req(s203, 4)?)?)?;
69    let units = field_str(field_req(desc, 8)?)?;
70    if scale == PerceptualScale::DbSpl && units != "dB-SPL" {
71        return Err(ProfileError::InvalidDomainConversion("dB-SPL scale must declare dB-SPL units"));
72    }
73    if scale == PerceptualScale::Lufs && units != "LUFS" {
74        return Err(ProfileError::InvalidDomainConversion("LUFS scale must declare LUFS units"));
75    }
76    let reference_pressure_pa = field_opt(s203, 8).map(field_f64).transpose()?;
77    if scale == PerceptualScale::DbSpl && reference_pressure_pa.is_none() {
78        return Err(ProfileError::InvalidMetadata("dB-SPL requires reference_pressure_pa"));
79    }
80    let gating_profile = field_opt(s203, 10).map(field_str).transpose()?;
81    if scale == PerceptualScale::Lufs && gating_profile.is_none() {
82        return Err(ProfileError::InvalidMetadata("LUFS requires BS.1770 gating_profile"));
83    }
84    let expected_stride = bands.checked_mul(4).ok_or(ProfileError::Overflow)?;
85    if e.stride() != expected_stride {
86        return Err(ProfileError::InvalidStride {
87            expected: expected_stride,
88            actual: e.stride(),
89        });
90    }
91    let s205 = env
92        .extension_block(desc, 205)?
93        .ok_or(ProfileError::MissingRequiredSchema(205))?;
94    let shape = field_u64_vec(field_req(s205, 14)?)?;
95    if shape.len() != 2 || shape[0] != e.record_count() || shape[1] != u64::from(bands) {
96        return Err(ProfileError::InvalidMetadata("perceptual tensor_shape mismatch"));
97    }
98    let payload = env.verify_chunk(entry_index)?;
99    let mask = env.read_validity_mask(desc, e.record_count())?;
100
101    let read_opt_f32_aux = |key: u16| -> Result<Option<Vec<f32>>, ProfileError> {
102        let Some(f) = field_opt(s203, key) else {
103            return Ok(None);
104        };
105        let b = env.verify_chunk(field_u32(f)?)?;
106        if b.len() % 4 != 0 {
107            return Err(ProfileError::InvalidPayloadLength);
108        }
109        let mut v = Vec::with_capacity(b.len() / 4);
110        for i in 0..b.len() / 4 {
111            v.push(read_f32_finite(b, i * 4)?);
112        }
113        Ok(Some(v))
114    };
115
116    let centers_hz = read_opt_f32_aux(5)?;
117    let filter_coefficients = read_opt_f32_aux(6)?;
118    let channel_weights = read_opt_f32_aux(9)?;
119
120    let chunk = PerceptualChunkView {
121        bytes: payload,
122        feature_count: bands as usize,
123        mask,
124    };
125    let mut scratch = vec![0.0f32; bands as usize];
126    for i in 0..chunk.frame_count() {
127        chunk.read_frame(i, &mut scratch)?;
128    }
129    Ok(PerceptualDocumentView {
130        chunk,
131        scale,
132        reference_pressure_pa,
133        gating_profile,
134        centers_hz,
135        filter_coefficients,
136        channel_weights,
137        units,
138    })
139}
140
141/// Migrates a legacy `Q4AU v2` container preserving exact original bytes (`mode 0x0104`),
142/// plane-0 spectra (`mode 0x0101` under `legacy-unknown`), mel & MFCC planes (`mode 0x0105`),
143/// and `Schema 209 LegacyRetention` lineage without fabricating window/hop metadata.
144pub fn migrate_legacy_q4au_v2_features(
145    legacy_bytes: &[u8],
146    limits: ProfileLimits,
147) -> Result<Vec<u8>, ProfileError> {
148    let header = parse_sidecar_header(legacy_bytes)
149        .ok_or(ProfileError::LegacyFormat("invalid Q4AU v1/v2 header"))?;
150    if header.version != AudioSpectralSidecarHeader::VERSION_V2 || header.sample_rate == 0 {
151        return Err(ProfileError::LegacyFormat("expected valid Q4AU v2 with sample_rate > 0"));
152    }
153    let frames = usize::try_from(header.frame_count).map_err(|_| ProfileError::Overflow)?;
154    let bins = usize::try_from(header.bin_count).map_err(|_| ProfileError::Overflow)?;
155    let hdr_sz = std::mem::size_of::<AudioSpectralSidecarHeader>();
156    let plane0_bytes = frames
157        .checked_mul(bins)
158        .and_then(|v| v.checked_mul(4))
159        .ok_or(ProfileError::Overflow)?;
160    let plane0_end = hdr_sz.checked_add(plane0_bytes).ok_or(ProfileError::Overflow)?;
161    let sub_sz = std::mem::size_of::<SpectralV2SubHeader>();
162    let sub_end = plane0_end.checked_add(sub_sz).ok_or(ProfileError::Overflow)?;
163    let sub_slice = legacy_bytes
164        .get(plane0_end..sub_end)
165        .ok_or(ProfileError::LegacyFormat("truncated Q4AU v2 subheader"))?;
166    let sub = bytemuck::pod_read_unaligned::<SpectralV2SubHeader>(sub_slice);
167    if sub.magic != SPECTRAL_V2_SUBHEADER_MAGIC || sub.n_mel == 0 || sub.n_mfcc == 0 {
168        return Err(ProfileError::LegacyFormat("invalid Q4M2 subheader"));
169    }
170    let n_mel = usize::try_from(sub.n_mel).map_err(|_| ProfileError::Overflow)?;
171    let n_mfcc = usize::try_from(sub.n_mfcc).map_err(|_| ProfileError::Overflow)?;
172    let mel_bytes = frames.checked_mul(n_mel).and_then(|v| v.checked_mul(4)).ok_or(ProfileError::Overflow)?;
173    let mfcc_bytes = frames.checked_mul(n_mfcc).and_then(|v| v.checked_mul(4)).ok_or(ProfileError::Overflow)?;
174    let mel_start = sub_end;
175    let mel_end = mel_start.checked_add(mel_bytes).ok_or(ProfileError::Overflow)?;
176    let mfcc_end = mel_end.checked_add(mfcc_bytes).ok_or(ProfileError::Overflow)?;
177    let plane0 = legacy_bytes.get(hdr_sz..plane0_end).ok_or(ProfileError::LegacyFormat("truncated plane0"))?;
178    let mel_slice = legacy_bytes.get(mel_start..mel_end).ok_or(ProfileError::LegacyFormat("truncated mel"))?;
179    let mfcc_slice = legacy_bytes.get(mel_end..mfcc_end).ok_or(ProfileError::LegacyFormat("truncated mfcc"))?;
180    for c in [plane0, mel_slice, mfcc_slice] {
181        for i in 0..c.len() / 4 {
182            let _ = read_f32_finite(c, i * 4)?;
183        }
184    }
185
186    let orig_digest: [u8; 32] = *blake3::hash(legacy_bytes).as_bytes();
187    let rate = RationalRate::new(u64::from(header.sample_rate), 1)?;
188    assemble_legacy_v2_ordered(legacy_bytes, orig_digest, rate, header.bin_count, frames, bins, sub, plane0, mel_slice, mfcc_slice, limits)
189}
190
191#[allow(clippy::too_many_arguments)]
192fn assemble_legacy_v2_ordered(
193    legacy_bytes: &[u8],
194    orig_digest: [u8; 32],
195    rate: RationalRate,
196    bin_count: u32,
197    frames: usize,
198    bins: usize,
199    sub: SpectralV2SubHeader,
200    plane0: &[u8],
201    mel_slice: &[u8],
202    mfcc_slice: &[u8],
203    limits: ProfileLimits,
204) -> Result<Vec<u8>, ProfileError> {
205    let mut meta = MetadataBuilder::new();
206    meta.push_clock(1, &ClockSpec { scale: 0, epoch_seconds: 0, epoch_nanoseconds: 0, ticks_per_second: rate })?;
207    let digests = [orig_digest];
208    meta.push_provenance(2, &ProvenanceSpec {
209        role: 2, source_digests: &digests, algorithm: Some("urn:qac:migration:q4au-v2"),
210        algorithm_version: Some("1"), instrument_uri: None, authority_receipt_digest: None,
211        lineage: Some("lossless Q4AU v2 mel/mfcc extraction with opaque original bytes"),
212    })?;
213    meta.push_provenance(3, &ProvenanceSpec {
214        role: 4, source_digests: &[], algorithm: None, algorithm_version: None,
215        instrument_uri: None, authority_receipt_digest: None, lineage: Some("unparsed original Q4AU v2"),
216    })?;
217    meta.push_block(OwnedBlock {
218        id: 4, schema_type: 201, revision: 1, critical: true,
219        fields: vec![
220            OwnedField::crit(1, OwnedValue::Utf8("legacy-unknown".to_owned())),
221            OwnedField::crit(13, OwnedValue::U32(vec![bin_count])),
222        ],
223    })?;
224    meta.push_block(OwnedBlock {
225        id: 5, schema_type: 209, revision: 1, critical: true,
226        fields: vec![
227            OwnedField::crit(1, OwnedValue::Utf8("Q4AU".to_owned())),
228            OwnedField::crit(2, OwnedValue::U32(vec![2])),
229            OwnedField::crit(3, OwnedValue::EntryRefs(vec![1])),
230            OwnedField::crit(4, OwnedValue::Bytes(orig_digest.to_vec())),
231            OwnedField::crit(5, OwnedValue::Utf8("urn:qac:migration:q4au-v2".to_owned())),
232            OwnedField::crit(6, OwnedValue::Utf8("1".to_owned())),
233            OwnedField::opt(7, OwnedValue::Utf8("plane0,n_mel,n_mfcc,sample_rate".to_owned())),
234            OwnedField::opt(8, OwnedValue::Utf8("fft_size,hop_samples,window".to_owned())),
235        ],
236    })?;
237    let stft_shape = [frames as u64, 1, bins as u64];
238    meta.push_model_grid(6, &ModelGridSpec {
239        model_uri: "urn:qac:model:legacy-unknown-spectrum:v1", model_version: "1", discretization: None,
240        component_offsets_xyz: &[], component_time_offset_num: &[], component_time_offset_den: &[],
241        timestep: None, tolerance_abs: None, tolerance_rel: None, tensor_shape: &stft_shape, component_names: "mag",
242    })?;
243    meta.push_descriptor(7, &DescriptorSpec {
244        clock_id: Some(1), frame_id: None, provenance_id: 2, medium_id: None, transform_id: Some(4),
245        calibration_id: None, quantity: "spectral-magnitude", units: "1", channels: Some(1),
246        layout: Some("frame-channel-bin"), scalar: Some(AuxScalar::F32), model_uri: "urn:qac:mode:0x0101:legacy:v1",
247        sample_rate: Some(rate), valid_record_count: None, validity_mask_entry: None, source_entries: &[1], extension_metadata: &[5, 6],
248    })?;
249    meta.push_descriptor(8, &DescriptorSpec {
250        clock_id: None, frame_id: None, provenance_id: 3, medium_id: None, transform_id: None,
251        calibration_id: None, quantity: "opaque-original", units: "1", channels: Some(1), layout: Some("byte"),
252        scalar: Some(AuxScalar::U8), model_uri: "urn:qac:mode:0x0104:opaque-original:v1", sample_rate: None,
253        valid_record_count: None, validity_mask_entry: None, source_entries: &[], extension_metadata: &[],
254    })?;
255    meta.push_block(OwnedBlock {
256        id: 9, schema_type: 203, revision: 1, critical: true,
257        fields: vec![
258            OwnedField::crit(1, OwnedValue::Utf8("urn:qac:legacy:q4au-v2-mel".to_owned())),
259            OwnedField::crit(2, OwnedValue::Utf8("1".to_owned())),
260            OwnedField::crit(3, OwnedValue::U32(vec![sub.n_mel])),
261            OwnedField::crit(4, OwnedValue::Utf8("mel".to_owned())),
262        ],
263    })?;
264    let mel_shape = [frames as u64, sub.n_mel as u64];
265    meta.push_model_grid(10, &ModelGridSpec {
266        model_uri: "urn:qac:legacy:q4au-v2-mel", model_version: "1", discretization: None,
267        component_offsets_xyz: &[], component_time_offset_num: &[], component_time_offset_den: &[],
268        timestep: None, tolerance_abs: None, tolerance_rel: None, tensor_shape: &mel_shape, component_names: "mel",
269    })?;
270    meta.push_descriptor(11, &DescriptorSpec {
271        clock_id: Some(1), frame_id: None, provenance_id: 2, medium_id: None, transform_id: None,
272        calibration_id: None, quantity: "perceptual-mel", units: "mel", channels: Some(1),
273        layout: Some("frame-feature"), scalar: Some(AuxScalar::F32), model_uri: "urn:qac:mode:0x0105:v1",
274        sample_rate: Some(rate), valid_record_count: None, validity_mask_entry: None, source_entries: &[1], extension_metadata: &[5, 9, 10],
275    })?;
276    meta.push_block(OwnedBlock {
277        id: 12, schema_type: 203, revision: 1, critical: true,
278        fields: vec![
279            OwnedField::crit(1, OwnedValue::Utf8("urn:qac:legacy:q4au-v2-mfcc".to_owned())),
280            OwnedField::crit(2, OwnedValue::Utf8("1".to_owned())),
281            OwnedField::crit(3, OwnedValue::U32(vec![sub.n_mfcc])),
282            OwnedField::crit(4, OwnedValue::Utf8("MFCC".to_owned())),
283        ],
284    })?;
285    let mfcc_shape = [frames as u64, sub.n_mfcc as u64];
286    meta.push_model_grid(13, &ModelGridSpec {
287        model_uri: "urn:qac:legacy:q4au-v2-mfcc", model_version: "1", discretization: None,
288        component_offsets_xyz: &[], component_time_offset_num: &[], component_time_offset_den: &[],
289        timestep: None, tolerance_abs: None, tolerance_rel: None, tensor_shape: &mfcc_shape, component_names: "mfcc",
290    })?;
291    meta.push_descriptor(14, &DescriptorSpec {
292        clock_id: Some(1), frame_id: None, provenance_id: 2, medium_id: None, transform_id: None,
293        calibration_id: None, quantity: "perceptual-mfcc", units: "1", channels: Some(1),
294        layout: Some("frame-feature"), scalar: Some(AuxScalar::F32), model_uri: "urn:qac:mode:0x0105:v1",
295        sample_rate: Some(rate), valid_record_count: None, validity_mask_entry: None, source_entries: &[1], extension_metadata: &[5, 12, 13],
296    })?;
297
298    let entries = vec![
299        OwnedEntry {
300            mode: MODE_OPAQUE_SOURCE, flags: 1, stream_id: 0, frame_id: 0, start_tick: 0,
301            time_count: 0, spatial_key: 0, record_count: legacy_bytes.len() as u64, stride: 1,
302            descriptor_id: 8, payload: legacy_bytes.to_vec(),
303        },
304        OwnedEntry {
305            mode: MODE_STFT_PRESERVATION, flags: 3, stream_id: 1, frame_id: 0, start_tick: 0,
306            time_count: frames as u64, spatial_key: 0, record_count: frames as u64, stride: (bins * 4) as u32,
307            descriptor_id: 7, payload: plane0.to_vec(),
308        },
309        OwnedEntry {
310            mode: MODE_PERCEPTUAL_FEATURES, flags: 3, stream_id: 1, frame_id: 0, start_tick: 0,
311            time_count: frames as u64, spatial_key: 0, record_count: frames as u64, stride: sub.n_mel * 4,
312            descriptor_id: 11, payload: mel_slice.to_vec(),
313        },
314        OwnedEntry {
315            mode: MODE_PERCEPTUAL_FEATURES, flags: 3, stream_id: 1, frame_id: 0, start_tick: 0,
316            time_count: frames as u64, spatial_key: 0, record_count: frames as u64, stride: sub.n_mfcc * 4,
317            descriptor_id: 14, payload: mfcc_slice.to_vec(),
318        },
319    ];
320    assemble_qac_v1(&meta, &entries, limits)
321}