wizz-method 2.11.2 → 2.13.0

package/src/skills-lib/wizz-video-effects/scripts/budget.py

@@ -0,0 +1,211 @@
+# -*- coding: utf-8 -*-
+"""Anti-excess engine: effects compete for a budget instead of all entering.
+
+Why it exists. A rule like "zoom punch on every SFX with vol >= 0.5" fired on
+almost every SFX of the source project (one zoom every 2.5s on the busiest
+pieces). An effect that always happens stops marking what matters.
+
+This module does not decide IF a SFX asks for an effect (that is `triggers`
+in the sound config) nor HOW the effect is drawn. It only decides WHICH
+candidates, from a list that already arrived too long, earn the right to
+appear: by narrative strength first, then a ceiling per curve section, a
+minimum distance between repeats of the same kind, a minimum global distance
+between dominant effects, and a limit on same-kind effects in a burst.
+
+Usage:
+    from budget import Candidate, select
+    res = select([Candidate(t=3.2, kind="punch", strength=0.8, reason="verdict")],
+                 total=55.0, cfg=cfg)
+    print(res.report())
+"""
+from __future__ import annotations
+
+from bisect import bisect_left, insort
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from config import Config, CurveSection
+
+
+@dataclass(frozen=True)
+class Candidate:
+    """An effect asking for a place in the timeline."""
+    t: float
+    kind: str        # key of budget.per_effect: punch, flash, shake, interrupt, transition
+    strength: float  # 0..1, narrative claim
+    reason: str      # short human-readable why
+
+
+@dataclass(frozen=True)
+class Refusal:
+    candidate: Candidate
+    rule: str        # "gap_min" | "gap_min_global" | "max_in_row" | "ceiling" | "unknown_kind"
+    detail: str
+
+
+@dataclass(frozen=True)
+class Result:
+    accepted: tuple[Candidate, ...]   # always sorted by t
+    refusals: tuple[Refusal, ...]
+
+    def by_kind(self) -> dict[str, int]:
+        count: dict[str, int] = {}
+        for c in self.accepted:
+            count[c.kind] = count.get(c.kind, 0) + 1
+        return count
+
+    def report(self) -> str:
+        lines = [f"accepted: {len(self.accepted)}   refused: {len(self.refusals)}"]
+        if self.accepted:
+            lines.append("by kind:")
+            for kind, n in self.by_kind().items():
+                lines.append(f"  {kind:<10} {n}")
+        if self.refusals:
+            lines.append("refusals:")
+            for r in self.refusals:
+                lines.append(f"  t={r.candidate.t:6.1f}s {r.candidate.kind:<10} "
+                             f"[{r.rule}] {r.detail}")
+        return "\n".join(lines)
+
+
+def _durations_and_weights(cfg: Config, total: float) -> list[tuple[str, float, float]]:
+    """Seconds of each curve section with its weight. The curve stores
+    CUMULATIVE fractions: a section runs from the previous until_frac to its own."""
+    out = []
+    prev = 0.0
+    for s in cfg.budget.curve:
+        out.append((s.name, (s.until_frac - prev) * total, s.weight))
+        prev = s.until_frac
+    return out
+
+
+def section_ceiling(cfg: Config, kind: str, section: CurveSection, total: float) -> int:
+    """How many `kind` events fit in this section.
+
+    The whole-piece ceiling (budget.ceiling, from max_per_min) is SPLIT across
+    the sections in proportion to duration * weight. A heavier section gets a
+    bigger slice of the SAME total; it never invents a new ceiling:
+
+        slice = total_ceiling * (dur * weight) / sum(dur_i * weight_i)
+
+    Rounded to the nearest integer. A short section may round to 0: there is
+    no per-section floor, only the whole-piece floor of 1.
+    """
+    total_ceiling = cfg.budget.ceiling(kind, total)
+    parts = _durations_and_weights(cfg, total)
+    weighted = sum(d * w for _, d, w in parts)
+    if weighted <= 0:
+        return total_ceiling
+    dur, weight = next((d, w) for name, d, w in parts if name == section.name)
+    return round(total_ceiling * (dur * weight) / weighted)
+
+
+def _nearest_gap(times: list[float], t: float) -> float | None:
+    """Distance to the nearest neighbour in a sorted list; None when empty."""
+    if not times:
+        return None
+    i = bisect_left(times, t)
+    near = []
+    if i > 0:
+        near.append(t - times[i - 1])
+    if i < len(times):
+        near.append(times[i] - t)
+    return min(near)
+
+
+def _in_row_if_inserted(accepted: list[Candidate], pos: int, kind: str,
+                        t: float, burst_gap: float) -> int:
+    """How many same-kind events would sit in the SAME BURST if a candidate
+    entered at `pos` of a list sorted by t.
+
+    Counted on the FINAL ORDER BY TIME, never on processing order (which is by
+    strength): a candidate accepted early for its strength can end up
+    surrounded, in time, by same-kind neighbours accepted later.
+
+    `burst_gap` separates bursts. Without it, "in a row" would span the whole
+    piece and a third punch 20s after the second would fail max_in_row=2,
+    cancelling the per-piece ceiling. A rule that cancels another rule of the
+    same module is wrong.
+    """
+    back, i, prev = 0, pos - 1, t
+    while i >= 0 and accepted[i].kind == kind and prev - accepted[i].t <= burst_gap:
+        back, prev, i = back + 1, accepted[i].t, i - 1
+    fwd, i, nxt = 0, pos, t
+    while i < len(accepted) and accepted[i].kind == kind and accepted[i].t - nxt <= burst_gap:
+        fwd, nxt, i = fwd + 1, accepted[i].t, i + 1
+    return back + fwd + 1
+
+
+def as_candidate(c) -> Candidate:
+    """Accept a Candidate or a dict with the same keys (sound.py emits dicts
+    on purpose, so the two modules stay independent). A missing key fails
+    here with its name, not later mid-selection."""
+    if isinstance(c, Candidate):
+        return c
+    try:
+        return Candidate(t=float(c["t"]), kind=str(c["kind"]),
+                         strength=float(c["strength"]), reason=str(c.get("reason", "")))
+    except (KeyError, TypeError) as e:
+        raise TypeError(
+            f"invalid candidate: {c!r}. Expected a Candidate or a dict with keys "
+            f"t, kind, strength (reason optional). Missing or wrong: {e}") from e
+
+
+def _check(cand: Candidate, cfg: Config, total: float, state: dict) -> tuple[str, str] | None:
+    """The first rule the candidate breaks, as (rule, detail), or None."""
+    rule = cfg.budget.rule(cand.kind)
+    if rule is None:
+        return "unknown_kind", (f"kind {cand.kind!r} is not in budget.per_effect. "
+                                f"Known: {', '.join(sorted(cfg.budget.per_effect))}")
+    sec = cfg.budget.section(cand.t, total)
+    cap = section_ceiling(cfg, cand.kind, sec, total)
+    used = state["per_section"].get((cand.kind, sec.name), 0)
+    if used >= cap:
+        return "ceiling", f"section {sec.name!r} of {cand.kind} already has {used} of {cap} allowed"
+    gap = _nearest_gap(state["times"].get(cand.kind, []), cand.t)
+    if gap is not None and gap < rule.gap_min:
+        return "gap_min", f"gap {gap:.1f}s < {rule.gap_min:.1f}s required for {cand.kind}"
+    if rule.dominant:
+        g = _nearest_gap(state["dominant"], cand.t)
+        if g is not None and g < cfg.budget.gap_min_global:
+            return "gap_min_global", (f"gap {g:.1f}s < {cfg.budget.gap_min_global:.1f}s "
+                                      f"required between dominant effects")
+    pos = bisect_left([c.t for c in state["accepted"]], cand.t)
+    row = _in_row_if_inserted(state["accepted"], pos, cand.kind, cand.t, cfg.budget.burst_gap_s)
+    if row > rule.max_in_row:
+        return "max_in_row", (f"{row} {cand.kind} in one burst (burst gap "
+                              f"{cfg.budget.burst_gap_s}s) > {rule.max_in_row} allowed")
+    return None
+
+
+def select(candidates: Iterable[Candidate | dict], total: float, cfg: Config) -> Result:
+    """Decide which candidates enter, by these rules in order:
+
+    1. Process by decreasing strength (tie: increasing t): the strongest
+       narrative claim picks its place first. PRIORITY is by strength;
+       final ACCEPTANCE is read in time order.
+    2. Unknown kind is never accepted silently.
+    3. Ceiling per curve section (see `section_ceiling`).
+    4. gap_min of the kind against accepted events of the SAME kind.
+    5. gap_min_global against accepted DOMINANT events of any kind (a
+       non-dominant candidate is not held by this rule).
+    6. max_in_row, measured on the final timeline sorted by t.
+
+    Deterministic: same input, same Result (no sets, no hash order, no random).
+    """
+    ordered = sorted((as_candidate(c) for c in candidates), key=lambda c: (-c.strength, c.t))
+    state = {"accepted": [], "per_section": {}, "times": {}, "dominant": []}
+    refusals: list[Refusal] = []
+    for cand in ordered:
+        broken = _check(cand, cfg, total, state)
+        if broken:
+            refusals.append(Refusal(cand, *broken))
+            continue
+        pos = bisect_left([c.t for c in state["accepted"]], cand.t)
+        state["accepted"].insert(pos, cand)
+        key = (cand.kind, cfg.budget.section(cand.t, total).name)
+        state["per_section"][key] = state["per_section"].get(key, 0) + 1
+        insort(state["times"].setdefault(cand.kind, []), cand.t)
+        if cfg.budget.rule(cand.kind).dominant:
+            insort(state["dominant"], cand.t)
+    return Result(accepted=tuple(state["accepted"]), refusals=tuple(refusals))

