wizz-method 2.11.2 → 2.13.0

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

@@ -0,0 +1,342 @@
+# -*- coding: utf-8 -*-
+"""Map story happenings to the SFX that marks them, and duck the narration.
+
+Why it exists. Without a rule that ties a sound to a happening, every SFX is
+picked by hand, and by hand the neutral one always wins (the source project
+measured two files covering almost every use while nine sat idle). Whoever
+assembles asks for "verdict" or "message", never "stamp.mp3". The table
+event -> file -> volume lives in the config (`sound.events`); this module only
+holds the logic that accepts or refuses a request.
+
+Three refusals, applied in this order to each request (sorted by t):
+    1. unknown_event    never falls back to a default sound. A wrong sound
+                        is worse than no sound.
+    2. collision        closer than sound.collision_window_s to the last
+                        ACCEPTED shot (a refused request never plays, so
+                        there is nothing to collide with).
+    3. same_sound_in_row the same file cannot repeat more than
+                        sound.max_same_sound_in_row times without another
+                        ACCEPTED sound between them.
+
+Volume always comes from the config: `map_requests` does not even take a
+volume argument. The ceiling relative to the voice is validated in config.py.
+
+Ducking. `ducking_envelope` returns narration duck windows, applied ONLY
+where a SFX sounds over the start of a spoken word. Numbers come from the
+`ducking` block of the config (marked there as an extrapolation).
+
+CLI:
+    python3 sound.py coverage [--config PATH] [--sfx-dir DIR]
+    python3 sound.py duck TIMELINE.json [--words WORDS.json] [--write]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from config import Config, ConfigError, add_config_arg, load
+import timeline as tl
+
+# ------------------------------------------------------------------ structures
+
+
+@dataclass(frozen=True)
+class Shot:
+    t: float
+    event: str                  # semantic key requested
+    src: str                    # "sfx/stamp.mp3", via cfg.sound.src()
+    vol: float
+    triggers: tuple[str, ...]   # visual effects this sound also fires
+    strength: float | None = None
+
+
+@dataclass(frozen=True)
+class SoundRefusal:
+    t: float
+    event: str
+    rule: str       # "unknown_event" | "same_sound_in_row" | "collision"
+    detail: str
+
+
+@dataclass(frozen=True)
+class SoundResult:
+    shots: tuple[Shot, ...]         # sorted by t
+    refusals: tuple[SoundRefusal, ...]
+
+    def by_sound(self) -> dict[str, int]:
+        """Accepted shots per FILE (several events can share one file)."""
+        count: dict[str, int] = {}
+        for s in self.shots:
+            name = Path(s.src).stem
+            count[name] = count.get(name, 0) + 1
+        return count
+
+    def report(self) -> str:
+        lines = [f"shots: {len(self.shots)}   refusals: {len(self.refusals)}"]
+        if self.shots:
+            lines.append("by sound:")
+            for name, n in sorted(self.by_sound().items(), key=lambda kv: (-kv[1], kv[0])):
+                lines.append(f"   {name:12} {n}")
+        if self.refusals:
+            by_rule: dict[str, int] = {}
+            for r in self.refusals:
+                by_rule[r.rule] = by_rule.get(r.rule, 0) + 1
+            lines.append("refusals by rule:")
+            for rule, n in sorted(by_rule.items(), key=lambda kv: (-kv[1], kv[0])):
+                lines.append(f"   {rule:20} {n}")
+        return "\n".join(lines)
+
+
+# ------------------------------------------------------------------------- map
+
+
+def map_requests(requests: Iterable[tuple[float, str]], cfg: Config) -> SoundResult:
+    """Accept or refuse each (t, event) request. Evaluated on the final order
+    by t, never on arrival order. sorted() is stable: two requests at the same
+    t keep arrival order, which decides who is 'first' on a tie."""
+    ordered = sorted(requests, key=lambda r: r[0])
+    window = cfg.sound.collision_window_s
+    limit = cfg.sound.max_same_sound_in_row
+    shots: list[Shot] = []
+    refusals: list[SoundRefusal] = []
+    last_t: float | None = None
+    last_sound: str | None = None
+    in_row = 0
+
+    for t, event in ordered:
+        ev = cfg.sound.events.get(event)
+        if ev is None:
+            refusals.append(SoundRefusal(
+                t, event, "unknown_event",
+                f"unknown sound event {event!r}. Valid events: "
+                f"{', '.join(sorted(cfg.sound.events))}"))
+            continue
+        if last_t is not None and (t - last_t) < window:
+            refusals.append(SoundRefusal(
+                t, event, "collision",
+                f"{t - last_t:.3f}s from the previous accepted shot "
+                f"(t={last_t:.3f}s); minimum {window}s"))
+            continue
+        candidate_row = in_row + 1 if ev.sound == last_sound else 1
+        if candidate_row > limit:
+            refusals.append(SoundRefusal(
+                t, event, "same_sound_in_row",
+                f"'{ev.sound}' already played {in_row}x in a row (max {limit}); "
+                f"needs another accepted sound between them"))
+            continue
+        shots.append(Shot(t=t, event=event, src=cfg.sound.src(event), vol=ev.vol,
+                          triggers=ev.triggers, strength=ev.strength))
+        last_t, last_sound, in_row = t, ev.sound, candidate_row
+
+    return SoundResult(shots=tuple(shots), refusals=tuple(refusals))
+
+
+def event_of(entry: dict, cfg: Config) -> str | None:
+    """Semantic event of a sound already in the timeline: its `event`, or
+    rebuilt from the (file, vol) pair when that pair is unique in the config.
+    Ambiguous or unknown pairs return None; the caller decides, never guessed."""
+    if entry.get("event") in cfg.sound.events:
+        return entry["event"]
+    name, vol = Path(str(entry.get("src", ""))).stem, float(entry.get("vol", -1))
+    found = [k for k, e in cfg.sound.events.items() if e.sound == name and abs(e.vol - vol) < 1e-9]
+    return found[0] if len(found) == 1 else None
+
+
+def effect_candidates(res: SoundResult) -> list[dict]:
+    """Bridge to budget.py: one plain dict per visual effect a shot fires.
+    Plain dicts on purpose, so the two modules never import each other.
+
+    `strength` comes from the event's own field (narrative weight), never from
+    the volume. Without it, vol is the fallback, and the reason says so."""
+    out = []
+    for s in res.shots:
+        fallback = s.strength is None
+        for kind in s.triggers:
+            reason = f"sound:{s.event}" + (" (strength from volume)" if fallback else "")
+            out.append({"t": s.t, "kind": kind,
+                        "strength": s.vol if fallback else s.strength,
+                        "reason": reason})
+    return out
+
+
+# -------------------------------------------------------------------- coverage
+
+
+def coverage(cfg: Config, sfx_dir: str | Path | None = None) -> dict:
+    """Disk vs config, both directions: a sound without event is idle work; an
+    event without file is a build that has not broken yet, but will."""
+    folder = Path(sfx_dir) if sfx_dir is not None else cfg.sfx_dir
+    exists = folder.is_dir()
+    on_disk = sorted(p.stem for p in folder.glob("*.mp3")) if exists else []
+    used = cfg.sound.sounds_used()
+    return {
+        "sfx_dir": str(folder),
+        "sfx_dir_exists": exists,
+        "on_disk": on_disk,
+        "sounds_without_event": sorted(set(on_disk) - used),
+        "events_without_file": sorted(
+            k for k, e in cfg.sound.events.items() if e.sound not in on_disk),
+    }
+
+
+# --------------------------------------------------------------------- ducking
+
+
+def _sfx_interval(s: dict, cfg: Config, durations: dict[str, float]) -> tuple[float, float]:
+    start = float(s["at"])
+    dur = s.get("dur")
+    if dur is None:
+        dur = durations.get(str(s.get("src", "")), cfg.ducking.assumed_sfx_duration_s)
+    return start, start + float(dur)
+
+
+def _merge(windows: list[dict]) -> list[dict]:
+    """Union of overlapping windows, deepest depth wins."""
+    merged: list[dict] = []
+    for w in sorted(windows, key=lambda w: w["start"]):
+        if merged and w["start"] <= merged[-1]["end"]:
+            last = merged[-1]
+            merged[-1] = {**last, "end": max(last["end"], w["end"]),
+                          "depth_db": max(last["depth_db"], w["depth_db"]),
+                          "cause": last["cause"] + "; " + w["cause"]}
+        else:
+            merged.append(dict(w))
+    return merged
+
+
+def ducking_envelope(sfx: Iterable[dict], words: Iterable[dict], cfg: Config,
+                     fps: int | None = None,
+                     durations: dict[str, float] | None = None) -> list[dict]:
+    """Narration duck windows, one per SFX that sounds over a word onset.
+
+    A SFX collides when a word `start` falls inside [sfx.at - attack, sfx end].
+    The window ramps down over `attack` so full depth is in place when the SFX
+    hits, holds until the SFX ends, then releases over `release`. Windows that
+    overlap are merged. Output shape: references/data-contract.md, `ducking[]`.
+    """
+    d = cfg.ducking
+    fps = fps or cfg.frame.fps
+    durations = durations or {}
+    onsets = sorted((float(w["start"]), str(w.get("text", ""))) for w in words)
+    windows = []
+    for s in sorted(sfx, key=lambda s: float(s["at"])):
+        start, end = _sfx_interval(s, cfg, durations)
+        hit = next(((t, txt) for t, txt in onsets if start - d.attack_s <= t <= end), None)
+        if hit is None:
+            continue
+        label = s.get("event") or Path(str(s.get("src", "?"))).stem
+        windows.append({
+            "start": round(max(0.0, start - d.attack_s), 4),
+            "end": round(end + d.release_s, 4),
+            "depth_db": d.depth_db, "attack_s": d.attack_s, "release_s": d.release_s,
+            "cause": f"{label}@{start:.3f}s over word '{hit[1]}'@{hit[0]:.3f}s"})
+    merged = _merge(windows)
+    for w in merged:
+        w["from_frame"] = int(w["start"] * fps)
+        w["to_frame"] = int(-(-w["end"] * fps // 1))
+    return merged
+
+
+def gain_db_at(t: float, windows: Iterable[dict]) -> float:
+    """Narration gain in dB at instant t (0.0 outside every window). The
+    Remotion volume callback in data-contract.md is this same function."""
+    g = 0.0
+    for w in windows:
+        s, e = w["start"], w["end"]
+        if not s <= t <= e:
+            continue
+        shape = 1.0
+        if t < s + w["attack_s"]:
+            shape = (t - s) / w["attack_s"]
+        elif t > e - w["release_s"]:
+            shape = (e - t) / w["release_s"]
+        g = min(g, -w["depth_db"] * max(0.0, min(1.0, shape)))
+    return g
+
+
+def probe_duration(path: Path) -> float | None:
+    """Duration of a media file via ffprobe, or None when it cannot be read."""
+    r = subprocess.run(["ffprobe", "-v", "error", "-show_entries", "format=duration",
+                        "-of", "csv=p=0", str(path)], capture_output=True, text=True)
+    try:
+        return float(r.stdout.strip())
+    except ValueError:
+        return None
+
+
+# ------------------------------------------------------------------------- CLI
+
+
+def _cmd_coverage(cfg: Config, sfx_dir: str | None) -> int:
+    cov = coverage(cfg, sfx_dir)
+    print(f"sfx dir: {cov['sfx_dir']}  (exists: {cov['sfx_dir_exists']})")
+    print(f"sounds on disk ({len(cov['on_disk'])}): {', '.join(cov['on_disk']) or '-'}")
+    idle = cov["sounds_without_event"]
+    print(f"sounds without event ({len(idle)}): {', '.join(idle) or 'none'}")
+    missing = cov["events_without_file"]
+    if missing:
+        print(f"events without file, broken build ({len(missing)}): {', '.join(missing)}")
+        return 1
+    print("events without file: none")
+    print("ok: coverage has no problem.")
+    return 0
+
+
+def _cmd_duck(cfg: Config, args) -> int:
+    data = tl.load(args.timeline)
+    words = json.loads(Path(args.words).read_text(encoding="utf-8")) if args.words \
+        else data.get("words") or []
+    if not words:
+        print("ERROR: no words: pass --words (ctc-align output) or put words[] in the timeline")
+        return 2
+    sfx_list = tl.sounds(data)
+    sfx_dir = Path(args.sfx_dir) if args.sfx_dir else cfg.sfx_dir
+    durations = {}
+    for s in sfx_list:
+        src = str(s.get("src", ""))
+        if src and "dur" not in s and src not in durations:
+            dur = probe_duration(sfx_dir / Path(src).name)
+            if dur is not None:
+                durations[src] = dur
+    windows = ducking_envelope(sfx_list, words, cfg, tl.fps(data, cfg.frame.fps), durations)
+    print(f"sounds: {len(sfx_list)}   duck windows: {len(windows)}")
+    for w in windows:
+        print(f"   {w['start']:7.3f}s -> {w['end']:7.3f}s  -{w['depth_db']:.1f} dB  {w['cause']}")
+    if args.write:
+        tl.save(args.timeline, {**data, "ducking": windows})
+        print(f"written: {args.timeline}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Sound coverage audit and narration ducking.")
+    add_config_arg(ap)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    cov = sub.add_parser("coverage", help="compare SFX on disk with the config events")
+    cov.add_argument("--sfx-dir", help="SFX folder (default: from the config paths)")
+    duck = sub.add_parser("duck", help="compute narration duck windows for a timeline")
+    duck.add_argument("timeline", help="timeline JSON (see references/data-contract.md)")
+    duck.add_argument("--words", help="ctc-align words JSON (default: timeline words[])")
+    duck.add_argument("--sfx-dir", help="SFX folder, to probe durations")
+    duck.add_argument("--write", action="store_true", help="write ducking[] into the timeline")
+    for sp in (cov, duck):   # --config also accepted after the subcommand
+        sp.add_argument("--config", metavar="PATH", default=argparse.SUPPRESS,
+                        help="effects config JSON (same as before the subcommand)")
+    args = ap.parse_args(argv)
+    try:
+        cfg = load(args.config)
+        if args.cmd == "coverage":
+            return _cmd_coverage(cfg, args.sfx_dir)
+        return _cmd_duck(cfg, args)
+    except (ConfigError, tl.TimelineError) as e:
+        print(f"ERROR: {e}")
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,131 @@
+# -*- coding: utf-8 -*-
+"""Tests of the anti-excess engine (budget.py).
+
+Each test builds a synthetic budget (never the template numbers) to isolate
+the rule it proves: a future change of the project numbers does not break
+these tests by accident.
+"""
+from __future__ import annotations
+
+import unittest
+from dataclasses import dataclass
+
+from budget import Candidate, select
+from config import Budget, CurveSection, EffectRule
+
+
+@dataclass(frozen=True)
+class _FakeCfg:
+    """budget.py only reads `budget`."""
+    budget: Budget
+
+
+def _single_section() -> tuple[CurveSection, ...]:
+    return (CurveSection(name="all", until_frac=1.0, weight=1.0),)
+
+
+def _rule(max_per_min=60.0, gap_min=0.0, max_in_row=99, dominant=False) -> EffectRule:
+    return EffectRule(max_per_min=max_per_min, gap_min=gap_min, max_in_row=max_in_row,
+                      dominant=dominant)
+
+
+def _cfg(per_effect, curve=None, gap_min_global=0.0) -> _FakeCfg:
+    return _FakeCfg(budget=Budget(gap_min_global=gap_min_global, burst_gap_s=5.0,
+                                  per_effect=per_effect, curve=curve or _single_section()))
+
+
+def C(t, kind, strength, reason="x"):
+    return Candidate(t=t, kind=kind, strength=strength, reason=reason)
+
+
+class TestCeiling(unittest.TestCase):
+    def test_ceiling_kept_and_strongest_win(self):
+        cfg = _cfg({"punch": _rule(max_per_min=2.0)})
+        res = select([C(1, "punch", .9), C(10, "punch", .8), C(20, "punch", .7),
+                      C(30, "punch", .6)], total=60.0, cfg=cfg)
+        self.assertEqual({c.t for c in res.accepted}, {1, 10})
+        self.assertTrue(all(r.rule == "ceiling" for r in res.refusals))
+
+    def test_heavier_section_gets_its_own_slice(self):
+        curve = (CurveSection("hook", 0.1, 2.0), CurveSection("body", 1.0, 1.0))
+        cfg = _cfg({"punch": _rule(max_per_min=6.0)}, curve=curve)
+        # total ceiling 6; hook slice = 6*12/66 ~ 1.09 -> 1.
+        res = select([C(1, "punch", .9), C(2, "punch", .8)], total=60.0, cfg=cfg)
+        self.assertEqual(len(res.accepted), 1)
+        self.assertEqual(res.refusals[0].rule, "ceiling")
+
+
+class TestGap(unittest.TestCase):
+    def test_same_kind_gap(self):
+        cfg = _cfg({"punch": _rule(gap_min=2.0)})
+        res = select([C(1.0, "punch", .9), C(1.5, "punch", .5)], total=30.0, cfg=cfg)
+        self.assertEqual([c.t for c in res.accepted], [1.0])
+        self.assertEqual(res.refusals[0].rule, "gap_min")
+
+    def test_global_gap_only_holds_dominant(self):
+        cfg = _cfg({"punch": _rule(dominant=True), "flash": _rule()}, gap_min_global=5.0)
+        res = select([C(1, "punch", .9), C(2, "punch", .8), C(2, "flash", .7)],
+                     total=30.0, cfg=cfg)
+        acc = {(c.t, c.kind) for c in res.accepted}
+        self.assertEqual(acc, {(1, "punch"), (2, "flash")})
+        self.assertEqual(res.refusals[0].rule, "gap_min_global")
+
+
+class TestInRow(unittest.TestCase):
+    def test_max_in_row(self):
+        cfg = _cfg({"flash": _rule(max_in_row=2)})
+        res = select([C(1, "flash", .9), C(2, "flash", .8), C(3, "flash", .7)], total=30.0, cfg=cfg)
+        self.assertEqual([c.t for c in res.accepted], [1, 2])
+        self.assertEqual(res.refusals[0].rule, "max_in_row")
+
+    def test_counted_on_final_time_order_not_processing_order(self):
+        cfg = _cfg({"shake": _rule(max_in_row=2)})
+        res = select([C(10, "shake", .9, "A"), C(1, "shake", .8, "B"),
+                      C(5, "shake", .7, "C, squeezed between B and A")], total=30.0, cfg=cfg)
+        self.assertEqual(sorted(c.t for c in res.accepted), [1, 10])
+        self.assertEqual(res.refusals[0].rule, "max_in_row")
+
+    def test_bursts_far_apart_do_not_chain(self):
+        cfg = _cfg({"punch": _rule(max_in_row=1)})
+        res = select([C(1, "punch", .9), C(20, "punch", .8)], total=60.0, cfg=cfg)
+        self.assertEqual(len(res.accepted), 2)
+
+
+class TestMisc(unittest.TestCase):
+    def test_strength_breaks_the_tie(self):
+        cfg = _cfg({"flash": _rule(max_per_min=1.0)})
+        res = select([C(1, "flash", .3, "weak"), C(2, "flash", .9, "strong")], total=60.0, cfg=cfg)
+        self.assertEqual(res.accepted[0].reason, "strong")
+
+    def test_unknown_kind(self):
+        res = select([C(1, "magic-sparkle", .9)], total=30.0, cfg=_cfg({"punch": _rule()}))
+        self.assertEqual(res.refusals[0].rule, "unknown_kind")
+
+    def test_empty(self):
+        res = select([], total=30.0, cfg=_cfg({"punch": _rule()}))
+        self.assertEqual((res.accepted, res.refusals, res.by_kind()), ((), (), {}))
+
+    def test_accepts_dicts_from_sound_py(self):
+        res = select([{"t": 1.0, "kind": "punch", "strength": 0.5}], total=30.0,
+                     cfg=_cfg({"punch": _rule()}))
+        self.assertEqual(len(res.accepted), 1)
+
+    def test_bad_dict_names_the_problem(self):
+        with self.assertRaises(TypeError):
+            select([{"t": 1.0}], total=30.0, cfg=_cfg({"punch": _rule()}))
+
+    def test_deterministic(self):
+        cfg = _cfg({"punch": _rule(10, 3.5, 2, True), "flash": _rule(10, 2.5, 3)},
+                   gap_min_global=2.0)
+        cands = [C(.5, "punch", .7), C(1.2, "flash", .6), C(4, "punch", .9),
+                 C(4.1, "flash", .9), C(6, "punch", .5), C(9, "unknown", .9)]
+        self.assertEqual(select(cands, 20.0, cfg), select(list(reversed(cands)), 20.0, cfg))
+
+    def test_report_is_text(self):
+        res = select([C(1, "punch", .9), C(1.1, "punch", .1)], total=30.0,
+                     cfg=_cfg({"punch": _rule(gap_min=1.0)}))
+        self.assertIn("refusals", res.report())
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,156 @@
+# -*- coding: utf-8 -*-
+"""Tests of check_loudness.py: parsing of the loudnorm JSON (no media), the
+gate decision, the printed fix command, and an optional integration test on
+synthetic audio generated by ffmpeg (skipped when ffmpeg is absent)."""
+import math
+import shlex
+import shutil
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+import check_loudness as CL
+from config import TEMPLATE, load
+
+LO = load(TEMPLATE).loudness
+
+STDERR = """[Parsed_loudnorm_0 @ 0x600]
+{
+\t"input_i" : "-19.52",
+\t"input_tp" : "-4.10",
+\t"input_lra" : "3.20",
+\t"input_thresh" : "-29.80",
+\t"output_i" : "-14.03",
+\t"output_tp" : "-1.00",
+\t"output_lra" : "2.90",
+\t"output_thresh" : "-24.30",
+\t"normalization_type" : "dynamic",
+\t"target_offset" : "0.03"
+}
+"""
+
+SILENT = STDERR.replace('"-19.52"', '"-inf"').replace('"-4.10"', '"-inf"')
+
+
+def _m(i, tp):
+    return {"input_i": i, "input_tp": tp, "input_lra": 3.0, "input_thresh": -24.0,
+            "target_offset": 0.0}
+
+
+class TestParse(unittest.TestCase):
+    def test_parse_values(self):
+        m = CL.parse_loudnorm("noise before {not json}\n" + STDERR)
+        self.assertEqual(m["input_i"], -19.52)
+        self.assertEqual(m["input_tp"], -4.10)
+        self.assertEqual(m["target_offset"], 0.03)
+
+    def test_silence_is_minus_inf(self):
+        m = CL.parse_loudnorm(SILENT)
+        self.assertTrue(math.isinf(m["input_i"]))
+
+    def test_no_json_raises(self):
+        with self.assertRaises(CL.LoudnessError):
+            CL.parse_loudnorm("ffmpeg: no such file")
+
+    def test_missing_field_raises(self):
+        with self.assertRaises(CL.LoudnessError):
+            CL.parse_loudnorm('{"input_i": "-14"}')
+
+
+class TestGate(unittest.TestCase):
+    def test_on_target_passes(self):
+        self.assertEqual(CL.evaluate(_m(LO.target_lufs, LO.max_true_peak_db - 0.5), LO), [])
+
+    def test_edges_of_tolerance(self):
+        self.assertEqual(CL.evaluate(_m(LO.target_lufs - LO.tolerance_lu, -3.0), LO), [])
+        self.assertTrue(CL.evaluate(_m(LO.target_lufs - LO.tolerance_lu - 0.1, -3.0), LO))
+        self.assertTrue(CL.evaluate(_m(LO.target_lufs + LO.tolerance_lu + 0.1, -3.0), LO))
+
+    def test_true_peak_over_ceiling_fails(self):
+        errs = CL.evaluate(_m(LO.target_lufs, LO.max_true_peak_db + 0.2), LO)
+        self.assertTrue(any("true peak" in e for e in errs))
+
+    def test_silence_fails(self):
+        self.assertTrue(CL.evaluate(CL.parse_loudnorm(SILENT), LO))
+
+    def test_fix_command_is_second_pass(self):
+        m = CL.parse_loudnorm(STDERR)
+        cmd = CL.fix_command(Path("out/piece.mp4"), m, LO)
+        self.assertIn("measured_I=-19.52", cmd)
+        self.assertIn("measured_TP=-4.1", cmd)
+        self.assertIn("linear=true", cmd)
+        self.assertIn(f"I={LO.target_lufs:g}", cmd)
+        self.assertIn("-c:v copy", cmd)
+        self.assertIn("piece.loudnorm.mp4", cmd)
+        self.assertNotIn("-c:v", CL.fix_command(Path("voice.wav"), m, LO))
+
+
+    def test_linear_when_the_gain_fits_under_the_peak(self):
+        # needs +2 dB; peak goes from -6 to -4, under -1 minus the lossy margin
+        self.assertIsNone(CL.dynamic_warning(_m(LO.target_lufs - 2, -6.0), Path("p.mp4"), LO))
+
+    def test_warns_when_the_gain_will_compress(self):
+        # needs +12.8 dB on a -10 dBTP peak: linear would clip, loudnorm compresses
+        w = CL.dynamic_warning(_m(LO.target_lufs - 12.8, -10.0), Path("p.mp4"), LO)
+        self.assertIsNotNone(w)
+        self.assertIn("dynamic", w)
+
+
+@unittest.skipUnless(shutil.which("ffmpeg"), "ffmpeg not installed")
+class TestIntegration(unittest.TestCase):
+    def _gen(self, tmp, name, src):
+        p = Path(tmp) / name
+        subprocess.run(["ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i", src,
+                        "-t", "4", str(p)], check=True)
+        return p
+
+    def test_sine_measures_and_silence_fails(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            tone = self._gen(tmp, "tone.wav", "sine=frequency=440:sample_rate=48000")
+            m, errs = CL.check(tone, LO)
+            self.assertTrue(-40.0 < m["input_i"] < 0.0, m)
+            self.assertEqual(bool(errs), abs(m["input_i"] - LO.target_lufs) > LO.tolerance_lu
+                             or m["input_tp"] > LO.max_true_peak_db)
+            silent = self._gen(tmp, "silent.wav", "anullsrc=r=48000:cl=mono")
+            _, errs = CL.check(silent, LO)
+            self.assertTrue(errs)
+
+    def test_fix_command_brings_tone_to_target(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            tone = self._gen(tmp, "tone.wav", "sine=frequency=440:sample_rate=48000")
+            m, _ = CL.check(tone, LO)
+            fixed = Path(tmp) / "tone.loudnorm.wav"
+            subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", str(tone),
+                            "-af", CL.loudnorm_filter(LO, m), "-ar", "48000", str(fixed)],
+                           check=True)
+            m2, errs = CL.check(fixed, LO)
+            self.assertEqual(errs, [], m2)
+
+    def test_fix_command_passes_the_gate_on_an_aac_mp4(self):
+        # Found assembling a real piece (rodada 5, 2026-09-24): the printed fix
+        # targeted TP exactly at the ceiling, then re-encoded to AAC, and the
+        # lossy encode overshot it (-1.0 -> -0.8 dBTP). The gate failed its
+        # own fix. The command must leave room for the encoder.
+        with tempfile.TemporaryDirectory() as tmp:
+            src = Path(tmp) / "quiet.mp4"
+            subprocess.run(["ffmpeg", "-v", "error", "-y",
+                            "-f", "lavfi", "-i", "anoisesrc=color=pink:amplitude=0.08:"
+                            "sample_rate=48000:seed=7",
+                            "-f", "lavfi", "-i", "color=c=black:s=64x64:r=30",
+                            "-t", "6", "-c:v", "libx264", "-c:a", "aac", "-b:a", "192k",
+                            "-shortest", str(src)], check=True)
+            m, errs = CL.check(src, LO)
+            self.assertTrue(errs, "fixture must start outside the target")
+            cmd = shlex.split(CL.fix_command(src, m, LO))
+            subprocess.run([cmd[0], "-v", "error", "-y"] + cmd[1:], check=True)
+            m2, errs2 = CL.check(src.with_name("quiet.loudnorm.mp4"), LO)
+            self.assertEqual(errs2, [], m2)
+
+    def test_missing_file_is_an_error(self):
+        with self.assertRaises(CL.LoudnessError):
+            CL.check(Path("/no/such/piece.mp4"), LO)
+
+
+if __name__ == "__main__":
+    unittest.main()