use crate::audio::AudioSpec;
use crate::decoder::Decoder;
use crate::error::DecodeError;
use crate::sample::{SampleFormat, MAX_BYTES_PER_SAMPLE};
const READY_LIMIT: usize = 65_536;
#[derive(Debug)]
pub struct PcmDecoder {
format: SampleFormat,
spec: AudioSpec,
pending: [u8; MAX_BYTES_PER_SAMPLE],
pending_len: usize,
ready: Vec<f32>,
produced: u64,
finished: bool,
}
impl PcmDecoder {
pub const fn new(format: SampleFormat, spec: AudioSpec) -> Self {
Self {
format,
spec,
pending: [0; MAX_BYTES_PER_SAMPLE],
pending_len: 0,
ready: Vec::new(),
produced: 0,
finished: false,
}
}
pub const fn format(&self) -> SampleFormat {
self.format
}
pub fn buffered_bytes(&self) -> usize {
let channels = u64::from(self.spec.channels).max(1);
let inside_frame = (self.produced % channels) as usize;
inside_frame * self.format.bytes_per_sample() + self.pending_len
}
fn frame_bytes(&self) -> usize {
usize::from(self.spec.channels).max(1) * self.format.bytes_per_sample()
}
fn push_samples(&mut self, bytes: &[u8]) {
self.produced += self.format.decode(bytes, &mut self.ready) as u64;
}
}
impl Decoder for PcmDecoder {
fn output_spec(&self) -> AudioSpec {
self.spec
}
fn feed(&mut self, input: &[u8]) -> Result<usize, DecodeError> {
if self.finished {
return Ok(0);
}
let mut room = READY_LIMIT.saturating_sub(self.ready.len());
if room == 0 {
return Ok(0);
}
let width = self.format.bytes_per_sample();
let mut taken = 0;
if self.pending_len > 0 {
let take = (width - self.pending_len).min(input.len());
self.pending[self.pending_len..self.pending_len + take].copy_from_slice(&input[..take]);
self.pending_len += take;
taken = take;
if self.pending_len < width {
return Ok(taken);
}
let completed = self.pending;
self.push_samples(&completed[..width]);
self.pending_len = 0;
room -= 1;
}
let rest = &input[taken..];
let whole = (rest.len() / width).min(room) * width;
self.push_samples(&rest[..whole]);
taken += whole;
let tail = &input[taken..];
if tail.len() < width {
self.pending[..tail.len()].copy_from_slice(tail);
self.pending_len = tail.len();
taken += tail.len();
}
Ok(taken)
}
fn decode(&mut self, output: &mut Vec<f32>) -> Result<usize, DecodeError> {
if self.finished {
return Ok(0);
}
let produced = self.ready.len();
output.append(&mut self.ready);
Ok(produced)
}
fn flush(&mut self, output: &mut Vec<f32>) -> Result<usize, DecodeError> {
if self.finished {
return Ok(0);
}
self.finished = true;
let held = self.buffered_bytes();
if held > 0 {
return Err(DecodeError::Truncated {
expected: self.frame_bytes() as u64,
available: held as u64,
});
}
let produced = self.ready.len();
output.append(&mut self.ready);
Ok(produced)
}
fn reset(&mut self) {
self.pending_len = 0;
self.ready.clear();
self.produced = 0;
self.finished = false;
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::audio::AudioBuffer;
use crate::sample::{I24_MAX, I24_MIN};
const ALL: [SampleFormat; 12] = [
SampleFormat::U8,
SampleFormat::I8,
SampleFormat::I16Le,
SampleFormat::I16Be,
SampleFormat::I24Le,
SampleFormat::I24Be,
SampleFormat::I32Le,
SampleFormat::I32Be,
SampleFormat::F32Le,
SampleFormat::F32Be,
SampleFormat::F64Le,
SampleFormat::F64Be,
];
fn drive(
decoder: &mut dyn Decoder,
input: &[u8],
chunk: usize,
) -> Result<AudioBuffer, DecodeError> {
let mut samples = Vec::new();
for piece in input.chunks(chunk) {
let mut offset = 0;
while offset < piece.len() {
offset += decoder.feed(&piece[offset..])?;
while decoder.decode(&mut samples)? > 0 {}
}
}
decoder.flush(&mut samples)?;
Ok(AudioBuffer::from_samples(decoder.output_spec(), samples))
}
fn encode(format: SampleFormat, samples: &[f32]) -> Vec<u8> {
let mut bytes = Vec::new();
format.encode(samples, &mut bytes);
bytes
}
#[test]
fn a_headerless_stream_decodes_at_the_spec_it_was_given() {
let mut decoder = PcmDecoder::new(SampleFormat::I16Le, AudioSpec::mono(8_000));
assert_eq!(decoder.format(), SampleFormat::I16Le);
assert_eq!(decoder.output_spec(), AudioSpec::mono(8_000));
let bytes = [0x00, 0x00, 0x00, 0x40, 0x00, 0x80, 0x00, 0xc0];
let decoded = drive(&mut decoder, &bytes, 64).expect("decode");
assert_eq!(decoded.samples(), [0.0, 0.5, -1.0, -0.5]);
assert_eq!(decoded.sample_rate(), 8_000);
assert_eq!(decoded.frames(), 4);
}
#[test]
fn the_feed_boundary_is_invisible_for_every_format() {
let samples: Vec<f32> = (0..64).map(|i| (i as f32 / 32.0) - 1.0).collect();
for format in ALL {
let bytes = encode(format, &samples);
let reference = {
let mut decoder = PcmDecoder::new(format, AudioSpec::mono(16_000));
drive(&mut decoder, &bytes, bytes.len()).expect("whole-input decode")
};
for chunk in [1, 2, 3, 5, 7, 8, 13, 64] {
let mut decoder = PcmDecoder::new(format, AudioSpec::mono(16_000));
let decoded = drive(&mut decoder, &bytes, chunk).expect("chunked decode");
assert_eq!(
decoded.samples(),
reference.samples(),
"{format:?} changed with a {chunk}-byte feed size"
);
}
}
}
#[test]
fn a_partial_sample_is_held_until_the_rest_arrives() {
let mut decoder = PcmDecoder::new(SampleFormat::F64Be, AudioSpec::mono(48_000));
let bytes = [0x3f, 0xf0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]; let mut out = Vec::new();
for (index, byte) in bytes.iter().enumerate() {
assert_eq!(decoder.feed(&[*byte]).expect("feed"), 1);
let produced = decoder.decode(&mut out).expect("decode");
if index < 7 {
assert_eq!(produced, 0, "byte {index} completed a sample too early");
assert_eq!(decoder.buffered_bytes(), index + 1);
} else {
assert_eq!(produced, 1, "the last byte must complete the sample");
assert_eq!(decoder.buffered_bytes(), 0);
}
}
assert_eq!(out, [1.0]);
assert_eq!(decoder.flush(&mut out).expect("flush"), 0);
}
#[test]
fn a_sample_split_across_two_feeds_is_reassembled() {
let mut decoder = PcmDecoder::new(SampleFormat::I24Le, AudioSpec::mono(44_100));
let mut out = Vec::new();
assert_eq!(decoder.feed(&[0xff, 0xff]).expect("feed"), 2);
assert_eq!(decoder.decode(&mut out).expect("decode"), 0);
assert_eq!(decoder.buffered_bytes(), 2);
assert_eq!(decoder.feed(&[0x7f]).expect("feed"), 1);
assert_eq!(decoder.decode(&mut out).expect("decode"), 1);
assert_eq!(out, [8_388_607.0 / 8_388_608.0]);
}
#[test]
fn a_feed_completing_one_sample_and_starting_another_holds_only_the_tail() {
let mut decoder = PcmDecoder::new(SampleFormat::I32Le, AudioSpec::mono(16_000));
let mut out = Vec::new();
assert_eq!(decoder.feed(&[0x00, 0x00]).expect("feed"), 2);
assert_eq!(
decoder.feed(&[0x00, 0x40, 0x11, 0x22, 0x33]).expect("feed"),
5
);
assert_eq!(decoder.decode(&mut out).expect("decode"), 1);
assert_eq!(out, [0.5]);
assert_eq!(decoder.buffered_bytes(), 3);
}
#[test]
fn a_partial_sample_at_end_of_stream_is_truncated() {
let mut decoder = PcmDecoder::new(SampleFormat::I32Be, AudioSpec::mono(16_000));
decoder.feed(&[0x11, 0x22, 0x33]).expect("feed");
let mut out = Vec::new();
let error = decoder.flush(&mut out).expect_err("flush must reject");
assert!(
matches!(
error,
DecodeError::Truncated {
expected: 4,
available: 3
}
),
"unexpected error: {error}"
);
assert_eq!(decoder.flush(&mut out).expect("second flush"), 0);
}
#[test]
fn a_partial_frame_at_end_of_stream_is_truncated() {
let mut decoder = PcmDecoder::new(SampleFormat::I16Le, AudioSpec::new(44_100, 2));
let mut out = Vec::new();
decoder.feed(&[0x00, 0x40]).expect("feed");
assert_eq!(decoder.decode(&mut out).expect("decode"), 1);
assert_eq!(
decoder.buffered_bytes(),
2,
"one sample into a 4-byte frame"
);
let error = decoder.flush(&mut out).expect_err("flush must reject");
assert!(
matches!(
error,
DecodeError::Truncated {
expected: 4,
available: 2
}
),
"unexpected error: {error}"
);
let mut decoder = PcmDecoder::new(SampleFormat::I16Le, AudioSpec::new(44_100, 2));
let decoded = drive(&mut decoder, &[0x00, 0x40, 0x00, 0xc0], 3).expect("decode");
assert_eq!(decoded.frames(), 1);
assert_eq!(decoded.samples(), [0.5, -0.5]);
}
#[test]
fn a_partial_sample_inside_a_partial_frame_reports_the_frame() {
let mut decoder = PcmDecoder::new(SampleFormat::I16Be, AudioSpec::new(48_000, 2));
decoder.feed(&[0x01, 0x02, 0x03]).expect("feed");
let mut out = Vec::new();
while decoder.decode(&mut out).expect("decode") > 0 {}
assert_eq!(decoder.buffered_bytes(), 3);
let error = decoder.flush(&mut out).expect_err("flush must reject");
assert!(
matches!(
error,
DecodeError::Truncated {
expected: 4,
available: 3
}
),
"unexpected error: {error}"
);
}
#[test]
fn the_sample_count_is_exact_for_every_format_and_layout() {
for format in ALL {
for channels in [1_u16, 2, 6] {
let frames = 50;
let spec = AudioSpec::new(48_000, channels);
let count = frames * usize::from(channels);
let bytes = encode(format, &vec![0.125; count]);
let mut decoder = PcmDecoder::new(format, spec);
let decoded = drive(&mut decoder, &bytes, 13).expect("decode");
assert_eq!(
decoded.samples().len(),
count,
"{format:?} at {channels} channels produced the wrong count"
);
assert_eq!(decoded.frames(), frames);
}
}
}
#[test]
fn a_starved_decoder_reports_zero_rather_than_end_of_stream() {
let mut decoder = PcmDecoder::new(SampleFormat::I16Le, AudioSpec::mono(16_000));
let mut out = Vec::new();
assert_eq!(decoder.decode(&mut out).expect("decode"), 0);
assert_eq!(decoder.feed(&[0x01]).expect("feed"), 1);
assert_eq!(decoder.decode(&mut out).expect("decode"), 0);
assert!(out.is_empty());
assert_eq!(decoder.feed(&[0x02]).expect("feed"), 1);
assert_eq!(decoder.decode(&mut out).expect("decode"), 1);
}
#[test]
fn feeding_after_flush_is_quiet_until_reset() {
let mut decoder = PcmDecoder::new(SampleFormat::U8, AudioSpec::mono(8_000));
let mut out = Vec::new();
assert_eq!(decoder.flush(&mut out).expect("flush"), 0);
assert_eq!(decoder.feed(&[0x80]).expect("feed"), 0);
assert_eq!(decoder.decode(&mut out).expect("decode"), 0);
assert!(out.is_empty());
decoder.reset();
assert_eq!(decoder.feed(&[0xff]).expect("feed"), 1);
assert_eq!(decoder.decode(&mut out).expect("decode"), 1);
assert_eq!(out, [127.0 / 128.0]);
}
#[test]
fn reset_drops_a_held_partial_frame() {
let mut decoder = PcmDecoder::new(SampleFormat::I16Le, AudioSpec::new(16_000, 2));
decoder.feed(&[0x01, 0x02, 0x03]).expect("feed");
assert_eq!(decoder.buffered_bytes(), 3);
decoder.reset();
assert_eq!(decoder.buffered_bytes(), 0);
let mut out = Vec::new();
assert_eq!(decoder.flush(&mut out).expect("flush after reset"), 0);
}
#[test]
fn a_full_decoder_applies_back_pressure_instead_of_growing() {
let spec = AudioSpec::mono(16_000);
let mut decoder = PcmDecoder::new(SampleFormat::U8, spec);
let bytes: Vec<u8> = (0..READY_LIMIT * 3).map(|i| (i % 256) as u8).collect();
let first = decoder.feed(&bytes).expect("feed");
assert!(first < bytes.len(), "a full decoder must return short");
assert_eq!(first, READY_LIMIT);
assert_eq!(decoder.feed(&bytes[first..]).expect("feed"), 0);
let decoded = drive(&mut decoder, &bytes, bytes.len()).expect("decode");
assert_eq!(decoded.samples().len(), bytes.len() + first);
}
#[test]
fn every_format_survives_the_decoder_round_trip() {
let edges = [0.0_f32, 0.5, -0.5, 1.0, -1.0, 1.0 / 128.0, -0.75];
for format in ALL {
let bytes = encode(format, &edges);
let mut decoder = PcmDecoder::new(format, AudioSpec::mono(16_000));
let decoded = drive(&mut decoder, &bytes, 5).expect("decode");
assert_eq!(decoded.samples().len(), edges.len());
for (original, recovered) in edges.iter().zip(decoded.samples()) {
assert!(
(original - recovered).abs() <= 1.0 / 128.0,
"{format:?}: {original} came back as {recovered}"
);
}
}
}
#[test]
fn the_integer_extremes_decode_to_the_expected_floats() {
let cases: [(SampleFormat, &[u8], f32); 6] = [
(SampleFormat::U8, &[0x00], -1.0),
(SampleFormat::I16Be, &[0x80, 0x00], -1.0),
(SampleFormat::I16Be, &[0x7f, 0xff], 32767.0 / 32768.0),
(SampleFormat::I24Be, &[0x80, 0x00, 0x00], -1.0),
(SampleFormat::I32Be, &[0x80, 0x00, 0x00, 0x00], -1.0),
(SampleFormat::I32Be, &[0x7f, 0xff, 0xff, 0xff], 1.0),
];
for (format, bytes, expected) in cases {
let mut decoder = PcmDecoder::new(format, AudioSpec::mono(8_000));
let decoded = drive(&mut decoder, bytes, 1).expect("decode");
assert_eq!(decoded.samples(), [expected], "{format:?} on {bytes:02x?}");
}
assert_eq!(I24_MIN, -8_388_608);
assert_eq!(I24_MAX, 8_388_607);
}
#[test]
fn the_decoder_is_object_safe_and_sendable() {
fn assert_send<T: Send>() {}
assert_send::<PcmDecoder>();
let boxed: Box<dyn Decoder> = Box::new(PcmDecoder::new(
SampleFormat::F32Le,
AudioSpec::new(44_100, 2),
));
assert_eq!(boxed.output_spec().channels, 2);
}
#[test]
fn a_zero_channel_spec_does_not_divide_by_zero() {
let mut decoder = PcmDecoder::new(SampleFormat::I16Le, AudioSpec::new(16_000, 0));
let mut out = Vec::new();
decoder.feed(&[0x00, 0x40]).expect("feed");
assert_eq!(decoder.decode(&mut out).expect("decode"), 1);
assert_eq!(decoder.buffered_bytes(), 0);
assert_eq!(decoder.flush(&mut out).expect("flush"), 0);
}
fn fnv1a(samples: &[f32]) -> u64 {
let mut hash = 0xcbf2_9ce4_8422_2325_u64;
for sample in samples {
for byte in sample.to_bits().to_le_bytes() {
hash ^= u64::from(byte);
hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
}
}
hash
}
fn witness_signal() -> Vec<f32> {
let mut state = 0x2545_F491_4F6C_DD1D_u64;
let mut signal: Vec<f32> = (0..254)
.map(|_| {
state = state
.wrapping_mul(6_364_136_223_846_793_005)
.wrapping_add(1_442_695_040_888_963_407);
crate::sample::i32_to_f32((state >> 32) as u32 as i32)
})
.collect();
signal.push(1.5);
signal.push(-3.0);
signal
}
#[test]
fn decoded_output_is_bit_identical_to_a_pinned_witness() {
let signal = witness_signal();
let mut samples = Vec::new();
for format in ALL {
let bytes = encode(format, &signal);
let mut decoder = PcmDecoder::new(format, AudioSpec::mono(16_000));
let decoded = drive(&mut decoder, &bytes, 7).expect("decode");
samples.extend_from_slice(decoded.samples());
}
assert_eq!(samples.len(), ALL.len() * signal.len());
assert_eq!(
fnv1a(&samples),
0x57ac_66d6_2a28_b665,
"decoded output changed"
);
}
}