Crate flacx

Expand description

Convert supported PCM containers to FLAC, decode FLAC back to PCM containers, and recompress existing FLAC streams.

flacx exposes two complementary ways to work:

the reset API built around staged readers, sources, configs, and writer-owning sessions
the convenience builtin helpers for one-shot file and byte workflows

Most applications should start with the reset API when they want control over metadata, output configuration, or progress reporting, and use builtin when a single function call is enough.

Advanced callers can also skip the reader façade and directly construct the concrete stream types that feed EncodeSource, DecodeSource, and FlacRecompressSource.

§Getting started

Encode a supported PCM container to FLAC:

use flacx::{EncoderConfig, PcmReader};
use std::{
    fs::File,
    io::{BufReader, BufWriter},
};

let input = BufReader::new(File::open("input.wav")?);
let source = PcmReader::new(input)?.into_source();

let output = BufWriter::new(File::create("output.flac")?);
let mut encoder = EncoderConfig::default().into_encoder(output);
let summary = encoder.encode_source(source)?;

println!("encoded {} samples", summary.total_samples);

Or construct a concrete stream directly when you already know the low-level format details:

use flacx::{EncodeSource, EncoderConfig, Metadata, WavPcmStream};
use std::{
    fs::File,
    io::{BufReader, BufWriter, Seek, SeekFrom},
};

let mut payload = BufReader::new(File::open("input.wav")?);
payload.seek(SeekFrom::Start(44))?; // canonical PCM payload offset

let stream = WavPcmStream::builder(payload)
    .sample_rate(44_100)
    .channels(2)
    .valid_bits_per_sample(16)
    .total_samples(1_024)
    .build()?;
let source = EncodeSource::new(Metadata::new(), stream);

let output = BufWriter::new(File::create("output.flac")?);
let mut encoder = EncoderConfig::default().into_encoder(output);
encoder.encode_source(source)?;

Decode a FLAC stream to a PCM container:

use flacx::{DecodeConfig, read_flac_reader};
use std::{
    fs::File,
    io::{BufReader, BufWriter},
};

let input = BufReader::new(File::open("input.flac")?);
let source = read_flac_reader(input)?.into_decode_source();

let output = BufWriter::new(File::create("output.wav")?);
let mut decoder = DecodeConfig::default().into_decoder(output);
decoder.decode_source(source)?;

Recompress an existing FLAC stream:

use flacx::{RecompressConfig, read_flac_reader};
use std::{
    fs::File,
    io::{BufReader, BufWriter},
};

let input = BufReader::new(File::open("input.flac")?);
let source = read_flac_reader(input)?.into_recompress_source();

let output = BufWriter::new(File::create("recompressed.flac")?);
let mut recompressor = RecompressConfig::default().into_recompressor(output);
recompressor.recompress(source)?;

If you prefer a one-shot path, start with builtin::encode_file, builtin::decode_file, or builtin::recompress_file.

§Choosing an API layer

Surface	Use it when	Main entry points
Reset API	You want direct control over staged input, direct stream construction, metadata, configs, output containers, or progress callbacks.	`core`, `EncoderConfig`, `DecodeConfig`, `RecompressConfig`, `PcmReader`, `read_flac_reader`, `WavPcmStream`, `FlacPcmStream`, `Encoder`, `Decoder`, `Recompressor`
Convenience helpers	You want file-path or byte-slice conversions with minimal setup.	`builtin`
Supporting types	You need presets, metadata editing, raw PCM descriptors, or preflight inspection helpers.	`level`, `Metadata`, `RawPcmDescriptor`, `inspect_pcm_total_samples`, `inspect_flac_total_samples`

§Main building blocks

The reset API is organized around a few reusable concepts:

Reset entry points parse an input format and hand it off into an owned source, such as PcmReader for PCM-container inputs and read_flac_reader for FLAC inputs.
Concrete streams can be reader-produced or directly constructed when you already know the payload layout, such as WavPcmStream, AiffPcmStream, CafPcmStream, RawPcmStream, and FlacPcmStream.
Sources carry parsed metadata and a single-pass PCM stream into the next stage, such as EncodeSource, DecodeSource, and FlacRecompressSource.
Configs and builders choose output policy and codec tuning, such as EncoderConfig, DecodeConfig, and RecompressConfig.
Sessions own the output writer and perform the actual encode, decode, or recompress operation through Encoder, Decoder, and Recompressor.

The core module re-exports the reset API in one place if you prefer a narrower import surface.

§Feature flags

flacx uses coarse feature flags for container families and optional progress callbacks:

wav enables WAV, RF64, and Wave64 support
aiff enables AIFF and AIFC support
caf enables CAF support
progress enables callback-based progress reporting via [ProgressSnapshot], [EncodeProgress], [DecodeProgress], and recompress progress helpers with explicit input-read and output-write counters

