loudcheck 0.3.0__tar.gz

loudcheck-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chaoz23
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

loudcheck-0.3.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: loudcheck
+Version: 0.3.0
+Summary: Loudness compliance verdicts against formal published standards (EBU R128, ATSC A/85) — a pass/fail answer with exact deltas, not raw meter output.
+Author-email: chaoz23 <chaoz23@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/chaoz23/loudcheck
+Project-URL: Issues, https://github.com/chaoz23/loudcheck/issues
+Keywords: loudness,ebu-r128,atsc-a85,lufs,true-peak,ffmpeg,compliance,mcp,agents,broadcast
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mcp
+Requires-Dist: mcp==1.28.1; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# loudcheck
+
+A **loudness compliance verdict**, not raw meter output. `loudcheck` measures
+a media file with ffmpeg and answers the question that actually matters —
+*does this file pass the spec?* — against formal published standards:
+
+- **EBU R 128** (European broadcast: −23.0 LUFS ±0.5 LU, max −1 dBTP)
+- **ATSC A/85** (US television: −24 LKFS ±2 dB, true peak below −2 dBTP)
+- **BS.1770** (measure-only: BS.1770 defines no compliance target, so this
+  mode returns verdict `measured` with the numbers and no judgment)
+
+```
+$ 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)
+```
+
+Ships as a CLI and an MCP tool over one engine, so agents and humans get the
+identical verdict.
+
+## Why this exists
+
+An agent (or an engineer) can run ffmpeg's `ebur128` filter and get numbers.
+What it can't get from a shell is the *verdict* — that requires knowing the
+standard's target, tolerance, and gating, and interpreting integrated
+loudness vs. LRA vs. true peak against them. Loudness is one of the most
+common causes of delivery rejection, and the gap is not measurement — it's
+the standards-aware answer. That's the whole tool.
+
+## Install
+
+```bash
+pip install -e .            # CLI (requires ffmpeg >= 5.0 on PATH)
+pip install -e ".[mcp]"     # + MCP server
+pip install -e ".[dev]"     # + pytest
+```
+
+## CLI
+
+```bash
+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
+```
+
+Batch mode prints one line per file (plus remediation for fails) and a
+summary; `--json` in batch emits an array. Exit code is `1` if *any* file
+fails.
+
+## For agents
+
+- **Exit codes carry the verdict:** `0` = pass, `1` = fail (non-compliant),
+  `2` = error (missing file, no audio stream, no ffmpeg). Gate a delivery on
+  the exit code alone.
+- **`--json` is the full contract:** overall `verdict`, per-metric
+  `measured/target/tolerance/delta/pass` with the spec citation attached to
+  every gated metric, `failures` in plain English, and `remediation` with the
+  **exact correction** — a fail 2.3 LU over target tells you to apply
+  −2.3 LU gain and hands you the ffmpeg incantation. This tool never applies
+  the fix (measurement and verdict only); the agent one-shots it with
+  `loudnorm` using the delta provided.
+- **MCP:** register `python -m loudcheck.mcp_server` (stdio). Tools:
+  `check_loudness(path, standard)` → same JSON as the CLI, and
+  `list_standards()` → the catalog with citations. Verified against
+  `mcp==1.28.1`.
+- **`tool.json`** at the repo root describes the surface machine-readably —
+  or fetch it live from any install with `loudcheck --schema` (the file ships
+  inside the package; a test keeps the two copies in sync).
+- **ffmpeg version is part of the contract:** every verdict includes
+  `measurement_context.ffmpeg_version`. Minimum supported: 5.0. Developed and
+  verified against 8.1.
+
+## The scope guardrail (read before contributing)
+
+**Only formal, stable standards live in this repo; per-platform delivery
+templates (Netflix, DPP, Apple TV+, Amazon, broadcaster specs) never do.**
+Platform specs change unilaterally and cover far more than loudness — the
+moment they enter, this stops being a near-zero-maintenance community tool
+and becomes a yearly-maintenance product. If a PR adds a target that a
+platform can change on its own, it belongs in a separate template layer
+built *on top of* this primitive, not here.
+
+Contributions of additional *formal* standards (e.g. a plain ITU-R BS.1770
+mode) are welcome: a standard is pure data in
+[`loudcheck/standards.py`](loudcheck/standards.py) — targets, tolerances, and
+citations. No code changes required.
+
+## How it measures
+
+One ffmpeg pass with `loudnorm=print_format=json` (analysis mode) yields
+integrated loudness, loudness range, true peak (oversampled dBTP per
+BS.1770), and the gating threshold. The test suite cross-checks loudnorm's
+reading against ffmpeg's independent `ebur128` implementation — the two must
+agree within 1 LU for CI to pass, so an ffmpeg release that changes filter
+behavior is caught by the suite, not by users.
+
+## Verification corpus
+
+`pytest` generates calibrated test tones on the fly (no binaries in the
+repo): per BS.1770's calibration statement, a mono 997 Hz sine at 0 dBFS
+reads −3.01 LKFS, so tones are generated at exact known loudness — compliant,
+too loud, too quiet, and true-peak-hot — and every verdict must match its
+known expectation.
+
+## Out of scope, permanently
+
+Loudness *correction* (use ffmpeg `loudnorm` with the delta this tool gives
+you) · full-file QC (codec/colour/cadence) · real-time monitoring · GUIs ·
+platform delivery templates (see guardrail).
+
+## License
+
+MIT

