CLI Manual

Subcommands

a9a_cli provides the following four subcommands.

The supported formats are WAV / FLAC / AIFF (including AIFF-C) / Ogg Vorbis / MP3. MP3 encoding additionally requires the LAME (libmp3lame) shared library.

probe

Measures and prints the input audio format and loudness.

a9a_cli probe input.wav

Options

Output

probe prints the following information.

• File information: file path, 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

render

Applies operations in order and writes audio output. Use --out for a single output file, and --out-dir for batch processing multiple files.

Basic single-input, single-output usage:

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

For batch processing multiple inputs, specify the output directory with --out-dir.

a9a_cli render a.wav b.wav \
  --out-dir out \
  --same-format \
  --op loudness target=-16LUFS max-true-peak=-1dBTP

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, start < end is required.

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 (writing an AIFF-C input back with --same-format produces the same 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; importing and writing other formats do not require it.
• Tags added with --comment are preserved for FLAC / Ogg Vorbis, but are discarded when writing WAV / AIFF / MP3.

Job File

You can collect processing settings in a TOML file and load it with render --job <JOB>.

a9a_cli render --job jobs/render.toml

The following example combines top-level settings with [[op]] operation entries.

input = ["../audio/a.wav", "../audio/b.wav"]
out_dir = "../out"
same_format = true
force = true
comment = ["ARTIST=a9a", "ALBUM=demo"]

[[op]]
type = "gain"
db = -3

[[op]]
type = "fade_in"
duration = "100ms"
curve = "equal_power"

[[op]]
type = "loop"
start = 12000
end = 96000

Top-level keys

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

[[op]]

Operations are defined with [[op]] tables. type accepts only the following values.

For loop, start < end is required.

Job file type values are fixed to snake_case. The CLI --op names fade-in and fade-out are not accepted in job files; use fade_in and fade_out.

Job file notes

• out is not accepted. Use output.
• max-true-peak is not accepted. Use max_true_peak.
• Unknown keys are errors.
• Relative paths in a job file are resolved from the job file’s own directory, not from the current working directory.

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.

a9a_cli version

To include third-party licenses, add --third-party-licenses.

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

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

Operational guidance

render can handle many preprocessing steps in one workflow, but valid settings depend on the combination of input, output, and format options. In production use, it helps to decide settings in this order.

1. Decide the output format first.
2. Decide the sample rate and bit depth policy.
3. Add the minimum required operations.
4. Move the finalized procedure into a job file.

Start by checking behavior with one file, then expand to batch processing.