package/src/skills-lib/wizz-video-effects/scripts/check_excess.py

@@ -0,0 +1,218 @@
+# -*- coding: utf-8 -*-
+"""EXCESS gate: measures what the other gates do not.
+
+Why it exists. Every other gate measures a LACK (of density, of anchor, of
+room inside the safe zone). None measured the opposite: an audit counted one
+zoom punch every 2.5s on the busiest pieces and no gate said anything. This
+script counts the real effects of a timeline JSON and fails when they exceed
+the budget in the config (`budget`).
+
+Timeline keys read (see references/data-contract.md; all may be absent):
+    punches, shakes, flashes   numbers or objects {"at": ...}
+    interrupts                 objects {"at": ..., "kind": ...}
+    scenes                     a scene with `transition` other than "" or
+                               "cut" counts as a transition event
+    duration                   if absent, derived from the scenes (and said)
+    sfx, scenes[].sfx          every sound, checked TOGETHER against the three
+                               refusals of sound.map_requests (unknown event,
+                               collision, same sound too many times in a row)
+
+Per effect kind it reports: count and per minute against the piece ceiling
+(budget.ceiling), smallest gap against gap_min, longest run of same-kind
+events closer than gap_min against max_in_row, and pairs of DIFFERENT dominant
+kinds closer than gap_min_global. It always reports the largest cluster of
+dominant effects in a CLUSTER_WINDOW_S window: it is what the viewer sees.
+
+Exit code: 0 pass, 1 fail, 2 usage error or missing file. --warn measures and
+always exits 0 (use it only while calibrating; the gate is meant to block).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from config import Budget, Config, ConfigError, add_config_arg, load
+import sound
+import timeline as tl
+
+# Report window for the largest cluster. A display choice, not a rule: the
+# span a viewer perceives at once.
+CLUSTER_WINDOW_S = 10.0
+
+
+def smallest_gap(times: list[float]) -> tuple[float | None, float | None]:
+    """(gap, instant of the first of the pair), or (None, None) with < 2 events."""
+    if len(times) < 2:
+        return None, None
+    a, b = min(zip(times, times[1:]), key=lambda p: p[1] - p[0])
+    return b - a, a
+
+
+def longest_run(times: list[float], gap_min: float) -> tuple[int, float | None]:
+    """Longest run where each consecutive pair is closer than gap_min. Reuses
+    gap_min as the only threshold the config gives for 'glued'."""
+    if not times:
+        return 0, None
+    best = cur = 1
+    cur_start = best_start = times[0]
+    for a, b in zip(times, times[1:]):
+        if b - a < gap_min:
+            cur += 1
+        else:
+            cur, cur_start = 1, b
+        if cur > best:
+            best, best_start = cur, cur_start
+    return best, best_start
+
+
+def _dominant(events: dict[str, list[float]], budget: Budget) -> list[tuple[float, str]]:
+    return sorted((t, kind) for kind, lst in events.items() for t in lst
+                  if (r := budget.rule(kind)) and r.dominant)
+
+
+def dominant_crossings(events: dict[str, list[float]], budget: Budget) -> list[tuple]:
+    """Pairs of DIFFERENT dominant kinds closer than gap_min_global. The
+    per-kind gap only guards repeats of the SAME kind; a punch glued to a
+    shake passes both and still overloads the same instant."""
+    marked = _dominant(events, budget)
+    found = []
+    for i, (ta, ka) in enumerate(marked):
+        for tb, kb in marked[i + 1:]:
+            dt = tb - ta
+            if dt >= budget.gap_min_global:
+                break
+            if ka != kb:
+                found.append((ta, ka, tb, kb, dt))
+    return found
+
+
+def largest_cluster(events: dict[str, list[float]], budget: Budget,
+                    window: float = CLUSTER_WINDOW_S) -> tuple[int, float | None]:
+    """Window of `window` seconds with the most dominant effects (two pointers)."""
+    dom = [t for t, _ in _dominant(events, budget)]
+    if not dom:
+        return 0, None
+    best_n, best_t, j = 1, dom[0], 0
+    for i in range(len(dom)):
+        while dom[i] - dom[j] >= window:
+            j += 1
+        if i - j + 1 > best_n:
+            best_n, best_t = i - j + 1, dom[j]
+    return best_n, best_t
+
+
+def _kind_row(kind: str, times: list[float], total: float, cfg: Config) -> tuple[dict, list[str]]:
+    rule = cfg.budget.rule(kind)
+    n = len(times)
+    per_min = (n / total * 60.0) if total > 0 else 0.0
+    ceiling = cfg.budget.ceiling(kind, total)
+    gap, gap_at = smallest_gap(times)
+    run, run_at = longest_run(times, rule.gap_min)
+    row = {"kind": kind, "n": n, "per_min": per_min, "ceiling": ceiling,
+           "gap_measured": gap, "gap_required": rule.gap_min,
+           "run_measured": run, "run_allowed": rule.max_in_row}
+    errs = []
+    if n > ceiling:
+        errs.append(f"{kind}: {n} event(s) > ceiling of {ceiling} for {total:.1f}s "
+                    f"({per_min:.1f}/min, limit budget.per_effect.{kind}.max_per_min="
+                    f"{rule.max_per_min:g})")
+    if gap is not None and gap < rule.gap_min:
+        errs.append(f"{kind}: gap of {gap:.2f}s at {gap_at:.2f}s < gap_min {rule.gap_min:.1f}s")
+    if run > rule.max_in_row:
+        errs.append(f"{kind}: {run} in a row from {run_at:.2f}s > max_in_row {rule.max_in_row}")
+    return row, errs
+
+
+def sound_violations(data: dict, cfg: Config) -> list[str]:
+    """The three sound refusals of sound.map_requests, applied to EVERY sound
+    in the timeline at once (sfx[] plus scene cut sounds). Sounds mapped in
+    separate passes can each be fine alone and still collide together."""
+    requests, errs = [], []
+    for s in tl.sounds(data):
+        ev = sound.event_of(s, cfg)
+        if ev is None:
+            errs.append(f"sound {s.get('src', '?')}@{float(s['at']):.2f}s refused "
+                        f"(unknown_event): no `event` and no unique (file, vol) match in "
+                        f"sound.events")
+            continue
+        requests.append((float(s["at"]), ev))
+    for r in sound.map_requests(requests, cfg).refusals:
+        errs.append(f"sound {r.event}@{r.t:.2f}s refused ({r.rule}): {r.detail}")
+    return errs
+
+
+def analyze(data: dict, name: str, cfg: Config) -> dict:
+    """Measure one timeline and return a structured report. Never prints."""
+    total, derived = tl.duration(data)
+    events = tl.effect_events(data)
+    rows, violations = [], []
+    for kind in cfg.budget.per_effect:
+        row, errs = _kind_row(kind, events.get(kind, []), total, cfg)
+        rows.append(row)
+        violations.extend(errs)
+    for ta, ka, tb, kb, dt in dominant_crossings(events, cfg.budget):
+        violations.append(f"{ka}@{ta:.2f}s glued to {kb}@{tb:.2f}s ({dt:.2f}s) "
+                          f"< gap_min_global {cfg.budget.gap_min_global:.1f}s")
+    violations.extend(sound_violations(data, cfg))
+    n_dom, t_dom = largest_cluster(events, cfg.budget)
+    return {"name": name, "duration": total, "duration_derived": derived, "rows": rows,
+            "cluster": {"n": n_dom, "start": t_dom}, "violations": violations,
+            "passed": not violations}
+
+
+def print_report(rep: dict) -> None:
+    print(f"== excess of {rep['name']} ==")
+    if rep["duration_derived"]:
+        print(f"  warning: no 'duration' in the JSON; derived from scenes: {rep['duration']:.2f}s")
+    print(f"  {'kind':<10} | {'n':>3} | {'per min':>7} | {'cap':>4} | "
+          f"{'min gap':>8} | {'required':>8} | {'in a row':>8}")
+    for r in rep["rows"]:
+        gap = f"{r['gap_measured']:.2f}s" if r["gap_measured"] is not None else "-"
+        print(f"  {r['kind']:<10} | {r['n']:>3} | {r['per_min']:>7.1f} | {r['ceiling']:>4} | "
+              f"{gap:>8} | {r['gap_required']:>7.1f}s | "
+              f"{str(r['run_measured']) + '/' + str(r['run_allowed']):>8}")
+    c = rep["cluster"]
+    if c["start"] is not None:
+        print(f"  largest cluster: {c['n']} dominant effect(s) in {CLUSTER_WINDOW_S:.0f}s "
+              f"from {c['start']:.2f}s")
+    else:
+        print("  largest cluster: no dominant effect in the piece")
+    for v in rep["violations"]:
+        print(f"  ERROR: {v}")
+    print(f"  FAILED: {len(rep['violations'])} excess violation(s)" if rep["violations"]
+          else "  ok: no excess measured")
+    print()
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        description="Excess gate: count effects of timeline JSON(s) against the budget.")
+    add_config_arg(ap)
+    ap.add_argument("timelines", nargs="+", help="timeline JSON path(s)")
+    ap.add_argument("--warn", action="store_true", help="measure but always exit 0")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    args = ap.parse_args(argv)
+    try:
+        cfg = load(args.config)
+        reports = [analyze(tl.load(p), Path(p).stem, cfg) for p in args.timelines]
+    except (ConfigError, tl.TimelineError) as e:
+        print(f"ERROR: {e}")
+        return 2
+    if args.json:
+        print(json.dumps({r["name"]: r for r in reports}, ensure_ascii=False, indent=2))
+    else:
+        for r in reports:
+            print_report(r)
+        if len(reports) > 1:
+            failed = [r["name"] for r in reports if not r["passed"]]
+            print(f"== summary: {len(failed)}/{len(reports)} failed: {', '.join(failed)} =="
+                  if failed else f"== summary: {len(reports)}/{len(reports)} passed ==")
+    if args.warn:
+        return 0
+    return 0 if all(r["passed"] for r in reports) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/skills-lib/wizz-video-effects/scripts/check_loudness.py

@@ -0,0 +1,175 @@
+# -*- coding: utf-8 -*-
+"""LOUDNESS gate on the final piece: integrated LUFS and true peak.
+
+Measures the final MP4 (or audio) with ffmpeg `loudnorm` in analysis mode
+(print_format=json) and BLOCKS when:
+    - integrated loudness is outside loudness.target_lufs +/- loudness.tolerance_lu
+    - true peak is above loudness.max_true_peak_db
+On failure it prints the ready two-pass ffmpeg command that fixes the file
+(pass 1 = this measurement, pass 2 = loudnorm with the measured values and
+linear=true, video stream copied).
+
+Why a gate and not a habit: masterizing louder than the target does not help
+(the platform turns it down) and a true peak near 0 dBTP distorts on the
+platform re-encode. The numbers and their weak source live in the config.
+
+Exit code: 0 pass, 1 fail, 2 error (missing file, ffmpeg without loudnorm
+output).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+from config import ConfigError, Loudness, add_config_arg, load
+
+FIELDS = ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset")
+VIDEO_EXT = {".mp4", ".mov", ".m4v", ".mkv"}
+
+
+class LoudnessError(Exception):
+    """File missing or loudnorm output not found."""
+
+
+LOSSLESS_EXT = {".wav", ".flac", ".aiff", ".aif"}
+
+
+def loudnorm_filter(lo: Loudness, measured: dict | None = None, tp_margin: float = 0.0) -> str:
+    """tp_margin: dB kept under max_true_peak_db in pass 2, for lossy output."""
+    base = (f"loudnorm=I={lo.target_lufs:g}:TP={lo.max_true_peak_db - tp_margin:g}"
+            f":LRA={lo.lra:g}")
+    if measured is None:
+        return base + ":print_format=json"
+    return (base + f":measured_I={measured['input_i']:g}:measured_TP={measured['input_tp']:g}"
+            f":measured_LRA={measured['input_lra']:g}"
+            f":measured_thresh={measured['input_thresh']:g}"
+            f":offset={measured['target_offset']:g}:linear=true:print_format=summary")
+
+
+def parse_loudnorm(stderr: str) -> dict:
+    """The LAST JSON object in ffmpeg's stderr, numeric fields as floats.
+    Silence gives "-inf", which becomes -math.inf (and fails the gate)."""
+    end = stderr.rfind("}")
+    start = stderr.rfind("{", 0, end + 1)
+    if start < 0 or end < 0:
+        raise LoudnessError("no loudnorm JSON in ffmpeg output")
+    try:
+        raw = json.loads(stderr[start:end + 1])
+    except json.JSONDecodeError as e:
+        raise LoudnessError(f"loudnorm JSON unreadable: {e}") from e
+    out = {}
+    for k in FIELDS:
+        if k not in raw:
+            raise LoudnessError(f"loudnorm JSON has no {k!r}")
+        out[k] = float(str(raw[k]).strip())   # float() accepts "-inf"
+    return out
+
+
+def measure(path: Path, lo: Loudness) -> dict:
+    if not path.exists():
+        raise LoudnessError(f"file not found: {path}")
+    r = subprocess.run(["ffmpeg", "-hide_banner", "-nostats", "-i", str(path),
+                        "-af", loudnorm_filter(lo), "-f", "null", "-"],
+                       capture_output=True, text=True)
+    try:
+        return parse_loudnorm(r.stderr)
+    except LoudnessError as e:
+        if "audio:0KiB" in r.stderr or "does not contain any stream" in r.stderr:
+            raise LoudnessError(f"{path}: has no audio stream") from e
+        raise LoudnessError(f"{path}: {e}: {r.stderr.strip()[-300:]}") from e
+
+
+def evaluate(m: dict, lo: Loudness) -> list[str]:
+    """Violations, empty when the measurement passes."""
+    errs = []
+    i, tp = m["input_i"], m["input_tp"]
+    if not math.isfinite(i):
+        errs.append("integrated loudness is -inf: the audio is silent or missing")
+    elif abs(i - lo.target_lufs) > lo.tolerance_lu:
+        errs.append(f"integrated {i:.1f} LUFS outside loudness.target_lufs "
+                    f"{lo.target_lufs:g} +/- loudness.tolerance_lu {lo.tolerance_lu:g}")
+    if tp > lo.max_true_peak_db:
+        errs.append(f"true peak {tp:.1f} dBTP above loudness.max_true_peak_db "
+                    f"{lo.max_true_peak_db:g}")
+    return errs
+
+
+def fix_command(path: Path, m: dict, lo: Loudness) -> str:
+    """Pass 2 of the two-pass loudnorm (pass 1 is the measurement above).
+
+    A lossy output (AAC in the MP4, MP3...) overshoots the true peak loudnorm
+    set, so its TP target sits loudness.encode_tp_margin_db lower: a fix that
+    fails the gate it came from is not a fix."""
+    out = path.with_name(path.stem + ".loudnorm" + path.suffix)
+    # loudnorm upsamples to 192 kHz internally: set the output rate back.
+    codec = "-c:v copy -c:a aac -b:a 192k -ar 48000" if path.suffix.lower() in VIDEO_EXT \
+        else "-ar 48000"
+    margin = 0.0 if path.suffix.lower() in LOSSLESS_EXT else lo.encode_tp_margin_db
+    return " ".join([
+        "ffmpeg -hide_banner -i", shlex.quote(str(path)),
+        "-af", shlex.quote(loudnorm_filter(lo, m, margin)), codec, shlex.quote(str(out))])
+
+
+def dynamic_warning(m: dict, path: Path, lo: Loudness) -> str | None:
+    """loudnorm only keeps linear=true when the gain it needs fits under the
+    true-peak target; otherwise it silently falls back to dynamic compression
+    (measured: +12.8 dB on a quiet narration flattened LRA from 3.1 to 1.8).
+    Say so before the fix runs, so the fix is a choice and not a surprise."""
+    margin = 0.0 if path.suffix.lower() in LOSSLESS_EXT else lo.encode_tp_margin_db
+    peak_after = m["input_tp"] + (lo.target_lufs - m["input_i"])
+    ceiling = lo.max_true_peak_db - margin
+    if not (math.isfinite(peak_after) and peak_after > ceiling):
+        return None
+    return (f"the fix needs {lo.target_lufs - m['input_i']:+.1f} dB, which puts the true peak "
+            f"at {peak_after:.1f} dBTP over the {ceiling:.1f} target: loudnorm will switch to "
+            f"dynamic compression. Prefer raising the narration before the render (it is "
+            f"usually the quiet layer) and measuring again.")
+
+
+def check(path: Path, lo: Loudness) -> tuple[dict, list[str]]:
+    m = measure(path, lo)
+    return m, evaluate(m, lo)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        description="Loudness gate: integrated LUFS and true peak of the final piece.")
+    add_config_arg(ap)
+    ap.add_argument("files", nargs="+", help="final MP4 or audio file(s)")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    args = ap.parse_args(argv)
+    try:
+        lo = load(args.config).loudness
+        results = {p: check(Path(p), lo) for p in args.files}
+    except (ConfigError, LoudnessError) as e:
+        print(f"ERROR: {e}")
+        return 2
+    failed = [p for p, (_, errs) in results.items() if errs]
+    if args.json:
+        finite = {p: {**{k: (v if math.isfinite(v) else None) for k, v in m.items()},
+                      "violations": e, "passed": not e} for p, (m, e) in results.items()}
+        print(json.dumps(finite, indent=2))
+        return 1 if failed else 0
+    for p, (m, errs) in results.items():
+        print(f"== loudness of {p} ==")
+        print(f"  integrated {m['input_i']:.1f} LUFS   true peak {m['input_tp']:.1f} dBTP"
+              f"   LRA {m['input_lra']:.1f} LU")
+        for e in errs:
+            print(f"  ERROR: {e}")
+        if errs and math.isfinite(m["input_i"]):
+            warning = dynamic_warning(m, Path(p), lo)
+            if warning:
+                print(f"  warning: {warning}")
+            print("  fix (pass 2 of 2):")
+            print(f"    {fix_command(Path(p), m, lo)}")
+        print("  FAILED" if errs else "  ok")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())