Skip to main content

qualia_core_db/audio/qac/signal/stft/
writer.rs

1//! Current-format Hann-windowed complex STFT + full retained f32 PCM producer.
2//! No fake synthesis, zero padding, magnitude reduction, or hidden allocation.
3use 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
33/// Caller-owned staging buffers for STFT calculation and container serialization.
34/// None of these buffers is a published result when encoding returns an error.
35pub 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    /// Computes Hann-windowed complex STFT via `etalon_signal`, serializes PCM,
192    /// STFT, optional opaque original, and strict schema metadata, then runs
193    /// full candidate admission before writing any byte to `output`.
194    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}