CLI Reference

To follow a workflow instead, see Matching Loudness, Exporting, and Batch Processing and Automation. This page is for looking things up.

Subcommands

The supported formats are WAV / FLAC / AIFF (including AIFF-C) / Ogg Vorbis / MP3 / AAC (M4A and ADTS, AAC-LC / HE-AAC v1 / HE-AAC v2). MP3 output requires LAME, and some AAC settings require libfdk-aac; see Getting Started for installation.

probe

Measures and prints the input audio format and loudness.

a9a_cli probe input.wav

Multiple inputs can be measured in one call. In text output, the per-file result blocks are separated by a single blank line.

a9a_cli probe a.wav b.wav

Options

Output

• File information: file path, format, sample rate, bit depth, channels, and duration
• Loudness metrics: integrated LUFS, true peak, LRA, and crest factor
• Other information: loop data, Vorbis Comments, and warnings

JSON output fields

The top level is always an array, even for a single input, with entries in the order the inputs were given.

Numeric measurements become null when they cannot be measured (±inf / NaN, for example on silence).

Errors and exit code

If some files fail to decode or measure, the remaining inputs are still processed. Failed files appear in the same array as {"file": "broken.wav", "error": "Failed to decode ..."}, and the exit code is non-zero when at least one input failed. Successful entries never include an error key.

The JSON schema may gain fields, but existing fields are never removed and their meaning does not change. Scripts should ignore unknown fields.

render

Applies operations in order and writes audio output.

a9a_cli render input.wav \
  --out output.flac \
  --op gain db=-3 \
  --op fade-in duration=100ms curve=linear

Input and output options

Operations

Use --op to specify an operation. When multiple --op arguments are provided, they are applied in the specified order.

For loop and trim, start < end is required.

trim keeps only the range from start to end (in frames, end exclusive) and discards the rest. Because it changes the length, the order of operations matters: a loop specified before trim is remapped onto the trimmed timeline (a loop entirely outside the trim range is discarded with a warning), while a loop specified after trim is resolved in trimmed coordinates.

limiter on loudness (default off) toggles the true peak limiter. When on, a look-ahead limiter keeps the true peak within max-true-peak while reaching the target integrated loudness. When off, the gain is capped so the true peak stays within the limit, and a warning is printed to stderr for files that fall short of the target.

release on loudness (default normal) selects how quickly the gain recovers after the limiter engages: fast (30 ms), normal (100 ms), or slow (300 ms). It takes effect only with limiter=on. Every setting keeps the true peak within max-true-peak.

Value formats

AIFF / AIFF-C (AIFC) input and output

Files with any of the .aiff / .aif / .aifc extensions are read as AIFF files. The AIFF-C (AIFC) container is also supported on input, covering the following compression types.

Constraints

Output path and format settings have the following constraints.

• --out and --out-dir cannot be specified together.
• With multiple inputs, --out cannot be used. Use --out-dir.
• --same-format and --format cannot be specified together.
• When --out is used, the output format must be determined by one of --format, --same-format, or the output path extension.
• When --format and --out are used together, and --out has an extension, that extension must match --format.

--sample-rate accepts only the following standard values.

8000, 11025, 16000, 22050, 32000, 44100, 48000, 88200, 96000, 176400, 192000

Format-specific options have the following constraints.

• --sample-format is valid only for WAV output. When using float, --bits-per-sample 32 is required.
• --aiff-container is valid only for AIFF output. When omitted, an AIFF/AIFF-C input keeps its container, while any other input produces plain AIFF (aiff). When specifying aifc-float32, --bits-per-sample 32 is required.
• FLAC bit depth is limited to 24 bit. --flac-compression-level is valid only for FLAC output.
• --vorbis-quality is valid only for Ogg Vorbis output.
• --mp3-vbr-quality and --mp3-bitrate are valid only for MP3 output and cannot be specified together. When both are omitted, the default VBR quality (roughly equivalent to 190 kbps) is used.
• MP3 output requires the LAME (libmp3lame) shared library at run time. When it is not installed, only MP3 output fails with an error.
• --aac-* options are valid only for AAC (m4a / aac) output. --aac-bitrate and --aac-vbr-quality cannot be specified together. Writing an AAC input back with --same-format preserves the input’s container and profile.
• Only M4A can carry accurate duration information (gapless metadata). ADTS has no way to express it, so some players show the file as longer by the encoder delay.
• The OS-native encoder (--aac-encoder os) has coverage limits: Windows supports only AAC-LC CBR at 96/128/160/192 kbps and 44.1/48 kHz, and macOS does not support AAC-LC at 88.2/96 kHz. With auto, unsupported settings fall back to libfdk-aac automatically (an error when it is not installed).
• Tags added with --comment are preserved for FLAC / Ogg Vorbis, but are discarded when writing WAV / AIFF / MP3 / AAC.

Job file

Collect processing settings in a TOML file and load it with render --job <JOB>. For how to write and operate them, see Batch Processing and Automation.

Top-level keys

output and out_dir cannot be specified together. same_format and format also cannot be specified together.

[[op]]

type values are fixed to snake_case. The CLI --op names fade-in and fade-out are not accepted.

Merge rules

When --job and CLI arguments are used together, they are resolved with these rules.

• Operations are concatenated: job file [[op]] entries first, then CLI --op entries.
• input prefers the CLI value.
• output / out_dir prefer the CLI value.
• Output overrides such as sample_rate prefer the CLI value field by field.
• force and same_format become true when either side is true.
• comment appends CLI --comment values to the job file array.

play

Plays an input audio file. During playback, the current playback position is displayed in the terminal. There are no options.

a9a_cli play input.wav

version

Shows application information. Add --third-party-licenses to include third-party licenses.

a9a_cli version
a9a_cli version --third-party-licenses

Examples

Write a single file as FLAC and normalize its loudness:

a9a_cli render input.wav \
  --out output.flac \
  --format flac \
  --sample-rate 48000 \
  --bits-per-sample 24 \
  --op loudness target=-16LUFS max-true-peak=-1dBTP limiter=on release=slow

Define the processing steps in a job file and override only the output directory from the CLI:

a9a_cli render \
  --job jobs/master.toml \
  --out-dir build/mastered \
  --comment REVISION=2026-03-20

Write AIFF-C (little-endian integer PCM, sowt):

a9a_cli render input.wav \
  --out output.aifc \
  --format aiff \
  --aiff-container aifc-sowt \
  --bits-per-sample 16 \
  --op gain db=-3

This page was written with generative AI.