Crate libflac_rs 

libflac-rs — a pure-Rust, bit-exact port of libFLAC 1.4.3: a complete FLAC encoder and decoder whose output is byte-identical to the C reference.

It exists for consumers that must recreate the exact bytes libFLAC/MAME produce (e.g. chd-rs reproducing MAME CHD audio), not merely emit valid FLAC. The output was verified byte-for-byte against the real libFLAC (and libogg, for Ogg) via a differential test harness; that harness is documented in ORACLE.md and kept out of the source tree so the crate is 100% pure Rust.

What’s supported

• Encoder, byte-identical to libFLAC: all compression levels 0–8, all bit depths (8/12/16/20/24/32), mono / stereo (with mid-side decorrelation) / multichannel, every metadata block (STREAMINFO, VORBIS_COMMENT, PADDING, APPLICATION, SEEKTABLE, PICTURE, CUESHEET), and the audio MD5.
• Decoder: lossless and MD5-verified, with decode_seek and variable-block-size support.
• Ogg FLAC (Encoder::encode_ogg / decode_ogg), byte-identical to libFLAC + libogg.
• Pure Rust, #![forbid(unsafe_code)], zero runtime dependencies.

Encoding

use libflac_rs::{Encoder, EncoderConfig};

// 2-channel, 16-bit, 44.1 kHz, compression level 8 (libFLAC's defaults).
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
assert_eq!(&flac[..4], b"fLaC");

For the raw frame stream MAME/CHD embeds, use EncoderConfig::chd with Encoder::encode_frames; for Ogg FLAC, Encoder::encode_ogg.

Decoding

let decoded = libflac_rs::decode(&flac).expect("valid FLAC");
assert_eq!(decoded.interleaved, pcm);
assert!(decoded.md5_ok);

See ROADMAP.md for the milestone history and ORACLE.md for how byte-exactness is re-verified against the C reference.

Structs

CueSheetIndex

One CUESHEET track index point (FLAC__StreamMetadata_CueSheet_Index).

CueSheetTrack

One CUESHEET track (FLAC__StreamMetadata_CueSheet_Track).

DecodedFrames

Decoded audio frames.

DecodedStream

A fully decoded FLAC stream (fLaC marker + metadata + frames).

Encoder

A one-shot FLAC encoder, byte-identical to libFLAC 1.4.3 at the same settings.

EncoderConfig

Audio format and compression settings for an Encoder.

SeekPoint

One SEEKTABLE seek point (FLAC__StreamMetadata_SeekPoint). In a template (before encoding) sample_number is the target sample to make seekable and the other two fields are 0; the encoder rewrites all three for the frame that holds each target (see Encoder).

SeekResult

The result of a decode_seek: PCM from first_sample to the end of the stream.

Enums

MetadataBlock

A metadata block the caller can place after STREAMINFO (which the encoder always writes first). libFLAC writes blocks in the order given (the OGG reorder is compiled out for native FLAC), so this list maps 1:1 to the output.

Constants

LIBFLAC_VENDOR_STRING

The vendor string libFLAC 1.4.3 writes into its auto VORBIS_COMMENT (FLAC__VENDOR_STRING = "reference libFLAC " PACKAGE_VERSION " 20230623" with no git tag/hash defined). Used to byte-match libFLAC’s default output.

Functions

decode

Decode a complete FLAC stream: the fLaC marker, the metadata blocks (only STREAMINFO is interpreted; the rest are skipped), then the audio frames. Verifies the audio MD5 against STREAMINFO when present. None on malformed input or any CRC mismatch.

decode_frames

Decode every audio frame in data (the raw frame stream produced by Encoder::encode_frames, i.e. no metadata) back to interleaved PCM. Returns None on any malformed/truncated input or CRC mismatch.

decode_ogg

Decode a complete Ogg FLAC stream: OggS pages → FLAC packets → PCM. Parses the BOS mapping packet (0x7F"FLAC" + version + header count + "fLaC" + STREAMINFO), concatenates the audio-frame packets, and decodes them, verifying the audio MD5 against STREAMINFO. None on malformed Ogg (a bad page CRC or missing mapping) or any frame CRC mismatch. (Ogg FLAC carries no seektable, so seek_points is empty.)

decode_seek

Decode a stream starting at target_sample, using the SEEKTABLE (if any) to jump near it before decoding forward. Returns the interleaved PCM from target_sample to the end of the stream. None on malformed input, a CRC mismatch, or target_sample >= total_samples (when the total is known). With no seektable it still works by decoding from the first frame.

spaced_seek_points

Build a SEEKTABLE template of num evenly-spaced placeholder points for a stream of total_samples (FLAC__metadata_object_seektable_template_append_spaced_points): point i targets sample total_samples * i / num, with zero offset/frame_samples, to be filled during encoding. Returns empty if num or total_samples is 0. (For a legal table — at most ~932k points so the block fits the 24-bit length field — the total_samples * i product cannot overflow u64.)