loudcheck

loudcheck

生のメータ出力ではなく、ラウドネス規格への適合判定を行います。loudcheck は ffmpeg でメディアファイルを測定し、実際に重要な問い――このファイルは仕様に適合しているか？――に、正式に公開された規格に照らして答えます。

エージェントはこちらから → SKILL.md — 呼び出すタイミング、実例、MUST／MUST NOT。ファミリーの契約については、FAMILY.md をご覧ください。

• EBU R 128（欧州の放送規格：−23.0 LUFS ±0.5 LU、最大 −1 dBTP）
• ATSC A/85（米国のテレビ放送規格：−24 LKFS ±2 dB、トゥルーピークは −2 dBTP 未満）
• BS.1770（測定のみ：BS.1770 は適合目標を定めていないため、このモードは数値を含む measured 判定を返し、適否は判断しません）

$ loudcheck master.wav --standard EBU_R128
FAIL — EBU R 128
  ✗ integrated -19.4 LUFS (target -23.0 ±0.5, delta +3.6)
  ✓ true peak -16.3 dBTP (max -1.0)
  · LRA 0.0 LU (informational)
  → apply -3.6 LU gain to reach -23.0 LUFS (e.g. ffmpeg -af volume=-3.6dB, or loudnorm I=-23)

1 つのエンジンを使う CLI と MCP ツールとして提供されるため、エージェントと人間に同じ判定結果を返します。

このツールが必要な理由

エージェント（またはエンジニア）は ffmpeg の ebur128 フィルターを実行して数値を取得できます。しかし、シェルだけでは判定結果を得られません。判定には規格の目標値、許容範囲、ゲーティングを把握し、それらに照らして統合ラウドネス、LRA、トゥルーピークを解釈する必要があります。ラウドネスは納品が却下される最もよくある原因の 1 つです。問題は測定ではなく、規格を踏まえた回答が得られないことです。このツールの役割はそれだけです。

インストール

Python 3.10 以降と、PATH 上にある ffmpeg 5.0 以降が必要です。

uvx loudcheck file.wav          # zero-install run (requires ffmpeg >= 5.0 on PATH)
pip install loudcheck           # CLI
pip install "loudcheck[mcp]"    # + MCP server

クローンからインストールする場合：pip install -e ".[mcp,dev]"。

CLI

loudcheck file.wav                          # EBU R128 by default
loudcheck file.mp4 --standard ATSC_A85      # first audio stream of a video
loudcheck file.wav --json                   # full structured verdict
loudcheck file.wav --standard BS_1770       # measurement only, no gates
loudcheck file.mov --all-streams            # verdict every audio track
loudcheck file.mov --stream 1               # a specific audio track
loudcheck file.wav --detailed               # + max momentary / short-term
loudcheck masters/ --standard EBU_R128      # batch a directory -> table
loudcheck a.wav b.wav c.wav                 # batch multiple files
loudcheck --schema                          # print the tool definition

バッチモードではファイルごとに 1 行（失敗時は修正方法も表示）を出力し、最後に要約を表示します。バッチモードで --json を指定すると、配列を出力します。終了コードは、いずれかのファイルが失敗した場合に 1 になります。

エージェント向け

• 終了コードに判定結果が反映されます： 0 = 合格、1 = 不合格（規格不適合）、2 = エラー（ファイルがない、オーディオストリームがない、ffmpeg がない）。終了コードだけで納品可否を判定できます。
• --json がすべての情報を含む契約です： 全体の verdict、メトリックごとの measured/target/tolerance/delta/pass（判定対象の各メトリックに規格の引用情報を添付）、平易な英語で記載した failures、そして正確な修正方法を示す remediation を含みます。目標値を 2.3 LU 上回る場合は、−2.3 LU のゲインを適用するよう伝え、ffmpeg の実行コマンドも提示します。このツールは修正を適用しません（測定と判定のみ）。エージェントは提示された差分を使って loudnorm で一度に修正できます。
• MCP： loudcheck-mcp を登録してください（stdio、または loudcheck --mcp、または python -m loudcheck.mcp_server）。インストール不要で使うには、uvx --from 'loudcheck[mcp]' loudcheck --mcp を実行します。ツール：check_loudness(path, standard) → CLI と同じ JSON、list_standards() → 引用情報付きの規格一覧。mcp==1.28.1 で検証済みです。
• リポジトリのルートにある tool.json は、ツールの仕様を機械可読形式で記述します。または、loudcheck --schema でインストール済みの環境から直接取得できます（ファイルはパッケージに含まれており、テストで 2 つのコピーが一致することを確認します）。
• ffmpeg のバージョンも契約の一部です： すべての判定に measurement_context.ffmpeg_version が含まれます。サポート対象の最小バージョンは 5.0 です。8.1 を使って開発・検証しています。

対応範囲のガードレール（貢献する前にお読みください）

このリポジトリに含めるのは、正式かつ安定した規格だけです。プラットフォームごとの納品テンプレート（Netflix、DPP、Apple TV+、Amazon、放送局の仕様）は含めません。 プラットフォームの仕様は一方的に変更され、ラウドネス以外の要件も多数含みます。そうした仕様を取り込むと、保守がほとんど不要なコミュニティツールではなく、毎年の保守が必要な製品になってしまいます。プルリクエストでプラットフォームが独自に変更できる目標値を追加する場合は、このプリミティブの上に構築する別のテンプレートレイヤーに追加してください。このリポジトリには追加しないでください。

追加の正式な規格（例：ITU-R BS.1770 のみを測定するモード）の貢献は歓迎します。規格は loudcheck/standards.py にある、目標値、許容範囲、引用情報からなる純粋なデータです。コードの変更は必要ありません。

測定方法

loudnorm=print_format=json（解析モード）を指定して ffmpeg を1回実行すると、統合ラウドネス、ラウドネスレンジ、トゥルーピーク（BS.1770 に基づくオーバーサンプリング後の dBTP）、およびゲーティングしきい値が得られます。テストスイートでは、loudnorm の測定値と ffmpeg の独立した ebur128 実装による測定値を照合します。CI を通過するには、両者が 1 LU 以内で一致する必要があります。そのため、フィルターの動作を変更する ffmpeg のリリースがあっても、ユーザーではなくテストスイートが検知できます。

検証用コーパス

pytest はその場で校正済みのテストトーンを生成します（リポジトリにバイナリはありません）。BS.1770 の校正に関する記述によると、0 dBFS のモノラル 997 Hz 正弦波は −3.01 LKFS と測定されます。そのため、適合、音量過大、音量過小、トゥルーピーク過大の各ケースについて、既知のラウドネス値となるトーンを生成し、それぞれの判定が既知の期待値と一致することを確認します。

恒久的に対象外とするもの

ラウドネスの補正（このツールが示す差分を使って ffmpeg の loudnorm を使用してください）・ファイル全体の QC（コーデック／色／フレームレート）・リアルタイム監視・GUI・プラットフォーム向け配信テンプレート（ガードレールを参照してください）。

ライセンス

MIT