Convert with a plan, not a prayer.

01 — Before you convert

Install flacser and its audio tools.

flacser calls ffmpeg to convert audio and ffprobe to inspect source audio when necessary. Both must be available on your PATH.

On Windows, install FFmpeg and make sure both ffmpeg.exe and ffprobe.exe are on PATH. Then confirm the setup without changing any files:

02 — One file

Convert a track beside its source.

Pass a supported file and a target format. flacser recognizes .flac, .aiff, .aif, and .wav case-insensitively. The source format comes from the extension; the target must be flac, aiff, or wav.

This creates ./music/track.aiff. Same-format conversions are rejected, and AIFF output always uses the canonical .aiff extension, even when the input uses .aif.

03 — A library

Convert a directory without losing its shape.

With a directory input, flacser finds supported files in its top level by default and converts every file that is not already in the target format. Add --recursive (or -r) to include subdirectories.

That command maps ./music/albums/one/song.flac to ./converted/albums/one/song.aiff. Without --output-dir, outputs are placed under the input directory itself, preserving the same relative path.

Use --jobs 2 (or -j 2) to limit parallel ffmpeg processes. The default is one fewer than the detected CPU cores, with at least one worker; flacser never starts more workers than planned jobs.

04 — Output layout

Pick a destination that fits the job.

Default

A single-file output sits beside its source. Directory outputs stay under the input root.

--output-dir DIR

Write under DIR. Missing output directories are created during conversion.

--flatten

With a recursive directory conversion, discard source subdirectories and write every output directly into the output root.

Flattening is useful for a small, uniquely named collection. It has no effect without --recursive. flacser stops before conversion if two inputs would map to the same flattened name, including ASCII case-only differences such as Song.flac and song.flac.

05 — Reference

Know the two commands.

flacser convert [OPTIONS] <INPUT_PATH>

--to FORMAT

Required target: flac, aiff, or wav. Set FLACSER_CONVERT_TO to supply it by environment instead.

-o, --output-dir DIR

Destination root for the converted file or files.

-n, --dry-run

Plan the conversion without running ffmpeg or ffprobe.

-r, --recursive

Discover supported files below a directory input.

-f, --flatten

Ignore nested paths for recursive directory outputs.

-j, --jobs N

Use a positive number of parallel conversion jobs.

flacser doctor [OPTIONS] [INPUT_PATH]

doctor accepts --to, --output-dir, and --jobs. It never converts, creates, or modifies files.

06 — Readiness checks

Ask doctor before a large batch.

Run doctor with no input to check FFmpeg, ffprobe, CPU detection, and default workers. Give it a path and target to also validate discovery and output planning. Directory diagnosis always scans recursively, so it sees the whole library.

The report marks checks as ok, warn, or fail. A worker count above available CPU cores is a warning; missing tools, unavailable inputs, invalid output paths, or failed output planning make the command exit non-zero.

07 — During conversion

Safe defaults, explicit results.

• Every job handles a conversion atomically, converted files are written only after ffmpeg succeeds. Source files are never modified.
• If an output already exists when its job starts, that job is skipped rather than overwritten.
• flacser prints completed-job progress and a final summary with converted, skipped, failed, interrupted, and worker counts.
• A failed job does not stop other jobs. The process exits with 1 when any job fails and 130 when interrupted.
• FLAC uses the FLAC encoder. WAV and AIFF choose a PCM codec from source information reported by ffprobe. Metadata transfer is best effort and depends on the container; WAV keeps only the first audio stream and drops cover art and other non-audio streams.

08 — Common fixes

When a command does not go to plan.

“target format is required”

Add --to flac, --to aiff, or --to wav, or set FLACSER_CONVERT_TO.

ffmpeg or ffprobe not found

Install FFmpeg and restart the terminal after adding its binary directory to PATH. Confirm with flacser doctor.

Output collision

Choose another output directory, preserve the directory structure, or rename conflicting source files. Do not use --flatten when names are not unique.

Output was skipped

An output file was already present. Move or rename it if you intend to make a new conversion; flacser does not overwrite it.