loudcheck-0.3.0/README.md

@@ -0,0 +1,123 @@
+# loudcheck
+
+A **loudness compliance verdict**, not raw meter output. `loudcheck` measures
+a media file with ffmpeg and answers the question that actually matters —
+*does this file pass the spec?* — against formal published standards:
+
+- **EBU R 128** (European broadcast: −23.0 LUFS ±0.5 LU, max −1 dBTP)
+- **ATSC A/85** (US television: −24 LKFS ±2 dB, true peak below −2 dBTP)
+- **BS.1770** (measure-only: BS.1770 defines no compliance target, so this
+  mode returns verdict `measured` with the numbers and no judgment)
+
+```
+$ 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)
+```
+
+Ships as a CLI and an MCP tool over one engine, so agents and humans get the
+identical verdict.
+
+## Why this exists
+
+An agent (or an engineer) can run ffmpeg's `ebur128` filter and get numbers.
+What it can't get from a shell is the *verdict* — that requires knowing the
+standard's target, tolerance, and gating, and interpreting integrated
+loudness vs. LRA vs. true peak against them. Loudness is one of the most
+common causes of delivery rejection, and the gap is not measurement — it's
+the standards-aware answer. That's the whole tool.
+
+## Install
+
+```bash
+pip install -e .            # CLI (requires ffmpeg >= 5.0 on PATH)
+pip install -e ".[mcp]"     # + MCP server
+pip install -e ".[dev]"     # + pytest
+```
+
+## CLI
+
+```bash
+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
+```
+
+Batch mode prints one line per file (plus remediation for fails) and a
+summary; `--json` in batch emits an array. Exit code is `1` if *any* file
+fails.
+
+## For agents
+
+- **Exit codes carry the verdict:** `0` = pass, `1` = fail (non-compliant),
+  `2` = error (missing file, no audio stream, no ffmpeg). Gate a delivery on
+  the exit code alone.
+- **`--json` is the full contract:** overall `verdict`, per-metric
+  `measured/target/tolerance/delta/pass` with the spec citation attached to
+  every gated metric, `failures` in plain English, and `remediation` with the
+  **exact correction** — a fail 2.3 LU over target tells you to apply
+  −2.3 LU gain and hands you the ffmpeg incantation. This tool never applies
+  the fix (measurement and verdict only); the agent one-shots it with
+  `loudnorm` using the delta provided.
+- **MCP:** register `python -m loudcheck.mcp_server` (stdio). Tools:
+  `check_loudness(path, standard)` → same JSON as the CLI, and
+  `list_standards()` → the catalog with citations. Verified against
+  `mcp==1.28.1`.
+- **`tool.json`** at the repo root describes the surface machine-readably —
+  or fetch it live from any install with `loudcheck --schema` (the file ships
+  inside the package; a test keeps the two copies in sync).
+- **ffmpeg version is part of the contract:** every verdict includes
+  `measurement_context.ffmpeg_version`. Minimum supported: 5.0. Developed and
+  verified against 8.1.
+
+## The scope guardrail (read before contributing)
+
+**Only formal, stable standards live in this repo; per-platform delivery
+templates (Netflix, DPP, Apple TV+, Amazon, broadcaster specs) never do.**
+Platform specs change unilaterally and cover far more than loudness — the
+moment they enter, this stops being a near-zero-maintenance community tool
+and becomes a yearly-maintenance product. If a PR adds a target that a
+platform can change on its own, it belongs in a separate template layer
+built *on top of* this primitive, not here.
+
+Contributions of additional *formal* standards (e.g. a plain ITU-R BS.1770
+mode) are welcome: a standard is pure data in
+[`loudcheck/standards.py`](loudcheck/standards.py) — targets, tolerances, and
+citations. No code changes required.
+
+## How it measures
+
+One ffmpeg pass with `loudnorm=print_format=json` (analysis mode) yields
+integrated loudness, loudness range, true peak (oversampled dBTP per
+BS.1770), and the gating threshold. The test suite cross-checks loudnorm's
+reading against ffmpeg's independent `ebur128` implementation — the two must
+agree within 1 LU for CI to pass, so an ffmpeg release that changes filter
+behavior is caught by the suite, not by users.
+
+## Verification corpus
+
+`pytest` generates calibrated test tones on the fly (no binaries in the
+repo): per BS.1770's calibration statement, a mono 997 Hz sine at 0 dBFS
+reads −3.01 LKFS, so tones are generated at exact known loudness — compliant,
+too loud, too quiet, and true-peak-hot — and every verdict must match its
+known expectation.
+
+## Out of scope, permanently
+
+Loudness *correction* (use ffmpeg `loudnorm` with the delta this tool gives
+you) · full-file QC (codec/colour/cadence) · real-time monitoring · GUIs ·
+platform delivery templates (see guardrail).
+
+## License
+
+MIT

