wizz-method 2.21.0 → 2.23.0

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

@@ -0,0 +1,376 @@
+# -*- coding: utf-8 -*-
+"""PAGE-CHROME gate: does the piece look like a slide or a HUD?
+
+Reads what text and shapes are on screen, never the pixels, from one of two
+sources:
+
+    --snapshot LAYOUT.json  a layout snapshot of an HTML composition
+        (HyperFrames, or Remotion Studio, which is also a DOM), written by
+        assets/chrome/collect_layout.js at a few seek times.
+    --timeline TIMELINE     the Remotion timeline: the text layers declared in
+        elements[] (`text`, `box`, `font_px`, `role`, `until`).
+
+Rules (thresholds in the config block chrome_lint):
+    C1 corner/edge label     small text parked in a corner or an edge band      FAIL
+    C2 tracked-caps label    small uppercase text with wide letter-spacing      FAIL
+    C3 counter               "02 / 05", "01 - THE WAIT", "Parte 3", bare "01"    FAIL
+    C4 production metadata   timecode, FPS, BPM, resolution, REC, version       FAIL
+    C6 header/footer bar     a wide bar or hairline in the top or bottom band   FAIL
+    C7 kicker over headline  a small line right above a headline 2x its size   FAIL
+    D1 deck layout           left-anchored headline with media on the right,
+                             a sub-line or 2+ lines: FAIL; alone: WARN
+    P1 progress bar          a thin bar that grows over time                    FAIL
+
+Not chrome: text whose `role` is in chrome_lint.exempt_roles (captions,
+legally required ad text, product UI). A rule the chosen style measured on
+real videos (the progress device of `desafio-numero`) is allowed with
+`--allow P1` or `chrome_allow: ["P1"]` in the timeline; allowed rules are
+printed, never silent.
+
+What it cannot see: text drawn into a <canvas>, an image, a video or burned
+into footage; text a Remotion component draws without declaring it in the
+timeline; whether a flagged element is still the right call. A PASS is not
+taste: look at the frames.
+
+Rules ported from gate G5 of motionmaxxing's lint.mjs (Apache-2.0,
+github.com/Tejashmakwana/motionmaxxing), rewritten for 9:16; see
+THIRD-PARTY-NOTICES.md.
+
+Exit code: 0 pass (warnings allowed), 1 fail, 2 input or config unreadable.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import timeline as tl
+from config import Config, ConfigError, add_config_arg, load, optional_block
+
+BLOCK = "chrome_lint"
+SEVERITY = {"C1": "FAIL", "C2": "FAIL", "C3": "FAIL", "C4": "FAIL", "C6": "FAIL",
+            "C7": "FAIL", "D1": "FAIL", "P1": "FAIL"}
+NAMES = {"C1": "corner/edge label", "C2": "tracked-caps label", "C3": "counter",
+         "C4": "production metadata", "C6": "header/footer bar", "C7": "kicker over headline",
+         "D1": "deck layout (left headline block)", "P1": "progress bar"}
+
+RX_COUNTER_NUM = re.compile(r"^\s*0?\d{1,2}\s*(?:[/·|]|-(?=\s*[A-Za-z]{3,}))\s*(?:0?\d{1,2}\b|[A-Za-zÀ-ú]{3,})")
+RX_COUNTER_WORD = re.compile(
+    r"\b(chapter|scene|act|step|part|episode|shot|take|beat|"
+    r"cap[ií]tulo|cena|ato|passo|parte|etapa|epis[oó]dio)\s*0?\d", re.I)
+RX_COUNTER_BARE = re.compile(r"^\s*0\d\s*$")
+RX_META = re.compile(
+    r"\bBPM\b|\bFPS\b|\bFRAME\s*\d|\b(?:1920|3840|1280|1080|720)\s*[x×]\s*(?:1080|2160|720|1920|1280)\b"
+    r"|\bT\s*\+\s*\d|\bTC\b|\b\d{1,2}:\d{2}:\d{2}(?:[.:]\d+)?\b|\b\d{1,2}:\d{2}\.\d{1,3}\b|\bREC\b")
+RX_VERSION = re.compile(r"\bv\d+\.\d+(?:\.\d+)?\b|©", re.I)
+RX_24_7 = re.compile(r"^\s*24\s*/\s*7\b")
+
+
+@dataclass(frozen=True)
+class ChromeRules:
+    small_text: float
+    corner_x: float
+    corner_y: float
+    edge_band: float
+    caps_tracking_em: float
+    caps_max_size: float
+    counter_max_size: float
+    headline_min_size: float
+    kicker_ratio: float
+    kicker_gap: float
+    deck_left_x: float
+    bar_min_width: float
+    bar_max_height: float
+    bar_band: float
+    progress_min_growth: float
+    held_s: float
+    exempt_roles: frozenset
+
+
+def rules(cfg: Config) -> tuple[ChromeRules, bool]:
+    b, from_template = optional_block(cfg, BLOCK)
+    try:
+        nums = {k: float(b[k]) for k in ChromeRules.__dataclass_fields__ if k != "exempt_roles"}
+        r = ChromeRules(**nums, exempt_roles=frozenset(str(x) for x in b["exempt_roles"]))
+    except (KeyError, TypeError, ValueError) as e:
+        raise ConfigError(f"{BLOCK}: missing or invalid key ({e})") from e
+    bad = [k for k, v in nums.items() if v <= 0]
+    if bad:
+        raise ConfigError(f"{BLOCK}: must be > 0: {', '.join(bad)}")
+    return r, from_template
+
+
+# ------------------------------------------------------------------ inputs
+
+@dataclass(frozen=True)
+class Block:
+    text: str
+    x0: float
+    y0: float
+    x1: float
+    y1: float
+    size: float          # font size / short side of the frame
+    caps: bool
+    tracking: float      # letter-spacing in em
+    role: str
+    align: str
+    lines: int
+
+    @property
+    def cx(self) -> float:
+        return (self.x0 + self.x1) / 2
+
+    @property
+    def cy(self) -> float:
+        return (self.y0 + self.y1) / 2
+
+
+@dataclass(frozen=True)
+class Shape:
+    sid: str
+    kind: str            # bar | rule | media | surface
+    x0: float
+    y0: float
+    x1: float
+    y1: float
+
+
+def _norm_box(box, w: float, h: float) -> tuple[float, float, float, float]:
+    x0, y0, x1, y1 = (float(v) for v in box)
+    return x0 / w, y0 / h, x1 / w, y1 / h
+
+
+def _block(d: dict, w: float, h: float) -> Block | None:
+    text = str(d.get("text") or "").strip()
+    if not text or "box" not in d:
+        return None
+    x0, y0, x1, y1 = _norm_box(d["box"], w, h)
+    caps = bool(d.get("caps")) or (text.upper() == text and any(c.isalpha() for c in text))
+    return Block(text, x0, y0, x1, y1, float(d.get("font_px", 0)) / min(w, h), caps,
+                 float(d.get("tracking_em", 0.0)), str(d.get("role") or ""),
+                 str(d.get("align") or ""), int(d.get("lines", 1)))
+
+
+def _shape(d: dict, i: int, w: float, h: float) -> Shape:
+    x0, y0, x1, y1 = _norm_box(d["box"], w, h)
+    return Shape(str(d.get("id", i)), str(d.get("kind", "bar")), x0, y0, x1, y1)
+
+
+def samples_from_snapshot(data: dict) -> list[dict]:
+    """[{t, blocks: [Block], shapes: [Shape]}] from a collect_layout.js file."""
+    w, h = float(data["width"]), float(data["height"])
+    out = []
+    for s in data.get("samples") or []:
+        blocks = [b for b in (_block(x, w, h) for x in s.get("blocks") or []) if b]
+        shapes = [_shape(x, i, w, h) for i, x in enumerate(s.get("shapes") or []) if "box" in x]
+        out.append({"t": float(s["t"]), "blocks": blocks, "shapes": shapes})
+    return sorted(out, key=lambda s: s["t"])
+
+
+def samples_from_timeline(data: dict, w: int, h: int, r: ChromeRules) -> list[dict]:
+    """One sample per layer start, with every declared layer visible then.
+    A layer shorter than held_s is in flight and is skipped; a bar with a
+    `box_end` wider than its `box` is a growing bar (P1)."""
+    total, _ = tl.duration(data)
+    layers = []
+    for i, e in enumerate(data.get("elements") or []):
+        if not isinstance(e, dict) or "box" not in e:
+            continue
+        start = float(e.get("at", 0.0))
+        end = float(e.get("until", total))
+        if end - start < r.held_s:
+            continue
+        layers.append((start, end, i, e))
+    out = []
+    for t in sorted({start for start, _, _, _ in layers}):
+        blocks, shapes = [], []
+        for start, end, i, e in layers:
+            if not start <= t < end:
+                continue
+            if e.get("text"):
+                b = _block(e, w, h)
+                if b:
+                    blocks.append(b)
+            elif e.get("kind") in ("bar", "rule", "media", "surface"):
+                shapes.append(_shape(e, i, w, h))
+                if e.get("box_end"):
+                    shapes.append(_shape({**e, "box": e["box_end"]}, i, w, h))
+        out.append({"t": t, "blocks": blocks, "shapes": shapes, "timeline": True})
+    return out
+
+
+# ------------------------------------------------------------------- rules
+
+def _held(b: Block, t: float, samples: list[dict], r: ChromeRules) -> bool:
+    """Parked, not flying through: the same text at the same place in the
+    neighbouring samples within held_s. No neighbour at all: held."""
+    near = [s for s in samples if s["t"] != t and abs(s["t"] - t) <= r.held_s]
+    if not near:
+        return True
+    return any(c.text == b.text and abs(c.x0 - b.x0) < 0.006 and abs(c.y0 - b.y0) < 0.006
+               for s in near for c in s["blocks"])
+
+
+def _text_rules(b: Block, r: ChromeRules) -> list[str]:
+    hits = []
+    small = b.size <= r.small_text
+    corner = (b.cx < r.corner_x or b.cx > 1 - r.corner_x) and (b.cy < r.corner_y or b.cy > 1 - r.corner_y)
+    edge = b.y1 < r.edge_band or b.y0 > 1 - r.edge_band or b.x1 < r.edge_band / 2 or b.x0 > 1 - r.edge_band / 2
+    if small and (corner or edge):
+        hits.append("C1")
+    letters = sum(1 for c in b.text if c.isalpha())
+    if b.caps and b.tracking >= r.caps_tracking_em and b.size <= r.caps_max_size and letters >= 2:
+        hits.append("C2")
+    counter = RX_COUNTER_NUM.search(b.text) or RX_COUNTER_WORD.search(b.text) or RX_COUNTER_BARE.search(b.text)
+    if b.size <= r.counter_max_size and counter and not RX_24_7.search(b.text):
+        hits.append("C3")
+    if (RX_META.search(b.text) and b.size <= r.counter_max_size) or (RX_VERSION.search(b.text) and small):
+        hits.append("C4")
+    return hits
+
+
+def _kickers(free: list[Block], r: ChromeRules) -> dict[int, Block]:
+    out = {}
+    for a in free:
+        for i, b in enumerate(free):
+            if a is b or a.size > r.small_text or b.size < max(a.size * r.kicker_ratio, r.headline_min_size):
+                continue
+            gap = b.y0 - a.y1
+            aligned = abs(a.x0 - b.x0) < 0.02 or abs(a.cx - b.cx) < 0.02
+            if -0.01 < gap < r.kicker_gap and aligned:
+                out[i] = a
+    return out
+
+
+def _deck(free: list[Block], shapes: list[Shape], kickers: dict[int, Block], r: ChromeRules):
+    biggest = max((b.size for b in free), default=0.0)
+    for i, b in enumerate(free):
+        left = 0.02 <= b.x0 < r.deck_left_x and b.x1 < 0.78
+        if not (b.size >= r.headline_min_size and b.size >= 0.85 * biggest and left
+                and b.align != "center" and abs(b.cx - 0.5) > 0.06):
+            continue
+        why = []
+        if any(c is not b and 0.02 <= c.size <= 0.6 * b.size and -0.005 < c.y0 - b.y1 < 0.08
+               and abs(c.x0 - b.x0) < 0.03 for c in free):
+            why.append("sub-line")
+        if i in kickers:
+            why.append("kicker")
+        if any(s.kind in ("media", "surface") and 0.04 <= (s.x1 - s.x0) * (s.y1 - s.y0) <= 0.7
+               and (s.x0 + s.x1) / 2 > 0.5 and s.x0 > b.x1 - 0.05 and s.y1 > b.y0 and s.y0 < b.y1 + 0.2
+               for s in shapes):
+            why.append("media on the right")
+        if b.lines >= 2:
+            why.append(f"{b.lines} lines")
+        yield b, why
+
+
+def _bars(shapes: list[Shape], r: ChromeRules) -> list[Shape]:
+    out = []
+    for s in shapes:
+        if s.kind in ("media", "surface"):
+            continue
+        w, h, cy = s.x1 - s.x0, s.y1 - s.y0, (s.y0 + s.y1) / 2
+        if w >= r.bar_min_width and h <= r.bar_max_height and (cy < r.bar_band or cy > 1 - r.bar_band):
+            out.append(s)
+    return out
+
+
+def _progress(samples: list[dict], r: ChromeRules) -> list[tuple[str, float, float]]:
+    """(id, first width, last width) of thin bars that grow over time."""
+    widths: dict[str, list[float]] = {}
+    for s in samples:
+        for sh in s["shapes"]:
+            if sh.kind not in ("media", "surface") and sh.y1 - sh.y0 <= 0.02:
+                widths.setdefault(sh.sid, []).append(sh.x1 - sh.x0)
+    out = []
+    for sid, ws in widths.items():
+        steps = [b - a for a, b in zip(ws, ws[1:])]
+        grows = ws[-1] - ws[0] >= r.progress_min_growth and all(d >= -0.005 for d in steps)
+        if len(ws) >= 2 and grows:
+            out.append((sid, ws[0], ws[-1]))
+    return out
+
+
+def lint(samples: list[dict], r: ChromeRules, allow: set[str]) -> dict:
+    hits: dict[tuple, dict] = {}
+
+    def add(rule: str, t: float, what: str, sev: str | None = None):
+        key = (rule, what)
+        h = hits.setdefault(key, {"rule": rule, "what": what, "times": [], "sev": sev or SEVERITY[rule]})
+        if t not in h["times"]:
+            h["times"].append(t)
+
+    for s in samples:
+        t = s["t"]
+        free = [b for b in s["blocks"] if b.role not in r.exempt_roles and _held(b, t, samples, r)]
+        for b in free:
+            for rule in _text_rules(b, r):
+                add(rule, t, b.text)
+        kickers = _kickers(free, r)
+        for i, a in kickers.items():
+            add("C7", t, f"{a.text!r} over {free[i].text!r}")
+        for b, why in _deck(free, s["shapes"], kickers, r):
+            add("D1", t, f"{b.text!r}" + (f" with {', '.join(why)}" if why else " alone"),
+                "FAIL" if why else "WARN")
+        for sh in _bars(s["shapes"], r):
+            add("C6", t, f"{sh.kind} {sh.sid} at y={sh.y0:.2f}-{sh.y1:.2f}")
+    for sid, w0, w1 in _progress(samples, r):
+        add("P1", samples[0]["t"], f"bar {sid} grows {w0:.2f} -> {w1:.2f} of the width")
+    used = sorted({h["rule"] for h in hits.values()} & allow)
+    kept = [h for h in hits.values() if h["rule"] not in allow]
+    kept.sort(key=lambda h: (h["rule"], h["times"][0]))
+    return {"hits": kept, "allowed": used, "passed": not any(h["sev"] == "FAIL" for h in kept)}
+
+
+# --------------------------------------------------------------------- CLI
+
+def report(rep: dict, source: str, n_samples: int, from_template: bool) -> int:
+    print(f"{source}: {n_samples} sample(s)")
+    if from_template:
+        print(f"  note: no '{BLOCK}' block in the project config; using the template's")
+    for h in rep["hits"]:
+        times = ", ".join(f"{t:.2f}s" for t in sorted(h["times"])[:6])
+        print(f"  {h['sev']:4} {h['rule']} {NAMES[h['rule']]}: {h['what']}  [{times}]")
+    for rule in rep["allowed"]:
+        print(f"  allowed {rule} {NAMES[rule]} (the style measured it)")
+    print(f"GATE chrome: {'PASS' if rep['passed'] else 'FAIL'}")
+    return 0 if rep["passed"] else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Page-chrome / slide-look lint on a layout snapshot or a timeline.")
+    add_config_arg(ap)
+    src = ap.add_mutually_exclusive_group(required=True)
+    src.add_argument("--snapshot", help="layout JSON written by assets/chrome/collect_layout.js")
+    src.add_argument("--timeline", help="timeline JSON with text layers in elements[]")
+    ap.add_argument("--allow", default="", help="comma-separated rules the chosen style measured (e.g. P1)")
+    args = ap.parse_args(argv)
+    try:
+        cfg = load(args.config)
+        r, from_template = rules(cfg)
+        allow = {a.strip() for a in args.allow.split(",") if a.strip()}
+        if args.snapshot:
+            p = Path(args.snapshot)
+            if not p.exists():
+                raise tl.TimelineError(f"snapshot not found: {p}")
+            samples = samples_from_snapshot(json.loads(p.read_text(encoding="utf-8")))
+            source = p.name
+        else:
+            data = tl.load(args.timeline)
+            allow |= set(data.get("chrome_allow") or [])
+            samples = samples_from_timeline(data, cfg.frame.width, cfg.frame.height, r)
+            source = Path(args.timeline).name
+        unknown = allow - set(SEVERITY)
+        if unknown:
+            raise ConfigError(f"unknown rule(s) in allow: {', '.join(sorted(unknown))}")
+        return report(lint(samples, r, allow), source, len(samples), from_template)
+    except (ConfigError, tl.TimelineError, json.JSONDecodeError, KeyError, ValueError, OSError) as e:
+        print(f"ERROR: {e}")
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,193 @@
+# -*- coding: utf-8 -*-
+"""DEAD-FRAME gate, measured on the FINAL MP4, every frame.
+
+Two measures on a small luma copy of each frame (dead_frames.analysis_width x
+dead_frames.analysis_height):
+
+    FLAT (blocks). A frame that is one uniform field: std-dev under
+        dead_frames.flat_std AND range under dead_frames.flat_range. A run of
+        MORE than dead_frames.flat_max_frames flat frames fails: a black or
+        blank gap between scenes, a render that lost a layer, a fade that
+        bottoms out on nothing. Shorter dips (a frame or three inside a
+        transition) are listed and ignored.
+    FROZEN (warns). A frame whose mean absolute difference to the previous
+        one is under dead_frames.frozen_diff. A frozen run longer than
+        dead_frames.frozen_warn_s is printed as a warning: a held card while
+        the voice talks may be the point (a price being read), so this never
+        blocks.
+
+Plus a MOTION note: the mean frame-to-frame change against
+dead_frames.motion_band_reference. It is a question, never a gate, and the
+reference comes from horizontal brand films, not vertical Reels.
+
+What it cannot see:
+    - A talking head is never flat and rarely frozen: sensor noise, breathing
+      and compression keep the frame difference above the threshold even when
+      the shot is visually dead. Boredom on camera is for the eye.
+    - Grain, a noise overlay or a looping background keep a dead slide
+      "moving". A caret or one small ticking element does too.
+    - A dark frame with one small line of text is not flat (its range is
+      high). Whether the frame is full enough is measure_density.py.
+    - Freezes under the threshold inside a region (half the frame still) do
+      not count: the measure is the whole frame.
+
+Ported from gate G2 of motionmaxxing (Apache-2.0,
+github.com/Tejashmakwana/motionmaxxing), adapted to 9:16; see
+THIRD-PARTY-NOTICES.md.
+
+Exit code: 0 pass (warnings allowed), 1 fail, 2 file or config unreadable.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Iterable
+
+from check_safe_zone import ReadError, all_frames, video_fps
+from config import Config, ConfigError, add_config_arg, load, optional_block
+
+BLOCK = "dead_frames"
+
+
+@dataclass(frozen=True)
+class DeadFrameRules:
+    width: int
+    height: int
+    flat_std: float
+    flat_range: int
+    flat_max_frames: int
+    frozen_diff: float
+    frozen_warn_s: float
+    motion_band: tuple[float, float, float]
+
+
+def rules(cfg: Config) -> tuple[DeadFrameRules, bool]:
+    """(rules, from_template). Refuses an incoherent block."""
+    b, from_template = optional_block(cfg, BLOCK)
+    try:
+        band = tuple(float(v) for v in b["motion_band_reference"])
+        r = DeadFrameRules(
+            width=int(b["analysis_width"]), height=int(b["analysis_height"]),
+            flat_std=float(b["flat_std"]), flat_range=int(b["flat_range"]),
+            flat_max_frames=int(b["flat_max_frames"]), frozen_diff=float(b["frozen_diff"]),
+            frozen_warn_s=float(b["frozen_warn_s"]), motion_band=band)
+    except (KeyError, TypeError, ValueError) as e:
+        raise ConfigError(f"{BLOCK}: missing or invalid key ({e})") from e
+    if r.width <= 0 or r.height <= 0:
+        raise ConfigError(f"{BLOCK}.analysis_width and analysis_height must be > 0")
+    if r.flat_max_frames < 0 or r.flat_std <= 0 or r.flat_range <= 0:
+        raise ConfigError(f"{BLOCK}.flat_* must be > 0 (flat_max_frames >= 0)")
+    if r.frozen_diff <= 0 or r.frozen_warn_s <= 0:
+        raise ConfigError(f"{BLOCK}.frozen_diff and frozen_warn_s must be > 0")
+    if len(band) != 3 or not band[0] <= band[1] <= band[2]:
+        raise ConfigError(f"{BLOCK}.motion_band_reference must be [q1, median, q3]")
+    return r, from_template
+
+
+def is_flat(frame: bytes, r: DeadFrameRules) -> bool:
+    n = len(frame)
+    if n == 0:
+        return True
+    if max(frame) - min(frame) >= r.flat_range:
+        return False
+    s = sum(frame)
+    var = sum(v * v for v in frame) / n - (s / n) ** 2
+    return (var ** 0.5 if var > 0 else 0.0) < r.flat_std
+
+
+def mean_abs_diff(a: bytes, b: bytes) -> float:
+    return sum(abs(x - y) for x, y in zip(a, b)) / max(1, len(a))
+
+
+def runs(flags: list[bool]) -> list[tuple[int, int]]:
+    """(first, last) index of every run of True."""
+    out, start = [], None
+    for i, f in enumerate(flags):
+        if f and start is None:
+            start = i
+        elif not f and start is not None:
+            out.append((start, i - 1))
+            start = None
+    if start is not None:
+        out.append((start, len(flags) - 1))
+    return out
+
+
+def analyze(frames: Iterable[bytes], fps: float, r: DeadFrameRules) -> dict:
+    flat, frozen, diffs, prev = [], [False], [], None
+    for fr in frames:
+        flat.append(is_flat(fr, r))
+        if prev is not None:
+            d = mean_abs_diff(fr, prev)
+            diffs.append(d)
+            frozen.append(d < r.frozen_diff)
+        prev = fr
+    if not flat:
+        raise ReadError("no frame decoded")
+    flat_runs = runs(flat)
+    too_long = [(s, e) for s, e in flat_runs if e - s + 1 > r.flat_max_frames]
+    # A flat run is also "frozen"; report it once, as flat.
+    frozen_runs = [(s - 1, e) for s, e in runs(frozen)
+                   if (e - s + 2) / fps > r.frozen_warn_s and not all(flat[s:e + 1])]
+    return {
+        "frames": len(flat),
+        "fps": fps,
+        "flat_fail": too_long,
+        "flat_ignored": [x for x in flat_runs if x not in too_long],
+        "frozen_warn": frozen_runs,
+        "motion_mean": sum(diffs) / len(diffs) if diffs else 0.0,
+        "passed": not too_long,
+    }
+
+
+def _span(s: int, e: int, fps: float) -> str:
+    return f"{s / fps:6.2f}s -> {(e + 1) / fps:6.2f}s ({e - s + 1} f)"
+
+
+def report(name: str, rep: dict, r: DeadFrameRules, from_template: bool) -> int:
+    fps = rep["fps"]
+    print(f"{name}: {rep['frames']} frames @ {fps:.2f} fps")
+    if from_template:
+        print(f"  note: no '{BLOCK}' block in the project config; using the template's")
+    if rep["flat_fail"]:
+        print(f"  FLAT: {len(rep['flat_fail'])} run(s) of more than "
+              f"dead_frames.flat_max_frames={r.flat_max_frames} uniform frames:")
+        for s, e in rep["flat_fail"][:10]:
+            print(f"     {_span(s, e, fps)}")
+    else:
+        print(f"  ok: no run of more than {r.flat_max_frames} flat frames")
+    if rep["flat_ignored"]:
+        print(f"  {len(rep['flat_ignored'])} short dip(s) ignored: "
+              + ", ".join(f"{s / fps:.2f}s" for s, _ in rep["flat_ignored"][:6]))
+    for s, e in rep["frozen_warn"][:10]:
+        print(f"  WARN frozen picture {_span(s, e, fps)} > dead_frames.frozen_warn_s="
+              f"{r.frozen_warn_s}: is something alive on it, or is the hold the point?")
+    q1, med, q3 = r.motion_band
+    print(f"  motion {rep['motion_mean']:.1f} (reference band {q1}-{q3}, median {med}, "
+          "horizontal brand films; a question, not a gate)")
+    return 0 if rep["passed"] else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Dead-frame gate: flat runs (block) and frozen picture (warn) on the final MP4.")
+    add_config_arg(ap)
+    ap.add_argument("video", help="final MP4")
+    args = ap.parse_args(argv)
+    try:
+        cfg = load(args.config)
+        r, from_template = rules(cfg)
+        if not os.path.exists(args.video):
+            raise ReadError(f"video not found: {args.video}")
+        frames = (f for _, f in all_frames(args.video, r.width, r.height))
+        rep = analyze(frames, video_fps(args.video), r)
+        return report(os.path.basename(args.video), rep, r, from_template)
+    except (ConfigError, ReadError, subprocess.SubprocessError, OSError) as e:
+        print(f"ERROR: {e}")
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())