CLI リファレンス | a9a Docs

使い方の流れから読みたい場合は、音量をそろえる、書き出す、バッチ処理と自動化を参照してください。このページは引くための一覧です。

サブコマンド

サブコマンド	役割
`probe`	入力オーディオのメタ情報とラウドネス情報を表示する
`render`	operation（処理）を順に適用し、1 件または複数件を書き出す
`play`	入力オーディオを再生する
`version`	アプリケーション情報を表示する

対応フォーマットは WAV / FLAC / AIFF（AIFF-C を含む）/ Ogg Vorbis / MP3 / AAC（M4A・ADTS、AAC-LC / HE-AAC v1 / HE-AAC v2）です。MP3 の書き出しには LAME、一部の AAC 設定には libfdk-aac が必要です。導入方法ははじめににまとめています。

`probe`

入力オーディオのフォーマットとラウドネスを計測して表示します。

a9a_cli probe input.wav

複数の入力をまとめて計測できます。テキスト出力では、ファイルごとの結果ブロックが空行 1 つで区切られて並びます。

a9a_cli probe a.wav b.wav

オプション

オプション	説明
`--json`	機械可読な JSON で出力します
`--no-indicator`	互換性のために受け付けます。`probe` では進捗表示を行わないため、指定しても動作は変わりません
`-q`, `--quiet`	テキスト出力の warning 行のみを抑制します。計測結果は表示します。`--json` の出力内容には影響しません（warnings は常に含まれます）

出力内容

ファイル情報: ファイルパス、format（フォーマット）、sample rate（サンプリング周波数）、bit depth（量子化ビット数）、channels（チャンネル数）、duration（長さ）
ラウドネス指標: integrated LUFS、true peak（トゥルーピーク）、LRA（ラウドネスレンジ）、crest factor（クレストファクター）
その他: loop 情報、Vorbis Comments、warnings

JSON 出力のフィールド

トップレベルは、入力が 1 件でも常に配列です。エントリは入力の指定順に並びます。

キー	型	説明
`file`	string	入力に指定したファイルパス
`format`	string	入力フォーマット。`wav`, `aiff`, `mp3`, `flac`, `ogg_vorbis`, `aac` のいずれか
`sample_rate_hz`	number	sample rate（Hz）
`bit_depth`	number / null	量子化ビット数。lossy フォーマット（MP3 / Ogg Vorbis / AAC）では null
`channels`	number	チャンネル数
`duration_seconds`	number	長さ（秒）
`integrated_lufs`	number / null	integrated loudness（LUFS）
`true_peak_dbtp`	number / null	全チャンネル中の最大 true peak（dBTP）
`channel_true_peaks_dbtp`	array	チャンネル別 true peak（dBTP）。各要素は number / null
`loudness_range_lu`	number / null	LRA（LU）。計測に必要な長さに満たない場合は null
`crest_factor_db`	number / null	crest factor（dB）
`channel_crest_factor_db`	array	チャンネル別 crest factor（dB）。各要素は number / null
`aac`	object / null	AAC 入力のみ `{"container": "m4a"\|"adts", "profile": "lc"\|"he-v1"\|"he-v2"}`。それ以外は null
`loop`	object / null	loop 情報 `{"start", "end", "length"}`（サンプル単位、`end` は排他）。loop が無い場合は null
`tags`	array	Vorbis Comments。`{"key", "value"}` の配列で、記録順と重複キーを保持します
`warnings`	array	デコード時の warning メッセージ（string）の配列

計測値の number は、無音などで測定不能な場合（±inf / NaN）に null になります。

エラーと exit code

一部のファイルが読み込みや計測に失敗しても、残りの入力は処理を続けます。失敗したファイルは {"file": "broken.wav", "error": "Failed to decode ..."} の形のエントリとして同じ配列に含まれ、1 件でも失敗があれば exit code は非ゼロになります。成功エントリに error キーは含まれません。

JSON スキーマは、フィールドの追加はあり得ますが、既存フィールドの意味変更・削除は行いません。スクリプト側は未知のフィールドを無視してください。

`render`

operation を順に適用してオーディオを書き出します。

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

入出力オプション

