1use super::*;
4
5pub 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
141pub 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}