Skip to main content

qualia_audio/
types.rs

1//! Stable auditory ABI (fixed-layout, caller-buffered where hot).
2
3/// Maximum events written per `infer_chunk`.
4pub const MAX_EVENTS: usize = 64;
5/// Maximum transcript tokens per chunk.
6pub const MAX_TRANSCRIPT_TOKENS: usize = 128;
7/// Max embed dim written.
8pub const MAX_EMBED_DIM: usize = 64;
9
10#[repr(u8)]
11#[derive(Debug, Clone, Copy, PartialEq, Eq)]
12pub enum SampleFormat {
13    I16 = 0,
14    I24Packed = 1,
15    I32 = 2,
16    F32 = 3,
17}
18
19/// Borrowed audio view — no ownership of samples.
20#[derive(Debug, Clone, Copy)]
21pub struct AudioView<'a> {
22    pub bytes: &'a [u8],
23    pub frames: u32,
24    pub channels: u16,
25    pub sample_rate: u32,
26    /// Bytes between frame starts (≥ channels × sample size).
27    pub frame_stride_bytes: u32,
28    pub format: SampleFormat,
29}
30
31impl<'a> AudioView<'a> {
32    #[inline]
33    /// Bytes per sample.
34    pub fn bytes_per_sample(self) -> u32 {
35        match self.format {
36            SampleFormat::I16 => 2,
37            SampleFormat::I24Packed => 3,
38            SampleFormat::I32 | SampleFormat::F32 => 4,
39        }
40    }
41
42    /// `true` when well-formed.
43    pub fn is_well_formed(self) -> bool {
44        if self.frames == 0 || self.channels == 0 || self.sample_rate == 0 {
45            return false;
46        }
47        let need = self
48            .frame_stride_bytes
49            .saturating_mul(self.frames.saturating_sub(1))
50            .saturating_add(self.channels as u32 * self.bytes_per_sample());
51        self.bytes.len() as u64 >= need as u64
52    }
53}
54
55/// One acoustic event proposal (epistemic, not ground truth).
56#[repr(C)]
57#[derive(Debug, Clone, Copy, PartialEq, Eq)]
58pub struct AuditoryEvent {
59    pub class_hash: u64,
60    pub source_hash: u64,
61    pub confidence_u16: u16,
62    pub channel: u16,
63    pub start_frame: u64,
64    pub end_frame: u64,
65    pub track_id: u32,
66    pub flags: u32,
67}
68
69impl AuditoryEvent {
70    pub const FLAG_REFERENCE_BACKEND: u32 = 1;
71    pub const FLAG_LOW_ASSURANCE: u32 = 2;
72    pub const FLAG_VAD: u32 = 4;
73
74    /// Empty instance.
75    pub fn empty() -> Self {
76        Self {
77            class_hash: 0,
78            source_hash: 0,
79            confidence_u16: 0,
80            channel: 0,
81            start_frame: 0,
82            end_frame: 0,
83            track_id: 0,
84            flags: 0,
85        }
86    }
87
88    /// Confidence as f32.
89    pub fn confidence_f32(self) -> f32 {
90        self.confidence_u16 as f32 / 65535.0
91    }
92}
93
94#[repr(C)]
95#[derive(Debug, Clone, Copy, PartialEq, Eq)]
96pub struct TranscriptToken {
97    pub form_hash: u64,
98    pub proposed_meaning_hash: u64,
99    pub confidence_u16: u16,
100    pub language_slot: u16,
101    pub start_frame: u64,
102    pub end_frame: u64,
103    pub speaker_track: u32,
104    pub flags: u32,
105}
106
107impl TranscriptToken {
108    /// Empty instance.
109    pub fn empty() -> Self {
110        Self {
111            form_hash: 0,
112            proposed_meaning_hash: 0,
113            confidence_u16: 0,
114            language_slot: 0,
115            start_frame: 0,
116            end_frame: 0,
117            speaker_track: 0,
118            flags: 0,
119        }
120    }
121}
122
123#[derive(Debug, Clone, Copy, PartialEq, Eq)]
124pub struct AuditoryCapabilities {
125    pub max_events: u16,
126    pub embed_dim: u16,
127    pub supports_vad: bool,
128    pub supports_transcript: bool,
129    pub is_reference_backend: bool,
130}
131
132#[derive(Debug, Clone, Copy, PartialEq, Eq)]
133pub struct AuditoryOutputCounts {
134    pub events: usize,
135    pub tokens: usize,
136    pub embedding_written: usize,
137}
138
139#[derive(Debug, Clone, Copy, PartialEq, Eq)]
140pub enum AudioError {
141    MalformedAudio,
142    OutputBufferTooSmall,
143    WorkspaceTooSmall,
144    BackendUnavailable,
145    UnsupportedFormat,
146    Cancelled,
147    PermissionDenied,
148    /// A parameter was out of range or inconsistent (e.g. non-power-of-two FFT size).
149    InvalidParameter,
150}
151
152/// Backend-agnostic auditory model.
153pub trait AuditoryModel {
154    fn capabilities(&self) -> AuditoryCapabilities;
155
156    fn infer_chunk(
157        &mut self,
158        audio: AudioView<'_>,
159        events_out: &mut [AuditoryEvent],
160        tokens_out: &mut [TranscriptToken],
161        embedding_out: &mut [f32],
162        workspace: &mut [u8],
163    ) -> Result<AuditoryOutputCounts, AudioError>;
164}