1use super::provider::{transform_into, Plan, ProviderError, ProviderLimits};
4use crate::audio::qac::signal::{
5 writer::{PcmSamples, Provenance, ProvenanceRole, SignalRelation},
6 Error, Limits, Scalar, Timing,
7};
8use crate::q42::{
9 field_envelope::{self as env, BlockInput, EntryInput, EnvelopeInput, FieldInput, FieldValue as V, MetadataInput},
10 field_semantics as sem,
11};
12
13#[derive(Clone, Copy, Debug, PartialEq, Eq)]
14pub enum StftQuantity {
15 DigitalSample,
16 Pressure,
17}
18impl StftQuantity {
19 fn pcm_names(self) -> (&'static str, &'static str) {
20 match self {
21 Self::DigitalSample => ("digital_sample", "1"),
22 Self::Pressure => ("pressure", "Pa"),
23 }
24 }
25 fn stft_names(self) -> (&'static str, &'static str) {
26 match self {
27 Self::DigitalSample => ("complex_digital_spectrum", "1"),
28 Self::Pressure => ("complex_pressure_spectrum", "Pa"),
29 }
30 }
31}
32
33pub struct StftWriteBuffers<'a> {
36 pub mono: &'a mut [f32],
37 pub fft: &'a mut [f32],
38 pub window: &'a mut [f32],
39 pub spectra: &'a mut [u8],
40 pub metadata: &'a mut [u8],
41 pub payload: &'a mut [u8],
42 pub file: &'a mut [u8],
43}
44
45#[derive(Clone, Copy, Debug, Default)]
46pub struct StftWriteOptions {
47 pub envelope: env::Limits,
48 pub shared: sem::Limits,
49 pub signal: Limits,
50 pub provider: ProviderLimits,
51}
52
53#[derive(Clone, Copy, Debug)]
54pub struct StftDocument<'a> {
55 pub samples: PcmSamples<'a>,
56 pub timing: Timing,
57 pub stream_id: u32,
58 pub channels: u32,
59 pub channel_order: &'a str,
60 pub fft_size: u32,
61 pub hop: u32,
62 pub pcm_purpose: &'a str,
63 pub stft_purpose: &'a str,
64 pub quantity: StftQuantity,
65 pub relation: SignalRelation,
66 pub pcm_provenance: Provenance<'a>,
67 pub stft_provenance: Provenance<'a>,
68 pub original: Option<&'a [u8]>,
69}
70
71fn map_provider_err(err: ProviderError) -> Error {
72 match err {
73 ProviderError::Shape | ProviderError::Frame | ProviderError::ShortInput => Error::Shape,
74 ProviderError::Capacity => Error::Envelope(env::Error::Extent),
75 ProviderError::Limit => Error::Limit,
76 ProviderError::Overflow => Error::Overflow,
77 ProviderError::Nonfinite => Error::Nonfinite,
78 ProviderError::Provider(etalon_signal::SignalError::NonFiniteInput) => Error::Nonfinite,
79 ProviderError::Provider(_) => Error::Shape,
80 }
81}
82
83fn relation_name(relation: SignalRelation) -> &'static str {
84 match relation {
85 SignalRelation::DigitalUnrelatedToPressure => "digital-unrelated-to-pressure",
86 SignalRelation::RawCounts => "raw-counts",
87 SignalRelation::PhysicalBaseUnits => "physical-base-units",
88 }
89}
90
91fn f(key: u16, value: V<'_>) -> FieldInput<'_> {
92 FieldInput { key, flags: 1, value }
93}
94fn b<'a>(id: u32, schema_type: u16, fields: &'a [FieldInput<'a>]) -> BlockInput<'a> {
95 BlockInput { id, schema_type, revision: 1, flags: 1, fields }
96}
97fn push<'a>(out: &mut [FieldInput<'a>], n: &mut usize, key: u16, value: V<'a>) {
98 out[*n] = f(key, value);
99 *n += 1;
100}
101
102fn fill_provenance<'a>(
103 out: &mut [FieldInput<'a>; 7],
104 role: &'a [u32; 1],
105 digest: Option<&'a [u8; 32]>,
106 prov: &'a Provenance<'a>,
107) -> usize {
108 let mut n = 0;
109 push(out, &mut n, 1, V::U32(role));
110 if let Some(d) = digest {
111 push(out, &mut n, 2, V::Bytes(d));
112 }
113 for (k, opt) in [(3, prov.algorithm), (4, prov.algorithm_version), (5, prov.instrument_uri), (7, prov.lineage)] {
114 if let Some(s) = opt {
115 push(out, &mut n, k, V::Utf8(s));
116 }
117 }
118 n
119}
120
121impl StftDocument<'_> {
122 pub const fn pcm_entry_index(&self) -> u32 {
123 if self.original.is_some() { 2 } else { 1 }
124 }
125 pub const fn stft_entry_index(&self) -> u32 {
126 if self.original.is_some() { 3 } else { 2 }
127 }
128 fn preflight(&self, options: StftWriteOptions) -> Result<(usize, Plan, u32, u32, crate::audio::qac::signal::Rate), Error> {
129 if self.samples.scalar() != Scalar::F32 {
130 return Err(Error::Scalar);
131 }
132 if self.stream_id == 0 || self.channels == 0 {
133 return Err(Error::Shape);
134 }
135 if self.stft_provenance.role != ProvenanceRole::Derived
136 || self.stft_provenance.algorithm.is_none()
137 || self.stft_provenance.algorithm_version.is_none()
138 {
139 return Err(Error::Profile);
140 }
141 match (self.quantity, self.relation) {
142 (StftQuantity::DigitalSample, SignalRelation::DigitalUnrelatedToPressure)
143 | (StftQuantity::Pressure, SignalRelation::PhysicalBaseUnits) => {}
144 _ => return Err(Error::Unit),
145 }
146 if self.original.is_some_and(|b| b.is_empty()) {
147 return Err(Error::Shape);
148 }
149 let pcm_bytes = self.samples.encoded_len()?;
150 let fft_size = usize::try_from(self.fft_size).map_err(|_| Error::Overflow)?;
151 let hop = usize::try_from(self.hop).map_err(|_| Error::Overflow)?;
152 let plan = Plan::new(pcm_bytes, self.channels, fft_size, hop, options.provider)
153 .map_err(map_provider_err)?;
154 let pcm_stride = self.channels.checked_mul(4).ok_or(Error::Overflow)?;
155 let stft_stride = self
156 .channels
157 .checked_mul(self.fft_size)
158 .and_then(|n| n.checked_mul(8))
159 .ok_or(Error::Overflow)?;
160 let frame_rate = self.timing.samples.divided_by(self.hop)?;
161 let orig_bytes = self.original.map_or(0u64, |b| b.len() as u64);
162 let stft_bytes = plan.output_bytes() as u64;
163 let total_bytes = (pcm_bytes as u64)
164 .checked_add(stft_bytes)
165 .and_then(|n| n.checked_add(orig_bytes))
166 .ok_or(Error::Overflow)?;
167 let pcm_scalars = pcm_bytes as u64 / 4;
168 let stft_scalars = stft_bytes / 8;
169 let total_samples = pcm_scalars
170 .checked_add(stft_scalars)
171 .and_then(|n| n.checked_add(orig_bytes))
172 .ok_or(Error::Overflow)?;
173 let min_entries = if self.original.is_some() { 3 } else { 2 };
174 if options.signal.work < total_bytes.checked_mul(2).ok_or(Error::Overflow)?
175 || total_bytes > options.signal.payload_bytes
176 || total_samples > options.signal.samples
177 || total_bytes > options.envelope.aggregate_decoded_bytes
178 || pcm_bytes as u64 > options.envelope.chunk_bytes
179 || stft_bytes > options.envelope.chunk_bytes
180 || orig_bytes > options.envelope.chunk_bytes
181 || options.signal.entries < min_entries
182 {
183 return Err(Error::Limit);
184 }
185 self.timing.time_at((plan.sample_frames() as u64) - 1)?;
186 let stft_timing = Timing { samples: frame_rate, ..self.timing };
187 stft_timing.time_at((plan.frames() as u64) - 1)?;
188 Ok((pcm_bytes, plan, pcm_stride, stft_stride, frame_rate))
189 }
190
191 pub fn encode_into(
195 &self,
196 buffers: StftWriteBuffers<'_>,
197 scratch: &mut sem::Scratch<'_>,
198 output: &mut [u8],
199 options: StftWriteOptions,
200 ) -> Result<usize, Error> {
201 let (pcm_bytes, plan, pcm_stride, stft_stride, frame_rate) = self.preflight(options)?;
202 let pcm_n = self.samples.encode_into(buffers.payload)?;
203 debug_assert_eq!(pcm_n, pcm_bytes);
204 let pcm_slice = &buffers.payload[..pcm_n];
205 let fft_size = plan.fft_size();
206 let stft_plan = transform_into(
207 pcm_slice,
208 self.channels,
209 fft_size,
210 plan.hop(),
211 buffers.mono,
212 buffers.fft,
213 buffers.window,
214 buffers.spectra,
215 options.provider,
216 )
217 .map_err(map_provider_err)?;
218 let stft_n = stft_plan.output_bytes();
219 let stft_slice = &buffers.spectra[..stft_n];
220 let window_slice = &buffers.window[..fft_size];
221 let pcm_digest = *blake3::hash(pcm_slice).as_bytes();
222 let orig_digest = self.original.map(|raw| *blake3::hash(raw).as_bytes());
223 let meta_n = encode_metadata(
224 self,
225 &plan,
226 frame_rate,
227 window_slice,
228 &pcm_digest,
229 orig_digest.as_ref(),
230 buffers.metadata,
231 options.envelope,
232 )?;
233 let empty = EntryInput {
234 mode: 0x104,
235 revision: 1,
236 flags: 0,
237 stream_id: 0,
238 frame_id: 0,
239 start_tick: 0,
240 time_count: 0,
241 spatial_key: 0,
242 record_count: 1,
243 stride: 1,
244 codec: 0,
245 descriptor_id: 13,
246 payload: &[],
247 };
248 let mut entries = [empty; 3];
249 let mut count = 0;
250 if let Some(original) = self.original {
251 entries[count] = EntryInput {
252 record_count: original.len() as u64,
253 payload: original,
254 ..empty
255 };
256 count += 1;
257 }
258 entries[count] = EntryInput {
259 mode: 0x100,
260 revision: 1,
261 flags: 2,
262 stream_id: self.stream_id,
263 frame_id: 0,
264 start_tick: self.timing.start_tick,
265 time_count: plan.sample_frames() as u64,
266 spatial_key: 0,
267 record_count: plan.sample_frames() as u64,
268 stride: pcm_stride,
269 codec: 0,
270 descriptor_id: 5,
271 payload: pcm_slice,
272 };
273 count += 1;
274 entries[count] = EntryInput {
275 mode: 0x101,
276 revision: 1,
277 flags: 2,
278 stream_id: self.stream_id,
279 frame_id: 0,
280 start_tick: self.timing.start_tick,
281 time_count: plan.frames() as u64,
282 spatial_key: 0,
283 record_count: plan.frames() as u64,
284 stride: stft_stride,
285 codec: 0,
286 descriptor_id: 10,
287 payload: stft_slice,
288 };
289 count += 1;
290 let input = EnvelopeInput {
291 family: env::Family::QacV1Candidate,
292 flags: 0,
293 metadata: &buffers.metadata[..meta_n],
294 entries: &entries[..count],
295 };
296 super::super::encode(
297 input,
298 options.envelope,
299 options.shared,
300 options.signal,
301 scratch,
302 buffers.file,
303 output,
304 )
305 }
306}
307
308#[allow(clippy::too_many_arguments)]
309fn encode_metadata(
310 doc: &StftDocument<'_>,
311 plan: &Plan,
312 frame_rate: crate::audio::qac::signal::Rate,
313 window: &[f32],
314 pcm_digest: &[u8; 32],
315 orig_digest: Option<&[u8; 32]>,
316 out: &mut [u8],
317 limits: env::Limits,
318) -> Result<usize, Error> {
319 let t = doc.timing;
320 let scale = [t.scale];
321 let epoch = [t.epoch_seconds];
322 let ns = [t.epoch_nanoseconds];
323 let ticks_n = [t.ticks.numerator];
324 let ticks_d = [t.ticks.denominator];
325 let clock = [
326 f(1, V::U32(&scale)),
327 f(2, V::I64(&epoch)),
328 f(3, V::U32(&ns)),
329 f(4, V::U64(&ticks_n)),
330 f(5, V::U64(&ticks_d)),
331 ];
332
333 let empty = f(0, V::Bytes(&[]));
334 let pcm_role = [doc.pcm_provenance.role as u32];
335 let mut pcm_prov = [empty; 7];
336 let pcm_pn = fill_provenance(&mut pcm_prov, &pcm_role, orig_digest, &doc.pcm_provenance);
337 let stft_role = [doc.stft_provenance.role as u32];
338 let mut stft_prov = [empty; 7];
339 let stft_pn = fill_provenance(&mut stft_prov, &stft_role, Some(pcm_digest), &doc.stft_provenance);
340
341 let pcm_dims = [plan.sample_frames() as u64, u64::from(doc.channels)];
342 let pcm_shape = [
343 f(1, V::Utf8("urn:qualia:qac:pcm-preservation:1")),
344 f(2, V::Utf8("1")),
345 f(14, V::U64(&pcm_dims)),
346 f(15, V::Utf8("sample")),
347 ];
348 let stft_dims = [plan.frames() as u64, u64::from(doc.channels), u64::from(doc.fft_size)];
349 let stft_shape = [
350 f(1, V::Utf8("urn:qualia:qac:stft-preservation:1")),
351 f(2, V::Utf8("1")),
352 f(14, V::U64(&stft_dims)),
353 f(15, V::Utf8("real,imag")),
354 ];
355
356 let gain_one = [1.0f64];
357 let offset_zero = [0.0f64];
358 let rel_str = relation_name(doc.relation);
359 let pcm_encoding = [
360 f(1, V::Utf8(doc.channel_order)),
361 f(2, V::F64(&gain_one)),
362 f(3, V::F64(&offset_zero)),
363 f(4, V::Utf8(doc.pcm_purpose)),
364 f(5, V::Utf8(rel_str)),
365 ];
366 let stft_encoding = [
367 f(1, V::Utf8(doc.channel_order)),
368 f(2, V::F64(&gain_one)),
369 f(3, V::F64(&offset_zero)),
370 f(4, V::Utf8(doc.stft_purpose)),
371 f(5, V::Utf8(rel_str)),
372 ];
373
374 let (pcm_q, pcm_u) = doc.quantity.pcm_names();
375 let (stft_q, stft_u) = doc.quantity.stft_names();
376 let clock_id = [1];
377 let pcm_prov_id = [2];
378 let pcm_ext = [3, 4];
379 let channels = [doc.channels];
380 let f32_scalar = [Scalar::F32 as u32];
381 let in_rate_n = [t.samples.numerator];
382 let in_rate_d = [t.samples.denominator];
383 let orig_src = [1];
384 let mut pcm_desc = [empty; 12];
385 let mut pdn = 0;
386 for (k, v) in [
387 (1, V::MetadataRefs(&clock_id)),
388 (3, V::MetadataRefs(&pcm_prov_id)),
389 (7, V::Utf8(pcm_q)),
390 (8, V::Utf8(pcm_u)),
391 (9, V::U32(&channels)),
392 (10, V::Utf8("time-channel")),
393 (11, V::U32(&f32_scalar)),
394 (12, V::Utf8("urn:qualia:qac:pcm-preservation:1")),
395 (13, V::U64(&in_rate_n)),
396 (14, V::U64(&in_rate_d)),
397 ] {
398 push(&mut pcm_desc, &mut pdn, k, v);
399 }
400 if doc.original.is_some() {
401 push(&mut pcm_desc, &mut pdn, 17, V::EntryRefs(&orig_src));
402 }
403 push(&mut pcm_desc, &mut pdn, 18, V::MetadataRefs(&pcm_ext));
404
405 let fft_u32 = [doc.fft_size];
406 let hop_u32 = [doc.hop];
407 let zero_u32 = [0u32];
408 let zero_i64 = [0i64];
409 let transform = [
410 f(1, V::Utf8("STFT-complex")),
411 f(2, V::U32(&fft_u32)),
412 f(3, V::U32(&hop_u32)),
413 f(4, V::Utf8("hann-symmetric-authored-f32")),
414 f(6, V::Utf8("forward-unscaled-inverse-1/N")),
415 f(7, V::U32(&zero_u32)),
416 f(9, V::Utf8("forward-negative-exponent")),
417 f(10, V::I64(&zero_i64)),
418 f(11, V::Utf8("none")),
419 f(12, V::Utf8(doc.channel_order)),
420 f(13, V::U32(&fft_u32)),
421 f(14, V::U64(&in_rate_n)),
422 f(15, V::U64(&in_rate_d)),
423 f(16, V::F32(window)),
424 f(17, V::Utf8("source-entry-first-sample")),
425 ];
426
427 let stft_prov_id = [6];
428 let stft_tx_id = [9];
429 let stft_ext = [7, 8];
430 let cf32_scalar = [Scalar::ComplexF32 as u32];
431 let frame_rate_n = [frame_rate.numerator];
432 let frame_rate_d = [frame_rate.denominator];
433 let pcm_src = [doc.pcm_entry_index()];
434 let stft_desc = [
435 f(1, V::MetadataRefs(&clock_id)),
436 f(3, V::MetadataRefs(&stft_prov_id)),
437 f(5, V::MetadataRefs(&stft_tx_id)),
438 f(7, V::Utf8(stft_q)),
439 f(8, V::Utf8(stft_u)),
440 f(9, V::U32(&channels)),
441 f(10, V::Utf8("frame-channel-bin")),
442 f(11, V::U32(&cf32_scalar)),
443 f(12, V::Utf8("urn:qualia:qac:stft-preservation:1")),
444 f(13, V::U64(&frame_rate_n)),
445 f(14, V::U64(&frame_rate_d)),
446 f(17, V::EntryRefs(&pcm_src)),
447 f(18, V::MetadataRefs(&stft_ext)),
448 ];
449
450 let opaque_role = [4u32];
451 let orig_len = [doc.original.map_or(0, |s| s.len() as u64)];
452 let orig_prov_id = [11];
453 let orig_shape_id = [12];
454 let one = [1u32];
455 let byte_scalar = [Scalar::U8 as u32];
456 let orig_prov = [f(1, V::U32(&opaque_role))];
457 let orig_shape = [
458 f(1, V::Utf8("urn:qualia:qac:opaque-original:1")),
459 f(2, V::Utf8("1")),
460 f(14, V::U64(&orig_len)),
461 f(15, V::Utf8("byte")),
462 ];
463 let orig_desc = [
464 f(3, V::MetadataRefs(&orig_prov_id)),
465 f(7, V::Utf8("original_bytes")),
466 f(8, V::Utf8("1")),
467 f(9, V::U32(&one)),
468 f(10, V::Utf8("byte")),
469 f(11, V::U32(&byte_scalar)),
470 f(12, V::Utf8("urn:qualia:qac:opaque-original:1")),
471 f(18, V::MetadataRefs(&orig_shape_id)),
472 ];
473
474 let blocks = [
475 b(1, 1, &clock),
476 b(2, 4, &pcm_prov[..pcm_pn]),
477 b(3, 205, &pcm_shape),
478 b(4, 210, &pcm_encoding),
479 b(5, 3, &pcm_desc[..pdn]),
480 b(6, 4, &stft_prov[..stft_pn]),
481 b(7, 205, &stft_shape),
482 b(8, 210, &stft_encoding),
483 b(9, 201, &transform),
484 b(10, 3, &stft_desc),
485 b(11, 4, &orig_prov),
486 b(12, 205, &orig_shape),
487 b(13, 3, &orig_desc),
488 ];
489 let count = if doc.original.is_some() { 13 } else { 10 };
490 Ok(MetadataInput {
491 blocks: &blocks[..count],
492 }
493 .encode_into(out, limits)?
494 .len())
495}