CLI マニュアル

サブコマンド一覧

a9a_cli には次の 4 つのサブコマンドがあります。

対応フォーマットは WAV / FLAC / AIFF（AIFF-C を含む）/ Ogg Vorbis / MP3 です。MP3 のエンコードには LAME（libmp3lame）の共有ライブラリが別途必要です。

probe

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

a9a_cli probe input.wav

オプション

出力内容

probe は次の情報を表示します。

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

render

operation を順に適用してオーディオを書き出します。単一ファイルへの出力には --out、複数ファイルの一括処理には --out-dir を使います。

単一入力・単一出力の基本形です。

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

複数入力を一括で処理する場合は --out-dir で出力先ディレクトリを指定します。

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

入出力オプション

operation

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

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

キーの値の形式

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

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

制約

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

• --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 であればそのコンテナを引き継ぎます（--same-format で 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 出力のみエラーになります（インポートや他フォーマットへの出力には不要）。
• --comment で追加したタグは FLAC / Ogg Vorbis では保持されますが、WAV / AIFF / MP3 では出力時に破棄されます。

Job File

処理内容を TOML ファイルにまとめ、render --job <JOB> で読み込めます。

a9a_cli render --job jobs/render.toml

次は top-level の設定と [[op]] を組み合わせた例です。

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 キー

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

[[op]]

operation は [[op]] テーブルで定義します。type には次の値のみを指定できます。

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

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

job file の注意点

• out は受け付けません。output を使います。
• max-true-peak は受け付けません。max_true_peak を使います。
• 定義されていないキーはエラーになります。
• job file 内の相対パスは、カレントディレクトリではなく job file 自身のディレクトリを基準に解決されます。

マージ規則

--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

アプリケーション情報を表示します。

a9a_cli version

third-party license を含める場合は --third-party-licenses を付けます。

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

処理内容を 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

運用上の考え方

render は多くの前処理を 1 本のワークフローで扱える反面、入出力条件の組み合わせによって有効な指定が変わります。実運用では次の順で整理しておくと扱いやすくなります。

1. 出力形式を先に決める
2. sample rate や bit depth の方針を決める
3. operation を必要最小限から積み上げる
4. 手順が固まったら job file に落とし込む

まずは単一ファイルで挙動を確認し、その後にバッチ処理へ広げるのが安全です。