use std::ops::Range;
use crate::audio::{AudioBuffer, AudioSpec};
use crate::codec::{CodecId, FourCc};
use crate::error::DecodeError;
use crate::md5::Md5;
use crate::sample::quantize;
use crate::source::StreamSource;
const MAGIC: FourCc = crate::probe::FLAC_MAGIC;
const METADATA_HEADER_BYTES: usize = 4;
const BLOCK_STREAMINFO: u8 = 0;
const BLOCK_FORBIDDEN: u8 = 127;
const STREAMINFO_BYTES: usize = 34;
const MIN_BLOCK_SIZE: u32 = 16;
const MAX_BLOCK_SIZE: u32 = 65_535;
const MAX_CHANNELS: u8 = 8;
const MAX_LPC_ORDER: usize = 32;
const MIN_FRAME_HEADER_BYTES: usize = 6;
const MAX_VERBATIM_FRAME_BYTES: usize = MAX_BLOCK_SIZE as usize * MAX_CHANNELS as usize * (32 / 8);
const MAX_FRAME_BYTES: usize = MAX_VERBATIM_FRAME_BYTES + 4_096;
const READY_LIMIT: usize = 65_536;
const MD5_STAGE_BYTES: usize = 4_096;
const CRC8: [u8; 256] = crc8_table();
const CRC16: [u16; 256] = crc16_table();
const fn crc8_table() -> [u8; 256] {
let mut table = [0u8; 256];
let mut index = 0;
while index < 256 {
let mut crc = index as u8;
let mut bit = 0;
while bit < 8 {
crc = if crc & 0x80 != 0 {
(crc << 1) ^ 0x07
} else {
crc << 1
};
bit += 1;
}
table[index] = crc;
index += 1;
}
table
}
const fn crc16_table() -> [u16; 256] {
let mut table = [0u16; 256];
let mut index = 0;
while index < 256 {
let mut crc = (index as u16) << 8;
let mut bit = 0;
while bit < 8 {
crc = if crc & 0x8000 != 0 {
(crc << 1) ^ 0x8005
} else {
crc << 1
};
bit += 1;
}
table[index] = crc;
index += 1;
}
table
}
fn crc8(bytes: &[u8]) -> u8 {
bytes
.iter()
.fold(0u8, |crc, byte| CRC8[usize::from(crc ^ byte)])
}
fn crc16(bytes: &[u8]) -> u16 {
bytes.iter().fold(0u16, |crc, byte| {
(crc << 8) ^ CRC16[usize::from((crc >> 8) as u8 ^ byte)]
})
}
const WINDOW_BITS: u32 = 57;
struct BitReader<'a> {
bytes: &'a [u8],
bit: usize,
base: u64,
}
impl<'a> BitReader<'a> {
fn new(bytes: &'a [u8], base: u64) -> Self {
Self {
bytes,
bit: 0,
base,
}
}
fn bits_left(&self) -> usize {
(self.bytes.len() * 8).saturating_sub(self.bit)
}
fn window(&self) -> u64 {
let byte = self.bit >> 3;
let shift = (self.bit & 7) as u32;
let mut buffer = [0u8; 8];
let take = self.bytes.len().saturating_sub(byte).min(8);
buffer[..take].copy_from_slice(&self.bytes[byte..byte + take]);
u64::from_be_bytes(buffer) << shift
}
fn read_bits(&mut self, count: u32) -> Result<u64, DecodeError> {
debug_assert!((1..=WINDOW_BITS).contains(&count));
if self.bits_left() < count as usize {
return Err(self.truncated(count as usize));
}
let value = self.window() >> (64 - count);
self.bit += count as usize;
Ok(value)
}
fn read_signed(&mut self, count: u32) -> Result<i64, DecodeError> {
let raw = self.read_bits(count)?;
Ok(((raw << (64 - count)) as i64) >> (64 - count))
}
fn read_unary(&mut self) -> Result<u32, DecodeError> {
let mut zeros = 0u32;
loop {
let window = self.window();
if window == 0 {
let step = self.bits_left().min(WINDOW_BITS as usize);
if step == 0 {
return Err(self.truncated(1));
}
zeros = zeros.saturating_add(step as u32);
self.bit += step;
continue;
}
let run = window.leading_zeros() as usize;
if run >= self.bits_left() {
return Err(self.truncated(run + 1));
}
self.bit += run + 1;
return Ok(zeros.saturating_add(run as u32));
}
}
fn align_to_byte(&mut self) {
self.bit = (self.bit + 7) & !7;
}
fn byte_position(&self) -> usize {
self.bit >> 3
}
fn truncated(&self, more_bits: usize) -> DecodeError {
DecodeError::Truncated {
expected: self.bit.saturating_add(more_bits).div_ceil(8) as u64,
available: self.bytes.len() as u64,
}
}
fn malformed(&self, expected: &'static str) -> DecodeError {
DecodeError::Malformed {
expected,
offset: self.base + (self.bit >> 3) as u64,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub struct FlacStreamInfo {
pub min_block_size: u16,
pub max_block_size: u16,
pub min_frame_size: Option<u32>,
pub max_frame_size: Option<u32>,
pub spec: AudioSpec,
pub bits_per_sample: u8,
pub total_samples: Option<u64>,
pub md5: Option<[u8; 16]>,
}
impl FlacStreamInfo {
pub fn from_block(body: &[u8]) -> Result<Self, DecodeError> {
parse_streaminfo(body, 0)
}
fn md5_bytes_per_sample(&self) -> usize {
usize::from(self.bits_per_sample).div_ceil(8)
}
}
fn parse_streaminfo(body: &[u8], offset: u64) -> Result<FlacStreamInfo, DecodeError> {
let malformed = |expected| DecodeError::Malformed { expected, offset };
if body.len() != STREAMINFO_BYTES {
return Err(malformed("a streaminfo block of exactly 34 bytes"));
}
let mut reader = BitReader::new(body, offset);
let min_block_size = reader.read_bits(16)? as u16;
let max_block_size = reader.read_bits(16)? as u16;
let min_frame_size = reader.read_bits(24)? as u32;
let max_frame_size = reader.read_bits(24)? as u32;
let sample_rate = reader.read_bits(20)? as u32;
let channels = reader.read_bits(3)? as u16 + 1;
let bits_per_sample = reader.read_bits(5)? as u8 + 1;
let total_samples = reader.read_bits(36)?;
let mut md5 = [0u8; 16];
md5.copy_from_slice(&body[18..34]);
if u32::from(min_block_size) < MIN_BLOCK_SIZE || u32::from(max_block_size) < MIN_BLOCK_SIZE {
return Err(malformed("a streaminfo block size of at least 16 samples"));
}
if min_block_size > max_block_size {
return Err(malformed(
"a streaminfo minimum block size no larger than the maximum",
));
}
if sample_rate == 0 {
return Err(malformed("a streaminfo sample rate above zero"));
}
if !(4..=32).contains(&bits_per_sample) {
return Err(malformed("a streaminfo bit depth between 4 and 32"));
}
Ok(FlacStreamInfo {
min_block_size,
max_block_size,
min_frame_size: (min_frame_size != 0).then_some(min_frame_size),
max_frame_size: (max_frame_size != 0).then_some(max_frame_size),
spec: AudioSpec::new(sample_rate, channels),
bits_per_sample,
total_samples: (total_samples != 0).then_some(total_samples),
md5: (md5 != [0u8; 16]).then_some(md5),
})
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Blocking {
Fixed,
Variable,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ChannelAssignment {
Independent(u8),
LeftSide,
SideRight,
MidSide,
}
impl ChannelAssignment {
const fn count(self) -> u8 {
match self {
Self::Independent(channels) => channels,
Self::LeftSide | Self::SideRight | Self::MidSide => 2,
}
}
const fn side_channel(self) -> Option<usize> {
match self {
Self::Independent(_) => None,
Self::LeftSide | Self::MidSide => Some(1),
Self::SideRight => Some(0),
}
}
}
#[derive(Debug, Clone, Copy)]
struct FrameHeader {
blocking: Blocking,
block_size: u32,
sample_rate: Option<u32>,
channels: ChannelAssignment,
bits_per_sample: Option<u8>,
coded_number: u64,
header_bytes: usize,
}
fn read_coded_number(reader: &mut BitReader<'_>) -> Result<u64, DecodeError> {
let first = reader.read_bits(8)? as u8;
let (continuations, mut value) = match first.leading_ones() {
0 => (0, u64::from(first)),
1 => return Err(reader.malformed("a coded number not starting with a continuation octet")),
leading @ 2..=7 => {
let payload = 7 - leading;
(
leading - 1,
u64::from(first & ((1u8 << payload).wrapping_sub(1))),
)
}
_ => return Err(reader.malformed("a coded number of at most seven octets")),
};
for _ in 0..continuations {
let octet = reader.read_bits(8)? as u8;
if octet & 0xC0 != 0x80 {
return Err(reader.malformed("a coded number continuation octet"));
}
value = (value << 6) | u64::from(octet & 0x3F);
}
Ok(value)
}
fn parse_frame_header(bytes: &[u8], base: u64) -> Result<FrameHeader, DecodeError> {
if bytes.len() < MIN_FRAME_HEADER_BYTES {
return Err(DecodeError::Truncated {
expected: MIN_FRAME_HEADER_BYTES as u64,
available: bytes.len() as u64,
});
}
let mut reader = BitReader::new(bytes, base);
if reader.read_bits(15)? != 0b111_1111_1111_1100 {
return Err(reader.malformed("a frame sync code"));
}
let blocking = if reader.read_bits(1)? == 0 {
Blocking::Fixed
} else {
Blocking::Variable
};
let block_size_bits = reader.read_bits(4)? as u8;
let sample_rate_bits = reader.read_bits(4)? as u8;
let channel_bits = reader.read_bits(4)? as u8;
let bit_depth_bits = reader.read_bits(3)? as u8;
if reader.read_bits(1)? != 0 {
return Err(reader.malformed("a cleared reserved bit in the frame header"));
}
let channels = match channel_bits {
0..=7 => ChannelAssignment::Independent(channel_bits + 1),
8 => ChannelAssignment::LeftSide,
9 => ChannelAssignment::SideRight,
10 => ChannelAssignment::MidSide,
_ => return Err(reader.malformed("a defined channel assignment")),
};
let bits_per_sample = match bit_depth_bits {
0 => None,
1 => Some(8),
2 => Some(12),
4 => Some(16),
5 => Some(20),
6 => Some(24),
7 => Some(32),
_ => return Err(reader.malformed("a defined bit depth")),
};
let block_size = match block_size_bits {
0 => return Err(reader.malformed("a block size other than the reserved 0b0000")),
1 => Some(192),
2..=5 => Some(144u32 << block_size_bits),
6 | 7 => None,
_ => Some(1u32 << block_size_bits),
};
let coded_number = read_coded_number(&mut reader)?;
let block_size = match block_size {
Some(size) => size,
None => {
let width = if block_size_bits == 6 { 8 } else { 16 };
let stored = reader.read_bits(width)? as u32;
if stored == 65_535 {
return Err(reader.malformed("a block size representable in streaminfo"));
}
stored + 1
}
};
let sample_rate = match sample_rate_bits {
0 => None,
1 => Some(88_200),
2 => Some(176_400),
3 => Some(192_000),
4 => Some(8_000),
5 => Some(16_000),
6 => Some(22_050),
7 => Some(24_000),
8 => Some(32_000),
9 => Some(44_100),
10 => Some(48_000),
11 => Some(96_000),
12 => Some(reader.read_bits(8)? as u32 * 1_000),
13 => Some(reader.read_bits(16)? as u32),
14 => Some(reader.read_bits(16)? as u32 * 10),
_ => return Err(reader.malformed("a sample rate other than the forbidden 0b1111")),
};
let header_bytes = reader.byte_position();
let stored_crc = reader.read_bits(8)? as u8;
if crc8(&bytes[..header_bytes]) != stored_crc {
return Err(DecodeError::Malformed {
expected: "a frame header whose CRC-8 matches its contents",
offset: base + header_bytes as u64,
});
}
Ok(FrameHeader {
blocking,
block_size,
sample_rate,
channels,
bits_per_sample,
coded_number,
header_bytes: header_bytes + 1,
})
}
const UNRESOLVED_RATE: &str =
"a frame sample rate, or a streaminfo block to resolve the sample rate code 0b0000";
const UNRESOLVED_DEPTH: &str =
"a frame bit depth, or a streaminfo block to resolve the bit depth code 0b000";
fn derive_stream_info(header: &FrameHeader, base: u64) -> Result<FlacStreamInfo, DecodeError> {
let Some(sample_rate) = header.sample_rate else {
return Err(DecodeError::Malformed {
expected: UNRESOLVED_RATE,
offset: base,
});
};
let Some(bits_per_sample) = header.bits_per_sample else {
return Err(DecodeError::Malformed {
expected: UNRESOLVED_DEPTH,
offset: base,
});
};
Ok(FlacStreamInfo {
min_block_size: MIN_BLOCK_SIZE as u16,
max_block_size: MAX_BLOCK_SIZE as u16,
min_frame_size: None,
max_frame_size: None,
spec: AudioSpec::new(sample_rate, u16::from(header.channels.count())),
bits_per_sample,
total_samples: None,
md5: None,
})
}
fn fixed_prediction(prior: &[i64], order: usize) -> i64 {
let at = prior.len();
let previous = |back: usize| prior[at - back];
match order {
0 => 0,
1 => previous(1),
2 => previous(1).wrapping_mul(2).wrapping_sub(previous(2)),
3 => previous(1)
.wrapping_mul(3)
.wrapping_sub(previous(2).wrapping_mul(3))
.wrapping_add(previous(3)),
_ => previous(1)
.wrapping_mul(4)
.wrapping_sub(previous(2).wrapping_mul(6))
.wrapping_add(previous(3).wrapping_mul(4))
.wrapping_sub(previous(4)),
}
}
fn lpc_prediction(coefficients: &[i64], prior: &[i64], shift: u32) -> i64 {
let at = prior.len();
let mut prediction = 0i64;
for (step, coefficient) in coefficients.iter().enumerate() {
prediction = prediction.wrapping_add(coefficient.wrapping_mul(prior[at - 1 - step]));
}
prediction >> shift
}
fn decode_subframe(
reader: &mut BitReader<'_>,
bits: u32,
dst: &mut [i64],
) -> Result<(), DecodeError> {
if reader.read_bits(1)? != 0 {
return Err(reader.malformed("a cleared leading bit in the subframe header"));
}
let subframe_type = reader.read_bits(6)? as u8;
let wasted = if reader.read_bits(1)? == 0 {
0
} else {
reader.read_unary()?.saturating_add(1)
};
if wasted >= bits {
return Err(reader.malformed("fewer wasted bits than the subframe's bit depth"));
}
let coded_bits = bits - wasted;
match subframe_type {
0 => {
let value = reader.read_signed(coded_bits)?;
dst.fill(value);
}
1 => {
for sample in dst.iter_mut() {
*sample = reader.read_signed(coded_bits)?;
}
}
8..=12 => decode_fixed(reader, coded_bits, usize::from(subframe_type - 8), dst)?,
32..=63 => decode_lpc(reader, coded_bits, usize::from(subframe_type - 31), dst)?,
_ => return Err(reader.malformed("a defined subframe type")),
}
if wasted > 0 {
for sample in dst.iter_mut() {
*sample <<= wasted;
}
}
Ok(())
}
fn decode_fixed(
reader: &mut BitReader<'_>,
bits: u32,
order: usize,
dst: &mut [i64],
) -> Result<(), DecodeError> {
if order > dst.len() {
return Err(reader.malformed("a predictor order no larger than the block size"));
}
for sample in dst.iter_mut().take(order) {
*sample = reader.read_signed(bits)?;
}
decode_residual(reader, order, dst)?;
for index in order..dst.len() {
let prediction = fixed_prediction(&dst[..index], order);
dst[index] = dst[index].wrapping_add(prediction);
}
Ok(())
}
fn decode_lpc(
reader: &mut BitReader<'_>,
bits: u32,
order: usize,
dst: &mut [i64],
) -> Result<(), DecodeError> {
if order > dst.len() {
return Err(reader.malformed("a predictor order no larger than the block size"));
}
for sample in dst.iter_mut().take(order) {
*sample = reader.read_signed(bits)?;
}
let precision = reader.read_bits(4)? as u32 + 1;
if precision > 15 {
return Err(reader.malformed("a coefficient precision other than the forbidden 0b1111"));
}
let shift = reader.read_signed(5)?;
if shift < 0 {
return Err(reader.malformed("a non-negative predictor right shift"));
}
let shift = shift as u32;
let mut coefficients = [0i64; MAX_LPC_ORDER];
for coefficient in coefficients.iter_mut().take(order) {
*coefficient = reader.read_signed(precision)?;
}
decode_residual(reader, order, dst)?;
for index in order..dst.len() {
let prediction = lpc_prediction(&coefficients[..order], &dst[..index], shift);
dst[index] = dst[index].wrapping_add(prediction);
}
Ok(())
}
fn decode_residual(
reader: &mut BitReader<'_>,
order: usize,
dst: &mut [i64],
) -> Result<(), DecodeError> {
let parameter_bits = match reader.read_bits(2)? {
0 => 4u32,
1 => 5,
_ => return Err(reader.malformed("a defined residual coding method")),
};
let escape = (1u64 << parameter_bits) - 1;
let partition_order = reader.read_bits(4)? as u32;
let partitions = 1usize << partition_order;
let block_size = dst.len();
if !block_size.is_multiple_of(partitions) {
return Err(reader.malformed("a block size divisible by the partition count"));
}
let per_partition = block_size >> partition_order;
if per_partition <= order {
return Err(reader.malformed("a partition longer than the predictor order"));
}
let mut at = order;
for partition in 0..partitions {
let count = if partition == 0 {
per_partition - order
} else {
per_partition
};
let parameter = reader.read_bits(parameter_bits)?;
if parameter == escape {
let width = reader.read_bits(5)? as u32;
if width == 0 {
dst[at..at + count].fill(0);
} else {
for sample in &mut dst[at..at + count] {
*sample = reader.read_signed(width)?;
}
}
} else {
let parameter = parameter as u32;
for sample in &mut dst[at..at + count] {
let high = u64::from(reader.read_unary()?);
let folded = if parameter == 0 {
high
} else {
(high << parameter) | reader.read_bits(parameter)?
};
if folded > u64::from(u32::MAX) - 1 {
return Err(reader.malformed("a residual within the format's 32-bit range"));
}
*sample = ((folded >> 1) as i64) ^ -((folded & 1) as i64);
}
}
at += count;
}
Ok(())
}
fn undo_decorrelation(assignment: ChannelAssignment, left: &mut [i64], right: &mut [i64]) {
match assignment {
ChannelAssignment::Independent(_) => {}
ChannelAssignment::LeftSide => {
for (channel, side) in left.iter().zip(right.iter_mut()) {
*side = channel.wrapping_sub(*side);
}
}
ChannelAssignment::SideRight => {
for (side, channel) in left.iter_mut().zip(right.iter()) {
*side = side.wrapping_add(*channel);
}
}
ChannelAssignment::MidSide => {
for (mid, side) in left.iter_mut().zip(right.iter_mut()) {
let restored = (mid.wrapping_shl(1)) | (*side & 1);
let difference = *side;
*mid = restored.wrapping_add(difference) >> 1;
*side = restored.wrapping_sub(difference) >> 1;
}
}
}
}
#[derive(Debug)]
struct FrameDecoder {
info: FlacStreamInfo,
channels: Vec<i64>,
hasher: Md5,
stage: [u8; MD5_STAGE_BYTES],
staged: usize,
samples_done: u64,
last_frame_seen: bool,
blocking: Option<Blocking>,
streaminfo: bool,
divisor: f32,
}
impl FrameDecoder {
fn new(info: FlacStreamInfo) -> Self {
Self::build(info, true)
}
fn from_first_frame(info: FlacStreamInfo) -> Self {
Self::build(info, false)
}
fn build(info: FlacStreamInfo, streaminfo: bool) -> Self {
let mut decoder = Self {
info,
channels: Vec::new(),
hasher: Md5::new(),
stage: [0; MD5_STAGE_BYTES],
staged: 0,
samples_done: 0,
last_frame_seen: false,
blocking: None,
streaminfo,
divisor: 0.0,
};
decoder.reset_to(info, streaminfo);
decoder
}
fn reset_to(&mut self, info: FlacStreamInfo, streaminfo: bool) {
self.info = info;
self.channels.clear();
self.hasher = Md5::new();
self.staged = 0;
self.samples_done = 0;
self.last_frame_seen = false;
self.blocking = None;
self.streaminfo = streaminfo;
self.divisor = (1u64 << (info.bits_per_sample - 1)) as f32;
}
fn decode_frame(
&mut self,
bytes: &[u8],
base: u64,
output: &mut Vec<f32>,
) -> Result<usize, DecodeError> {
let header = parse_frame_header(bytes, base)?;
self.check_against_stream(&header, base)?;
self.blocking = Some(header.blocking);
let block_size = header.block_size as usize;
let channel_count = usize::from(header.channels.count());
let bits = u32::from(self.info.bits_per_sample);
self.channels.clear();
self.channels.resize(block_size * channel_count, 0);
let mut reader = BitReader::new(bytes, base);
reader.bit = header.header_bytes * 8;
for channel in 0..channel_count {
let side = header.channels.side_channel() == Some(channel);
let start = channel * block_size;
decode_subframe(
&mut reader,
bits + u32::from(side),
&mut self.channels[start..start + block_size],
)?;
}
reader.align_to_byte();
let frame_bytes = reader.byte_position();
let stored_crc = reader.read_bits(16)? as u16;
if crc16(&bytes[..frame_bytes]) != stored_crc {
return Err(DecodeError::Malformed {
expected: "a frame whose CRC-16 matches its contents",
offset: base + frame_bytes as u64,
});
}
if channel_count == 2 {
let (left, right) = self.channels.split_at_mut(block_size);
undo_decorrelation(header.channels, left, right);
}
self.emit(block_size, channel_count, output);
self.samples_done += header.block_size as u64;
self.last_frame_seen = header.block_size < MIN_BLOCK_SIZE;
Ok(frame_bytes + 2)
}
fn check_against_stream(&self, header: &FrameHeader, base: u64) -> Result<(), DecodeError> {
let malformed = |expected| DecodeError::Malformed {
expected,
offset: base,
};
if let Some(blocking) = self.blocking {
if blocking != header.blocking {
return Err(malformed("an unchanging blocking strategy"));
}
}
if self.last_frame_seen {
return Err(malformed(
"no frame after one shorter than the minimum block size",
));
}
if u32::from(header.channels.count()) != u32::from(self.info.spec.channels) {
return Err(malformed("a channel count matching streaminfo"));
}
match header.bits_per_sample {
Some(bits) if bits != self.info.bits_per_sample => {
return Err(malformed("a bit depth matching streaminfo"))
}
None if !self.streaminfo => return Err(malformed(UNRESOLVED_DEPTH)),
_ => {}
}
match header.sample_rate {
Some(rate) if rate != self.info.spec.sample_rate => {
return Err(malformed("a sample rate matching streaminfo"))
}
None if !self.streaminfo => return Err(malformed(UNRESOLVED_RATE)),
_ => {}
}
if header.block_size > u32::from(self.info.max_block_size) {
return Err(malformed(
"a block size no larger than the streaminfo maximum",
));
}
Ok(())
}
fn emit(&mut self, block_size: usize, channel_count: usize, output: &mut Vec<f32>) {
let width = self.info.md5_bytes_per_sample();
output.reserve(block_size * channel_count);
for index in 0..block_size {
for channel in 0..channel_count {
let sample = self.channels[channel * block_size + index];
output.push(sample as f32 / self.divisor);
if self.staged + width > MD5_STAGE_BYTES {
self.hasher.update(&self.stage[..self.staged]);
self.staged = 0;
}
self.stage[self.staged..self.staged + width]
.copy_from_slice(&sample.to_le_bytes()[..width]);
self.staged += width;
}
}
}
fn finish(mut self, md5_offset: u64) -> Result<(), DecodeError> {
if let Some(total) = self.info.total_samples {
if self.samples_done != total {
return Err(if self.samples_done < total {
DecodeError::Truncated {
expected: total,
available: self.samples_done,
}
} else {
DecodeError::Malformed {
expected: "a stream holding exactly the declared total number of samples",
offset: md5_offset,
}
});
}
}
let Some(declared) = self.info.md5 else {
return Ok(());
};
self.hasher.update(&self.stage[..self.staged]);
self.staged = 0;
if self.hasher.finish() != declared {
return Err(DecodeError::Malformed {
expected: "decoded audio matching the streaminfo MD5 checksum",
offset: md5_offset,
});
}
Ok(())
}
}
struct Metadata {
info: FlacStreamInfo,
md5_offset: u64,
audio_offset: usize,
}
fn read_metadata(bytes: &[u8]) -> Result<Metadata, DecodeError> {
let magic = bytes
.get(..4)
.map(|head| FourCc([head[0], head[1], head[2], head[3]]));
match magic {
Some(tag) if tag == MAGIC => {}
Some(tag) => return Err(DecodeError::UnsupportedContainer { tag }),
None => {
return Err(DecodeError::Truncated {
expected: 4,
available: bytes.len() as u64,
})
}
}
let mut at = 4usize;
let mut info: Option<(FlacStreamInfo, u64)> = None;
loop {
let Some(header) = bytes.get(at..at + METADATA_HEADER_BYTES) else {
return Err(DecodeError::Truncated {
expected: (at + METADATA_HEADER_BYTES) as u64,
available: bytes.len() as u64,
});
};
let last = header[0] & 0x80 != 0;
let kind = header[0] & 0x7F;
let length =
(u64::from(header[1]) << 16) | (u64::from(header[2]) << 8) | u64::from(header[3]);
let body_at = at as u64 + METADATA_HEADER_BYTES as u64;
if kind == BLOCK_FORBIDDEN {
return Err(DecodeError::Malformed {
expected: "a metadata block type other than the forbidden 127",
offset: at as u64,
});
}
if body_at + length > bytes.len() as u64 {
return Err(DecodeError::Truncated {
expected: body_at + length,
available: bytes.len() as u64,
});
}
let body_at = body_at as usize;
let body_end = body_at + length as usize;
if kind == BLOCK_STREAMINFO {
if info.is_some() {
return Err(DecodeError::Malformed {
expected: "exactly one streaminfo metadata block",
offset: at as u64,
});
}
info = Some((
parse_streaminfo(&bytes[body_at..body_end], body_at as u64)?,
body_at as u64 + 18,
));
} else if info.is_none() {
return Err(DecodeError::Malformed {
expected: "a streaminfo block first among the metadata blocks",
offset: at as u64,
});
}
at = body_end;
if last {
break;
}
}
let Some((info, md5_offset)) = info else {
return Err(DecodeError::Malformed {
expected: "a streaminfo metadata block",
offset: 4,
});
};
Ok(Metadata {
info,
md5_offset,
audio_offset: at,
})
}
fn looks_like_a_frame(bytes: &[u8]) -> bool {
matches!(bytes, [0xFF, second, ..] if second & 0xFE == 0xF8)
}
fn decode_frames(
decoder: &mut FrameDecoder,
audio: &[u8],
base: u64,
output: &mut Vec<f32>,
) -> Result<usize, DecodeError> {
let total = decoder.info.total_samples;
let mut at = 0usize;
while at < audio.len() {
if total.is_some_and(|total| decoder.samples_done >= total) {
break;
}
at += decoder.decode_frame(&audio[at..], base + at as u64, output)?;
}
if total.is_some() && looks_like_a_frame(&audio[at..]) {
return Err(DecodeError::Malformed {
expected: "a stream holding exactly the declared total number of samples",
offset: base + at as u64,
});
}
Ok(at)
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Md5Check {
Verified,
NoStreamInfo,
ChecksumUnset,
AudioIncomplete,
}
impl Md5Check {
pub const fn is_verified(self) -> bool {
matches!(self, Self::Verified)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FlacReader<'a> {
info: FlacStreamInfo,
md5_offset: u64,
audio: &'a [u8],
audio_offset: u64,
}
impl<'a> FlacReader<'a> {
pub fn new(bytes: &'a [u8]) -> Result<Self, DecodeError> {
let metadata = read_metadata(bytes)?;
Ok(Self {
info: metadata.info,
md5_offset: metadata.md5_offset,
audio: &bytes[metadata.audio_offset..],
audio_offset: metadata.audio_offset as u64,
})
}
pub const fn stream_info(&self) -> &FlacStreamInfo {
&self.info
}
pub const fn spec(&self) -> AudioSpec {
self.info.spec
}
pub const fn frames(&self) -> Option<u64> {
self.info.total_samples
}
pub const fn frame_data(&self) -> &'a [u8] {
self.audio
}
pub fn decode(&self, output: &mut Vec<f32>) -> Result<usize, DecodeError> {
let before = output.len();
let mut decoder = FrameDecoder::new(self.info);
decode_frames(&mut decoder, self.audio, self.audio_offset, output)?;
decoder.finish(self.md5_offset)?;
Ok(output.len() - before)
}
pub fn decode_to_end(&self) -> Result<AudioBuffer, DecodeError> {
let mut samples = Vec::new();
self.decode(&mut samples)?;
Ok(AudioBuffer::from_samples(self.info.spec, samples))
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub struct FlacFrameReport {
pub samples: usize,
pub md5: Md5Check,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FlacFrameReader<'a> {
audio: &'a [u8],
info: FlacStreamInfo,
streaminfo: bool,
}
impl<'a> FlacFrameReader<'a> {
pub fn new(bytes: &'a [u8]) -> Result<Self, DecodeError> {
let header = parse_frame_header(bytes, 0)?;
Ok(Self {
audio: bytes,
info: derive_stream_info(&header, 0)?,
streaminfo: false,
})
}
pub const fn with_stream_info(bytes: &'a [u8], info: FlacStreamInfo) -> Self {
Self {
audio: bytes,
info,
streaminfo: true,
}
}
pub const fn stream_info(&self) -> &FlacStreamInfo {
&self.info
}
pub const fn spec(&self) -> AudioSpec {
self.info.spec
}
pub const fn frames(&self) -> Option<u64> {
self.info.total_samples
}
pub fn decode(&self, output: &mut Vec<f32>) -> Result<FlacFrameReport, DecodeError> {
let before = output.len();
let mut decoder = if self.streaminfo {
FrameDecoder::new(self.info)
} else {
FrameDecoder::from_first_frame(self.info)
};
decode_frames(&mut decoder, self.audio, 0, output)?;
decoder.finish(self.audio.len() as u64)?;
Ok(FlacFrameReport {
samples: output.len() - before,
md5: self.md5_outcome(),
})
}
pub fn decode_to_end(&self) -> Result<(AudioBuffer, FlacFrameReport), DecodeError> {
let mut samples = Vec::new();
let report = self.decode(&mut samples)?;
Ok((AudioBuffer::from_samples(self.info.spec, samples), report))
}
fn md5_outcome(&self) -> Md5Check {
if !self.streaminfo {
Md5Check::NoStreamInfo
} else if self.info.md5.is_none() {
Md5Check::ChecksumUnset
} else {
Md5Check::Verified
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum FlacSkipReason {
NoSyncPoint,
FrameRejected,
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct FlacSkip {
pub bytes: Range<u64>,
pub frames: Option<Range<u64>>,
pub reason: FlacSkipReason,
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct FlacRecoveryReport {
pub samples: usize,
pub md5: Md5Check,
pub skipped: Vec<FlacSkip>,
pub first_frame: Option<u64>,
pub stream_info: FlacStreamInfo,
}
impl FlacRecoveryReport {
pub fn frames_lost(&self) -> Option<u64> {
let mut total = 0u64;
for skip in &self.skipped {
let range = skip.frames.as_ref()?;
total += range.end.saturating_sub(range.start);
}
Some(total)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FlacRecovery<'a> {
bytes: &'a [u8],
info: Option<FlacStreamInfo>,
}
struct PendingSkip {
bytes: Range<u64>,
before: Option<(u64, u32)>,
after: Option<u64>,
reason: FlacSkipReason,
}
impl<'a> FlacRecovery<'a> {
pub const fn new(bytes: &'a [u8]) -> Self {
Self { bytes, info: None }
}
pub const fn with_stream_info(bytes: &'a [u8], info: FlacStreamInfo) -> Self {
Self {
bytes,
info: Some(info),
}
}
pub fn decode(&self, output: &mut Vec<f32>) -> Result<FlacRecoveryReport, DecodeError> {
let before = output.len();
let end = self.bytes.len() as u64;
let mut pending: Vec<PendingSkip> = Vec::new();
let mut trial: Option<FrameDecoder> = None;
let mut scratch: Vec<f32> = Vec::new();
let Some((first, header)) = self.find_sync(0, &mut trial, &mut scratch) else {
return Err(DecodeError::Malformed {
expected: "at least one frame whose CRC-16 matches and which another frame follows",
offset: 0,
});
};
let info = match self.info {
Some(info) => info,
None => derive_stream_info(&header, first as u64)?,
};
let mut decoder = if self.info.is_some() {
FrameDecoder::new(info)
} else {
FrameDecoder::from_first_frame(info)
};
pending.push(PendingSkip {
bytes: 0..first as u64,
before: None,
after: Some(header.coded_number),
reason: FlacSkipReason::NoSyncPoint,
});
let mut blocking = None;
let mut widest_block = 0u32;
let mut last: Option<(u64, u32)> = None;
let mut first_coded: Option<u64> = None;
let mut adjacent: Option<(u64, u32)> = None;
let mut frame_numbered: Option<bool> = None;
let mut at = first;
let mut skip_from = first;
let mut reason = FlacSkipReason::NoSyncPoint;
let mut locked = true;
while at < self.bytes.len() {
if locked {
let step = parse_frame_header(&self.bytes[at..], at as u64).and_then(|header| {
decoder
.decode_frame(&self.bytes[at..], at as u64, output)
.map(|consumed| (header, consumed))
});
match step {
Ok((header, consumed)) => {
blocking = Some(header.blocking);
widest_block = widest_block.max(header.block_size);
first_coded.get_or_insert(header.coded_number);
if frame_numbered.is_none() {
if let Some((before, block)) = adjacent {
if header.coded_number == before + 1 {
frame_numbered = Some(true);
} else if header.coded_number == before + u64::from(block) {
frame_numbered = Some(false);
}
}
}
adjacent = Some((header.coded_number, header.block_size));
last = adjacent;
at += consumed;
skip_from = at;
}
Err(_) => {
locked = false;
adjacent = None;
reason = FlacSkipReason::FrameRejected;
at += 1;
}
}
continue;
}
let Some((start, header)) = self.find_sync(at, &mut trial, &mut scratch) else {
break;
};
pending.push(PendingSkip {
bytes: skip_from as u64..start as u64,
before: last,
after: Some(header.coded_number),
reason,
});
reason = FlacSkipReason::NoSyncPoint;
at = start;
skip_from = start;
locked = true;
adjacent = None;
}
if skip_from < self.bytes.len() {
pending.push(PendingSkip {
bytes: skip_from as u64..end,
before: last,
after: None,
reason,
});
}
let numbering = Numbering {
frame_numbered: frame_numbered.unwrap_or(blocking == Some(Blocking::Fixed)),
known: blocking.is_some(),
widest: widest_block,
total: info.total_samples,
from_zero: self.info.is_some(),
};
let mut report = FlacRecoveryReport {
samples: output.len() - before,
md5: Md5Check::AudioIncomplete,
skipped: resolve_skips(&pending, &numbering),
first_frame: first_coded.and_then(|coded| numbering.position(coded)),
stream_info: info,
};
report.md5 = if report.frames_lost() != Some(0) {
Md5Check::AudioIncomplete
} else if self.info.is_none() {
Md5Check::NoStreamInfo
} else if info.md5.is_none() {
decoder.finish(end)?;
Md5Check::ChecksumUnset
} else {
decoder.finish(end)?;
Md5Check::Verified
};
Ok(report)
}
pub fn decode_to_end(&self) -> Result<(AudioBuffer, FlacRecoveryReport), DecodeError> {
let mut samples = Vec::new();
let report = self.decode(&mut samples)?;
let spec = report.stream_info.spec;
Ok((AudioBuffer::from_samples(spec, samples), report))
}
fn find_sync(
&self,
from: usize,
trial: &mut Option<FrameDecoder>,
scratch: &mut Vec<f32>,
) -> Option<(usize, FrameHeader)> {
let last_start = self.bytes.len().checked_sub(MIN_FRAME_HEADER_BYTES)?;
for start in from..=last_start {
if self.bytes[start] != 0xFF || self.bytes[start + 1] & 0xFE != 0xF8 {
continue;
}
let Ok(header) = parse_frame_header(&self.bytes[start..], start as u64) else {
continue;
};
let info = match self.info {
Some(info) => info,
None => match derive_stream_info(&header, start as u64) {
Ok(info) => info,
Err(_) => continue,
},
};
let streaminfo = self.info.is_some();
let trial = trial.get_or_insert_with(|| FrameDecoder::build(info, streaminfo));
trial.reset_to(info, streaminfo);
scratch.clear();
let Ok(consumed) = trial.decode_frame(&self.bytes[start..], start as u64, scratch)
else {
continue;
};
let next = start + consumed;
if next == self.bytes.len()
|| parse_frame_header(&self.bytes[next..], next as u64).is_ok()
{
return Some((start, header));
}
}
None
}
}
struct Numbering {
frame_numbered: bool,
known: bool,
widest: u32,
total: Option<u64>,
from_zero: bool,
}
impl Numbering {
fn position(&self, coded: u64) -> Option<u64> {
match (self.known, self.frame_numbered) {
(false, _) => None,
(true, false) => Some(coded),
(true, true) if self.widest > 0 => Some(coded * u64::from(self.widest)),
(true, true) => None,
}
}
}
fn resolve_skips(pending: &[PendingSkip], numbering: &Numbering) -> Vec<FlacSkip> {
pending
.iter()
.map(|skip| {
let start = match skip.before {
Some((coded, block)) => numbering.position(coded).map(|at| at + u64::from(block)),
None if numbering.from_zero => Some(0),
None => match skip.after.and_then(|coded| numbering.position(coded)) {
Some(0) => Some(0),
_ => None,
},
};
let end = match skip.after {
Some(coded) => numbering.position(coded),
None => numbering.total,
};
FlacSkip {
bytes: skip.bytes.clone(),
frames: match (start, end) {
(Some(start), Some(end)) => Some(start..end.max(start)),
_ => None,
},
reason: skip.reason,
}
})
.filter(|skip| {
!(skip.bytes.is_empty() && skip.frames.as_ref().is_some_and(Range::is_empty))
})
.collect()
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum State {
Signature,
BlockHeader,
StreaminfoBody { last: bool, offset: u64 },
SkipBlock { last: bool, left: u64 },
Audio,
Done,
}
#[derive(Debug)]
pub struct FlacStreamDecoder {
state: State,
pending: Vec<u8>,
offset: u64,
frame_offset: u64,
frame_needs: usize,
info: Option<FlacStreamInfo>,
md5_offset: u64,
decoder: Option<FrameDecoder>,
streaminfo: bool,
md5: Option<Md5Check>,
ready: Vec<f32>,
ready_read: usize,
finished: bool,
origin: Origin,
}
#[derive(Debug, Clone, Copy)]
enum Origin {
Stream,
BareFrames,
BareFramesWith(FlacStreamInfo),
}
impl Default for FlacStreamDecoder {
fn default() -> Self {
Self::new()
}
}
impl FlacStreamDecoder {
pub fn new() -> Self {
Self::from_origin(Origin::Stream)
}
pub fn frames() -> Self {
Self::from_origin(Origin::BareFrames)
}
pub fn frames_with_stream_info(info: FlacStreamInfo) -> Self {
Self::from_origin(Origin::BareFramesWith(info))
}
fn from_origin(origin: Origin) -> Self {
let mut reader = Self {
state: State::Signature,
pending: Vec::new(),
offset: 0,
frame_offset: 0,
frame_needs: MIN_FRAME_HEADER_BYTES,
info: None,
md5_offset: 0,
decoder: None,
streaminfo: true,
md5: None,
ready: Vec::new(),
ready_read: 0,
finished: false,
origin,
};
match origin {
Origin::Stream => {}
Origin::BareFrames => {
reader.state = State::Audio;
reader.streaminfo = false;
}
Origin::BareFramesWith(info) => {
reader.state = State::Audio;
reader.info = Some(info);
reader.decoder = Some(FrameDecoder::new(info));
}
}
reader
}
pub const fn stream_info(&self) -> Option<FlacStreamInfo> {
self.info
}
pub const fn md5_check(&self) -> Option<Md5Check> {
self.md5
}
pub fn ready_samples(&self) -> usize {
self.ready.len() - self.ready_read
}
fn accumulate(&mut self, bytes: &[u8], need: usize, taken: &mut usize) -> bool {
let want = need.saturating_sub(self.pending.len()).min(bytes.len());
self.pending.extend_from_slice(&bytes[..want]);
*taken += want;
self.offset += want as u64;
self.pending.len() >= need
}
fn start_block(&mut self) -> Result<(), DecodeError> {
let at = self.offset - METADATA_HEADER_BYTES as u64;
let mut header = [0u8; METADATA_HEADER_BYTES];
header.copy_from_slice(&self.pending);
self.pending.clear();
let last = header[0] & 0x80 != 0;
let kind = header[0] & 0x7F;
let length =
(u64::from(header[1]) << 16) | (u64::from(header[2]) << 8) | u64::from(header[3]);
if kind == BLOCK_FORBIDDEN {
return Err(DecodeError::Malformed {
expected: "a metadata block type other than the forbidden 127",
offset: at,
});
}
if kind == BLOCK_STREAMINFO {
if self.info.is_some() {
return Err(DecodeError::Malformed {
expected: "exactly one streaminfo metadata block",
offset: at,
});
}
if length != STREAMINFO_BYTES as u64 {
return Err(DecodeError::Malformed {
expected: "a streaminfo block of exactly 34 bytes",
offset: at,
});
}
self.state = State::StreaminfoBody {
last,
offset: self.offset,
};
return Ok(());
}
if self.info.is_none() {
return Err(DecodeError::Malformed {
expected: "a streaminfo block first among the metadata blocks",
offset: at,
});
}
self.state = if length == 0 {
self.enter_audio(last)
} else {
State::SkipBlock { last, left: length }
};
Ok(())
}
fn enter_audio(&mut self, last: bool) -> State {
if last {
self.frame_offset = self.offset;
self.frame_needs = MIN_FRAME_HEADER_BYTES;
State::Audio
} else {
State::BlockHeader
}
}
fn finish_streaminfo(&mut self, last: bool, offset: u64) -> Result<(), DecodeError> {
let info = parse_streaminfo(&self.pending, offset)?;
self.pending.clear();
self.info = Some(info);
self.md5_offset = offset + 18;
self.decoder = Some(FrameDecoder::new(info));
self.state = self.enter_audio(last);
Ok(())
}
fn drain_frames(&mut self) -> Result<(), DecodeError> {
while self.pending.len() >= self.frame_needs {
if self.decoder.is_none() {
match parse_frame_header(&self.pending, self.frame_offset) {
Ok(header) => {
let info = derive_stream_info(&header, self.frame_offset)?;
self.info = Some(info);
self.decoder = Some(FrameDecoder::from_first_frame(info));
}
Err(DecodeError::Truncated { expected, .. }) => {
self.frame_needs = (expected as usize).max(self.pending.len() + 1);
return Ok(());
}
Err(other) => return Err(other),
}
}
let Some(decoder) = self.decoder.as_mut() else {
return Ok(());
};
if let Some(info) = self.info {
if info
.total_samples
.is_some_and(|total| decoder.samples_done >= total)
{
self.state = State::Done;
self.pending.clear();
return Ok(());
}
}
match decoder.decode_frame(&self.pending, self.frame_offset, &mut self.ready) {
Ok(consumed) => {
self.pending.drain(..consumed);
self.frame_offset += consumed as u64;
self.frame_needs = MIN_FRAME_HEADER_BYTES;
}
Err(DecodeError::Truncated { expected, .. }) => {
self.frame_needs = (expected as usize).max(self.pending.len() + 1);
if self.frame_needs > MAX_FRAME_BYTES {
return Err(DecodeError::Malformed {
expected: "a frame no larger than the format's own maximum",
offset: self.frame_offset,
});
}
return Ok(());
}
Err(other) => return Err(other),
}
}
Ok(())
}
fn push_inner(&mut self, bytes: &[u8], taken: &mut usize) -> Result<(), DecodeError> {
while *taken < bytes.len() {
let rest = &bytes[*taken..];
match self.state {
State::Signature => {
if !self.accumulate(rest, 4, taken) {
break;
}
let tag = FourCc([
self.pending[0],
self.pending[1],
self.pending[2],
self.pending[3],
]);
self.pending.clear();
if tag != MAGIC {
return Err(DecodeError::UnsupportedContainer { tag });
}
self.state = State::BlockHeader;
}
State::BlockHeader => {
if !self.accumulate(rest, METADATA_HEADER_BYTES, taken) {
break;
}
self.start_block()?;
}
State::StreaminfoBody { last, offset } => {
if !self.accumulate(rest, STREAMINFO_BYTES, taken) {
break;
}
self.finish_streaminfo(last, offset)?;
}
State::SkipBlock { last, left } => {
let step = left.min(rest.len() as u64);
*taken += step as usize;
self.offset += step;
let left = left - step;
self.state = if left == 0 {
self.enter_audio(last)
} else {
State::SkipBlock { last, left }
};
}
State::Audio => {
if self.ready.len() - self.ready_read >= READY_LIMIT {
break;
}
let room = MAX_FRAME_BYTES - self.pending.len();
if room == 0 {
return Err(DecodeError::Malformed {
expected: "a frame no larger than the format's own maximum",
offset: self.frame_offset,
});
}
let step = room.min(rest.len());
self.pending.extend_from_slice(&rest[..step]);
*taken += step;
self.offset += step as u64;
self.drain_frames()?;
}
State::Done => {
self.offset += (bytes.len() - *taken) as u64;
*taken = bytes.len();
}
}
}
Ok(())
}
}
impl StreamSource for FlacStreamDecoder {
fn push(&mut self, bytes: &[u8]) -> Result<usize, DecodeError> {
if self.finished {
return Ok(0);
}
let mut taken = 0;
let result = self.push_inner(bytes, &mut taken);
if result.is_err() {
self.finished = true;
}
result.map(|()| taken)
}
fn pull(&mut self, output: &mut Vec<f32>, max_frames: usize) -> Result<usize, DecodeError> {
let Some(info) = self.info else {
return Ok(0);
};
let channels = usize::from(info.spec.channels);
let available = self.ready.len() - self.ready_read;
let frames = (available / channels).min(max_frames);
let count = frames * channels;
output.extend_from_slice(&self.ready[self.ready_read..self.ready_read + count]);
self.ready_read += count;
if self.ready_read == self.ready.len() {
self.ready.clear();
self.ready_read = 0;
} else if self.ready_read >= self.ready.len() / 2 {
self.ready.drain(..self.ready_read);
self.ready_read = 0;
}
Ok(frames)
}
fn spec(&self) -> Option<AudioSpec> {
self.info.map(|info| info.spec)
}
fn buffered_bytes(&self) -> usize {
self.pending.len()
}
fn finish(&mut self, output: &mut Vec<f32>) -> Result<usize, DecodeError> {
if self.finished {
return Ok(0);
}
self.finished = true;
match self.state {
State::Done => {}
State::Signature => {
return Err(DecodeError::Truncated {
expected: 4,
available: self.pending.len() as u64,
})
}
State::BlockHeader => {
return Err(DecodeError::Truncated {
expected: METADATA_HEADER_BYTES as u64,
available: self.pending.len() as u64,
})
}
State::StreaminfoBody { .. } => {
return Err(DecodeError::Truncated {
expected: STREAMINFO_BYTES as u64,
available: self.pending.len() as u64,
})
}
State::SkipBlock { left, .. } => {
return Err(DecodeError::Truncated {
expected: left,
available: 0,
})
}
State::Audio => {
if !self.pending.is_empty() {
return Err(DecodeError::Truncated {
expected: self.frame_needs as u64,
available: self.pending.len() as u64,
});
}
}
}
if let Some(decoder) = self.decoder.take() {
let at = if self.md5_offset == 0 {
self.offset
} else {
self.md5_offset
};
decoder.finish(at)?;
}
let Some(info) = self.info else {
return Ok(0);
};
self.md5 = Some(if !self.streaminfo {
Md5Check::NoStreamInfo
} else if info.md5.is_none() {
Md5Check::ChecksumUnset
} else {
Md5Check::Verified
});
let channels = usize::from(info.spec.channels);
let frames = (self.ready.len() - self.ready_read) / channels;
output.extend_from_slice(&self.ready[self.ready_read..self.ready_read + frames * channels]);
self.ready.clear();
self.ready_read = 0;
Ok(frames)
}
fn reset(&mut self) {
*self = Self::from_origin(self.origin);
}
}
fn det_cos_pi(x: f64) -> f64 {
let (x, sign) = if x > 0.5 { (1.0 - x, -1.0) } else { (x, 1.0) };
let theta = x * std::f64::consts::PI;
let z = theta * theta;
let mut sum = 1.0f64;
let mut term = 1.0f64;
for k in 1i32..=10 {
term *= -z / f64::from((2 * k - 1) * (2 * k));
sum += term;
}
sign * sum
}
fn det_log2(x: f64) -> f64 {
debug_assert!(x > 0.0 && x.is_finite());
let bits = x.to_bits();
let raw_exponent = (bits >> 52) & 0x7FF;
if raw_exponent == 0 {
return det_log2(x * (1u64 << 60) as f64) - 60.0;
}
let exponent = raw_exponent as i64 - 1023;
let mantissa = f64::from_bits((bits & ((1u64 << 52) - 1)) | (1023u64 << 52));
let z = (mantissa - 1.0) / (mantissa + 1.0);
let z_squared = z * z;
let mut term = z;
let mut sum = 0.0f64;
for k in 0i32..12 {
sum += term / f64::from(2 * k + 1);
term *= z_squared;
}
exponent as f64 + 2.0 * sum * std::f64::consts::LOG2_E
}
struct BitWriter {
out: Vec<u8>,
accumulator: u64,
filled: u32,
}
impl BitWriter {
fn new() -> Self {
Self {
out: Vec::new(),
accumulator: 0,
filled: 0,
}
}
fn write(&mut self, value: u64, count: u32) {
debug_assert!((1..=WINDOW_BITS).contains(&count));
debug_assert!(count == 64 || value >> count == 0);
self.accumulator = (self.accumulator << count) | value;
self.filled += count;
while self.filled >= 8 {
self.filled -= 8;
self.out.push((self.accumulator >> self.filled) as u8);
}
}
fn write_signed(&mut self, value: i64, count: u32) {
let mask = if count >= 64 {
u64::MAX
} else {
(1u64 << count) - 1
};
self.write(value as u64 & mask, count);
}
fn write_unary(&mut self, quotient: u64) {
let mut left = quotient;
while left >= 32 {
self.write(0, 32);
left -= 32;
}
self.write(1, left as u32 + 1);
}
fn align(&mut self) {
if self.filled > 0 {
self.write(0, 8 - self.filled);
}
}
fn bytes(&self) -> &[u8] {
debug_assert_eq!(self.filled, 0);
&self.out
}
fn into_bytes(mut self) -> Vec<u8> {
self.align();
self.out
}
}
fn write_coded_number(writer: &mut BitWriter, value: u64) {
debug_assert!(value < 1u64 << 36);
if value < 0x80 {
writer.write(value, 8);
return;
}
let mut octets = 2u32;
while octets < 7 && value >= 1u64 << (6 * (octets - 1) + (7 - octets)) {
octets += 1;
}
let lead = (0xFFu64 << (8 - octets)) & 0xFF;
writer.write(lead | (value >> (6 * (octets - 1))), 8);
for step in (0..octets - 1).rev() {
writer.write(0x80 | ((value >> (6 * step)) & 0x3F), 8);
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Stereo {
Independent,
Estimated,
Exhaustive,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum WindowShape {
Tukey50,
Hann,
Tukey25,
}
impl WindowShape {
fn build(self, len: usize) -> Vec<f64> {
let alpha = match self {
Self::Tukey50 => 0.5,
Self::Hann => 1.0,
Self::Tukey25 => 0.25,
};
if len <= 1 {
return vec![1.0; len];
}
let taper = alpha * (len - 1) as f64 / 2.0;
(0..len)
.map(|index| {
let edge = (index.min(len - 1 - index)) as f64;
if taper <= 0.0 || edge >= taper {
1.0
} else {
0.5 * (1.0 + det_cos_pi(1.0 - edge / taper))
}
})
.collect()
}
}
struct Level {
block_size: u32,
stereo: Stereo,
max_lpc_order: usize,
max_partition_order: u32,
windows: &'static [WindowShape],
lpc_candidates: usize,
}
const LEVELS: [Level; 9] = [
Level {
block_size: 1152,
stereo: Stereo::Independent,
max_lpc_order: 0,
max_partition_order: 3,
windows: &[],
lpc_candidates: 0,
},
Level {
block_size: 1152,
stereo: Stereo::Estimated,
max_lpc_order: 0,
max_partition_order: 3,
windows: &[],
lpc_candidates: 0,
},
Level {
block_size: 1152,
stereo: Stereo::Exhaustive,
max_lpc_order: 0,
max_partition_order: 3,
windows: &[],
lpc_candidates: 0,
},
Level {
block_size: 4096,
stereo: Stereo::Independent,
max_lpc_order: 6,
max_partition_order: 4,
windows: &[WindowShape::Tukey50],
lpc_candidates: 1,
},
Level {
block_size: 4096,
stereo: Stereo::Estimated,
max_lpc_order: 8,
max_partition_order: 4,
windows: &[WindowShape::Tukey50],
lpc_candidates: 1,
},
Level {
block_size: 4096,
stereo: Stereo::Exhaustive,
max_lpc_order: 8,
max_partition_order: 5,
windows: &[WindowShape::Tukey50],
lpc_candidates: 1,
},
Level {
block_size: 4096,
stereo: Stereo::Exhaustive,
max_lpc_order: 8,
max_partition_order: 6,
windows: &[WindowShape::Tukey50],
lpc_candidates: 2,
},
Level {
block_size: 4096,
stereo: Stereo::Exhaustive,
max_lpc_order: 12,
max_partition_order: 6,
windows: &[WindowShape::Tukey50, WindowShape::Hann],
lpc_candidates: 2,
},
Level {
block_size: 4096,
stereo: Stereo::Exhaustive,
max_lpc_order: 12,
max_partition_order: 6,
windows: &[
WindowShape::Tukey50,
WindowShape::Hann,
WindowShape::Tukey25,
],
lpc_candidates: 3,
},
];
const COEFFICIENT_PRECISION: u32 = 15;
const RICE4_MAX: u32 = 14;
const RICE5_MAX: u32 = 30;
#[derive(Debug, Clone)]
struct ResidualPlan {
bits: u64,
partition_order: u32,
five_bit: bool,
parameters: Vec<u32>,
}
fn zigzag(residual: i64) -> u64 {
(residual.wrapping_shl(1) ^ (residual >> 63)) as u64
}
fn residual_in_range(residual: &[i64]) -> bool {
residual
.iter()
.all(|&value| value.unsigned_abs() <= i32::MAX as u64)
}
fn plan_residual(folded: &[u64], block_size: usize, order: usize, max_po: u32) -> ResidualPlan {
let mut po = max_po.min(block_size.trailing_zeros());
while po > 0 && (block_size >> po) <= order {
po -= 1;
}
let mut partitions = 1usize << po;
let part_len = block_size >> po;
let mut counts = vec![0u64; partitions];
let mut sums = vec![[0u64; (RICE5_MAX + 1) as usize]; partitions];
for (index, &value) in folded.iter().enumerate() {
let j = (order + index) / part_len;
counts[j] += 1;
let mut shifted = value;
let mut p = 0usize;
while shifted > 0 && p <= RICE5_MAX as usize {
sums[j][p] += shifted;
shifted >>= 1;
p += 1;
}
}
let mut best: Option<ResidualPlan> = None;
loop {
let mut total4 = 2u64 + 4;
let mut total5 = 2u64 + 4;
let mut params4 = Vec::with_capacity(partitions);
let mut params5 = Vec::with_capacity(partitions);
for j in 0..partitions {
let mut best4 = u64::MAX;
let mut best4_p = 0u32;
let mut best5 = u64::MAX;
let mut best5_p = 0u32;
for p in 0..=RICE5_MAX {
let cost = counts[j] * u64::from(p + 1) + sums[j][p as usize];
if p <= RICE4_MAX && cost < best4 {
best4 = cost;
best4_p = p;
}
if cost < best5 {
best5 = cost;
best5_p = p;
}
}
total4 = total4.saturating_add(4 + best4);
total5 = total5.saturating_add(5 + best5);
params4.push(best4_p);
params5.push(best5_p);
}
let (total, five_bit, params) = if total4 <= total5 {
(total4, false, params4)
} else {
(total5, true, params5)
};
if best.as_ref().is_none_or(|held| total < held.bits) {
best = Some(ResidualPlan {
bits: total,
partition_order: po,
five_bit,
parameters: params,
});
}
if po == 0 {
break;
}
po -= 1;
partitions /= 2;
for j in 0..partitions {
counts[j] = counts[2 * j] + counts[2 * j + 1];
let left = sums[2 * j];
let right = sums[2 * j + 1];
for (slot, (a, b)) in sums[j].iter_mut().zip(left.iter().zip(right.iter())) {
*slot = a + b;
}
}
counts.truncate(partitions);
sums.truncate(partitions);
}
best.expect("the partition order zero pass always produces a plan")
}
fn write_residual(
writer: &mut BitWriter,
residual: &[i64],
block_size: usize,
order: usize,
plan: &ResidualPlan,
) {
writer.write(u64::from(plan.five_bit), 2);
writer.write(u64::from(plan.partition_order), 4);
let parameter_bits = if plan.five_bit { 5 } else { 4 };
let part_len = block_size >> plan.partition_order;
let mut at = 0usize;
for (index, ¶meter) in plan.parameters.iter().enumerate() {
writer.write(u64::from(parameter), parameter_bits);
let count = if index == 0 {
part_len - order
} else {
part_len
};
for &value in &residual[at..at + count] {
let folded = zigzag(value);
writer.write_unary(folded >> parameter);
if parameter > 0 {
writer.write(folded & ((1u64 << parameter) - 1), parameter);
}
}
at += count;
}
}
enum SubframeKind {
Constant(i64),
Verbatim,
Fixed {
order: usize,
residual: Vec<i64>,
partitions: ResidualPlan,
},
Lpc {
order: usize,
shift: u32,
coefficients: Vec<i64>,
residual: Vec<i64>,
partitions: ResidualPlan,
},
}
struct SubframePlan {
kind: SubframeKind,
wasted: u32,
depth: u32,
shifted: Vec<i64>,
cost: u64,
}
fn subframe_header_bits(wasted: u32) -> u64 {
8 + if wasted > 0 { u64::from(wasted) } else { 0 }
}
fn levinson(
autocorrelation: &[f64],
max_order: usize,
coefficients: &mut [[f64; MAX_LPC_ORDER]; MAX_LPC_ORDER],
errors: &mut [f64; MAX_LPC_ORDER],
) -> usize {
let mut error = autocorrelation[0];
let mut lpc = [0f64; MAX_LPC_ORDER];
for m in 0..max_order {
if error <= 0.0 || !error.is_finite() {
return m;
}
let mut acc = autocorrelation[m + 1];
for j in 0..m {
acc -= lpc[j] * autocorrelation[m - j];
}
let reflection = acc / error;
lpc[m] = reflection;
for j in 0..m / 2 {
let held = lpc[j];
lpc[j] = held - reflection * lpc[m - 1 - j];
lpc[m - 1 - j] -= reflection * held;
}
if m % 2 == 1 {
let mid = m / 2;
lpc[mid] -= reflection * lpc[mid];
}
error *= 1.0 - reflection * reflection;
coefficients[m][..=m].copy_from_slice(&lpc[..=m]);
errors[m] = error;
}
max_order
}
fn quantise_lpc(coefficients: &[f64], precision: u32) -> Option<(Vec<i64>, u32)> {
let mut largest = 0f64;
for &coefficient in coefficients {
let magnitude = coefficient.abs();
if !magnitude.is_finite() {
return None;
}
if magnitude > largest {
largest = magnitude;
}
}
if largest <= 0.0 {
return None;
}
let exponent = ((largest.to_bits() >> 52) & 0x7FF) as i64 - 1023;
let shift = (i64::from(precision) - 2 - exponent).clamp(0, 15) as u32;
let scale = (1u64 << shift) as f64;
let ceiling = (1i64 << (precision - 1)) - 1;
let floor = -(1i64 << (precision - 1));
let mut quantised = Vec::with_capacity(coefficients.len());
let mut error = 0f64;
let mut any_nonzero = false;
for &coefficient in coefficients {
let target = coefficient * scale + error;
let rounded = ((target + 0.5).floor() as i64).clamp(floor, ceiling);
error = target - rounded as f64;
quantised.push(rounded);
if rounded != 0 {
any_nonzero = true;
}
}
if !any_nonzero {
return None;
}
Some((quantised, shift))
}
fn autocorrelation(windowed: &[f64], max_lag: usize, out: &mut [f64]) {
for (lag, slot) in out.iter_mut().enumerate().take(max_lag + 1) {
*slot = windowed[lag..]
.iter()
.zip(windowed.iter())
.map(|(&late, &early)| late * early)
.sum();
}
}
fn plan_subframe(samples: &[i64], depth: u32, level: &Level, windows: &[Vec<f64>]) -> SubframePlan {
let n = samples.len();
debug_assert!(n > 0);
if samples.iter().all(|&sample| sample == samples[0]) {
return SubframePlan {
kind: SubframeKind::Constant(samples[0]),
wasted: 0,
depth,
shifted: Vec::new(),
cost: 8 + u64::from(depth),
};
}
let mut wasted = depth - 1;
for &sample in samples {
if sample != 0 {
wasted = wasted.min(sample.trailing_zeros());
if wasted == 0 {
break;
}
}
}
let coded_bits = depth - wasted;
let shifted: Vec<i64> = if wasted == 0 {
samples.to_vec()
} else {
samples.iter().map(|&sample| sample >> wasted).collect()
};
let header = subframe_header_bits(wasted);
let mut best_kind = SubframeKind::Verbatim;
let mut best_cost = header + n as u64 * u64::from(coded_bits);
let max_fixed = 4.min(n - 1);
let mut difference = shifted.clone();
let mut order_sums = [u64::MAX; 5];
order_sums[0] = shifted
.iter()
.fold(0u64, |acc, &v| acc.saturating_add(v.unsigned_abs()));
for order in 1..=max_fixed {
for index in (order..n).rev() {
difference[index] = difference[index].wrapping_sub(difference[index - 1]);
}
order_sums[order] = difference[order..]
.iter()
.fold(0u64, |acc, &v| acc.saturating_add(v.unsigned_abs()));
}
let mut ranked: Vec<usize> = (0..=max_fixed).collect();
ranked.sort_by_key(|&order| (order_sums[order], order));
for &order in ranked.iter().take(2) {
let residual: Vec<i64> = (order..n)
.map(|index| shifted[index].wrapping_sub(fixed_prediction(&shifted[..index], order)))
.collect();
if !residual_in_range(&residual) {
continue;
}
let folded: Vec<u64> = residual.iter().map(|&value| zigzag(value)).collect();
let partitions = plan_residual(&folded, n, order, level.max_partition_order);
let cost = header + order as u64 * u64::from(coded_bits) + partitions.bits;
if cost < best_cost {
best_cost = cost;
best_kind = SubframeKind::Fixed {
order,
residual,
partitions,
};
}
}
let max_lpc = level.max_lpc_order.min(n - 1);
if max_lpc >= 1 {
for window in windows {
let windowed: Vec<f64> = shifted
.iter()
.zip(window.iter())
.map(|(&sample, &weight)| sample as f64 * weight)
.collect();
let mut autoc = [0f64; MAX_LPC_ORDER + 1];
autocorrelation(&windowed, max_lpc, &mut autoc);
if autoc[0] <= 0.0 {
continue;
}
let mut coefficients = [[0f64; MAX_LPC_ORDER]; MAX_LPC_ORDER];
let mut errors = [0f64; MAX_LPC_ORDER];
let available = levinson(&autoc, max_lpc, &mut coefficients, &mut errors);
let mut estimates: Vec<(f64, usize)> = (1..=available)
.map(|order| {
let variance = (errors[order - 1] / n as f64).max(1e-12);
let per_residual = (0.5 * det_log2(variance) + 1.6).max(0.0);
let estimate = (n - order) as f64 * per_residual
+ (order as u64 * u64::from(coded_bits + COEFFICIENT_PRECISION)) as f64;
(estimate, order)
})
.collect();
estimates.sort_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1)));
for &(_, order) in estimates.iter().take(level.lpc_candidates) {
let Some((quantised, shift)) =
quantise_lpc(&coefficients[order - 1][..order], COEFFICIENT_PRECISION)
else {
continue;
};
let residual: Vec<i64> = (order..n)
.map(|index| {
shifted[index].wrapping_sub(lpc_prediction(
&quantised,
&shifted[..index],
shift,
))
})
.collect();
if !residual_in_range(&residual) {
continue;
}
let folded: Vec<u64> = residual.iter().map(|&value| zigzag(value)).collect();
let partitions = plan_residual(&folded, n, order, level.max_partition_order);
let cost = header
+ order as u64 * u64::from(coded_bits)
+ 4
+ 5
+ order as u64 * u64::from(COEFFICIENT_PRECISION)
+ partitions.bits;
if cost < best_cost {
best_cost = cost;
best_kind = SubframeKind::Lpc {
order,
shift,
coefficients: quantised,
residual,
partitions,
};
}
}
}
}
SubframePlan {
kind: best_kind,
wasted,
depth,
shifted,
cost: best_cost,
}
}
fn stereo_estimate(samples: &[i64]) -> f64 {
let n = samples.len();
if n < 3 {
return n as f64 * 8.0;
}
let mut sum = 0u64;
for window in samples.windows(3) {
let second = window[2]
.wrapping_sub(window[1].wrapping_mul(2))
.wrapping_add(window[0]);
sum = sum.saturating_add(second.unsigned_abs());
}
let mean = sum as f64 / (n - 2) as f64;
n as f64 * (det_log2(mean + 1.0) + 2.0)
}
fn plan_stereo(
left: &[i64],
right: &[i64],
bits: u32,
level: &Level,
windows: &[Vec<f64>],
) -> (u8, Vec<SubframePlan>) {
let mid: Vec<i64> = left
.iter()
.zip(right.iter())
.map(|(&l, &r)| (l + r) >> 1)
.collect();
let side: Vec<i64> = left
.iter()
.zip(right.iter())
.map(|(&l, &r)| l - r)
.collect();
match level.stereo {
Stereo::Independent => (
1,
vec![
plan_subframe(left, bits, level, windows),
plan_subframe(right, bits, level, windows),
],
),
Stereo::Estimated => {
let estimate_left = stereo_estimate(left);
let estimate_right = stereo_estimate(right);
let estimate_mid = stereo_estimate(&mid);
let estimate_side = stereo_estimate(&side);
let modes = [
(estimate_left + estimate_right, 1u8),
(estimate_left + estimate_side, 8),
(estimate_side + estimate_right, 9),
(estimate_mid + estimate_side, 10),
];
let mut chosen = modes[0];
for &mode in &modes[1..] {
if mode.0.total_cmp(&chosen.0).is_lt() {
chosen = mode;
}
}
let plans = match chosen.1 {
1 => vec![
plan_subframe(left, bits, level, windows),
plan_subframe(right, bits, level, windows),
],
8 => vec![
plan_subframe(left, bits, level, windows),
plan_subframe(&side, bits + 1, level, windows),
],
9 => vec![
plan_subframe(&side, bits + 1, level, windows),
plan_subframe(right, bits, level, windows),
],
_ => vec![
plan_subframe(&mid, bits, level, windows),
plan_subframe(&side, bits + 1, level, windows),
],
};
(chosen.1, plans)
}
Stereo::Exhaustive => {
let plan_left = plan_subframe(left, bits, level, windows);
let plan_right = plan_subframe(right, bits, level, windows);
let plan_mid = plan_subframe(&mid, bits, level, windows);
let plan_side = plan_subframe(&side, bits + 1, level, windows);
let costs = [
(plan_left.cost + plan_right.cost, 1u8),
(plan_left.cost + plan_side.cost, 8),
(plan_side.cost + plan_right.cost, 9),
(plan_mid.cost + plan_side.cost, 10),
];
let mut chosen = costs[0];
for &mode in &costs[1..] {
if mode.0 < chosen.0 {
chosen = mode;
}
}
match chosen.1 {
1 => (1, vec![plan_left, plan_right]),
8 => (8, vec![plan_left, plan_side]),
9 => (9, vec![plan_side, plan_right]),
_ => (10, vec![plan_mid, plan_side]),
}
}
}
}
fn block_size_code(count: usize) -> (u64, Option<(u64, u32)>) {
match count {
192 => (1, None),
576 => (2, None),
1152 => (3, None),
2304 => (4, None),
4608 => (5, None),
256 => (8, None),
512 => (9, None),
1024 => (10, None),
2048 => (11, None),
4096 => (12, None),
8192 => (13, None),
16384 => (14, None),
32768 => (15, None),
_ if count <= 256 => (6, Some((count as u64 - 1, 8))),
_ => (7, Some((count as u64 - 1, 16))),
}
}
fn sample_rate_code(rate: u32) -> u64 {
match rate {
88_200 => 1,
176_400 => 2,
192_000 => 3,
8_000 => 4,
16_000 => 5,
22_050 => 6,
24_000 => 7,
32_000 => 8,
44_100 => 9,
48_000 => 10,
96_000 => 11,
_ => 0,
}
}
fn bit_depth_code(bits: u32) -> u64 {
match bits {
8 => 1,
12 => 2,
16 => 4,
20 => 5,
24 => 6,
32 => 7,
_ => 0,
}
}
fn write_subframe(writer: &mut BitWriter, plan: &SubframePlan, block_size: usize) {
writer.write(0, 1);
let type_code = match &plan.kind {
SubframeKind::Constant(_) => 0u64,
SubframeKind::Verbatim => 1,
SubframeKind::Fixed { order, .. } => 8 + *order as u64,
SubframeKind::Lpc { order, .. } => 31 + *order as u64,
};
writer.write(type_code, 6);
if plan.wasted == 0 {
writer.write(0, 1);
} else {
writer.write(1, 1);
writer.write(1, plan.wasted);
}
let coded_bits = plan.depth - plan.wasted;
match &plan.kind {
SubframeKind::Constant(value) => writer.write_signed(*value, coded_bits),
SubframeKind::Verbatim => {
for &value in &plan.shifted {
writer.write_signed(value, coded_bits);
}
}
SubframeKind::Fixed {
order,
residual,
partitions,
} => {
for &value in &plan.shifted[..*order] {
writer.write_signed(value, coded_bits);
}
write_residual(writer, residual, block_size, *order, partitions);
}
SubframeKind::Lpc {
order,
shift,
coefficients,
residual,
partitions,
} => {
for &value in &plan.shifted[..*order] {
writer.write_signed(value, coded_bits);
}
writer.write(u64::from(COEFFICIENT_PRECISION - 1), 4);
writer.write(u64::from(*shift), 5);
for &coefficient in coefficients {
writer.write_signed(coefficient, COEFFICIENT_PRECISION);
}
write_residual(writer, residual, block_size, *order, partitions);
}
}
}
fn write_frame(
out: &mut Vec<u8>,
frame_index: u64,
block_size: usize,
sample_rate: u32,
bits: u32,
assignment: u8,
plans: &[SubframePlan],
) -> usize {
let mut writer = BitWriter::new();
writer.write(0b111_1111_1111_1100, 15);
writer.write(0, 1);
let (size_code, size_tail) = block_size_code(block_size);
writer.write(size_code, 4);
writer.write(sample_rate_code(sample_rate), 4);
writer.write(u64::from(assignment), 4);
writer.write(bit_depth_code(bits), 3);
writer.write(0, 1);
write_coded_number(&mut writer, frame_index);
if let Some((value, width)) = size_tail {
writer.write(value, width);
}
let header_crc = crc8(writer.bytes());
writer.write(u64::from(header_crc), 8);
for plan in plans {
write_subframe(&mut writer, plan, block_size);
}
writer.align();
let frame_crc = crc16(writer.bytes());
writer.write(u64::from(frame_crc), 16);
let bytes = writer.into_bytes();
out.extend_from_slice(&bytes);
bytes.len()
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct FlacWriter {
spec: AudioSpec,
bits_per_sample: u8,
level: u8,
}
impl FlacWriter {
pub const fn new(spec: AudioSpec, bits_per_sample: u8) -> Self {
Self {
spec,
bits_per_sample,
level: 5,
}
}
pub const fn with_level(mut self, level: u8) -> Self {
self.level = level;
self
}
pub const fn spec(&self) -> AudioSpec {
self.spec
}
pub const fn bits_per_sample(&self) -> u8 {
self.bits_per_sample
}
pub const fn level(&self) -> u8 {
self.level
}
pub fn write(&self, samples: &[f32], output: &mut Vec<u8>) -> Result<usize, DecodeError> {
let channels = usize::from(self.spec.channels);
if channels == 0 || channels > usize::from(MAX_CHANNELS) {
return Err(DecodeError::UnsupportedChannelLayout {
channels: self.spec.channels,
});
}
if self.spec.sample_rate == 0 || self.spec.sample_rate > 0xF_FFFF {
return Err(DecodeError::Malformed {
expected: "a sample rate between 1 and 1048575, the range streaminfo carries",
offset: 18,
});
}
if !(4..=32).contains(&self.bits_per_sample) {
return Err(DecodeError::UnsupportedSampleFormat {
format: CodecId::Name("FLAC".to_string()),
bits_per_sample: u16::from(self.bits_per_sample),
});
}
if usize::from(self.level) >= LEVELS.len() {
return Err(DecodeError::Malformed {
expected: "a compression level between 0 and 8",
offset: 0,
});
}
let leftover = samples.len() % channels;
if leftover != 0 {
return Err(DecodeError::Truncated {
expected: channels as u64,
available: leftover as u64,
});
}
let total_frames = (samples.len() / channels) as u64;
if total_frames >= 1u64 << 36 {
return Err(DecodeError::Malformed {
expected: "no more sample frames than streaminfo's 36-bit total can declare",
offset: 21,
});
}
let level = &LEVELS[usize::from(self.level)];
let bits = u32::from(self.bits_per_sample);
let block = level.block_size as usize;
let scale = (1u64 << (bits - 1)) as f32;
let floor = -(1i64 << (bits - 1));
let ceiling = (1i64 << (bits - 1)) - 1;
let width = usize::from(self.bits_per_sample).div_ceil(8);
let mut hasher = Md5::new();
let mut body: Vec<u8> = Vec::new();
let mut smallest_frame = u64::MAX;
let mut largest_frame = 0u64;
let mut channel_data: Vec<Vec<i64>> = vec![Vec::new(); channels];
let mut hash_stage: Vec<u8> = Vec::new();
let mut windows: Vec<Vec<f64>> = Vec::new();
let mut window_len = 0usize;
let mut frame_index = 0u64;
let mut done = 0usize;
let total = total_frames as usize;
while done < total {
let count = block.min(total - done);
for channel in &mut channel_data {
channel.clear();
}
hash_stage.clear();
let base = done * channels;
for frame in 0..count {
for (channel, data) in channel_data.iter_mut().enumerate() {
let value = quantize(
samples[base + frame * channels + channel],
scale,
floor,
ceiling,
);
data.push(value);
hash_stage.extend_from_slice(&value.to_le_bytes()[..width]);
}
}
hasher.update(&hash_stage);
if level.max_lpc_order > 0 && (windows.is_empty() || window_len != count) {
windows = level
.windows
.iter()
.map(|shape| shape.build(count))
.collect();
window_len = count;
}
let (assignment, plans) = if channels == 2 && level.stereo != Stereo::Independent {
plan_stereo(&channel_data[0], &channel_data[1], bits, level, &windows)
} else {
(
(channels - 1) as u8,
channel_data
.iter()
.map(|channel| plan_subframe(channel, bits, level, &windows))
.collect(),
)
};
let frame_bytes = write_frame(
&mut body,
frame_index,
count,
self.spec.sample_rate,
bits,
assignment,
&plans,
) as u64;
smallest_frame = smallest_frame.min(frame_bytes);
largest_frame = largest_frame.max(frame_bytes);
frame_index += 1;
done += count;
}
let digest = hasher.finish();
let start = output.len();
output.extend_from_slice(MAGIC.as_bytes());
output.push(0x80);
output.extend_from_slice(&[0, 0, STREAMINFO_BYTES as u8]);
let mut info = BitWriter::new();
info.write(u64::from(level.block_size), 16);
info.write(u64::from(level.block_size), 16);
let (min_frame, max_frame) = if frame_index == 0 {
(0, 0)
} else {
(smallest_frame, largest_frame)
};
info.write(min_frame, 24);
info.write(max_frame, 24);
info.write(u64::from(self.spec.sample_rate), 20);
info.write(channels as u64 - 1, 3);
info.write(u64::from(bits) - 1, 5);
info.write(total_frames, 36);
output.extend_from_slice(&info.into_bytes());
output.extend_from_slice(&digest);
output.extend_from_slice(&body);
Ok(output.len() - start)
}
pub fn to_bytes(&self, samples: &[f32]) -> Result<Vec<u8>, DecodeError> {
let mut output = Vec::new();
self.write(samples, &mut output)?;
Ok(output)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::sample::{i16_to_f32, i24_to_f32, i32_to_f32, i8_to_f32};
const EXAMPLE_1: [u8; 45] = [
0x66, 0x4c, 0x61, 0x43, 0x80, 0x00, 0x00, 0x22, 0x10, 0x00, 0x10, 0x00, 0x00, 0x00, 0x0f,
0x00, 0x00, 0x0f, 0x0a, 0xc4, 0x42, 0xf0, 0x00, 0x00, 0x00, 0x01, 0x3e, 0x84, 0xb4, 0x18,
0x07, 0xdc, 0x69, 0x03, 0x07, 0x58, 0x6a, 0x3d, 0xad, 0x1a, 0x2e, 0x0f, 0xff, 0xf8, 0x69,
];
const EXAMPLE_1_TAIL: [u8; 8] = [0x18, 0x00, 0x00, 0xbf, 0x03, 0x58, 0xfd, 0x03];
const EXAMPLE_1_CRC: [u8; 4] = [0x12, 0x8b, 0xaa, 0x9a];
fn example_1() -> Vec<u8> {
let mut file = EXAMPLE_1.to_vec();
file.extend_from_slice(&EXAMPLE_1_TAIL);
file.extend_from_slice(&EXAMPLE_1_CRC);
file
}
#[test]
fn crc8_matches_the_specification() {
assert_eq!(crc8(&[0x00]), 0x00);
assert_eq!(crc8(&[0x01]), 0x07);
let file = example_1();
assert_eq!(crc8(&file[0x2a..0x30]), file[0x30]);
}
#[test]
fn crc16_matches_the_specification() {
assert_eq!(crc16(&[0x00]), 0x0000);
assert_eq!(crc16(&[0x01]), 0x8005);
let file = example_1();
assert_eq!(
crc16(&file[0x2a..0x37]),
u16::from_be_bytes([file[0x37], file[0x38]])
);
}
#[test]
fn the_coded_number_is_not_utf8() {
let bytes = [0xFE, 0xAF, 0x9F, 0xB5, 0xA3, 0xB8, 0x80];
let mut reader = BitReader::new(&bytes, 0);
assert_eq!(
read_coded_number(&mut reader).expect("read"),
51_000_000_000
);
let mut reader = BitReader::new(&[0x7F], 0);
assert_eq!(read_coded_number(&mut reader).expect("read"), 127);
for first in [0x80u8, 0xFF] {
let bytes = [first, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80];
let mut reader = BitReader::new(&bytes, 0);
assert!(read_coded_number(&mut reader).is_err());
}
}
#[test]
fn the_bit_reader_reads_across_byte_boundaries() {
let bytes = [0b1010_1100, 0b1111_0000, 0b0000_1111];
let mut reader = BitReader::new(&bytes, 0);
assert_eq!(reader.read_bits(3).expect("read"), 0b101);
assert_eq!(reader.read_bits(7).expect("read"), 0b011_0011);
assert_eq!(reader.read_bits(14).expect("read"), 0b11_0000_0000_1111);
assert!(reader.read_bits(1).is_err());
}
#[test]
fn the_bit_reader_sign_extends() {
let bytes = [0b1110_1110, 0b0000_0000];
let mut reader = BitReader::new(&bytes, 0);
assert_eq!(reader.read_signed(3).expect("read"), -1);
assert_eq!(reader.read_signed(3).expect("read"), 3);
assert_eq!(reader.read_signed(3).expect("read"), -4);
let mut reader = BitReader::new(&bytes, 0);
reader.bit = 6;
assert_eq!(reader.read_bits(3).expect("read"), 4);
}
#[test]
fn unary_counts_zeros_and_eats_the_one() {
let bytes = [0b0000_0100, 0b1000_0000];
let mut reader = BitReader::new(&bytes, 0);
assert_eq!(reader.read_unary().expect("read"), 5);
assert_eq!(reader.read_unary().expect("read"), 2);
let mut reader = BitReader::new(&[0u8; 32], 0);
assert!(reader.read_unary().is_err());
}
#[test]
fn a_long_unary_run_terminates() {
let mut bytes = vec![0u8; 16];
bytes.push(0x80);
let mut reader = BitReader::new(&bytes, 0);
assert_eq!(reader.read_unary().expect("read"), 128);
}
#[test]
fn flac_scaling_agrees_with_sample_rs() {
fn flac_scale(sample: i64, bits: u8) -> f32 {
sample as f32 / (1u64 << (bits - 1)) as f32
}
for value in i16::MIN..=i16::MAX {
assert_eq!(flac_scale(i64::from(value), 16), i16_to_f32(value));
}
for value in i8::MIN..=i8::MAX {
assert_eq!(flac_scale(i64::from(value), 8), i8_to_f32(value));
}
for value in [
crate::sample::I24_MIN,
-1,
0,
1,
crate::sample::I24_MAX,
123_456,
] {
assert_eq!(flac_scale(i64::from(value), 24), i24_to_f32(value));
}
for value in [i32::MIN, -1, 0, 1, i32::MAX, 1_234_567_890] {
assert_eq!(flac_scale(i64::from(value), 32), i32_to_f32(value));
}
}
#[test]
fn mid_side_reconstruction_is_lossless_over_a_swept_domain() {
for left in -300i64..=300 {
for right in -300i64..=300 {
let mid = (left + right) >> 1;
let side = left - right;
let mut a = [mid];
let mut b = [side];
undo_decorrelation(ChannelAssignment::MidSide, &mut a, &mut b);
assert_eq!((a[0], b[0]), (left, right), "mid/side lost {left},{right}");
}
}
}
#[test]
fn left_side_and_side_right_reconstruction_round_trip() {
for left in [-32_768i64, -1, 0, 1, 32_767] {
for right in [-32_768i64, -1, 0, 1, 32_767] {
let side = left - right;
let mut a = [left];
let mut b = [side];
undo_decorrelation(ChannelAssignment::LeftSide, &mut a, &mut b);
assert_eq!((a[0], b[0]), (left, right));
let mut a = [side];
let mut b = [right];
undo_decorrelation(ChannelAssignment::SideRight, &mut a, &mut b);
assert_eq!((a[0], b[0]), (left, right));
}
}
}
#[test]
fn the_worked_example_decodes_exactly() {
let file = example_1();
let reader = FlacReader::new(&file).expect("open");
assert_eq!(reader.spec(), AudioSpec::new(44_100, 2));
assert_eq!(reader.stream_info().bits_per_sample, 16);
assert_eq!(reader.frames(), Some(1));
let decoded = reader.decode_to_end().expect("decode");
assert_eq!(
decoded.samples(),
[25_588.0 / 32_768.0, 10_416.0 / 32_768.0]
);
}
#[test]
fn a_wrong_magic_is_named_rather_than_categorised() {
let error = FlacReader::new(b"RIFFxxxxWAVE").expect_err("must reject");
assert!(
matches!(error, DecodeError::UnsupportedContainer { tag } if tag.as_bytes() == b"RIFF"),
"unexpected error: {error}"
);
}
#[test]
fn the_streaming_path_matches_the_whole_file_path() {
let file = example_1();
let whole = FlacReader::new(&file)
.expect("open")
.decode_to_end()
.expect("decode");
for chunk in [1, 2, 3, 7, 16, 64, 4096] {
let mut stream = FlacStreamDecoder::new();
let mut samples = Vec::new();
for piece in file.chunks(chunk) {
let mut offset = 0;
while offset < piece.len() {
offset += stream.push(&piece[offset..]).expect("push");
while stream.pull(&mut samples, usize::MAX).expect("pull") > 0 {}
}
}
stream.finish(&mut samples).expect("finish");
assert_eq!(
samples,
whole.samples(),
"output changed with a {chunk}-byte feed size"
);
}
}
#[test]
fn an_all_zero_md5_is_unset_rather_than_a_failure() {
let mut file = example_1();
file[26..42].fill(0);
let reader = FlacReader::new(&file).expect("open");
assert_eq!(reader.stream_info().md5, None);
assert!(reader.decode_to_end().is_ok());
}
#[test]
fn a_wrong_md5_is_a_typed_error_rather_than_audio() {
let mut file = example_1();
file[26] ^= 0xFF;
let error = FlacReader::new(&file)
.expect("open")
.decode_to_end()
.expect_err("must reject");
assert!(
matches!(
error,
DecodeError::Malformed {
expected: "decoded audio matching the streaminfo MD5 checksum",
..
}
),
"unexpected error: {error}"
);
}
fn splitmix(state: &mut u64) -> u64 {
*state = state.wrapping_add(0x9E37_79B9_7F4A_7C15);
let mut z = *state;
z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
z ^ (z >> 31)
}
fn brute_partition_cost(folded: &[u64], parameter: u32) -> u64 {
folded
.iter()
.map(|&value| (value >> parameter) + 1 + u64::from(parameter))
.sum()
}
#[test]
fn the_partition_search_matches_exhaustive_enumeration() {
let mut state = 0x5EED_CAFE_u64;
for (block_size, order, max_po) in
[(64usize, 2usize, 3u32), (96, 0, 4), (256, 4, 8), (33, 1, 6)]
{
let folded: Vec<u64> = (0..block_size - order)
.map(|_| {
let raw = splitmix(&mut state);
if raw.is_multiple_of(13) {
raw >> 34
} else {
raw >> 56
}
})
.collect();
let plan = plan_residual(&folded, block_size, order, max_po);
let mut expected = u64::MAX;
let mut po = max_po.min(block_size.trailing_zeros());
while block_size >> po <= order {
po -= 1;
}
for po in (0..=po).rev() {
if !block_size.is_multiple_of(1 << po) {
continue;
}
let part_len = block_size >> po;
for (parameter_bits, max_parameter) in [(4u64, RICE4_MAX), (5, RICE5_MAX)] {
let mut total = 2 + 4;
let mut at = 0usize;
for partition in 0..1usize << po {
let count = if partition == 0 {
part_len - order
} else {
part_len
};
let best = (0..=max_parameter)
.map(|p| brute_partition_cost(&folded[at..at + count], p))
.min()
.expect("at least one parameter");
total += parameter_bits + best;
at += count;
}
expected = expected.min(total);
}
}
assert_eq!(
plan.bits, expected,
"block {block_size} order {order} max_po {max_po}"
);
let residual: Vec<i64> = folded
.iter()
.map(|&value| ((value >> 1) as i64) ^ -((value & 1) as i64))
.collect();
let mut writer = BitWriter::new();
write_residual(&mut writer, &residual, block_size, order, &plan);
let written_bits = writer.out.len() as u64 * 8 + u64::from(writer.filled);
assert_eq!(written_bits, plan.bits, "written size vs planned size");
}
}
#[test]
fn the_bit_writer_mirrors_the_bit_reader() {
let mut writer = BitWriter::new();
writer.write(0b101, 3);
writer.write_signed(-1, 7);
writer.write(0x5A5A, 16);
writer.write_signed(-12345, 33);
writer.write_unary(0);
writer.write_unary(5);
writer.write_unary(100);
writer.write(1, 1);
let bytes = writer.into_bytes();
let mut reader = BitReader::new(&bytes, 0);
assert_eq!(reader.read_bits(3).expect("read"), 0b101);
assert_eq!(reader.read_signed(7).expect("read"), -1);
assert_eq!(reader.read_bits(16).expect("read"), 0x5A5A);
assert_eq!(reader.read_signed(33).expect("read"), -12345);
assert_eq!(reader.read_unary().expect("read"), 0);
assert_eq!(reader.read_unary().expect("read"), 5);
assert_eq!(reader.read_unary().expect("read"), 100);
assert_eq!(reader.read_bits(1).expect("read"), 1);
}
#[test]
fn the_coded_number_round_trips_at_every_length_boundary() {
for value in [
0u64,
0x7F,
0x80,
0x7FF,
0x800,
0xFFFF,
0x1_0000,
0x1F_FFFF,
0x20_0000,
0x3FF_FFFF,
0x400_0000,
0x7FFF_FFFF,
0x8000_0000,
(1 << 36) - 1,
] {
let mut writer = BitWriter::new();
write_coded_number(&mut writer, value);
let bytes = writer.into_bytes();
let mut reader = BitReader::new(&bytes, 0);
assert_eq!(
read_coded_number(&mut reader).expect("read"),
value,
"coded number {value:#x}"
);
}
}
#[test]
fn the_deterministic_math_lands_near_the_true_values() {
assert!((det_cos_pi(0.0) - 1.0).abs() < 1e-12);
assert!(det_cos_pi(0.5).abs() < 1e-12);
assert!((det_cos_pi(1.0) + 1.0).abs() < 1e-12);
assert!((det_cos_pi(1.0 / 3.0) - 0.5).abs() < 1e-9);
assert!((det_log2(8.0) - 3.0).abs() < 1e-9);
assert!((det_log2(1.0)).abs() < 1e-9);
assert!((det_log2(0.125) + 3.0).abs() < 1e-9);
assert!((det_log2(3.0) - 1.584_962_500_721_156).abs() < 1e-9);
assert!(det_log2(f64::from_bits(1)) < -1000.0);
}
#[test]
fn quantised_coefficients_fit_their_fields() {
let mut state = 0xC0FF_EE00_u64;
for _ in 0..200 {
let order = (splitmix(&mut state) % 32 + 1) as usize;
let coefficients: Vec<f64> = (0..order)
.map(|_| {
let raw = splitmix(&mut state);
let magnitude = ((raw >> 40) as f64 + 1.0) / 1_048_576.0;
let scaled = magnitude * ((1 << (raw % 18)) as f64 / 8.0);
if raw & 1 == 0 {
scaled
} else {
-scaled
}
})
.collect();
let Some((quantised, shift)) = quantise_lpc(&coefficients, COEFFICIENT_PRECISION)
else {
continue;
};
assert!(shift <= 15, "shift {shift} does not fit the 5-bit field");
assert_eq!(quantised.len(), order);
let ceiling = (1i64 << (COEFFICIENT_PRECISION - 1)) - 1;
let floor = -(1i64 << (COEFFICIENT_PRECISION - 1));
for &q in &quantised {
assert!(
(floor..=ceiling).contains(&q),
"coefficient {q} does not fit {COEFFICIENT_PRECISION} bits"
);
}
}
}
#[test]
fn the_shared_predictions_match_hand_arithmetic() {
let history = [3i64, 5, 9, 15, 23];
assert_eq!(fixed_prediction(&history, 0), 0);
assert_eq!(fixed_prediction(&history, 1), 23);
assert_eq!(fixed_prediction(&history, 2), 2 * 23 - 15);
assert_eq!(fixed_prediction(&history, 3), 3 * 23 - 3 * 15 + 9);
assert_eq!(fixed_prediction(&history, 4), 4 * 23 - 6 * 15 + 4 * 9 - 5);
assert_eq!(lpc_prediction(&[2, 1], &history, 2), (2 * 23 + 15) >> 2);
}
}