libflac_rs/lib.rs
1//! `libflac-rs` — a pure-Rust, **bit-exact** port of **libFLAC 1.4.3**: a complete
2//! FLAC **encoder and decoder** whose output is byte-identical to the C reference.
3//!
4//! It exists for consumers that must *recreate* the exact bytes libFLAC/MAME produce
5//! (e.g. `chd-rs` reproducing MAME CHD audio), not merely emit valid FLAC. The output
6//! was verified byte-for-byte against the real libFLAC (and libogg, for Ogg) via a
7//! differential test harness; that harness is documented in `ORACLE.md` and kept out
8//! of the source tree so the crate is 100% pure Rust.
9//!
10//! # What's supported
11//! - **Encoder**, byte-identical to libFLAC: all compression levels 0–8, all bit
12//! depths (8/12/16/20/24/32), mono / stereo (with mid-side decorrelation) /
13//! multichannel, every metadata block (STREAMINFO, VORBIS_COMMENT, PADDING,
14//! APPLICATION, SEEKTABLE, PICTURE, CUESHEET), and the audio MD5.
15//! - **Decoder**: lossless and MD5-verified, with [`decode_seek`] and
16//! variable-block-size support.
17//! - **Ogg FLAC** ([`Encoder::encode_ogg`] / [`decode_ogg`]), byte-identical to
18//! libFLAC + libogg.
19//! - Pure Rust, `#![forbid(unsafe_code)]`, **zero runtime dependencies**.
20//!
21//! # Encoding
22//! ```
23//! use libflac_rs::{Encoder, EncoderConfig};
24//!
25//! // 2-channel, 16-bit, 44.1 kHz, compression level 8 (libFLAC's defaults).
26//! let enc = Encoder::new(EncoderConfig::new(2, 16, 44_100));
27//! let pcm: Vec<i32> = vec![0; 4096 * 2]; // interleaved: L R L R …
28//! let flac: Vec<u8> = enc.encode(&pcm); // a complete .flac file
29//! assert_eq!(&flac[..4], b"fLaC");
30//! ```
31//! For the raw frame stream MAME/CHD embeds, use [`EncoderConfig::chd`] with
32//! [`Encoder::encode_frames`]; for Ogg FLAC, [`Encoder::encode_ogg`].
33//!
34//! # Decoding
35//! ```
36//! # use libflac_rs::{Encoder, EncoderConfig};
37//! # let enc = Encoder::new(EncoderConfig::new(2, 16, 44_100));
38//! # let pcm: Vec<i32> = vec![7; 4096 * 2];
39//! # let flac = enc.encode(&pcm);
40//! let decoded = libflac_rs::decode(&flac).expect("valid FLAC");
41//! assert_eq!(decoded.interleaved, pcm);
42//! assert!(decoded.md5_ok);
43//! ```
44//!
45//! See `ROADMAP.md` for the milestone history and `ORACLE.md` for how byte-exactness
46//! is re-verified against the C reference.
47
48#![forbid(unsafe_code)]
49
50mod bitmath;
51mod bitreader;
52mod bitwriter;
53mod crc;
54mod decoder;
55mod encoder;
56mod fixed;
57mod format;
58mod frame;
59mod lpc;
60mod md5;
61mod metadata;
62mod ogg;
63mod rice;
64mod subframe;
65mod window;
66
67pub use decoder::{
68 DecodedFrames, DecodedStream, SeekResult, decode, decode_frames, decode_ogg, decode_seek,
69};
70pub use encoder::{Encoder, EncoderConfig};
71pub use metadata::{
72 CueSheetIndex, CueSheetTrack, LIBFLAC_VENDOR_STRING, MetadataBlock, SeekPoint,
73 spaced_seek_points,
74};