loudcheck-0.3.0/loudcheck/__init__.py

@@ -0,0 +1,7 @@
+"""loudcheck — standards-based loudness compliance verdicts (EBU R128, ATSC A/85)."""
+
+from .analyze import AnalysisError, Measurement, measure  # noqa: F401
+from .standards import STANDARDS  # noqa: F401
+from .verdict import check  # noqa: F401
+
+__version__ = "0.2.0"

loudcheck-0.3.0/loudcheck/analyze.py

@@ -0,0 +1,174 @@
+"""
+Measurement engine — run ffmpeg's loudnorm analysis pass and parse metrics.
+
+Design decisions:
+- Single ffmpeg invocation using `loudnorm=print_format=json` in analysis
+  mode. The input_* measurement fields are independent of the normalization
+  parameters, so one pass yields integrated loudness, LRA, true peak, and
+  threshold. (The alternative `ebur128` filter is used in the test suite as
+  a cross-check so the two ffmpeg implementations must agree for CI to pass.)
+- ffmpeg version is part of the contract: it is captured and returned with
+  every measurement, because filter behavior across ffmpeg releases is the
+  one realistic maintenance surface this tool has. Minimum supported: 5.0.
+- Errors are specific, `Error:`-prefixed, and never a raw trace (P0.5).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Optional
+
+MIN_FFMPEG_MAJOR = 5
+
+
+class AnalysisError(Exception):
+    """Raised with a clean, user-facing message (no traceback semantics)."""
+
+
+@dataclass
+class Measurement:
+    integrated: float      # LUFS/LKFS (identical scales; name differs by spec)
+    lra: float             # LU
+    true_peak: float       # dBTP
+    threshold: float       # LUFS, gating threshold used
+    sample_rate: Optional[int]
+    channels: Optional[int]
+    duration_seconds: Optional[float]
+    ffmpeg_version: str
+    stream_index: int = 0
+    max_momentary: Optional[float] = None    # LUFS, 400 ms window (--detailed)
+    max_short_term: Optional[float] = None   # LUFS, 3 s window (--detailed)
+
+
+def _ffmpeg_path() -> str:
+    path = shutil.which("ffmpeg")
+    if not path:
+        raise AnalysisError(
+            "Error: ffmpeg not found on PATH (loudcheck requires ffmpeg >= "
+            f"{MIN_FFMPEG_MAJOR}.0)")
+    return path
+
+
+def ffmpeg_version(path: Optional[str] = None) -> str:
+    out = subprocess.run(
+        [path or _ffmpeg_path(), "-version"],
+        capture_output=True, text=True).stdout
+    m = re.match(r"ffmpeg version (\S+)", out)
+    return m.group(1) if m else "unknown"
+
+
+def _probe(path: str, ffmpeg: str) -> dict:
+    """Light probe via ffmpeg itself (no ffprobe dependency): stream info
+    from the -i banner on stderr."""
+    r = subprocess.run(
+        [ffmpeg, "-hide_banner", "-i", path],
+        capture_output=True, text=True)
+    err = r.stderr
+    if "No such file or directory" in err:
+        raise AnalysisError(f"Error: file not found: {path}")
+    if "Invalid data found" in err:
+        raise AnalysisError(f"Error: unreadable or unsupported file: {path}")
+    info: dict = {"has_audio": "Stream" in err and "Audio:" in err}
+    info["audio_streams"] = len(re.findall(r"Stream #\d+:\d+.*?: Audio:", err))
+    m = re.search(r"Audio:.*?(\d+) Hz.*?(mono|stereo|(\d+)(?:\.\d+)? channels)", err)
+    if m:
+        info["sample_rate"] = int(m.group(1))
+        ch = m.group(2)
+        info["channels"] = 1 if ch == "mono" else 2 if ch == "stereo" \
+            else int(m.group(3) or 0)
+    d = re.search(r"Duration: (\d+):(\d+):(\d+\.\d+)", err)
+    if d:
+        h, mi, s = int(d.group(1)), int(d.group(2)), float(d.group(3))
+        info["duration"] = h * 3600 + mi * 60 + s
+    return info
+
+
+def audio_stream_count(path: str) -> int:
+    """Number of audio streams in the file (0 if none)."""
+    return _probe(path, _ffmpeg_path()).get("audio_streams", 0)
+
+
+def _detailed_pass(ffmpeg: str, path: str, stream: int) -> tuple[float, float]:
+    """Second pass with ebur128 to extract max momentary / max short-term.
+    The filter logs M/S every 100 ms; we take the maxima."""
+    r = subprocess.run(
+        [ffmpeg, "-hide_banner", "-nostats", "-i", path,
+         "-map", f"0:a:{stream}",
+         "-af", "ebur128=peak=true", "-f", "null", "-"],
+        capture_output=True, text=True)
+    momentary = [float(m) for m in re.findall(r"M:\s*(-?[\d.]+)", r.stderr)]
+    short_term = [float(s) for s in re.findall(r"S:\s*(-?[\d.]+)", r.stderr)]
+    if not momentary or not short_term:
+        raise AnalysisError(
+            "Error: ebur128 produced no momentary/short-term readings")
+    return max(momentary), max(short_term)
+
+
+def measure(path: str, stream: int = 0, detailed: bool = False) -> Measurement:
+    """Measure integrated loudness, LRA, and true peak of one audio stream.
+
+    stream: zero-based audio stream index (0:a:N).
+    detailed: also run an ebur128 pass for max momentary / max short-term.
+    """
+    ffmpeg = _ffmpeg_path()
+
+    version = ffmpeg_version(ffmpeg)
+    major = re.match(r"(\d+)", version)
+    if major and int(major.group(1)) < MIN_FFMPEG_MAJOR:
+        raise AnalysisError(
+            f"Error: ffmpeg {version} is below the supported minimum "
+            f"({MIN_FFMPEG_MAJOR}.0); loudnorm measurement behavior is "
+            "not verified on older releases")
+
+    info = _probe(path, ffmpeg)
+    if not info.get("has_audio"):
+        raise AnalysisError("Error: no audio stream found")
+    n_streams = info.get("audio_streams", 1)
+    if stream >= n_streams:
+        raise AnalysisError(
+            f"Error: audio stream {stream} not found "
+            f"(file has {n_streams} audio stream(s))")
+
+    r = subprocess.run(
+        [ffmpeg, "-hide_banner", "-nostats", "-i", path,
+         "-map", f"0:a:{stream}",
+         "-af", "loudnorm=print_format=json",
+         "-f", "null", "-"],
+        capture_output=True, text=True)
+    # loudnorm prints its JSON block to stderr after processing.
+    m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", r.stderr, re.S)
+    if not m:
+        raise AnalysisError(
+            "Error: ffmpeg loudnorm produced no measurement "
+            f"(ffmpeg exit {r.returncode})")
+    data = json.loads(m.group(0))
+
+    def f(key: str) -> float:
+        v = data.get(key)
+        if v in (None, "-inf", "inf"):
+            raise AnalysisError(
+                f"Error: measurement '{key}' unavailable (silent or "
+                "too-short audio?)")
+        return float(v)
+
+    max_m = max_s = None
+    if detailed:
+        max_m, max_s = _detailed_pass(ffmpeg, path, stream)
+
+    return Measurement(
+        integrated=f("input_i"),
+        lra=f("input_lra"),
+        true_peak=f("input_tp"),
+        threshold=f("input_thresh"),
+        sample_rate=info.get("sample_rate"),
+        channels=info.get("channels"),
+        duration_seconds=info.get("duration"),
+        ffmpeg_version=version,
+        stream_index=stream,
+        max_momentary=max_m,
+        max_short_term=max_s,
+    )

loudcheck-0.3.0/loudcheck/cli.py

@@ -0,0 +1,159 @@
+"""
+loudcheck CLI — one engine, two surfaces (this and mcp_server.py).
+
+Exit codes (agent contract): 0 = pass (or "measured" for gate-free
+standards like BS_1770), 1 = fail — in batch mode, any fail,
+2 = error (missing file, no audio, no ffmpeg, unknown standard).
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.resources
+import json
+import sys
+from pathlib import Path
+
+from .analyze import AnalysisError, audio_stream_count, measure
+from .standards import STANDARDS
+from .verdict import check
+
+MEDIA_EXTS = {".wav", ".mp3", ".m4a", ".aac", ".flac", ".ogg", ".opus",
+              ".mp4", ".mov", ".mkv", ".mka", ".webm", ".mxf", ".ts", ".aiff"}
+
+
+def tool_schema() -> str:
+    """The machine-readable tool definition, shipped inside the package
+    (the repo-root tool.json is a synced copy for agents browsing GitHub)."""
+    return importlib.resources.files("loudcheck").joinpath(
+        "tool.json").read_text(encoding="utf-8")
+
+
+def human(result: dict) -> str:
+    lines = [f"{result['verdict'].upper()} — {result['standard_name']}"]
+    m = result["metrics"]
+
+    integ = m["integrated"]
+    if integ.get("informational"):
+        lines.append(f"  · integrated {integ['measured']:.1f} {integ['unit']}")
+    else:
+        mark = "✓" if integ["pass"] else "✗"
+        lines.append(
+            f"  {mark} integrated {integ['measured']:.1f} {integ['unit']} "
+            f"(target {integ['target']:.1f} ±{integ['tolerance']}, "
+            f"delta {integ['delta']:+.1f})")
+
+    tp = m["true_peak"]
+    if tp.get("informational"):
+        lines.append(f"  · true peak {tp['measured']:.1f} dBTP")
+    else:
+        mark = "✓" if tp["pass"] else "✗"
+        lines.append(
+            f"  {mark} true peak {tp['measured']:.1f} dBTP (max {tp['max']:.1f})")
+
+    lines.append(f"  · LRA {m['lra']['measured']:.1f} LU (informational)")
+    for key, label in (("max_momentary", "max momentary"),
+                       ("max_short_term", "max short-term")):
+        if key in m:
+            lines.append(
+                f"  · {label} {m[key]['measured']:.1f} {m[key]['unit']}")
+    for r in result["remediation"]:
+        lines.append(f"  → {r}")
+    return "\n".join(lines)
+
+
+def expand_targets(paths: list[str]) -> list[str]:
+    """Files stay files; a directory expands to its media files (sorted)."""
+    out: list[str] = []
+    for p in paths:
+        pp = Path(p)
+        if pp.is_dir():
+            out.extend(sorted(
+                str(f) for f in pp.iterdir()
+                if f.suffix.lower() in MEDIA_EXTS and f.is_file()))
+        else:
+            out.append(p)
+    return out
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        prog="loudcheck",
+        description="Loudness compliance verdict against formal published "
+                    "standards (EBU R128, ATSC A/85, BS.1770 measure-only).")
+    p.add_argument("files", nargs="*",
+                   help="media file(s) or a directory (batch mode)")
+    p.add_argument("--schema", action="store_true",
+                   help="print the machine-readable tool definition "
+                        "(tool.json) and exit")
+    p.add_argument("--standard", default="EBU_R128",
+                   choices=sorted(STANDARDS),
+                   help="standard to verdict against (default: EBU_R128)")
+    p.add_argument("--stream", type=int, default=0,
+                   help="audio stream index to check (default: 0)")
+    p.add_argument("--all-streams", action="store_true",
+                   help="verdict every audio stream in the file")
+    p.add_argument("--detailed", action="store_true",
+                   help="add max momentary / max short-term (extra ffmpeg pass)")
+    p.add_argument("--json", action="store_true",
+                   help="emit the full verdict JSON")
+    args = p.parse_args(argv)
+
+    if args.schema:
+        print(tool_schema())
+        return 0
+    if not args.files:
+        p.error("files required (or --schema)")
+
+    targets = expand_targets(args.files)
+    if not targets:
+        print("Error: no media files found", file=sys.stderr)
+        return 2
+
+    results = []
+    try:
+        for path in targets:
+            if args.all_streams:
+                n = audio_stream_count(path)
+                if n == 0:
+                    raise AnalysisError("Error: no audio stream found")
+                for s in range(n):
+                    r = check(measure(path, stream=s, detailed=args.detailed),
+                              args.standard)
+                    r["file"] = path
+                    results.append(r)
+            else:
+                r = check(measure(path, stream=args.stream,
+                                  detailed=args.detailed), args.standard)
+                r["file"] = path
+                results.append(r)
+    except (AnalysisError, ValueError) as e:
+        print(str(e), file=sys.stderr)
+        return 2
+
+    batch = len(results) > 1
+    if args.json:
+        print(json.dumps(results if batch else results[0], indent=2))
+    elif batch:
+        # table: one line per file/stream
+        for r in results:
+            m = r["metrics"]
+            stream = r["measurement_context"]["audio_stream"]
+            tag = f"{r['file']}" + (f" [a:{stream}]" if args.all_streams else "")
+            lines = [f"{r['verdict'].upper():8} {tag}  "
+                     f"I {m['integrated']['measured']:.1f} "
+                     f"TP {m['true_peak']['measured']:.1f}"]
+            for rem in r["remediation"]:
+                lines.append(f"         → {rem}")
+            print("\n".join(lines))
+        n_fail = sum(1 for r in results if r["verdict"] == "fail")
+        print(f"-- {len(results)} checked, "
+              f"{len(results) - n_fail} pass, {n_fail} fail")
+    else:
+        print(human(results[0]))
+
+    return 1 if any(r["verdict"] == "fail" for r in results) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

