flacser

flacser is a Rust CLI tool that converts lossless FLAC, AIFF, and WAV files using ffmpeg.

It supports single-file conversion, directory batch conversion with parallel execution, and a read-only doctor command for readiness checks.

Install

# Homebrew
brew install chrizzlekicks/flacser/flacser

# Cargo
cargo install flacser

Requirements

• ffmpeg
• ffprobe
• Rust toolchain (for building from source)

Install the FFmpeg suite:

# Arch 
sudo pacman -S ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# macOS (Homebrew)
brew install ffmpeg

Windows:

• install FFmpeg
• ensure ffmpeg.exe and ffprobe.exe are available on PATH

Build

cargo build --release

Binary path:

target/release/flacser

Usage

flacser <COMMAND> [OPTIONS]

Commands

• convert [OPTIONS] <INPUT_PATH>: convert between FLAC, AIFF, and WAV
• doctor [OPTIONS] [INPUT_PATH]: check whether the system is ready to run conversions

<INPUT_PATH> for convert can be:

• a single .flac, .aiff, .aif, or .wav file
• a directory (batch mode)

Options

convert:

• --to <FORMAT>: target format (flac, aiff, or wav); required unless FLACSER_CONVERT_TO is set
• --output-dir <OUTPUT_DIR>, -o <OUTPUT_DIR>: write outputs into a specific directory
• --dry-run, -n: plan/execute flow without running ffmpeg or ffprobe
• --recursive, -r: recurse into subdirectories in directory mode
• --flatten, -f: write recursive directory outputs directly into the output directory and fail if flattened output names collide
• --jobs <JOBS>, -j <JOBS>: set the number of parallel conversion jobs

doctor:

• --to <FORMAT>: target format (flac, aiff, or wav) to validate conversion planning; falls back to FLACSER_CONVERT_TO
• --output-dir <OUTPUT_DIR>, -o <OUTPUT_DIR>: diagnose a specific output directory
• --jobs <JOBS>, -j <JOBS>: diagnose a specific parallel worker limit

doctor always discovers supported audio files recursively when validating a directory input. When --to is provided, files already in the target format are excluded from conversion planning.

Behavior

File mode

• Converts one supported .flac, .aiff, .aif, or .wav input file to the requested target format
• Source format is inferred from the file extension case-insensitively
• .aif is accepted as AIFF input, but --to aif is not supported
• Default output path is next to the input file
• If --output-dir is set, output is written there
• Supports all cross-format FLAC/AIFF/WAV conversions; same-format conversion is rejected

Directory mode

• Non-recursive by default (top-level only)
• Recurses into subdirectories when --recursive is set
• Finds .flac, .aiff, .aif, and .wav files case-insensitively
• Excludes files already in the target format
• Preserves relative structure from the input root
• Uses the target format's canonical extension; AIFF outputs use .aiff
• Non-flatten planning checks collisions on exact output paths
• With --recursive --flatten, writes all outputs directly into the output root and fails if flattened output names collide, including ASCII case-insensitive pairs such as Song.aiff and song.aiff
• --flatten has no effect without --recursive because non-recursive discovery only sees top-level files
• Skips outputs that already exist

Execution and exits

• Runs jobs in parallel using Rayon
• Prints per-job progress during execution as [completed/total] processed
• Default jobs: max(1, cpu_cores - 1)
• Summary reports actual workers used for the run
• Continues processing when individual jobs fail
• Exits 1 if any job fails and 130 when interrupted

Doctor command

• Prints a read-only report with ok, warn, and fail checks
• Verifies ffmpeg and ffprobe availability and version
• Checks detected CPU cores and default worker settings
• Optionally validates an input path, target format, output directory, and configured worker limit
• Requires --to or FLACSER_CONVERT_TO to validate output planning for an input path
• Validates directory inputs with recursive discovery (always scans subdirectories)
• Exits non-zero when any required check fails

Examples

Single file:

flacser convert ./music/track.flac --to aiff

Single file with output dir:

flacser convert ./music/track.flac --to wav --output-dir ./out

Directory dry run:

flacser convert ./music --to aiff --dry-run

Directory conversion with two parallel jobs:

flacser convert ./music --to flac --jobs 2

Environment fallback target:

FLACSER_CONVERT_TO=aiff flacser convert ./music

Flatten recursive directory output:

flacser convert ./music --recursive --flatten --output-dir ./out

System readiness check:

flacser doctor ./music --to aiff --output-dir ./out --jobs 2

Encoding and metadata

• FLAC output uses the flac encoder
• WAV and AIFF output select PCM codecs from the source bit depth and sample format reported by ffprobe
• WAV output keeps the first audio stream and drops cover art / non-audio / extra streams
• Metadata is best-effort and depends on ffmpeg/container support

Testing

Run all tests:

cargo test

Test suite includes:

• unit tests for discover/plan/convert/summary/config logic
• integration tests for CLI behavior and exit codes
• cross-platform integration tests with mocked ffmpeg / ffprobe and PATH portability helpers

CI runs the Rust test suite on Ubuntu, Windows, and macOS.

Interrupt handling is covered by tests; OS signal hookup remains platform-specific.

License

MIT