オプション	説明
`-o`, `--out <PATH>`	単一の出力ファイル
`--out-dir <DIR>`	複数入力向けの出力ディレクトリ
`--force`	既存の出力を上書きする
`--same-format`	入力のフォーマットを維持する
`--format <wav\|flac\|aiff\|ogg\|mp3\|m4a\|aac>`	出力フォーマットを明示する（`m4a` = AAC/MP4 コンテナ、`aac` = AAC/ADTS）
`--sample-rate <HZ>`	出力の sample rate を指定する
`--bits-per-sample <BITS>`	WAV / FLAC / AIFF の bit depth
`--sample-format <int\|float>`	WAV の sample format
`--aiff-container <aiff\|aifc-none\|aifc-sowt\|aifc-float32>`	AIFF 出力時のコンテナ／圧縮方式
`--flac-compression-level <0..8>`	FLAC の圧縮レベル
`--vorbis-quality <-1..10>`	Ogg Vorbis の品質
`--mp3-vbr-quality <0..9>`	MP3 の VBR 品質（0 が最高音質）。LAME が必要
`--mp3-bitrate <8..320>`	MP3 の平均ビットレート（kbps, ABR）。`--mp3-vbr-quality` とは併用不可
`--aac-profile <lc\|he-v1\|he-v2>`	AAC のプロファイル。省略時は AAC 入力ならそのプロファイル、それ以外は `lc`
`--aac-bitrate <8..320>`	AAC のビットレート（kbps, CBR）。省略時はプロファイル別の既定値（LC=192 / HE v1=64 / HE v2=32）
`--aac-vbr-quality <1..5>`	AAC の VBR 品質（5 が最高音質）。`--aac-bitrate` とは併用不可
`--aac-encoder <auto\|fdk\|os>`	AAC エンコーダの選択。`auto` は OS ネイティブ優先で、OS 側が対応しない設定は libfdk-aac へフォールバック
`--comment KEY=VALUE`	Vorbis Comment を追加する
`--no-indicator`	progress bar と operation ごとの進捗出力を無効化する
`-q`, `--quiet`	warning と途中経過の表示を抑制する。indicator も無効化する
`--job <JOB>`	TOML job file を読み込む

operation

--op で適用する処理を指定します。同じ --op を複数並べると、指定した順に適用されます。

operation	必須キー	任意キー
`gain`	`db`	-
`loudness`	`target`	`max-true-peak`, `limiter`, `release`
`fade-in`	`duration`	`curve`
`fade-out`	`duration`	`curve`
`loop`	`start`, `end`	-
`trim`	`start`, `end`	-

loop と trim では start < end である必要があります。

trim は start〜end（フレーム単位、end は排他）の範囲だけを残し、範囲外を破棄します。長さが変わるため、operation の指定順が意味を持ちます。trim より前に指定した loop はトリム後のタイムラインへ再マップされ（トリム範囲の完全に外にあるループは warning を出して破棄）、trim より後に指定した loop はトリム後の座標で解決されます。

loudness の limiter（省略時 off）は true peak limiter の有効・無効を切り替えます。有効にすると、ルックアヘッド型リミッターで true peak を max-true-peak 以内に抑えたまま、ターゲットの integrated loudness まで持ち上げます。無効の場合は true peak が上限を超えないようゲインが制限され、その結果ターゲットに届かなかったときは stderr に warning が表示されます。

loudness の release（省略時 normal）は、リミッターが掛かった後にゲインが戻る速さを fast（30 ms）/ normal（100 ms）/ slow（300 ms）から選択します。limiter=on のときのみ効果があります。どのプリセットでも true peak は max-true-peak 以内に保たれます。

キーの値の形式

キー	形式	例
`db`, `target`, `max-true-peak`	数値、または suffix 付き文字列	`-3`, `-3dB`, `-16LUFS`, `-1dBTP`
`limiter`	`on`, `off`, `true`, `false` のいずれか	`on`
`release`	`fast`, `normal`, `slow` のいずれか	`slow`
`duration`	`100ms`、`1s`、または suffix なしのミリ秒整数	`100ms`, `1s`, `100`
`curve`	`linear`, `equal_power`, `s_curve`, `log`, `exp` のいずれか	`equal_power`
`start`, `end`	フレーム単位の整数（`end` は排他）	`48000`

AIFF / AIFF-C（AIFC）の入出力

.aiff / .aif / .aifc のいずれの拡張子も AIFF ファイルとして読み込めます。読み込み時は AIFF-C（AIFC）コンテナにも対応しており、以下の圧縮方式（compression type）を扱えます。

compression type	内容	読み込み	書き込み
（プレーン AIFF）	ビッグエンディアンの整数 PCM	○	○
`NONE` / `twos` / `in16` / `in24` / `in32`	AIFF-C のビッグエンディアン整数 PCM	○	○（`aifc-none`）
`sowt`	AIFF-C のリトルエンディアン整数 PCM	○	○（`aifc-sowt`）
`fl32`	AIFF-C の 32bit float（IEEE754）	○	○（`aifc-float32`）
上記以外（`ulaw`, `ima4`, `fl64` など）	圧縮コーデックや 64bit float	×	×

制約

出力先とフォーマットの指定には、次の制約があります。

--out と --out-dir は同時に指定できません。
複数入力では --out を使えません。--out-dir を使います。
--same-format と --format は同時に指定できません。
--out を使う場合、出力フォーマットを --format、--same-format、または出力パスの拡張子のいずれかで決定できる必要があります。
--format と --out を併用し、--out に拡張子があるときは、拡張子と --format が一致している必要があります。

--sample-rate には次の標準値のみ指定できます。

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

フォーマット別のオプションには、次の制約があります。

