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
This commit is contained in:
el-j
2026-11-15 15:11:43 +01:00
parent fe6b443acf
commit cdf4a2fa6e
5 changed files with 751 additions and 2 deletions
+6
View File
@@ -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"]
+1
View File
@@ -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 |
+558
View File
@@ -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<T> = std::result::Result<T, DecodeError>;
/// 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<StreamInfo> {
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<Vec<i32>>,
/// 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<u32> {
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<u64> {
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<i64> {
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<u64> {
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<StreamInfo>,
}
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<Frame> {
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<i64>> = 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<Vec<i32>> =
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<u64> {
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<Vec<i64>> {
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<Vec<i32>>,
}
/// 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<Decoded> {
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<Decoded> {
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<StreamInfo> = 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<i32>> = 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 })
}
+7 -2
View File
@@ -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
+179
View File
@@ -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<Vec<i32>> {
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<i32>], rate: u32, bits: u8, block: u16, level: u8) -> Vec<u8> {
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<u8> {
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}");
}
}
}
}