バッチ処理と自動化

進め方の基本

大量のファイルをまとめて処理するときは、次の順で固めていくと扱いやすくなります。

1. GUI で 1 ファイル分の設定を詰め、狙った結果になることを耳と目で確認する
2. 同じ設定を a9a_cli render の --op に書き下し、1 ファイルで再現することを確認する
3. --out-dir で複数ファイルへ広げる
4. 手順が固まったら job file に落とし、コマンドラインからは入出力だけを渡す

GUI と CLI は同じ処理エンジンを共有しているため、GUI で確認した結果はそのまま CLI でも再現できます。

複数ファイルを一括処理する

複数の入力を渡し、--out-dir で出力先ディレクトリを指定します。複数入力のときに --out は使えません。

a9a_cli render assets/*.wav \
  --out-dir build/mastered \
  --same-format \
  --force \
  --op loudness target=-16LUFS max-true-peak=-1dBTP limiter=on

--op は並べた順に適用されます。処理の順序が結果を変える場合（特に trim を含む場合）は、波形を編集する の注意点を確認してください。

進捗表示が不要な場合は --no-indicator、警告や途中経過も含めて抑制したい場合は -q / --quiet を付けます。ログを残す自動処理では --no-indicator を付けておくと出力が読みやすくなります。

手順を job file にまとめる

処理内容を TOML ファイルにまとめ、render --job <JOB> で読み込めます。出力仕様ごとに job file を用意しておけば、手順そのものをリポジトリで管理できます。

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

a9a_cli render --job jobs/render.toml

キーの一覧は CLI リファレンス にまとめています。

job file とコマンドライン引数を併用する

共通の処理を job file に置き、案件ごとに変わる部分だけをコマンドラインで渡す使い方ができます。

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

両方を指定した場合は、次の規則で解決されます。

ファイルをまとめてチェックする

probe に --json を付けると、計測結果が機械可読な JSON で stdout に出力されます。一括チェックや、CI でのアセット品質ゲートに使えます。

a9a_cli probe assets/*.wav --json | jq '.[0].integrated_lufs'

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

[
  {
    "file": "input.wav",
    "format": "wav",
    "sample_rate_hz": 48000,
    "bit_depth": 16,
    "channels": 2,
    "duration_seconds": 1.0,
    "integrated_lufs": -14.0,
    "true_peak_dbtp": -1.0,
    "channel_true_peaks_dbtp": [-1.0, -1.0],
    "loudness_range_lu": null,
    "crest_factor_db": 3.0,
    "channel_crest_factor_db": [3.0, 3.0],
    "aac": null,
    "loop": {"start": 4, "end": 12, "length": 8},
    "tags": [{"key": "ARTIST", "value": "a9a"}],
    "warnings": []
  }
]

無音などで測定不能な値（±inf / NaN）は null になります。フィールドの意味は CLI リファレンス にまとめています。

失敗したファイルの扱い

一部のファイルが読み込みや計測に失敗しても、残りの入力は処理を続けます。失敗したファイルは次の形のエントリとして同じ配列に含まれ、1 件でも失敗があれば exit code は非ゼロになります。

{"file": "broken.wav", "error": "Failed to decode ..."}

成功エントリに error キーは含まれないため、error キーの有無で成否を判別できます。

品質ゲートの例

読み込みに成功したうえで、integrated loudness が目標の ±1 LU に収まっていることを確認する例です。条件を満たさなければ jq -e が非ゼロで終了するので、そのまま CI のステップとして使えます。

set -o pipefail
a9a_cli probe assets/*.wav --json \
  | jq -e 'all(.[]; .error == null and .integrated_lufs >= -17 and .integrated_lufs <= -15)'

サンプルレートとチャンネル数の混在を検出する例です。

set -o pipefail
a9a_cli probe assets/*.wav --json \
  | jq -e 'all(.[]; .error == null)
           and ([.[] | {sample_rate_hz, channels}] | unique | length == 1)'

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