バッチ処理と自動化

進め方の基本

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

1. GUI で 1 ファイル分の設定を詰め、狙った結果になることを耳と目で確認する
2. 同じ設定を a9a_cli render の --op に書き下し、1 ファイルで再現することを確認する（GUI のバウンスダイアログから job file を書き出せば、この書き下しを省略できます。後述の「GUI から job file を書き出す」を参照）
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 リファレンス にまとめています。

GUI から job file を書き出す

job file は手で書くほかに、GUI のバウンスダイアログから書き出せます。GUI で耳と目で確認した設定と編集内容が、そのまま render --job で実行できる job file になります（書き出しの操作は 書き出す を参照）。

• Export job file as a preset を有効にして書き出した job file には input / output / out_dir が含まれません。入力と出力先をコマンドラインで渡して、別のファイル群に使い回せます（a9a_cli render --job preset.toml --out-dir out/ *.wav）
• GUI のバウンスは入力が持つループ情報を常に GUI 側の設定で置き換えるため、書き出される job file には clear_loop = true が含まれます
• GUI のループ位置は確定済みのため、loop op は snap = false（ゼロクロス吸着なし）で書き出されます
• 編集内容が異なるファイルは、それぞれ別の job file に分かれて書き出されます

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": [],
    "silence": {
      "threshold_dbfs": -60.0,
      "min_duration_ms": 100.0,
      "leading_frames": 24000,
      "leading_seconds": 0.5,
      "trailing_frames": 0,
      "trailing_seconds": 0.0,
      "total_frames": 24000,
      "total_seconds": 0.5,
      "regions": [
        {"start_frame": 0, "end_frame": 24000, "start_seconds": 0.0, "end_seconds": 0.5}
      ]
    }
  }
]

無音などで測定不能な値（±inf / NaN）は null になります。silence の判定条件は --silence-threshold（既定 -60 dBFS）と --silence-min-duration（既定 100 ms）で変更できます。フィールドの意味は 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)'

先頭・末尾に 10 ms を超える無音が残っていないことを確認する例です。

set -o pipefail
a9a_cli probe assets/*.wav --json \
  | jq -e 'all(.[]; .error == null
           and .silence.leading_seconds <= 0.01
           and .silence.trailing_seconds <= 0.01)'

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