loudcheck-0.3.0/loudcheck/mcp_server.py

@@ -0,0 +1,57 @@
+"""
+MCP surface — thin wrapper over the same engine the CLI uses (P0.6).
+
+Register as a stdio MCP server:
+    python -m loudcheck.mcp_server
+Import path verified against mcp==1.28.1.
+"""
+
+from mcp.server.fastmcp import FastMCP
+
+from .analyze import AnalysisError, measure
+from .standards import STANDARDS
+from .verdict import check
+
+mcp = FastMCP("loudcheck")
+
+
+@mcp.tool()
+def check_loudness(path: str, standard: str = "EBU_R128",
+                   stream: int = 0, detailed: bool = False) -> dict:
+    """
+    Loudness compliance verdict for a media file against a formal published
+    standard. Measures integrated loudness, loudness range, and true peak
+    (via ffmpeg), then evaluates them against the named standard's targets
+    and tolerances.
+
+    Args:
+        path: media file to check (any format ffmpeg can read).
+        standard: EBU_R128 (broadcast, -23 LUFS), ATSC_A85 (US TV, -24 LKFS),
+            or BS_1770 (measurement only — verdict "measured", no gates).
+        stream: zero-based audio stream index for multi-track files.
+        detailed: also report max momentary / max short-term loudness
+            (one extra ffmpeg pass).
+
+    Returns:
+        dict with: verdict (pass|fail|measured), per-metric
+        measured/target/delta and pass booleans, failures (plain-English
+        causes), remediation (exact corrections, e.g. "apply -2.3 LU gain"),
+        and measurement_context (ffmpeg version, stream info).
+    """
+    try:
+        result = check(measure(path, stream=stream, detailed=detailed), standard)
+        result["file"] = path  # echoed for batch-calling agents; matches CLI JSON
+        return result
+    except (AnalysisError, ValueError) as e:
+        return {"verdict": "error", "error": str(e), "file": path}
+
+
+@mcp.tool()
+def list_standards() -> dict:
+    """List the standards this tool can verdict against, with their targets,
+    tolerances, and spec citations."""
+    return {"standards": STANDARDS}
+
+
+if __name__ == "__main__":
+    mcp.run()