loudcheck 0.3.0__py3-none-any.whl

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/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/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/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()

loudcheck/standards.py

@@ -0,0 +1,94 @@
+"""
+Standards catalog — PURE DATA, no logic.
+
+Every entry cites the published spec text it encodes. Only formal, stable
+standards belong here; per-platform delivery templates (Netflix/DPP/...)
+are explicitly out of scope — see the scope guardrail in the README. A
+standard is: targets + tolerances + citations. Nothing else.
+
+Verified against published text on 2026-07-02:
+- EBU R 128 (v4, 2020): "the Programme Loudness Level shall be normalised
+  to a Target Level of -23.0 LUFS. The deviation from the Target Level
+  shall not exceed +/-0.5 LU" ... "The Maximum Permitted True Peak Level
+  of a programme during production shall be -1 dBTP." R 128 sets NO hard
+  limit on Loudness Range; LRA is reported as informational.
+  https://tech.ebu.ch/docs/r/r128.pdf
+- ATSC A/85:2013 (§5.4, §5.5): "the Target Loudness value should be
+  -24 LKFS. Minor measurement variations of up to approximately +/-2 dB
+  about this value are anticipated, due to measurement uncertainty, and
+  are acceptable" ... "The true-peak level should be kept below -2 dB TP
+  in order to provide headroom to avoid potential clipping due to
+  downstream processing."
+  https://www.atsc.org/atsc-documents/a85-techniques-for-establishing-and-maintaining-audio-loudness-for-digital-television/
+"""
+
+STANDARDS = {
+    "EBU_R128": {
+        "name": "EBU R 128",
+        "citation": "EBU R 128 (https://tech.ebu.ch/docs/r/r128.pdf)",
+        "unit": "LUFS",
+        "metrics": {
+            "integrated": {
+                "target": -23.0,
+                "tolerance": 0.5,   # LU; R128 permits ±1.0 for live programmes
+                "gated": True,
+                "citation": "R 128: Target Level -23.0 LUFS, deviation shall not exceed ±0.5 LU",
+            },
+            "true_peak": {
+                "max": -1.0,        # dBTP
+                "gated": True,
+                "citation": "R 128: Maximum Permitted True Peak Level -1 dBTP",
+            },
+            "lra": {
+                "gated": False,     # R128 core sets no LRA limit — informational
+                "citation": "R 128 defines LRA measurement (EBU Tech 3342) but sets no limit",
+            },
+        },
+    },
+    "BS_1770": {
+        # Measure-only base mode: ITU-R BS.1770 defines the MEASUREMENT
+        # algorithm (K-weighted loudness, true peak, gating) but sets no
+        # compliance target — so this entry gates nothing and the verdict is
+        # "measured", not pass/fail. This is deliberately NOT a place to
+        # invent targets; see the scope guardrail.
+        "name": "ITU-R BS.1770 (measurement only)",
+        "citation": "ITU-R BS.1770-5 (https://www.itu.int/rec/R-REC-BS.1770)",
+        "unit": "LUFS",
+        "metrics": {
+            "integrated": {
+                "gated": False,
+                "citation": "BS.1770 defines measurement; no compliance target exists in the spec",
+            },
+            "true_peak": {
+                "gated": False,
+                "citation": "BS.1770 Annex 2 defines true-peak measurement; no limit exists in the spec",
+            },
+            "lra": {
+                "gated": False,
+                "citation": "LRA per EBU Tech 3342; informational",
+            },
+        },
+    },
+    "ATSC_A85": {
+        "name": "ATSC A/85:2013",
+        "citation": "ATSC A/85:2013 (https://www.atsc.org/atsc-documents/a85-techniques-for-establishing-and-maintaining-audio-loudness-for-digital-television/)",
+        "unit": "LKFS",
+        "metrics": {
+            "integrated": {
+                "target": -24.0,
+                "tolerance": 2.0,   # dB; A/85 §5.4 "variations of up to approximately ±2 dB ... are acceptable"
+                "gated": True,
+                "citation": "A/85: Target Loudness -24 LKFS, ±2 dB measurement variation acceptable",
+            },
+            "true_peak": {
+                "max": -2.0,        # dBTP
+                "gated": True,
+                "citation": "A/85: true-peak level should be kept below -2 dBTP",
+            },
+            "lra": {
+                "gated": False,
+                "citation": "A/85 sets no loudness-range limit — informational",
+            },
+        },
+    },
+}

loudcheck/tool.json

