Skip to main content

qualia_audio/
wav.rs

1//! Minimal WAV (PCM i16 / f32 LE) cold decoder — no external codec crate.
2
3use crate::types::{AudioError, AudioView, SampleFormat};
4use std::io::{self, Read, Seek, SeekFrom};
5
6#[derive(Debug, Clone)]
7pub struct DecodedWav {
8    pub sample_rate: u32,
9    pub channels: u16,
10    pub format: SampleFormat,
11    pub pcm: Vec<u8>,
12    pub frames: u32,
13}
14
15/// Parse a complete WAV file from bytes.
16pub fn decode_wav(bytes: &[u8]) -> Result<DecodedWav, AudioError> {
17    if bytes.len() < 44 || &bytes[0..4] != b"RIFF" || &bytes[8..12] != b"WAVE" {
18        return Err(AudioError::MalformedAudio);
19    }
20    let mut pos = 12usize;
21    let mut fmt_code = 0u16;
22    let mut channels = 0u16;
23    let mut sample_rate = 0u32;
24    let mut bits = 0u16;
25    let mut data: Option<&[u8]> = None;
26    while pos + 8 <= bytes.len() {
27        let id = &bytes[pos..pos + 4];
28        let size = u32::from_le_bytes([
29            bytes[pos + 4],
30            bytes[pos + 5],
31            bytes[pos + 6],
32            bytes[pos + 7],
33        ]) as usize;
34        pos += 8;
35        if pos + size > bytes.len() {
36            break;
37        }
38        let chunk = &bytes[pos..pos + size];
39        if id == b"fmt " && size >= 16 {
40            fmt_code = u16::from_le_bytes([chunk[0], chunk[1]]);
41            channels = u16::from_le_bytes([chunk[2], chunk[3]]);
42            sample_rate = u32::from_le_bytes([chunk[4], chunk[5], chunk[6], chunk[7]]);
43            bits = u16::from_le_bytes([chunk[14], chunk[15]]);
44        } else if id == b"data" {
45            data = Some(chunk);
46        }
47        pos += size + (size % 2); // word align
48    }
49    let data = data.ok_or(AudioError::MalformedAudio)?;
50    let format = match (fmt_code, bits) {
51        (1, 16) => SampleFormat::I16,
52        (1, 24) => SampleFormat::I24Packed,
53        (1, 32) => SampleFormat::I32,
54        (3, 32) => SampleFormat::F32,
55        _ => return Err(AudioError::UnsupportedFormat),
56    };
57    if channels == 0 || sample_rate == 0 {
58        return Err(AudioError::MalformedAudio);
59    }
60    let bps = match format {
61        SampleFormat::I16 => 2,
62        SampleFormat::I32 | SampleFormat::F32 => 4,
63        SampleFormat::I24Packed => 3,
64    };
65    let frames = (data.len() / (channels as usize * bps)) as u32;
66    Ok(DecodedWav {
67        sample_rate,
68        channels,
69        format,
70        pcm: data.to_vec(),
71        frames,
72    })
73}
74
75/// A seekable, bounded RIFF/WAVE PCM source. The owner must supply a stable,
76/// authorized reader whose range begins at its current position and remains
77/// unchanged for this object's lifetime. Parsing does not establish authority,
78/// provenance, or integrity. Reads use a caller-provided byte buffer.
79pub struct WavStream<R> {
80    reader: R,
81    sample_rate: u32,
82    channels: u16,
83    format: SampleFormat,
84    frames: u64,
85    frame_bytes: usize,
86    data_offset: u64,
87    frame: u64,
88    failed: bool,
89}
90
91fn invalid_wav(message: &'static str) -> io::Error {
92    io::Error::new(io::ErrorKind::InvalidData, message)
93}
94
95impl<R: Read + Seek> WavStream<R> {
96    /// Scan a bounded WAVE range. Chunk headers are limited to 4096; PCM 16,
97    /// packed PCM 24, PCM 32 and IEEE float 32 are admitted. The source length
98    /// is supplied by the owner so adjacent container data is never scanned.
99    pub fn open(mut reader: R, source_len: u64) -> io::Result<Self> {
100        let base = reader.stream_position()?;
101        let source_end = base.checked_add(source_len).ok_or_else(|| invalid_wav("WAV source overflow"))?;
102        if source_len < 12 { return Err(invalid_wav("truncated WAV header")); }
103        let mut header = [0u8; 12];
104        reader.read_exact(&mut header)?;
105        if &header[..4] != b"RIFF" || &header[8..] != b"WAVE" { return Err(invalid_wav("not RIFF/WAVE")); }
106        let riff_len = u64::from(u32::from_le_bytes(header[4..8].try_into().unwrap())) + 8;
107        let end = base.checked_add(riff_len).ok_or_else(|| invalid_wav("WAV length overflow"))?;
108        if riff_len < 12 || end > source_end { return Err(invalid_wav("WAV extends past source")); }
109        let mut pos = base + 12;
110        let mut fmt = None;
111        let mut data = None;
112        let mut chunks = 0usize;
113        while pos < end {
114            chunks += 1;
115            if chunks > 4096 || end - pos < 8 { return Err(invalid_wav("invalid WAV chunk table")); }
116            reader.seek(SeekFrom::Start(pos))?;
117            let mut h = [0u8; 8];
118            reader.read_exact(&mut h)?;
119            let size = u64::from(u32::from_le_bytes(h[4..8].try_into().unwrap()));
120            let start = pos + 8;
121            let next = start.checked_add(size).and_then(|n| n.checked_add(size & 1)).ok_or_else(|| invalid_wav("WAV chunk overflow"))?;
122            if next > end { return Err(invalid_wav("WAV chunk extends past RIFF")); }
123            if &h[..4] == b"fmt " {
124                if fmt.is_some() || size < 16 { return Err(invalid_wav("invalid or duplicate WAV format")); }
125                let mut f = [0u8; 16];
126                reader.read_exact(&mut f)?;
127                let code = u16::from_le_bytes(f[0..2].try_into().unwrap());
128                let channels = u16::from_le_bytes(f[2..4].try_into().unwrap());
129                let rate = u32::from_le_bytes(f[4..8].try_into().unwrap());
130                let byte_rate = u32::from_le_bytes(f[8..12].try_into().unwrap());
131                let align = u16::from_le_bytes(f[12..14].try_into().unwrap());
132                let bits = u16::from_le_bytes(f[14..16].try_into().unwrap());
133                let (format, bps) = match (code, bits) {
134                    (1, 16) => (SampleFormat::I16, 2u16),
135                    (1, 24) => (SampleFormat::I24Packed, 3),
136                    (1, 32) => (SampleFormat::I32, 4),
137                    (3, 32) => (SampleFormat::F32, 4),
138                    _ => return Err(invalid_wav("unsupported WAV format")),
139                };
140                let expected = channels.checked_mul(bps).ok_or_else(|| invalid_wav("WAV alignment overflow"))?;
141                if channels == 0 || channels > 32 || rate == 0 || align != expected || rate.checked_mul(u32::from(align)) != Some(byte_rate) {
142                    return Err(invalid_wav("invalid WAV layout"));
143                }
144                fmt = Some((format, channels, rate, usize::from(align)));
145            } else if &h[..4] == b"data" {
146                if data.replace((start, size)).is_some() { return Err(invalid_wav("duplicate WAV data")); }
147            }
148            pos = next;
149        }
150        let (format, channels, sample_rate, frame_bytes) = fmt.ok_or_else(|| invalid_wav("WAV format absent"))?;
151        let (data_offset, data_len) = data.ok_or_else(|| invalid_wav("WAV data absent"))?;
152        if data_len % frame_bytes as u64 != 0 { return Err(invalid_wav("partial WAV frame")); }
153        reader.seek(SeekFrom::Start(data_offset))?;
154        Ok(Self { reader, sample_rate, channels, format, frames: data_len / frame_bytes as u64, frame_bytes, data_offset, frame: 0, failed: false })
155    }
156
157    pub fn sample_rate(&self) -> u32 { self.sample_rate }
158    pub fn channels(&self) -> u16 { self.channels }
159    pub fn format(&self) -> SampleFormat { self.format }
160    pub fn frames(&self) -> u64 { self.frames }
161    pub fn position_frames(&self) -> u64 { self.frame }
162
163    /// Seek in whole frames, including the end-of-stream position.
164    pub fn seek_frame(&mut self, frame: u64) -> io::Result<()> {
165        if self.failed || frame > self.frames { return Err(io::Error::new(io::ErrorKind::InvalidInput, "WAV seek outside source or failed stream")); }
166        let offset = frame.checked_mul(self.frame_bytes as u64).and_then(|n| self.data_offset.checked_add(n)).ok_or_else(|| invalid_wav("WAV seek overflow"))?;
167        if let Err(e) = self.reader.seek(SeekFrom::Start(offset)) { self.failed = true; return Err(e); }
168        self.frame = frame;
169        Ok(())
170    }
171
172    /// Read whole frames into `output`; returns frames read. At EOF returns 0.
173    /// An I/O failure poisons the reader so partial bytes cannot be replayed as
174    /// a valid frame sequence. Caller may expose the filled bytes via AudioView.
175    pub fn read_frames(&mut self, output: &mut [u8]) -> io::Result<usize> {
176        if self.failed { return Err(invalid_wav("WAV stream failed")); }
177        if self.frame == self.frames { return Ok(0); }
178        let capacity = output.len() / self.frame_bytes;
179        if capacity == 0 { return Err(io::Error::new(io::ErrorKind::InvalidInput, "buffer cannot hold one frame")); }
180        let count = (self.frames - self.frame).min(capacity as u64) as usize;
181        let len = count * self.frame_bytes;
182        if let Err(e) = self.reader.read_exact(&mut output[..len]) { self.failed = true; return Err(e); }
183        self.frame += count as u64;
184        Ok(count)
185    }
186}
187
188impl DecodedWav {
189    /// View.
190    pub fn view(&self) -> AudioView<'_> {
191        let bps = match self.format {
192            SampleFormat::I16 => 2,
193            SampleFormat::I32 | SampleFormat::F32 => 4,
194            SampleFormat::I24Packed => 3,
195        };
196        AudioView {
197            bytes: &self.pcm,
198            frames: self.frames,
199            channels: self.channels,
200            sample_rate: self.sample_rate,
201            frame_stride_bytes: self.channels as u32 * bps,
202            format: self.format,
203        }
204    }
205}
206
207/// Encode mono i16 LE as a minimal WAV into `out`. Returns bytes written.
208pub fn encode_wav_i16_mono(
209    samples: &[i16],
210    sample_rate: u32,
211    out: &mut [u8],
212) -> Result<usize, AudioError> {
213    let data_len = samples.len() * 2;
214    let file_len = 44 + data_len;
215    if out.len() < file_len {
216        return Err(AudioError::OutputBufferTooSmall);
217    }
218    out[0..4].copy_from_slice(b"RIFF");
219    write_u32(&mut out[4..8], (file_len - 8) as u32);
220    out[8..12].copy_from_slice(b"WAVE");
221    out[12..16].copy_from_slice(b"fmt ");
222    write_u32(&mut out[16..20], 16);
223    write_u16(&mut out[20..22], 1); // PCM
224    write_u16(&mut out[22..24], 1); // mono
225    write_u32(&mut out[24..28], sample_rate);
226    write_u32(&mut out[28..32], sample_rate * 2);
227    write_u16(&mut out[32..34], 2);
228    write_u16(&mut out[34..36], 16);
229    out[36..40].copy_from_slice(b"data");
230    write_u32(&mut out[40..44], data_len as u32);
231    for (i, s) in samples.iter().enumerate() {
232        let b = s.to_le_bytes();
233        out[44 + i * 2] = b[0];
234        out[44 + i * 2 + 1] = b[1];
235    }
236    Ok(file_len)
237}
238
239fn write_u16(d: &mut [u8], v: u16) {
240    d[0] = (v & 0xFF) as u8;
241    d[1] = (v >> 8) as u8;
242}
243fn write_u32(d: &mut [u8], v: u32) {
244    d[0] = (v & 0xFF) as u8;
245    d[1] = ((v >> 8) & 0xFF) as u8;
246    d[2] = ((v >> 16) & 0xFF) as u8;
247    d[3] = ((v >> 24) & 0xFF) as u8;
248}
249
250#[cfg(test)]
251mod tests {
252    use super::*;
253    use std::io::Cursor;
254
255    #[test]
256    fn wav_roundtrip() {
257        let samples = [0i16, 1000, -1000, 0];
258        let mut buf = vec![0u8; 128];
259        let n = encode_wav_i16_mono(&samples, 16000, &mut buf).unwrap();
260        let d = decode_wav(&buf[..n]).unwrap();
261        assert_eq!(d.sample_rate, 16000);
262        assert_eq!(d.frames, 4);
263        assert_eq!(d.channels, 1);
264    }
265
266    #[test]
267    fn packed_24_decode_and_stream_in_small_blocks() {
268        let mut wav = Vec::new();
269        wav.extend_from_slice(b"RIFF"); wav.extend_from_slice(&46u32.to_le_bytes());
270        wav.extend_from_slice(b"WAVEfmt "); wav.extend_from_slice(&16u32.to_le_bytes());
271        wav.extend_from_slice(&1u16.to_le_bytes()); wav.extend_from_slice(&1u16.to_le_bytes());
272        wav.extend_from_slice(&48_000u32.to_le_bytes()); wav.extend_from_slice(&144_000u32.to_le_bytes());
273        wav.extend_from_slice(&3u16.to_le_bytes()); wav.extend_from_slice(&24u16.to_le_bytes());
274        wav.extend_from_slice(b"data"); wav.extend_from_slice(&9u32.to_le_bytes());
275        wav.extend_from_slice(&[0,0,0x80, 0xff,0xff,0x7f, 0,0,0]); wav.push(0);
276        let decoded = decode_wav(&wav).unwrap();
277        assert_eq!(decoded.format, SampleFormat::I24Packed);
278        assert_eq!(decoded.frames, 3);
279        let mut converted = [0.0; 3];
280        crate::convert::to_mono_f32(decoded.view(), &mut converted).unwrap();
281        assert_eq!(converted[0], -1.0);
282        assert!(converted[1] > 0.9999);
283        let mut stream = WavStream::open(Cursor::new(&wav), wav.len() as u64).unwrap();
284        assert_eq!((stream.channels(), stream.sample_rate(), stream.frames()), (1, 48_000, 3));
285        let mut block = [0u8; 6];
286        assert_eq!(stream.read_frames(&mut block).unwrap(), 2);
287        assert_eq!(&block, &[0,0,0x80,0xff,0xff,0x7f]);
288        assert_eq!(stream.read_frames(&mut block).unwrap(), 1);
289        assert_eq!(stream.read_frames(&mut block).unwrap(), 0);
290        stream.seek_frame(1).unwrap();
291        assert_eq!(stream.read_frames(&mut block).unwrap(), 2);
292        assert_eq!(&block, &[0xff,0xff,0x7f,0,0,0]);
293        assert!(stream.seek_frame(4).is_err());
294    }
295
296    #[test]
297    fn streaming_wav_rejects_truncation_partial_frames_and_invalid_ranges() {
298        let mut wav = vec![0u8; 48];
299        let n = encode_wav_i16_mono(&[1, 2], 8, &mut wav).unwrap();
300        let mut trailing = wav.clone(); trailing.extend_from_slice(&[0xaa; 10]);
301        assert!(WavStream::open(Cursor::new(&trailing), (n - 1) as u64).is_err());
302        let mut stream = WavStream::open(Cursor::new(&trailing), n as u64).unwrap();
303        assert!(stream.read_frames(&mut [0u8; 1]).is_err());
304        let mut output = [0x55u8; 8];
305        assert_eq!(stream.read_frames(&mut output).unwrap(), 2);
306        assert_eq!(&output[..4], &[1, 0, 2, 0]);
307        assert_eq!(&output[4..], &[0x55; 4]);
308        assert_eq!(stream.read_frames(&mut output).unwrap(), 0);
309        assert!(stream.seek_frame(3).is_err());
310        wav[40..44].copy_from_slice(&3u32.to_le_bytes());
311        assert!(WavStream::open(Cursor::new(&wav), n as u64).is_err());
312    }
313}