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
• Silence detection: the threshold and minimum length used, leading silence, trailing silence, the total length and count of silent regions, and the list of silent regions (frame positions and seconds; none when there are none)
• Other information: loop data, Vorbis Comments, and warnings

Silence is detected by checking whether the RMS level of each 5 ms block (summed across all channels) falls below the threshold. Region boundaries are rounded to block boundaries.

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. reverse takes no keys.

By default, the start / end of loop are snapped to the best loop seam (zero crossing) within a search window of 128 frames on each side. With snap=off, no snapping happens and the given frames are used as the loop boundaries as-is (for example, to use positions already finalized in the GUI).

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.

trim-silence detects and automatically trims leading and trailing silence. Regions where the RMS level of each short block (5 ms) falls below threshold (default -60dBFS) are treated as silence, the silence running from the start and end is dropped, and the rest is applied as the same non-destructive trim as trim. With margin (default 0ms), that much silence is kept before and after the audible range. Detection runs against the timeline at that point (the audio with any earlier gain / fade-in / fade-out / trim / reverse applied), so placing it after gain means the detection uses the boosted levels. Files with no leading or trailing silence, and files entirely below the threshold, are left unchanged with a warning. trim-silence accepts only the threshold and margin keys; keys for other operations (db, duration, start, and so on) are errors.

reverse reverses the time axis (reversed playback). Combined with trim, the audio kept by trim is reversed as-is (in either order). A loop specified before reverse is remapped to the reversed coordinates (start' = length - end, end' = length - start), while a loop specified after reverse is resolved in reversed coordinates. Fades always apply to the start (fade-in) and end (fade-out) of the output, so combining reverse with fade-in produces reversed material whose attack fades in. reverse toggles the reversed state: specifying it twice restores the original (remapping the loop each time).

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. Writing float PCM input (32-bit float WAV / AIFF-C float32) to FLAC requires --bits-per-sample.
• --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. The GUI’s bounce dialog can also export its settings and edits as a job file (see Exporting).

Top-level keys

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

[[op]]

For loop and trim, start < end is required. reverse takes no keys (specifying any is an error). Each type accepts only the keys in the table above; keys for other operations (for example duration on gain) are errors.

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, same_format, and clear_loop become true when either side is true.
• comment / remove_comment append CLI --comment / --remove-comment values to the job file arrays.

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.