@@ -0,0 +1,35 @@
+{
+  "name": "loudcheck",
+  "description": "Loudness compliance verdict against formal published standards (EBU R128, ATSC A/85). Measures integrated loudness, loudness range, and true peak via ffmpeg, returns pass/fail with per-metric deltas and exact remediation — a compliance answer, not raw meter output.",
+  "usage": "loudcheck <file> [--standard EBU_R128|ATSC_A85] [--json] | loudcheck --schema",
+  "requires": "ffmpeg >= 5.0 on PATH",
+  "exit_codes": {
+    "0": "pass — file complies with the standard",
+    "1": "fail — non-compliant; remediation included in output",
+    "2": "error — missing file, no audio stream, ffmpeg absent, unknown standard"
+  },
+  "output": {
+    "json_flag": "--json emits the full verdict object on stdout",
+    "shape": {
+      "verdict": "pass | fail",
+      "standard": "standard id",
+      "metrics": "integrated {measured,target,tolerance,delta,pass,citation}, true_peak {measured,max,delta,pass,citation}, lra {measured,informational}",
+      "failures": "plain-English causes, one per failed metric",
+      "remediation": "exact corrections, e.g. 'apply -2.3 LU gain ... loudnorm I=-23'",
+      "measurement_context": "ffmpeg_version, sample_rate, channels, duration_seconds, gating_threshold"
+    },
+    "errors": "Error:-prefixed text on stderr, never a traceback"
+  },
+  "mcp": {
+    "server": "python -m loudcheck.mcp_server",
+    "transport": "stdio",
+    "tools": [
+      "check_loudness(path, standard='EBU_R128') -> verdict dict (identical to CLI --json)",
+      "list_standards() -> catalog with targets, tolerances, citations"
+    ]
+  },
+  "scope": {
+    "in": "formal, stable standards only (EBU R128, ATSC A/85; PRs adding formal standards welcome as pure data)",
+    "out": "per-platform delivery templates (Netflix/DPP/...), loudness correction, full-file QC, real-time monitoring"
+  }
+}

loudcheck/verdict.py