§Navigating the docs

Start with core for the reset API.
Use builtin for the shortest file/byte workflows.
Visit level for compression presets and PcmContainer for decode output-family selection.
Visit Metadata and RawPcmDescriptor when you need to control preservation or raw PCM ingest.

The repository README.md gives a short workspace overview, while this rustdoc is the authoritative library reference.

Modules§

builtin: Built-in one-shot orchestration helpers layered on top of the reset API.
core: Reset API surface for callers that want the typed/configured pipeline without the one-shot convenience wrappers.
level: Compression level presets and tuning profiles used by the encoder. Compression level presets and tuning profiles used by flacx.

Structs§

AiffPcmDescriptor: Explicit descriptor for direct AIFF/AIFC PCM stream construction.
AiffPcmStream: Single-pass PCM stream produced by AiffReader.
AiffReader: Reader façade for AIFF/AIFC encode inputs.
CafPcmStream: Single-pass PCM stream produced by CafReader.
CafReader: Reader façade for CAF encode inputs.
DecodeBuilder: Fluent builder for DecodeConfig.
DecodeConfig: User-facing decode configuration for FLAC-to-PCM-container conversion.
DecodeSource: Owned decode-side handoff that keeps metadata and the PCM stream together.
DecodeSummary: Summary of the PCM stream produced by a decode operation.
Decoder: Writer-owning FLAC-to-PCM-container decode session.
EncodeSource: Owned encode-side handoff that keeps metadata and the PCM stream together.
EncodeSummary: Summary of the FLAC stream produced by an encode operation.
Encoder: Writer-owning PCM-container-to-FLAC encode session.
EncoderBuilder: Fluent builder for EncoderConfig.
EncoderConfig: User-facing encoder configuration for PCM-container-to-FLAC conversion.
FlacPcmStream
FlacPcmStreamBuilder: Builder for directly constructing FlacPcmStream from a seekable FLAC frame source plus explicit STREAMINFO-driven structural inputs.
FlacReader: Reader façade for FLAC inputs.
FlacReaderOptions: Options for FlacReader parsing and validation.
FlacRecompressSource: Reader-to-session handoff for explicit FLAC recompression.
Metadata: Semantic metadata captured from container inputs or staged for output.
PcmSpec: Immutable description of a PCM stream.
PcmStream: Fully materialized interleaved PCM samples plus their PcmSpec.
PcmStreamSpec: Immutable description of a PCM stream.
RawPcmDescriptor: Explicit descriptor for raw signed-integer PCM inputs.
RawPcmReader: Reader façade for explicit raw signed-integer PCM input.
RawPcmStream: Single-pass raw PCM stream produced by RawPcmReader.
RecompressBuilder: Fluent builder for RecompressConfig.
RecompressConfig: User-facing recompression configuration for FLAC-to-FLAC conversion.
RecompressSummary: Summary of the FLAC stream produced by a recompress operation.
Recompressor: Writer-owning FLAC-to-FLAC recompress session.
StreamInfo
WavPcmStream: Single-pass PCM stream produced by WavReader.
WavPcmStreamBuilder: Builder for direct WAV/RF64/Wave64 PCM stream construction.
WavReader: Reader façade for WAV/RF64/Wave64 encode inputs.
WavReaderOptions: Reader options for RIFF/WAVE-family encode-side parsing.

Enums§

Error: Error type used by encode, decode, inspect, and recompress operations.
PcmContainer: Output container family for decode and PCM writing operations.
PcmReader: Family-dispatched PCM reader for the explicit encode workflow.
RawPcmByteOrder: Byte order for explicit raw signed-integer PCM descriptors.
RecompressMode: Mode presets for recompress-side metadata handling and relaxable validation.

Traits§

DecodePcmStream: Single-pass FLAC decode stream consumed by crate::Decoder and recompress flows.
EncodePcmStream: Single-pass PCM sample source consumed by the encode session.

Functions§

inspect_flac_total_samples: Inspect a FLAC stream and return the total sample count recorded in its STREAMINFO metadata.
inspect_pcm_total_samples: Inspect a supported PCM-container stream and return its total sample count without decoding it. Inspect a supported PCM-container stream and return its total sample count.
inspect_raw_pcm_total_samples: Inspect raw signed-integer PCM and return its total sample count when an explicit descriptor is supplied.
read_flac_reader: Parse a FLAC stream into a reusable FlacReader.
read_flac_reader_with_options: Parse a FLAC stream into a reusable FlacReader with explicit validation options.
write_pcm_stream: Write a typed PcmStream out to a supported PCM-container family without invoking convenience-layer file routing or extension inference.

Type Aliases§

Result: Result alias used by the public flacx API.

Crate flacx

Crate flacx Copy item path

§Getting started

§Choosing an API layer

§Main building blocks

§Feature flags

§Navigating the docs

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate flacx