--sample-format は WAV 出力でのみ有効です。float を使う場合は --bits-per-sample 32 が必要です。
--aiff-container は AIFF 出力でのみ有効です。省略した場合、入力が AIFF/AIFF-C であればそのコンテナを引き継ぎます。入力が AIFF/AIFF-C 以外の場合は素の AIFF（aiff）になります。aifc-float32 を指定する場合は --bits-per-sample 32 が必要です。
FLAC の bit depth は 24 bit までです。--flac-compression-level は FLAC 出力でのみ有効です。
--vorbis-quality は Ogg Vorbis 出力でのみ有効です。
--mp3-vbr-quality と --mp3-bitrate は MP3 出力でのみ有効で、同時には指定できません。どちらも省略した場合は既定の VBR 品質（おおよそ 190 kbps 相当）になります。
MP3 出力には LAME（libmp3lame）の共有ライブラリが実行時に必要です。インストールされていない場合は MP3 出力のみエラーになります。
--aac-* は AAC（m4a / aac）出力でのみ有効です。--aac-bitrate と --aac-vbr-quality は同時には指定できません。--same-format で AAC 入力を書き戻すと、入力のコンテナとプロファイルを維持します。
AAC 出力のうち、正確な再生時間情報（gapless メタデータ）を持てるのは M4A のみです。ADTS はフォーマット上その手段がないため、プレーヤーによってはエンコーダディレイ分だけ長く表示されます。
OS ネイティブエンコーダ（--aac-encoder os）には対応範囲の制約があります。Windows は AAC-LC の CBR 96/128/160/192 kbps・44.1/48 kHz のみ、macOS は AAC-LC の 88.2/96 kHz に非対応です。auto では OS 側が対応しない設定のとき自動的に libfdk-aac へフォールバックします（未インストールならエラー）。
--comment で追加したタグは FLAC / Ogg Vorbis では保持されますが、WAV / AIFF / MP3 / AAC では出力時に破棄されます。

job file

処理内容を TOML ファイルにまとめ、render --job <JOB> で読み込めます。書き方と運用はバッチ処理と自動化を参照してください。

top-level キー

キー	説明
`input`	単一の入力、または入力の配列
`output`	単一の出力ファイル
`out_dir`	複数入力時の出力ディレクトリ
`force`	`true` で既存の出力を上書きする
`same_format`	入力のフォーマットを維持する
`format`	`wav`, `flac`, `aiff`, `ogg`, `mp3`, `m4a`, `aac`
`sample_rate`	出力の sample rate
`bits_per_sample`	出力の bit depth
`sample_format`	WAV 用。`int`, `float`
`aiff_container`	AIFF 用。`aiff`, `aifc-none`, `aifc-sowt`, `aifc-float32`
`flac_compression_level`	FLAC 用
`vorbis_quality`	Ogg Vorbis 用。`-1..10`
`mp3_vbr_quality`	MP3 用。`0..9`（0 が最高音質）。LAME が必要
`mp3_bitrate`	MP3 用。平均ビットレート（kbps, ABR）。`mp3_vbr_quality` とは併用不可
`aac_profile`	AAC 用。`lc`, `he-v1`, `he-v2`
`aac_bitrate`	AAC 用。ビットレート（kbps, CBR）。`aac_vbr_quality` とは併用不可
`aac_vbr_quality`	AAC 用。`1..5`（5 が最高音質）
`aac_encoder`	AAC 用。`auto`, `fdk`, `os`
`comment`	`KEY=VALUE` 文字列の配列

output と out_dir、および same_format と format は、それぞれ同時に指定できません。

`[[op]]`

type	必須キー	任意キー
`gain`	`db`	-
`loudness`	`target`	`unit`（指定する場合は `LUFS`）、`max_true_peak`、`limiter`（boolean、省略時 `false`）、`release`（`"fast"` / `"normal"` / `"slow"`、省略時 `"normal"`）
`fade_in`	`duration`	`curve`
`fade_out`	`duration`	`curve`
`loop`	`start`, `end`	-
`trim`	`start`, `end`	-

type は snake_case に固定です。CLI の --op で使う fade-in / fade-out は受け付けません。

マージ規則

--job と CLI 引数を同時に使う場合は、次の規則で解決されます。

operation は job file の [[op]] の後ろに CLI の --op を連結します。
input は CLI 側を優先します。
output / out_dir は CLI 側を優先します。
sample_rate などの出力 override は、フィールド単位で CLI 側を優先します。
force と same_format は、どちらかが true であれば true になります。
comment は job file の配列に CLI の --comment を追記します。

`play`

入力オーディオを再生します。再生中は端末に再生位置を表示します。オプションはありません。

a9a_cli play input.wav

`version`

アプリケーション情報を表示します。third-party license を含める場合は --third-party-licenses を付けます。

a9a_cli version
a9a_cli version --third-party-licenses

代表例

単一ファイルを FLAC に書き出し、ラウドネスを整える例です。

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

処理内容を job file にまとめ、CLI 側で出力先だけを差し替える例です。

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

AIFF-C（リトルエンディアン整数 PCM, sowt）として書き出す例です。

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

このページは生成 AI を用いて作成しています。