@@ -0,0 +1,134 @@
+"""
+Verdict engine — evaluate a Measurement against a named standard.
+
+Output contract (P0.3, P0.4): a JSON-serializable dict with a top-level
+verdict, per-metric measured/target/tolerance/delta/pass, and — on any
+fail — concrete remediation text with the exact correction (e.g. "apply
+-2.3 LU gain"). Gain remediation maps directly onto ffmpeg's loudnorm/volume
+filters; this tool never applies it (measurement and verdict only).
+
+Gating is data-driven from the standards catalog: a metric only gates the
+verdict if its catalog entry says `gated: True`. A standard with no gated
+metrics (BS_1770) yields verdict "measured" — measurement without judgment,
+because the spec defines no target to judge against.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .analyze import Measurement
+from .standards import STANDARDS
+
+
+def check(measurement: Measurement, standard: str) -> dict[str, Any]:
+    if standard not in STANDARDS:
+        raise ValueError(
+            f"Error: unknown standard '{standard}' "
+            f"(available: {', '.join(sorted(STANDARDS))})")
+    spec = STANDARDS[standard]
+    unit = spec["unit"]
+    metrics: dict[str, Any] = {}
+    failures: list[str] = []
+    remediation: list[str] = []
+    any_gate = False
+
+    # --- integrated loudness (gate: target ± tolerance) ---------------------
+    integ = spec["metrics"]["integrated"]
+    entry: dict[str, Any] = {
+        "measured": round(measurement.integrated, 2),
+        "unit": unit,
+        "citation": integ["citation"],
+    }
+    if integ["gated"]:
+        any_gate = True
+        delta = round(measurement.integrated - integ["target"], 2)
+        integ_pass = abs(delta) <= integ["tolerance"]
+        entry.update(target=integ["target"], tolerance=integ["tolerance"],
+                     delta=delta)
+        entry["pass"] = integ_pass
+        if not integ_pass:
+            direction = "over" if delta > 0 else "under"
+            failures.append(
+                f"integrated loudness {measurement.integrated:.1f} {unit} is "
+                f"{abs(delta):.1f} LU {direction} target {integ['target']:.1f}")
+            remediation.append(
+                f"apply {-delta:+.1f} LU gain to reach {integ['target']:.1f} "
+                f"{unit} (e.g. ffmpeg -af volume={-delta:.1f}dB, or loudnorm "
+                f"I={integ['target']:.0f})")
+    else:
+        entry["pass"] = True
+        entry["informational"] = True
+    metrics["integrated"] = entry
+
+    # --- true peak (gate: hard maximum) --------------------------------------
+    tp = spec["metrics"]["true_peak"]
+    entry = {
+        "measured": round(measurement.true_peak, 2),
+        "unit": "dBTP",
+        "citation": tp["citation"],
+    }
+    if tp["gated"]:
+        any_gate = True
+        overage = round(measurement.true_peak - tp["max"], 2)
+        tp_pass = measurement.true_peak <= tp["max"]
+        entry.update(max=tp["max"], delta=overage)
+        entry["pass"] = tp_pass
+        if not tp_pass:
+            failures.append(
+                f"true peak {measurement.true_peak:.1f} dBTP exceeds the "
+                f"{tp['max']:.1f} dBTP limit by {overage:.1f} dB")
+            remediation.append(
+                f"reduce peaks by at least {overage:.1f} dB (a "
+                f"{-overage:.1f} dB gain reduction, or a true-peak limiter at "
+                f"{tp['max']:.1f} dBTP)")
+    else:
+        entry["pass"] = True
+        entry["informational"] = True
+    metrics["true_peak"] = entry
+
+    # --- loudness range (informational unless a standard gates it) -----------
+    lra = spec["metrics"]["lra"]
+    metrics["lra"] = {
+        "measured": round(measurement.lra, 2),
+        "unit": "LU",
+        "pass": True,
+        "informational": not lra["gated"],
+        "citation": lra["citation"],
+    }
+
+    # --- optional detailed metrics (P1.3) -------------------------------------
+    if measurement.max_momentary is not None:
+        metrics["max_momentary"] = {
+            "measured": round(measurement.max_momentary, 2),
+            "unit": unit, "pass": True, "informational": True,
+            "citation": "max momentary loudness (400 ms window), diagnostic",
+        }
+    if measurement.max_short_term is not None:
+        metrics["max_short_term"] = {
+            "measured": round(measurement.max_short_term, 2),
+            "unit": unit, "pass": True, "informational": True,
+            "citation": "max short-term loudness (3 s window), diagnostic",
+        }
+
+    if not any_gate:
+        verdict = "measured"
+    else:
+        verdict = "pass" if not failures else "fail"
+    return {
+        "verdict": verdict,
+        "standard": standard,
+        "standard_name": spec["name"],
+        "citation": spec["citation"],
+        "metrics": metrics,
+        "failures": failures,
+        "remediation": remediation,
+        "measurement_context": {
+            "ffmpeg_version": measurement.ffmpeg_version,
+            "audio_stream": measurement.stream_index,
+            "sample_rate": measurement.sample_rate,
+            "channels": measurement.channels,
+            "duration_seconds": measurement.duration_seconds,
+            "gating_threshold": measurement.threshold,
+        },
+    }

loudcheck-0.3.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+loudcheck/__init__.py,sha256=vJwKa9Ys9d1DOpCiaP1R-480VmPn-EWfV-zl2i-13GM,271
+loudcheck/analyze.py,sha256=-Mo8NI_0pBnxckDw4xH0aTM7k9NxKrFb8sN7Vo8QEr0,6518
+loudcheck/cli.py,sha256=Kw3uYbzlpJ1aj6fUbzIvH7kZkNVIjVIaXoMT4lbZdIs,5939
+loudcheck/mcp_server.py,sha256=9UwqTRtLrAVmcfET6BXbNCKMvBRBXDU_BnkJmxlvAZE,2003
+loudcheck/standards.py,sha256=-BxUc1IGbuJRZxbSofZf90UwPgXUh_IElx1FyX0eWuE,4173
+loudcheck/tool.json,sha256=oC9GnA7-VSIfTK-GGn_GFclcYsuGJpG9x1NJ2IdODGo,1853
+loudcheck/verdict.py,sha256=kiXq6gPCMOiudAfOOXfWT3PT7OpPGGaUIrDYBlG9Bt8,5206
+loudcheck-0.3.0.dist-info/licenses/LICENSE,sha256=IR3NcBta7PqYBrYZxTwEOvVeWeqBJLk7IRiZ-LnqQMA,1064
+loudcheck-0.3.0.dist-info/METADATA,sha256=3Lt772pL40P9r7ZqCvY_RgbEUhEvrN85jlQz8qVf7No,6246
+loudcheck-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+loudcheck-0.3.0.dist-info/entry_points.txt,sha256=MC4t7DjSPczcG2XC79HuIw3EedvvgECC2Exnv3hl63I,49
+loudcheck-0.3.0.dist-info/top_level.txt,sha256=2J7bj-M6rxZ9Sptljbz2ss2AJVIF_R5L-GK2Mzix_dY,10
+loudcheck-0.3.0.dist-info/RECORD,,

loudcheck-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

loudcheck-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+loudcheck = loudcheck.cli:main

loudcheck-0.3.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+loudcheck