A FLAC encoder and decoder in pure Rust whose encoder output is byte-identical to libFLAC 1.5.0 at the same settings.
Most FLAC encoders produce valid FLAC; this one produces libFLAC's FLAC, down to
the last byte. That matters when bytes must be reproduced rather than just decoded:
recreating the audio in MAME CHD files, verifying archives against reference
encodes, or replacing libFLAC in a pipeline without changing its output. It has no
dependencies, no build script and no unsafe.
- Encoder
- compression levels 0–8 with libFLAC's presets
- every bit depth from 4 to 32, 1–8 channels (with mid/side stereo decorrelation), sample rates up to 1 048 575 Hz, block sizes 16–65535
- input checked as libFLAC checks it: invalid settings, samples outside the bit
depth, and metadata libFLAC refuses or the format cannot hold are rejected
(
try_new/try_encode*return anEncodeError, the other methods panic) instead of producing a corrupt file - output as a complete
.flacfile, as raw frames (what MAME/CHD stores), or as Ogg FLAC - every metadata block: STREAMINFO (with the audio MD5), VORBIS_COMMENT with tags, PADDING, APPLICATION, SEEKTABLE (filled in during encoding), CUESHEET, PICTURE
- Decoder
- streaming from any
std::io::Read, block by block with bounded memory, or into memory with an optional sample limit - native and Ogg FLAC, including chained Ogg streams; fixed and variable block sizes
- MD5 verification, SEEKTABLE-based seeking, tags
- missing frames are reported and filled with silence as libFLAC 1.5.0 does
- lossless: it decodes everything the encoder produces and libFLAC's output
- streaming from any
- Pure Rust,
#![forbid(unsafe_code)], zero dependencies, Rust 1.85+
Releases are published on GitHub, not on crates.io:
[dependencies]
libflac-rs = { git = "https://github.com/trackIT-Systems/libflac-rs", tag = "v0.150.2" }What changed between versions is in CHANGELOG.md.
use libflac_rs::{Encoder, EncoderConfig};
// 2 channels, 16 bits, 44.1 kHz at libFLAC's defaults (level 8, MD5 on).
let enc = Encoder::new(EncoderConfig::new(2, 16, 44_100));
let pcm: Vec<i32> = vec![0; 4096 * 2]; // interleaved: L R L R …
let flac: Vec<u8> = enc.encode(&pcm); // a complete .flac file
let frames: Vec<u8> = enc.encode_frames(&pcm); // raw frames, as MAME/CHD stores them
let ogg: Vec<u8> = enc.encode_ogg(&pcm, 0); // Ogg FLAC, logical stream serial 0
let decoded = libflac_rs::decode(&flac).unwrap();
assert_eq!(decoded.interleaved, pcm);
assert!(decoded.md5_ok);Settings are adjusted with with_compression_level, with_block_size and
with_md5. For MAME's CHD audio codec (level 8, 2 channels, 16 bits, 44.1 kHz, MD5
off), use EncoderConfig::chd(block_size) with encode_frames.
Tags go into a VORBIS_COMMENT block; vorbis_comment_entry checks names and values
the way libFLAC does:
use libflac_rs::{Encoder, EncoderConfig, LIBFLAC_VENDOR_STRING, MetadataBlock, vorbis_comment_entry};
let enc = Encoder::new(EncoderConfig::new(1, 16, 384_000).with_compression_level(5));
let entries = [vorbis_comment_entry("TITLE", "Night 1").unwrap()];
let comments: Vec<&str> = entries.iter().map(String::as_str).collect();
let flac = enc.encode_with_metadata(
&[0i32; 4096],
&[MetadataBlock::VorbisCommentEntries { vendor: LIBFLAC_VENDOR_STRING, comments: &comments }],
);
let decoded = libflac_rs::decode(&flac).unwrap();
assert_eq!(decoded.vorbis_comment.unwrap().comments, ["TITLE=Night 1"]);For long streams, files read from disk or the network, or untrusted input, decode block by block instead of into memory. A few bytes of FLAC can legitimately decode to gigabytes (digital silence compresses extremely well):
use libflac_rs::{DecodeError, StreamDecoder};
use std::{fs::File, io::BufReader};
fn play(path: &str) -> Result<(), DecodeError> {
let mut decoder = StreamDecoder::new(BufReader::new(File::open(path)?))?;
let header = decoder.header();
println!("{} Hz, {} channels", header.sample_rate, header.channels);
for block in &mut decoder {
let block = block?; // one frame (or gap silence), interleaved
// ... process block.interleaved ...
}
assert_eq!(decoder.md5_ok(), Some(true));
Ok(())
}decode_with(data, &DecodeOptions { max_samples: Some(n) }) decodes into memory
but fails with DecodeError::LimitExceeded instead of growing past n samples
per channel. All decoders stop at the sample count STREAMINFO declares, when it
does.
The full API is documented in the crate docs (cargo doc --open).
- libFLAC version. 0.150.x matches libFLAC 1.5.0; 0.143.x matched 1.4.3. The two
differ only where 1.5.0 changed the encoder: loose mid-side at levels 1 and 4,
constant 32-bit signals, seektable targets past the end, and the vendor string
(details in
CHANGELOG.md). - MAME / CHD. The CHD configuration is unaffected by those changes, so CHD audio stays byte-identical to the libFLAC 1.4.3 that MAME ships.
- Platforms. Like libFLAC, the encoder takes
cosandlogfrom the platform's math library, whose last-bit rounding differs between glibc, musl and macOS. The output matches libFLAC built on the same platform and can differ between platforms in rare cases. Measurements are inORACLE.md. - Decoder. Byte-identical output is an encoder property; the decoder is
checked for producing the same samples as libFLAC 1.5.0's decoder, including
chained Ogg links, the silence it inserts for missing frames, its arithmetic on
damaged frames, its handling of malformed metadata and Ogg pages, and ending a
truncated stream after the last complete frame (
truncated). Unlike libFLAC, it does not resynchronize after a corrupt frame (bad CRC, or samples beyond the bit depth): decoding then fails.
The separate oracle/ crate compiles the C libFLAC 1.5.0 and libogg 1.3.5 from the
Xiph release tags and compares complete encoder outputs byte for byte, through the
public API. It covers all levels, bit depths, channel counts, block sizes, sample
rates and metadata blocks, and compares decoded samples with libFLAC's decoder. It
runs in CI on glibc and musl. The library itself never builds C.
cargo test # the library: unit and round-trip tests
oracle/fetch-sources.sh && (cd oracle && cargo test) # against the C referenceThe fuzz/ crate (cargo-fuzz) checks the decoder against arbitrary input, the
encoder for lossless round trips, and both against libFLAC on generated signals
and mutated streams; see fuzz/README.md.
ORACLE.md describes the oracle; ROADMAP.md records how
the port was built.
BSD-3-Clause, retaining the Xiph.Org copyrights of the ported libFLAC and libogg
code. See LICENSE.