From cdf4a2fa6e23f80e6a8210361a79f6e9600a4056 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 15:11:43 +0100 Subject: [PATCH 1/3] craft-audio: native FLAC decoder (flac-decode) Adds flac::decode for whole files and flac::Decoder for single frames: RFC 9639 subframes (constant, verbatim, fixed, LPC), Rice and escaped partitions, wasted bits, all stereo modes, fixed and variable block sizes, 4 to 32 bits, CRC-8 and CRC-16 checked. Not yet wired into craft_audio::decode, which still uses symphonia for FLAC. Part of #1546 --- crates/audio/Cargo.toml | 6 + crates/audio/README.md | 1 + crates/audio/src/flac_decode.rs | 558 ++++++++++++++++++++++++++++++ crates/audio/src/lib.rs | 9 +- crates/audio/tests/flac_decode.rs | 179 ++++++++++ 5 files changed, 751 insertions(+), 2 deletions(-) create mode 100644 crates/audio/src/flac_decode.rs create mode 100644 crates/audio/tests/flac_decode.rs diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index c411a0357..a0d1070bd 100644 --- a/crates/audio/Cargo.toml +++ b/crates/audio/Cargo.toml @@ -29,6 +29,8 @@ encode = ["lossless-encode", "aac-encode", "alac-encode", "ac3-encode", "eac3-en lossless-encode = ["pcm-encode", "flac-encode"] # Encode WAV/BWF/RF64 and AIFF/AIFF-C files. pcm-encode = [] +# Decode FLAC files and frames natively (`flac::decode`, `flac::Decoder`). +flac-decode = [] # Encode FLAC files. flac-encode = ["craft-media/bitstream"] # Encode Ogg Vorbis files (desktop only: builds the reference libvorbis from its C sources). @@ -84,6 +86,10 @@ required-features = ["decode", "lossless-encode", "peaks"] name = "codecs" required-features = ["decode", "encode"] +[[test]] +name = "flac_decode" +required-features = ["flac-decode", "flac-encode"] + [[example]] name = "info" required-features = ["decode"] diff --git a/crates/audio/README.md b/crates/audio/README.md index 63251db8d..c336b4b8e 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -32,6 +32,7 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou | `encode` | every encoder, and every format of `encode` and `FileEncoder` | `lossless-encode`, `aac-encode`, `alac-encode`, `ac3-encode`, `eac3-encode`, `mp3-encode`, `opus-encode` | | `lossless-encode` | WAV, AIFF and FLAC writing | `pcm-encode`, `flac-encode` | | `pcm-encode` | `encode`, `FileEncoder` for WAV and AIFF; `wav_float_header`; `pcm_wav_file`, `pcm_wav_header`, `pcm_aiff_file`, `pcm_aiff_header` (minimal files around integer PCM bytes, for essence embedded in AAF / OMF) | none | +| `flac-decode` | `flac::decode` (whole `.flac` files) and `flac::Decoder` (single frames, for callers that demux FLAC themselves); native, CRC-checked, 4 to 32 bits. `decode` still uses symphonia for FLAC files | none | | `flac-encode` | `encode`, `FileEncoder` for FLAC; `flac::Encoder`, the packet encoder for callers that mux FLAC themselves | craft-media `bitstream` | | `aac-decode`, `aac-encode` | `aac::Decoder`, `aac::Encoder`; with `aac-decode`, `aac::latm_config` / `latm_split` for LOAS / LATM frames (AAC in MPEG transport streams); with `aac-encode`, `encode`, `FileEncoder` for AAC in M4A | craft-media `bitstream`; `aac-encode` also `isobmff` | | `alac-decode` | `alac::Decoder` | none | diff --git a/crates/audio/src/flac_decode.rs b/crates/audio/src/flac_decode.rs new file mode 100644 index 000000000..dfb6f5fc1 --- /dev/null +++ b/crates/audio/src/flac_decode.rs @@ -0,0 +1,558 @@ +//! A native FLAC decoder (RFC 9639): [`decode`] for whole `.flac` files and [`Decoder`] for single +//! frames (the packets of FLAC in MP4, Matroska or Ogg). +//! +//! Every frame is checked against its CRC-8 and CRC-16. Subframe types constant, verbatim, fixed +//! and LPC; Rice partitions with 4- and 5-bit parameters and escaped partitions; wasted bits; +//! left/side, side/right and mid/side stereo; fixed and variable block sizes; 4 to 32 bits per +//! sample. The STREAMINFO MD5 is not verified. +//! +//! Samples come back as `i32`, one `Vec` per channel, in the FLAC channel order. + +/// What went wrong decoding FLAC. +#[non_exhaustive] +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum DecodeError { + /// The data ends early. + #[error("truncated FLAC data")] + Truncated, + /// The data is not valid FLAC. + #[error("invalid FLAC data: {0}")] + Invalid(&'static str), + /// A frame or header failed its CRC. + #[error("FLAC CRC mismatch in {0}")] + Crc(&'static str), + /// Valid FLAC that is not decoded. + #[error("unsupported FLAC feature: {0}")] + Unsupported(&'static str), + /// The stream is longer than the sample limit. + #[error("FLAC stream exceeds the sample limit")] + TooLarge, +} + +/// `Result` of this module. +pub type Result = std::result::Result; + +/// The STREAMINFO metadata block (RFC 9639 section 8.2). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct StreamInfo { + /// Smallest block size in samples. + pub min_block_size: u16, + /// Largest block size in samples. + pub max_block_size: u16, + /// Smallest frame in bytes, 0 if unknown. + pub min_frame_size: u32, + /// Largest frame in bytes, 0 if unknown. + pub max_frame_size: u32, + /// Sample rate in Hz. + pub sample_rate: u32, + /// Channel count, 1 to 8. + pub channels: u8, + /// Bits per sample, 4 to 32. + pub bits_per_sample: u8, + /// Samples per channel in the stream, 0 if unknown. + pub total_samples: u64, + /// MD5 of the unencoded audio, all zero if not set. + pub md5: [u8; 16], +} + +impl StreamInfo { + /// Parse the 34 bytes of a STREAMINFO block body. + pub fn parse(b: &[u8]) -> Result { + let b = b.get(..34).ok_or(DecodeError::Truncated)?; + let packed = u64::from_be_bytes([b[10], b[11], b[12], b[13], b[14], b[15], b[16], b[17]]); + let info = StreamInfo { + min_block_size: u16::from_be_bytes([b[0], b[1]]), + max_block_size: u16::from_be_bytes([b[2], b[3]]), + min_frame_size: u32::from_be_bytes([0, b[4], b[5], b[6]]), + max_frame_size: u32::from_be_bytes([0, b[7], b[8], b[9]]), + sample_rate: (packed >> 44) as u32, + channels: ((packed >> 41) & 7) as u8 + 1, + bits_per_sample: ((packed >> 36) & 31) as u8 + 1, + total_samples: packed & 0xF_FFFF_FFFF, + md5: b[18..34].try_into().map_err(|_| DecodeError::Truncated)?, + }; + if info.bits_per_sample < 4 { + return Err(DecodeError::Invalid("bits per sample below 4")); + } + if info.min_block_size != 0 + && (info.min_block_size < 16 && info.min_block_size != info.max_block_size || info.max_block_size < info.min_block_size) + { + return Err(DecodeError::Invalid("inconsistent block sizes")); + } + Ok(info) + } +} + +/// One decoded frame. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Frame { + /// Sample rate in Hz. + pub sample_rate: u32, + /// Bits per sample. + pub bits_per_sample: u8, + /// `true` when `number` is the first sample's index (variable block size), `false` when it is + /// the frame's index (fixed block size). + pub variable_block_size: bool, + /// The coded number of the frame header. + pub number: u64, + /// Samples per channel in the frame. + pub block_size: usize, + /// One `Vec` per channel, after undoing any stereo decorrelation. + pub channels: Vec>, + /// Bytes the frame took, including the header and CRC footer. + pub size: usize, +} + +// ---- checksums ---- + +fn crc8(data: &[u8]) -> u8 { + let mut crc = 0u8; + for &b in data { + crc ^= b; + for _ in 0..8 { + crc = if crc & 0x80 != 0 { crc << 1 ^ 0x07 } else { crc << 1 }; + } + } + crc +} + +fn crc16(data: &[u8]) -> u16 { + let mut crc = 0u16; + for &b in data { + crc ^= u16::from(b) << 8; + for _ in 0..8 { + crc = if crc & 0x8000 != 0 { crc << 1 ^ 0x8005 } else { crc << 1 }; + } + } + crc +} + +// ---- bits ---- + +struct Bits<'a> { + data: &'a [u8], + /// Position in bits. + pos: usize, +} + +impl<'a> Bits<'a> { + fn new(data: &'a [u8]) -> Self { + Bits { data, pos: 0 } + } + + fn left(&self) -> usize { + self.data.len() * 8 - self.pos + } + + fn bit(&mut self) -> Result { + let byte = *self.data.get(self.pos / 8).ok_or(DecodeError::Truncated)?; + let v = (byte >> (7 - self.pos % 8)) & 1; + self.pos += 1; + Ok(u32::from(v)) + } + + /// `n` bits (0 to 32) as an unsigned number. + fn bits(&mut self, n: u32) -> Result { + if n as usize > self.left() { + return Err(DecodeError::Truncated); + } + let mut v = 0u64; + let mut n = n as usize; + while n > 0 { + let byte = u64::from(self.data[self.pos / 8]); + let avail = 8 - self.pos % 8; + let take = avail.min(n); + v = v << take | (byte >> (avail - take)) & ((1 << take) - 1); + self.pos += take; + n -= take; + } + Ok(v) + } + + /// `n` bits (0 to 33) as a two's complement number. + fn signed(&mut self, n: u32) -> Result { + if n == 0 { + return Ok(0); + } + let v = self.bits(n)? as i64; + Ok(if v >> (n - 1) & 1 == 1 { v - (1 << n) } else { v }) + } + + /// Zero bits up to the next one bit (which is consumed). + fn unary(&mut self) -> Result { + let mut n = 0u64; + loop { + // Skip whole zero bytes when aligned. + if self.pos.is_multiple_of(8) { + while self.data.get(self.pos / 8) == Some(&0) { + self.pos += 8; + n += 8; + } + } + if self.bit()? == 1 { + return Ok(n); + } + n += 1; + } + } + + fn align(&mut self) { + self.pos = self.pos.div_ceil(8) * 8; + } +} + +// ---- frame ---- + +const BLOCK_SIZES: [usize; 16] = [0, 192, 576, 1152, 2304, 4608, 0, 0, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768]; + +/// A frame decoder. `info` supplies what a frame header leaves to the STREAMINFO. +#[derive(Debug, Clone, Copy, Default)] +pub struct Decoder { + info: Option, +} + +impl Decoder { + /// A decoder with the stream's STREAMINFO (needed for frames whose header defers the sample + /// rate or bit depth to it). + pub fn new(info: StreamInfo) -> Decoder { + Decoder { info: Some(info) } + } + + /// A decoder without STREAMINFO: frames that defer to it are an error. + pub fn without_streaminfo() -> Decoder { + Decoder { info: None } + } + + /// Decode the frame at the start of `data`. + pub fn decode_frame(&self, data: &[u8]) -> Result { + let mut r = Bits::new(data); + if r.bits(15)? != 0x7FFC { + return Err(DecodeError::Invalid("missing frame sync code")); + } + let variable = r.bit()? == 1; + let (bs_code, sr_code) = (r.bits(4)? as usize, r.bits(4)? as usize); + let (ch_code, bps_code) = (r.bits(4)? as usize, r.bits(3)? as usize); + if r.bit()? != 0 { + return Err(DecodeError::Invalid("reserved bit set")); + } + let number = coded_number(&mut r)?; + let block_size = match bs_code { + 0 => return Err(DecodeError::Invalid("reserved block size")), + 6 => r.bits(8)? as usize + 1, + 7 => r.bits(16)? as usize + 1, + c => BLOCK_SIZES[c], + }; + let sample_rate = match sr_code { + 0 => self.info.map(|i| i.sample_rate).ok_or(DecodeError::Invalid("sample rate only in STREAMINFO"))?, + 1 => 88_200, + 2 => 176_400, + 3 => 192_000, + 4 => 8_000, + 5 => 16_000, + 6 => 22_050, + 7 => 24_000, + 8 => 32_000, + 9 => 44_100, + 10 => 48_000, + 11 => 96_000, + 12 => r.bits(8)? as u32 * 1000, + 13 => r.bits(16)? as u32, + 14 => r.bits(16)? as u32 * 10, + _ => return Err(DecodeError::Invalid("forbidden sample rate code")), + }; + let header_len = r.pos.div_ceil(8); + let stored_crc = r.bits(8)? as u8; + if crc8(&data[..header_len]) != stored_crc { + return Err(DecodeError::Crc("a frame header")); + } + let bits = match bps_code { + 0 => self.info.map(|i| u32::from(i.bits_per_sample)).ok_or(DecodeError::Invalid("bit depth only in STREAMINFO"))?, + 1 => 8, + 2 => 12, + 4 => 16, + 5 => 20, + 6 => 24, + 7 => 32, + _ => return Err(DecodeError::Invalid("reserved bit depth")), + }; + let (channels, mode) = match ch_code { + 0..=7 => (ch_code + 1, Stereo::Independent), + 8 => (2, Stereo::LeftSide), + 9 => (2, Stereo::SideRight), + 10 => (2, Stereo::MidSide), + _ => return Err(DecodeError::Invalid("reserved channel assignment")), + }; + let mut out: Vec> = Vec::with_capacity(channels); + for c in 0..channels { + let extra = match (mode, c) { + (Stereo::LeftSide, 1) | (Stereo::SideRight, 0) | (Stereo::MidSide, 1) => 1, + _ => 0, + }; + out.push(subframe(&mut r, block_size, bits + extra)?); + } + r.align(); + let size = r.pos / 8; + let crc = r.bits(16)? as u16; + if crc16(&data[..size]) != crc { + return Err(DecodeError::Crc("a frame")); + } + let size = size + 2; + if mode != Stereo::Independent { + let (first, rest) = out.split_at_mut(1); + let (a, b) = (&mut first[0], &mut rest[0]); + for (x, y) in a.iter_mut().zip(b.iter_mut()) { + match mode { + Stereo::LeftSide => *y = x.wrapping_sub(*y), + Stereo::SideRight => *x = x.wrapping_add(*y), + _ => { + let m = x.wrapping_shl(1) | (*y & 1); + let side = *y; + *x = m.wrapping_add(side) >> 1; + *y = m.wrapping_sub(side) >> 1; + } + } + } + } + let mut chans = Vec::with_capacity(channels); + for c in out { + let v: Result> = + c.into_iter().map(|s| i32::try_from(s).map_err(|_| DecodeError::Invalid("sample outside the bit depth"))).collect(); + chans.push(v?); + } + Ok(Frame { sample_rate, bits_per_sample: bits as u8, variable_block_size: variable, number, block_size, channels: chans, size }) + } +} + +#[derive(Clone, Copy, PartialEq, Eq)] +enum Stereo { + Independent, + LeftSide, + SideRight, + MidSide, +} + +/// The UTF-8-like coded number of a frame header (up to 36 bits, 7 bytes). +fn coded_number(r: &mut Bits) -> Result { + let first = r.bits(8)? as u8; + let extra = match first { + 0x00..=0x7F => return Ok(u64::from(first)), + 0xC0..=0xDF => 1, + 0xE0..=0xEF => 2, + 0xF0..=0xF7 => 3, + 0xF8..=0xFB => 4, + 0xFC..=0xFD => 5, + 0xFE => 6, + _ => return Err(DecodeError::Invalid("bad coded number")), + }; + let mut v = if extra == 6 { 0 } else { u64::from(first & (0x3F >> extra)) }; + for _ in 0..extra { + let b = r.bits(8)?; + if b & 0xC0 != 0x80 { + return Err(DecodeError::Invalid("bad coded number")); + } + v = v << 6 | (b & 0x3F); + } + Ok(v) +} + +/// One subframe: `bits` is the frame bit depth (plus 1 for a side channel). +fn subframe(r: &mut Bits, n: usize, bits: u32) -> Result> { + if r.bit()? != 0 { + return Err(DecodeError::Invalid("subframe header padding bit set")); + } + let kind = r.bits(6)? as u32; + let wasted = if r.bit()? == 1 { r.unary()? as u32 + 1 } else { 0 }; + if wasted >= bits { + return Err(DecodeError::Invalid("wasted bits leave no sample bits")); + } + let bps = bits - wasted; + let mut s = vec![0i64; n]; + match kind { + 0 => { + let v = r.signed(bps)?; + s.fill(v); + } + 1 => { + for v in s.iter_mut() { + *v = r.signed(bps)?; + } + } + 8..=12 => { + let order = (kind - 8) as usize; + warmup(r, &mut s, order, bps)?; + residual(r, &mut s, order)?; + for i in order..n { + let at = |k: usize| s[i - k]; + // Wrapping: hostile residuals can overflow; such samples fail the range check later. + let p = match order { + 0 => 0, + 1 => at(1), + 2 => at(1).wrapping_mul(2).wrapping_sub(at(2)), + 3 => at(1).wrapping_mul(3).wrapping_sub(at(2).wrapping_mul(3)).wrapping_add(at(3)), + _ => at(1).wrapping_mul(4).wrapping_sub(at(2).wrapping_mul(6)).wrapping_add(at(3).wrapping_mul(4)).wrapping_sub(at(4)), + }; + s[i] = s[i].wrapping_add(p); + } + } + 32..=63 => { + let order = (kind - 31) as usize; + warmup(r, &mut s, order, bps)?; + let precision = r.bits(4)? as u32 + 1; + if precision == 16 { + return Err(DecodeError::Invalid("forbidden coefficient precision")); + } + let shift = r.signed(5)?; + if shift < 0 { + return Err(DecodeError::Invalid("negative prediction shift")); + } + let mut coefs = [0i64; 32]; + for c in coefs.iter_mut().take(order) { + *c = r.signed(precision)?; + } + residual(r, &mut s, order)?; + for i in order..n { + let mut sum = 0i64; + for (k, &c) in coefs.iter().take(order).enumerate() { + sum = sum.wrapping_add(c.wrapping_mul(s[i - 1 - k])); + } + s[i] = s[i].wrapping_add(sum >> shift); + } + } + _ => return Err(DecodeError::Invalid("reserved subframe type")), + } + if wasted > 0 { + for v in s.iter_mut() { + *v = v.wrapping_shl(wasted); + } + } + Ok(s) +} + +fn warmup(r: &mut Bits, s: &mut [i64], order: usize, bps: u32) -> Result<()> { + if order > s.len() { + return Err(DecodeError::Invalid("predictor order above the block size")); + } + for v in s.iter_mut().take(order) { + *v = r.signed(bps)?; + } + Ok(()) +} + +/// The coded residual (RFC 9639 section 9.2.7), into `s[order..]`. +fn residual(r: &mut Bits, s: &mut [i64], order: usize) -> Result<()> { + let method = r.bits(2)?; + let (param_bits, escape) = match method { + 0 => (4, 15), + 1 => (5, 31), + _ => return Err(DecodeError::Invalid("reserved residual coding method")), + }; + let part_order = r.bits(4)? as u32; + let n = s.len(); + let parts = 1usize << part_order; + if !n.is_multiple_of(parts) { + return Err(DecodeError::Invalid("partition order does not divide the block size")); + } + let per = n >> part_order; + if per < order { + return Err(DecodeError::Invalid("partition shorter than the predictor order")); + } + let mut i = order; + for p in 0..parts { + let count = if p == 0 { per - order } else { per }; + let k = r.bits(param_bits)? as u32; + if k == escape { + let width = r.bits(5)? as u32; + for v in s[i..i + count].iter_mut() { + *v = r.signed(width)?; + } + } else { + for v in s[i..i + count].iter_mut() { + let q = r.unary()?; + if q > (1 << 32) { + return Err(DecodeError::Invalid("Rice quotient too large")); + } + let low = r.bits(k)?; + let folded = q << k | low; + *v = if folded & 1 == 0 { (folded >> 1) as i64 } else { -((folded >> 1) as i64) - 1 }; + } + } + i += count; + } + Ok(()) +} + +// ---- files ---- + +/// A decoded file. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Decoded { + /// The STREAMINFO block. + pub info: StreamInfo, + /// One `Vec` of samples per channel. + pub channels: Vec>, +} + +/// Most sample values (samples x channels) [`decode`] will produce. +pub const DEFAULT_MAX_VALUES: u64 = 1 << 28; + +/// Decode a whole `.flac` file (an ID3v2 tag in front is skipped). +pub fn decode(bytes: &[u8]) -> Result { + decode_with_limit(bytes, DEFAULT_MAX_VALUES) +} + +/// [`decode`] with a limit on the sample values (samples x channels) produced. +pub fn decode_with_limit(bytes: &[u8], max_values: u64) -> Result { + let mut pos = 0usize; + if bytes.starts_with(b"ID3") { + let size = bytes.get(6..10).ok_or(DecodeError::Truncated)?; + if size.iter().any(|&b| b & 0x80 != 0) { + return Err(DecodeError::Invalid("bad ID3v2 size")); + } + pos = 10 + size.iter().fold(0usize, |a, &b| a << 7 | usize::from(b)); + } + if bytes.get(pos..pos + 4) != Some(b"fLaC") { + return Err(DecodeError::Invalid("missing fLaC marker")); + } + pos += 4; + let mut info: Option = None; + loop { + let head = bytes.get(pos..pos + 4).ok_or(DecodeError::Truncated)?; + let last = head[0] & 0x80 != 0; + let kind = head[0] & 0x7F; + let len = usize::from(head[1]) << 16 | usize::from(head[2]) << 8 | usize::from(head[3]); + let body = bytes.get(pos + 4..pos + 4 + len).ok_or(DecodeError::Truncated)?; + match (kind, &info) { + (0, None) => info = Some(StreamInfo::parse(body)?), + (0, Some(_)) => return Err(DecodeError::Invalid("a second STREAMINFO block")), + (_, None) => return Err(DecodeError::Invalid("STREAMINFO is not the first block")), + (127, _) => return Err(DecodeError::Invalid("forbidden metadata block type")), + _ => {} + } + pos += 4 + len; + if last { + break; + } + } + let info = info.ok_or(DecodeError::Invalid("no STREAMINFO"))?; + let dec = Decoder::new(info); + let mut channels: Vec> = vec![Vec::new(); usize::from(info.channels)]; + let mut total = 0u64; + while pos + 2 <= bytes.len() && bytes[pos] == 0xFF && bytes[pos + 1] & 0xFE == 0xF8 { + let frame = dec.decode_frame(&bytes[pos..])?; + if frame.channels.len() != channels.len() { + return Err(DecodeError::Invalid("the channel count changes inside the stream")); + } + total += frame.block_size as u64; + if total.saturating_mul(channels.len() as u64) > max_values { + return Err(DecodeError::TooLarge); + } + for (dst, src) in channels.iter_mut().zip(frame.channels) { + dst.extend_from_slice(&src); + } + pos += frame.size; + } + if info.total_samples != 0 && total != info.total_samples { + return Err(DecodeError::Truncated); + } + Ok(Decoded { info, channels }) +} diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 33dcdee3b..f14530b26 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -27,7 +27,7 @@ //! - Codec modules for packet-level use, each with its own features: [`aac`] (`aac-decode`, //! `aac-encode`), [`alac`] (`alac-decode`, `alac-encode`), [`opus`] (`opus-decode`, and //! [`opus::encoder`] with `opus-encode`), [`ac3`] (`ac3-decode`), [`mpa`] (`mpa-decode`), [`mp3`] -//! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-encode`: the packet encoder). +//! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-decode`: the frame and file decoder; `flac-encode`: the packet encoder). //! //! The shared types below build with no features. @@ -88,10 +88,15 @@ pub use write::{OGG_BITRATES, encode_ogg}; /// assert!(file.len() < 48_000 * 2 * 2 / 2); // well under half of 16-bit PCM /// # Ok::<(), craft_audio::flac::Error>(()) /// ``` -#[cfg(feature = "flac-encode")] +#[cfg(any(feature = "flac-encode", feature = "flac-decode"))] pub mod flac { + #[cfg(feature = "flac-decode")] + pub use crate::flac_decode::{DEFAULT_MAX_VALUES, DecodeError, Decoded, Decoder, Frame, StreamInfo, decode, decode_with_limit}; + #[cfg(feature = "flac-encode")] pub use crate::write::flac::encoder::{Encoder, EncoderConfig, Error, STREAMINFO_OFFSET}; } +#[cfg(feature = "flac-decode")] +mod flac_decode; pub use buffer::AudioBuffer; /// The craft-media this crate is built with, for its containers: using it rather than a separate diff --git a/crates/audio/tests/flac_decode.rs b/crates/audio/tests/flac_decode.rs new file mode 100644 index 000000000..03d6d678e --- /dev/null +++ b/crates/audio/tests/flac_decode.rs @@ -0,0 +1,179 @@ +//! The native FLAC decoder: round trips through this crate's encoder over bit depths, channel +//! counts, block sizes and effort levels; hostile input; and ffmpeg as the reference (oracle; +//! skipped when ffmpeg is absent, a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`) for files +//! ffmpeg's encoder writes at every compression level. + +use craft_audio::flac::{DecodeError, Decoder, Encoder, EncoderConfig, STREAMINFO_OFFSET, StreamInfo, decode}; +use std::process::Command; + +fn signal(channels: usize, frames: usize, bits: u32, seed: u32) -> Vec> { + let max = if bits == 32 { i32::MAX as f64 } else { ((1i64 << (bits - 1)) - 1) as f64 }; + let mut s = seed; + (0..channels) + .map(|c| { + (0..frames) + .map(|i| { + s ^= s << 13; + s ^= s >> 17; + s ^= s << 5; + let t = i as f64; + let v = match (i / 3000) % 4 { + 0 => (t * (0.01 + 0.007 * c as f64)).sin() * 0.6 + (t * 0.31).sin() * 0.1, + 1 => (f64::from(s) / f64::from(u32::MAX) - 0.5) * 1.8, + 2 => 0.0, + _ => { + if (i / 40) % 2 == 0 { + 0.99 + } else { + -0.99 + } + } + }; + (v * max).round() as i32 + }) + .collect() + }) + .collect() +} + +fn encode(channels: &[Vec], rate: u32, bits: u8, block: u16, level: u8) -> Vec { + let mut cfg = EncoderConfig::new(rate, channels.len() as u8, bits); + cfg.block_size = block; + cfg.level = level; + let mut enc = Encoder::new(cfg).expect("encoder"); + let mut file = enc.header(&[]); + let refs: Vec<&[i32]> = channels.iter().map(Vec::as_slice).collect(); + file.extend(enc.encode(&refs).expect("encode")); + file.extend(enc.finish()); + let at = STREAMINFO_OFFSET as usize; + file[at..at + 34].copy_from_slice(&enc.streaminfo()); + file +} + +#[test] +fn round_trips_through_the_encoder() { + for (channels, bits) in [(1usize, 8u8), (2, 8), (1, 12), (2, 16), (2, 20), (3, 24), (6, 24), (8, 16), (2, 32), (1, 32)] { + for (block, level) in [(4096u16, 5u8), (16, 0), (1000, 8), (65535, 3), (576, 1)] { + let frames = 9000 + usize::from(block % 97); + let src = signal(channels, frames, u32::from(bits), 0x1234_5679 + u32::from(bits)); + let file = encode(&src, 44_100, bits, block, level); + let got = decode(&file).unwrap_or_else(|e| panic!("{channels}ch {bits}-bit block {block} level {level}: {e}")); + assert_eq!((got.info.channels as usize, got.info.bits_per_sample, got.info.sample_rate), (channels, bits, 44_100)); + assert_eq!(got.channels, src, "{channels}ch {bits}-bit block {block} level {level}"); + } + } +} + +#[test] +fn frames_decode_one_at_a_time() { + let src = signal(2, 10_000, 16, 7); + let file = encode(&src, 48_000, 16, 4096, 5); + let info = StreamInfo::parse(&file[STREAMINFO_OFFSET as usize..]).expect("streaminfo"); + let dec = Decoder::new(info); + // The first frame follows the metadata blocks; find the first position a frame decodes at. + let at = (42..file.len()).find(|&p| dec.decode_frame(&file[p..]).is_ok()).expect("a frame"); + let first = dec.decode_frame(&file[at..]).expect("frame"); + assert_eq!((first.block_size, first.number, first.sample_rate, first.bits_per_sample), (4096, 0, 48_000, 16)); + assert_eq!(first.channels[0], src[0][..4096]); + // Without the STREAMINFO a frame that spells out its own rate and depth still decodes. + let _ = Decoder::without_streaminfo().decode_frame(&file[at..]); +} + +#[test] +fn hostile_input_is_an_error_not_a_panic() { + let src = signal(2, 6000, 16, 11); + let file = encode(&src, 44_100, 16, 1152, 5); + for n in 0..file.len().min(3000) { + let _ = decode(&file[..n]); + } + // A cut file is truncated, not silently shorter. + assert!(decode(&file[..file.len() - 5]).is_err()); + // Every bit flip in the first frames is caught by a CRC or another check, never a panic. + for i in 0..file.len().min(2500) { + for bit in 0..8 { + let mut c = file.clone(); + c[i] ^= 1 << bit; + let _ = decode(&c); + } + } + // A sample limit stops a stream that claims too much. + assert_eq!(craft_audio::flac::decode_with_limit(&file, 1000), Err(DecodeError::TooLarge)); + assert!(decode(b"nope").is_err()); + assert!(decode(b"fLaC").is_err()); +} + +// ---- ffmpeg ---- + +fn ffmpeg_run(ff: &std::path::Path, args: &[&str]) -> Vec { + let out = Command::new(ff).args(["-v", "error", "-nostdin", "-y"]).args(args).output().expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg {args:?}: {}", String::from_utf8_lossy(&out.stderr)); + out.stdout +} + +#[test] +fn ffmpeg_files_decode_to_ffmpegs_samples() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("flac_decode"); + let tones = "aevalsrc=exprs=0.4*sin(2*PI*441*t)+0.2*sin(2*PI*3100*t)|0.3*sin(2*PI*660*t)*sin(2*PI*3*t):s=44100:d=1.3"; + let noise = "anoisesrc=d=1.3:c=white:r=44100:a=0.5:s=3"; + for (src, name) in [(tones, "tones"), (noise, "noise")] { + for channels in [1usize, 2, 6] { + for (fmt, bytes, bits) in [("s16", 2usize, 16u32), ("s32", 4, 24)] { + for level in [0, 3, 5, 8, 12] { + let file = dir.join(format!("ffmpeg_{name}_{channels}ch_{bits}_l{level}.flac")); + let f = file.to_str().expect("path"); + let (ch, lv) = (channels.to_string(), level.to_string()); + ffmpeg_run(&ff, &["-f", "lavfi", "-i", src, "-ac", &ch, "-sample_fmt", fmt, "-compression_level", &lv, "-c:a", "flac", f]); + let theirs = ffmpeg_run(&ff, &["-i", f, "-f", if bits == 16 { "s16le" } else { "s32le" }, "-"]); + let got = + decode(&std::fs::read(&file).expect("read")).unwrap_or_else(|e| panic!("{name} {channels}ch {bits}-bit level {level}: {e}")); + assert_eq!(got.info.channels as usize, channels); + let frames = got.channels[0].len(); + assert_eq!(theirs.len(), frames * channels * bytes, "{name} {channels}ch {bits} l{level}: length"); + let mut ok = true; + for i in 0..frames { + for c in 0..channels { + let at = (i * channels + c) * bytes; + let want = if bytes == 2 { + i32::from(i16::from_le_bytes([theirs[at], theirs[at + 1]])) + } else { + i32::from_le_bytes([theirs[at], theirs[at + 1], theirs[at + 2], theirs[at + 3]]) + }; + // ffmpeg returns 24-bit audio left-aligned in 32 bits. + let mine = if bits == 24 { got.channels[c][i] << 8 } else { got.channels[c][i] }; + if mine != want { + ok = false; + } + } + } + assert!(ok, "{name} {channels}ch {bits}-bit level {level}: samples differ from ffmpeg's decode"); + } + } + } + } +} + +#[test] +fn ffmpeg_decodes_our_files_to_our_samples() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("flac_decode"); + for (channels, bits) in [(1usize, 16u8), (2, 16), (2, 24), (6, 16)] { + let src = signal(channels, 20_000, u32::from(bits), 99); + let file = dir.join(format!("ours_{channels}ch_{bits}.flac")); + std::fs::write(&file, encode(&src, 44_100, bits, 4096, 5)).expect("write"); + let theirs = ffmpeg_run(&ff, &["-i", file.to_str().expect("path"), "-f", if bits == 16 { "s16le" } else { "s32le" }, "-"]); + let got = decode(&std::fs::read(&file).expect("read")).expect("decode"); + let bytes = if bits == 16 { 2 } else { 4 }; + for i in 0..20_000 { + for c in 0..channels { + let at = (i * channels + c) * bytes; + let want = if bytes == 2 { + i32::from(i16::from_le_bytes([theirs[at], theirs[at + 1]])) + } else { + i32::from_le_bytes([theirs[at], theirs[at + 1], theirs[at + 2], theirs[at + 3]]) >> 8 + }; + assert_eq!(got.channels[c][i], want, "{channels}ch {bits}-bit sample {i} of channel {c}"); + } + } + } +} From 2d5f2e4a73eb54326b3192120a7a4457ad79b07f Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 15:25:56 +0100 Subject: [PATCH 2/3] craft-audio: flac_decode tests without index loops (CI clippy) --- crates/audio/tests/flac_decode.rs | 49 ++++++++++++++----------------- 1 file changed, 22 insertions(+), 27 deletions(-) diff --git a/crates/audio/tests/flac_decode.rs b/crates/audio/tests/flac_decode.rs index 03d6d678e..c35267b08 100644 --- a/crates/audio/tests/flac_decode.rs +++ b/crates/audio/tests/flac_decode.rs @@ -104,6 +104,21 @@ fn hostile_input_is_an_error_not_a_panic() { // ---- ffmpeg ---- +/// Little-endian 16- or 32-bit samples of raw PCM. +fn pcm_values(raw: &[u8], bytes: usize) -> Vec { + if bytes == 2 { + raw.as_chunks::<2>().0.iter().map(|b| i32::from(i16::from_le_bytes(*b))).collect() + } else { + raw.as_chunks::<4>().0.iter().map(|b| i32::from_le_bytes(*b)).collect() + } +} + +/// Planar channels as interleaved samples. +fn interleave(channels: &[Vec]) -> Vec { + let frames = channels.first().map_or(0, Vec::len); + (0..frames).flat_map(|i| channels.iter().map(move |c| c[i])).collect() +} + fn ffmpeg_run(ff: &std::path::Path, args: &[&str]) -> Vec { let out = Command::new(ff).args(["-v", "error", "-nostdin", "-y"]).args(args).output().expect("run ffmpeg"); assert!(out.status.success(), "ffmpeg {args:?}: {}", String::from_utf8_lossy(&out.stderr)); @@ -130,22 +145,10 @@ fn ffmpeg_files_decode_to_ffmpegs_samples() { assert_eq!(got.info.channels as usize, channels); let frames = got.channels[0].len(); assert_eq!(theirs.len(), frames * channels * bytes, "{name} {channels}ch {bits} l{level}: length"); - let mut ok = true; - for i in 0..frames { - for c in 0..channels { - let at = (i * channels + c) * bytes; - let want = if bytes == 2 { - i32::from(i16::from_le_bytes([theirs[at], theirs[at + 1]])) - } else { - i32::from_le_bytes([theirs[at], theirs[at + 1], theirs[at + 2], theirs[at + 3]]) - }; - // ffmpeg returns 24-bit audio left-aligned in 32 bits. - let mine = if bits == 24 { got.channels[c][i] << 8 } else { got.channels[c][i] }; - if mine != want { - ok = false; - } - } - } + // ffmpeg returns 24-bit audio left-aligned in 32 bits. + let shift = if bits == 24 { 8 } else { 0 }; + let mine: Vec = interleave(&got.channels).into_iter().map(|v| v << shift).collect(); + let ok = mine == pcm_values(&theirs, bytes); assert!(ok, "{name} {channels}ch {bits}-bit level {level}: samples differ from ffmpeg's decode"); } } @@ -164,16 +167,8 @@ fn ffmpeg_decodes_our_files_to_our_samples() { let theirs = ffmpeg_run(&ff, &["-i", file.to_str().expect("path"), "-f", if bits == 16 { "s16le" } else { "s32le" }, "-"]); let got = decode(&std::fs::read(&file).expect("read")).expect("decode"); let bytes = if bits == 16 { 2 } else { 4 }; - for i in 0..20_000 { - for c in 0..channels { - let at = (i * channels + c) * bytes; - let want = if bytes == 2 { - i32::from(i16::from_le_bytes([theirs[at], theirs[at + 1]])) - } else { - i32::from_le_bytes([theirs[at], theirs[at + 1], theirs[at + 2], theirs[at + 3]]) >> 8 - }; - assert_eq!(got.channels[c][i], want, "{channels}ch {bits}-bit sample {i} of channel {c}"); - } - } + let shift = if bytes == 4 { 8 } else { 0 }; + let want: Vec = pcm_values(&theirs, bytes).into_iter().map(|v| v >> shift).collect(); + assert!(interleave(&got.channels) == want, "{channels}ch {bits}-bit: samples differ from ffmpeg's decode"); } } From ad9850f18fadac54048f680d1da7f50f379cd124 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 11:05:37 -0500 Subject: [PATCH 3/3] fix(audio): validate FLAC stream precision and complete consumption --- crates/audio/src/flac_decode.rs | 49 +++++++++++++++++++++++++++++-- crates/audio/tests/flac_decode.rs | 37 +++++++++++++++++++++++ 2 files changed, 84 insertions(+), 2 deletions(-) diff --git a/crates/audio/src/flac_decode.rs b/crates/audio/src/flac_decode.rs index dfb6f5fc1..bb56e65c5 100644 --- a/crates/audio/src/flac_decode.rs +++ b/crates/audio/src/flac_decode.rs @@ -225,6 +225,11 @@ impl Decoder { /// Decode the frame at the start of `data`. pub fn decode_frame(&self, data: &[u8]) -> Result { + // StreamInfo has public fields: container callers can construct it without + // parse(), so validate before it can control shifts and sample reads. + if self.info.is_some_and(|i| !(4..=32).contains(&i.bits_per_sample) || !(1..=8).contains(&i.channels) || i.sample_rate == 0) { + return Err(DecodeError::Invalid("invalid decoder STREAMINFO")); + } let mut r = Bits::new(data); if r.bits(15)? != 0x7FFC { return Err(DecodeError::Invalid("missing frame sync code")); @@ -315,8 +320,7 @@ impl Decoder { } let mut chans = Vec::with_capacity(channels); for c in out { - let v: Result> = - c.into_iter().map(|s| i32::try_from(s).map_err(|_| DecodeError::Invalid("sample outside the bit depth"))).collect(); + let v: Result> = c.into_iter().map(|s| checked_sample(s, bits)).collect(); chans.push(v?); } Ok(Frame { sample_rate, bits_per_sample: bits as u8, variable_block_size: variable, number, block_size, channels: chans, size }) @@ -542,6 +546,11 @@ pub fn decode_with_limit(bytes: &[u8], max_values: u64) -> Result { if frame.channels.len() != channels.len() { return Err(DecodeError::Invalid("the channel count changes inside the stream")); } + // One file has one sample rate and depth. Otherwise callers would play + // samples under incompatible STREAMINFO metadata. + if frame.sample_rate != info.sample_rate || frame.bits_per_sample != info.bits_per_sample { + return Err(DecodeError::Invalid("frame format differs from STREAMINFO")); + } total += frame.block_size as u64; if total.saturating_mul(channels.len() as u64) > max_values { return Err(DecodeError::TooLarge); @@ -551,8 +560,44 @@ pub fn decode_with_limit(bytes: &[u8], max_values: u64) -> Result { } pos += frame.size; } + // Unknown total_samples must not turn a corrupt/truncated next frame into + // a successfully decoded shorter recording. + if pos != bytes.len() { + return Err(DecodeError::Invalid("trailing data or missing frame sync")); + } if info.total_samples != 0 && total != info.total_samples { return Err(DecodeError::Truncated); } Ok(Decoded { info, channels }) } + +// Validate the advertised precision, not just the storage type. Malformed +// predictors may produce an i32 that is still invalid for 4–24-bit audio. +fn checked_sample(sample: i64, bits: u32) -> Result { + if !(4..=32).contains(&bits) { + return Err(DecodeError::Invalid("invalid sample bit depth")); + } + let bound = 1i64 << (bits - 1); + if !(-bound..bound).contains(&sample) { + return Err(DecodeError::Invalid("sample outside the bit depth")); + } + i32::try_from(sample).map_err(|_| DecodeError::Invalid("sample outside the bit depth")) +} + +#[cfg(test)] +mod sample_bounds_tests { + use super::checked_sample; + + #[test] + fn samples_must_fit_declared_precision() { + for bits in 4..=32 { + let bound = 1i64 << (bits - 1); + assert_eq!(checked_sample(-bound, bits).map(i64::from), Ok(-bound)); + assert_eq!(checked_sample(bound - 1, bits).map(i64::from), Ok(bound - 1)); + assert!(checked_sample(-bound - 1, bits).is_err()); + assert!(checked_sample(bound, bits).is_err()); + } + assert!(checked_sample(0, 0).is_err()); + assert!(checked_sample(0, 255).is_err()); + } +} diff --git a/crates/audio/tests/flac_decode.rs b/crates/audio/tests/flac_decode.rs index c35267b08..a1895789b 100644 --- a/crates/audio/tests/flac_decode.rs +++ b/crates/audio/tests/flac_decode.rs @@ -172,3 +172,40 @@ fn ffmpeg_decodes_our_files_to_our_samples() { assert!(interleave(&got.channels) == want, "{channels}ch {bits}-bit: samples differ from ffmpeg's decode"); } } + +#[test] +fn rejects_unknown_length_corruption_and_streaminfo_format_mismatch() { + let src = signal(1, 100, 16, 7); + let original = encode(&src, 44_100, 16, 4096, 5); + let at = STREAMINFO_OFFSET as usize; + // STREAMINFO is not CRC-covered. Clear only the 36-bit total sample count. + let mut unknown = original.clone(); + unknown[at + 13] &= 0xf0; + unknown[at + 14..at + 18].fill(0); + assert_eq!(decode(&unknown).unwrap().channels, src); + for tail in [vec![0xff], vec![0x00, 0x00]] { + let mut broken = unknown.clone(); + broken.extend(tail); + assert!(decode(&broken).is_err()); + } + // The encoder spells these in frame headers, independent of STREAMINFO. + let mut wrong_rate = original.clone(); + let mut packed = u64::from_be_bytes(wrong_rate[at + 10..at + 18].try_into().unwrap()); + packed = (packed & ((1u64 << 44) - 1)) | (48_000u64 << 44); + wrong_rate[at + 10..at + 18].copy_from_slice(&packed.to_be_bytes()); + assert!(decode(&wrong_rate).is_err()); + let mut wrong_depth = original; + wrong_depth[at + 12] = (wrong_depth[at + 12] & !1) | 1; + wrong_depth[at + 13] = (wrong_depth[at + 13] & 0x0f) | 0x70; + assert!(decode(&wrong_depth).is_err()); +} + +#[test] +fn caller_constructed_streaminfo_is_validated_before_decoding() { + let file = encode(&signal(1, 100, 16, 9), 44_100, 16, 4096, 5); + let info = StreamInfo::parse(&file[STREAMINFO_OFFSET as usize..]).unwrap(); + for bits in [0, 1, 3, 33, 64, 255] { + let invalid = StreamInfo { bits_per_sample: bits, ..info }; + assert!(matches!(Decoder::new(invalid).decode_frame(&[]), Err(DecodeError::Invalid(_)))); + } +}