Skip to content

Looksmaxxing for motion graphics. An agent skill that turns AI slop videos into films that look made by a motion designer.

30.1 KB
Raw Blame
#!/usr/bin/env python3
"""look.py - make a finished film inspectable: contact sheet, cuts, frozen stretches, end hold, pre-cut frames, loudness. stdlib + ffmpeg.

Usage:
  python3 look.py film.mp4 [--out look] [--frames 16] [--scene 0.3] [--scene-low 0.12] [--freeze-min 0.6]
                  [--events events.json] [--hold-warn 1.4] [--hold-eps 0.35] [--shown 12]
                  [--expect S] [--expect-tol 0.15] [--expect-audio] [--strict]

Cuts - two sources, events win:
  1. EVENTS (authoritative). If --events FILE is given, or <film>.events.json / <film stem>.events.json exists (render.mjs writes
     <out>.mp4.events.json from window.__events), every event whose "type" is cut/show/hide or contains "cut" is a cut at
     "t" seconds (or "frame"/fps). Events without a "type" (e.g. an SFX list) are ignored. Detection still runs and anything it
     finds that the events do not explain is printed as a cross-check.
  2. DETECTION (no events). A cut is a frame where (a) ffmpeg scene score >= --scene, or (b) scene >= --scene-low AND the picture is
     structurally different from the previous frame (luma correlation < 0.7) AND the change is abrupt (not a multi-frame animation), or (c) a pixel-difference spike (>= 2.5x the median of
     the neighbouring frame diffs, mean |diff| >= 5/255 on a 96x54 luma) with correlation < 0.6. (c) catches cuts between
     similar-toned shots that the scene score misses; the correlation test rejects fast pushes/zooms of one picture. Candidates
     within 3 frames of each other are merged (strongest kept).

Writes (nothing per-frame ever touches the disk; frames are tiled inside ffmpeg):
  look/sheet.jpg   contact sheet, N evenly spaced frames (4 columns) with timecodes burned in
  look/cuts.txt    cut times (s, frame, timecode, source)
  look/still.txt   stretches >= --freeze-min seconds where the picture does not change (ffmpeg freezedetect)
  look/mid.jpg     frames 2 frames BEFORE each cut (max --shown) - where broken transitions hide
  look/strips.jpg  one row per cut (max --shown): frames cut-1 | cut | cut+1
Report adds: longest static-ish stretch (mean frame diff < --hold-eps /255), the final shot (last cut -> end) and the END HOLD:
how long the picture is unchanged at the end (trailing frames with diff < --hold-eps, so slow scale/position drift counts as held).
--hold-warn S (default 1.4, 0 = off) prints a WARNING when the end hold exceeds S seconds.
GATES block (printed last, also written to look/gates.json): the gates this script can compute from the finished file.
  G0 render exists: decodes, is not blank (>= 5 % of frames have picture content), moves (>= 5 % of frames change), duration matches
     --expect S (+-0.15 s, --expect-tol) when given, an audio stream exists and is not silent when --expect-audio.
  G2 no empty frame: a run of MORE than 3 consecutive frames that are one flat field (luma std < 1.5 and range < 8 on the 96x54 analysis
     frame) is a FAIL with its times; runs of <= 3 frames (a dip inside a transition) are ignored.
  G3 end card: the picture-unchanged end hold must be <= --hold-warn (1.4 s); a hold under 0.6 s is a NOTE (the film ends mid-motion:
     fine when intended); the final shot (last cut -> end) must be <= 25 % of the film.
  G1 (proof readable), G4 (one hero per frame) are judged by eye on sheet.jpg; G5 (no page chrome) is lint.mjs.
AUDIO block (when the film has sound): integrated LUFS / LRA / true peak (peak above -1 dBTP is flagged), audible span (leading and
  trailing silence, dropouts of digital silence in the middle), silent tail > 0.5 s at the end, and audio onsets next to the picture
  cuts (share of cuts that land within +-80 ms of a sound onset; pros land about a third of their cuts on a hit).
MOTION note: mean frame-to-frame luma change (0-255 on the 96x54 analysis frame). Human-made films: median 6.8, IQR 4.4-9.8. A QUESTION,
  never a gate: below the band ask what is alive between beats; above it ask whether the picture is too busy to read.
Options for the gates: --expect S (expected duration)  --expect-tol S  --expect-audio  --strict (exit 3 when any gate FAILs).
Facts only, no scores. Exit: 0 ok, 1 failure, 2 bad usage, 3 a gate FAILed under --strict.
"""
from __future__ import annotations
import argparse, json, math, operator, os, re, shutil, subprocess, sys

FONTS = ["/System/Library/Fonts/Menlo.ttc", "/System/Library/Fonts/Supplemental/Courier New.ttf",
         "/System/Library/Fonts/Helvetica.ttc", "/Library/Fonts/Arial.ttf", "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf"]
AW, AH = 96, 54          # analysis resolution (luma)
ST = {}                  # per-frame luma stats filled by analyse(): mean, std, range
MERGE = 3                # frames: candidates closer than this are one cut


def die(msg, code=1):
    print("error: " + msg, file=sys.stderr)
    sys.exit(code)


def ff(args, check=True):
    r = subprocess.run(["ffmpeg", "-hide_banner", "-nostats", "-y"] + args, capture_output=True, text=True)
    if check and r.returncode:
        die("ffmpeg failed: " + " ".join(args[:6]) + " ...\n" + r.stderr[-1000:])
    return r


def probe(f):
    r = subprocess.run(["ffprobe", "-v", "error", "-show_streams", "-show_format", "-of", "json", f], capture_output=True, text=True)
    if r.returncode:
        die("ffprobe cannot read %s: %s" % (f, r.stderr.strip()[:300]))
    return json.loads(r.stdout)


def tc(t):
    return "%d:%05.2f" % (int(t // 60), t % 60)


def drawtext_filter(font):
    if not font:
        return ""
    return ("drawtext=fontfile='%s':text='%%{pts\\:hms}':x=6:y=h-th-6:fontsize=18:fontcolor=white:box=1:[email protected]:boxborderw=4," % font)


def median(v):
    s = sorted(v)
    n = len(s)
    return 0.0 if not n else (s[n // 2] if n % 2 else (s[n // 2 - 1] + s[n // 2]) / 2)


def analyse(film):
    """One streamed pass over a tiny luma version of the film -> per-frame (mean |diff| to previous, luma correlation to previous)."""
    p = subprocess.Popen(["ffmpeg", "-v", "error", "-i", film, "-an", "-vf", "scale=%d:%d:flags=area,format=gray" % (AW, AH), "-f", "rawvideo", "-"],
                         stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
    size = AW * AH
    prev = None
    M, C = [], []
    sub, mul = operator.sub, operator.mul
    prev_stats = None
    ST.clear(); ST.update(mean=[], std=[], rng=[])
    while True:
        buf = p.stdout.read(size)
        if len(buf) < size:
            break
        fr = buf
        mean = sum(fr) / size
        var = sum(map(mul, fr, fr)) - size * mean * mean
        ST["mean"].append(mean); ST["std"].append(math.sqrt(max(0.0, var) / size)); ST["rng"].append(max(fr) - min(fr))
        if prev is None:
            M.append(0.0); C.append(1.0)
        else:
            M.append(sum(map(abs, map(sub, fr, prev))) / size)
            pm, pv = prev_stats
            if var < 1e-3 and pv < 1e-3:
                C.append(1.0 if abs(mean - pm) < 2 else 0.0)
            elif var < 1e-3 or pv < 1e-3:
                C.append(0.0)
            else:
                cov = sum(map(mul, fr, prev)) - size * mean * pm
                C.append(cov / math.sqrt(var * pv))
        prev, prev_stats = fr, (mean, var)
    p.wait()
    return M, C


def merge_frames(cands, gap=MERGE):
    """cands: [(frame, info[, strength])] -> non-max suppression: the strongest of every group closer than gap+1 frames survives
    (equal strength: the earlier one). Events carry no strength, so the first one wins."""
    order = sorted(cands, key=lambda x: (-(x[2] if len(x) > 2 else 0.0), x[0]))
    kept = []
    for c in order:
        if all(abs(c[0] - k[0]) > gap for k in kept):
            kept.append(c)
    return [(k[0], k[1]) for k in sorted(kept, key=lambda x: x[0])]


def detect(M, C, scene, scene_hi, scene_lo):
    n = len(M)
    cands = []
    for i in range(2, n):
        sc = scene.get(i, 0.0)
        strength = max(sc, min(1.0, M[i] / 150.0))
        if sc >= scene_hi:
            cands.append((i, "scene %.2f" % sc, strength)); continue
        before = median(M[max(1, i - 4):i])
        after = median(M[i + 1:i + 5]) if i + 1 < n else 0.0
        r = M[i] / (max(before, after) + 0.3)       # how much this frame stands out from its neighbours (an abrupt change, not an animation)
        if sc >= scene_lo and C[i] < 0.7 and M[i] >= 3.0 and r >= 1.8:
            cands.append((i, "scene %.2f + corr %.2f spike x%.1f" % (sc, C[i], r), strength)); continue
        if r >= 2.5 and M[i] >= 5.0 and C[i] < 0.6:
            cands.append((i, "pixel spike x%.1f diff %.1f corr %.2f scene %.2f" % (r, M[i], C[i], sc), strength))
    return merge_frames(cands)


def find_events(film, given):
    cands = [given] if given else [film + ".events.json", os.path.splitext(film)[0] + ".events.json"]
    for c in cands:
        if c and os.path.isfile(c):
            return c
    if given:
        die("events file not found: " + given, 2)
    return None


def events_to_cuts(path, fps, nframes):
    try:
        ev = json.load(open(path))
    except (OSError, ValueError) as e:
        die("cannot read events %s: %s" % (path, e))
    if isinstance(ev, dict):
        ev = ev.get("events", [])
    out, kinds = [], {}
    for e in ev if isinstance(ev, list) else []:
        if not isinstance(e, dict):
            continue
        ty = str(e.get("type", "")).lower()
        if not ty or not (ty in ("cut", "show", "hide") or "cut" in ty):
            continue
        if isinstance(e.get("t"), (int, float)):
            fr = int(round(e["t"] * fps))
        elif isinstance(e.get("frame"), (int, float)):
            fr = int(round(e["frame"]))
        else:
            continue
        if 0 < fr < nframes:
            out.append((fr, "event %s%s" % (ty, " '%s'" % e["label"] if e.get("label") else "")))
            kinds[ty] = kinds.get(ty, 0) + 1
    return merge_frames(out), kinds


def runs_below(M, eps):
    """[(first_frame, last_frame)] of consecutive frames (index>=1) whose diff to the previous frame is < eps."""
    out, s = [], None
    for i in range(1, len(M)):
        if M[i] < eps:
            s = i if s is None else s
        elif s is not None:
            out.append((s, i - 1)); s = None
    if s is not None:
        out.append((s, len(M) - 1))
    return out


# ------------------------------------------------------------------ gates + audio audit
HUMAN_MOTION = (6.8, 4.4, 9.8)    # median, Q1, Q3 of mean |frame diff| over human-made launch films (same 96x54 luma measure)
FLAT_STD, FLAT_RNG, FLAT_MAX_OK = 1.5, 8, 3


def audio_env(film, sr=8000, hop=0.01):
    """Mono 8 kHz decode -> RMS level in dBFS per 10 ms window. Pure python (array); ~0.3 s per 10 s of film."""
    import array
    r = subprocess.run(["ffmpeg", "-v", "error", "-i", film, "-vn", "-ac", "1", "-ar", str(sr), "-f", "s16le", "-"], capture_output=True)
    raw = r.stdout[: len(r.stdout) // 2 * 2]
    a = array.array("h")
    a.frombytes(raw)
    n = int(sr * hop)
    env = []
    full = 32768.0 ** 2
    for i in range(0, len(a) - n + 1, n):
        seg = a[i:i + n]
        env.append(10 * math.log10(max(sum(x * x for x in seg) / n / full, 1e-12)))
    return env, hop


def audio_audit(film, dur, cut_times):
    env, hop = audio_env(film)
    if len(env) < 10:
        return None
    AUD, DIG = -50.0, -70.0
    idx = [i for i, v in enumerate(env) if v >= AUD]
    res = {"dur": dur, "env_n": len(env)}
    if not idx:
        res.update(audible=None, lead=dur, tail=dur, dropouts=[], onsets=[], silent=True)
        return res
    first, last = idx[0] * hop, (idx[-1] + 1) * hop
    # dropouts: digital silence (< -70 dB) of >= 0.25 s strictly between first and last audible
    drops, s0 = [], None
    for i in range(idx[0], idx[-1] + 1):
        if env[i] < DIG:
            s0 = i if s0 is None else s0
        elif s0 is not None:
            if (i - s0) * hop >= 0.25:
                drops.append((s0 * hop, i * hop))
            s0 = None
    # onsets: >= 8 dB above the median of the previous 70 ms, and above -38 dB; merged within 80 ms
    on = []
    for i in range(8, len(env) - 1):
        peak = max(env[i], env[i + 1])
        if peak >= -38 and peak - median(env[i - 8:i - 1]) >= 8 and env[i - 1] < peak - 3:
            t = i * hop
            if not on or t - on[-1] > 0.08:
                on.append(t)
    res.update(audible=(first, last), lead=first, tail=max(0.0, dur - last), dropouts=drops, onsets=on, silent=False)
    if cut_times and on:
        offs = []
        for c in cut_times:
            o = min(on, key=lambda x: abs(x - c))
            offs.append((c, o - c))
        res["cut_offsets"] = offs
    return res


def print_audio(res, loud, au, cut_times):
    if not au:
        return
    print("AUDIO")
    tp = loud.get("true_peak_dbfs") if loud else None
    flags = []
    try:
        if tp is not None and float(tp) > -1.0:
            flags.append("true peak %s dBFS is above -1 dBTP (inter-sample clipping risk on lossy encode)" % tp)
        lu = float(loud["integrated_lufs"]) if loud and loud.get("integrated_lufs") else None
        if lu is not None and not (-17.5 <= lu <= -11.5):
            flags.append("integrated %.1f LUFS is far from the -14 LUFS delivery target" % lu)
    except (TypeError, ValueError):
        pass
    if loud:
        print("  loudness   integrated %s LUFS   LRA %s LU   true peak %s dBFS" % (loud["integrated_lufs"], loud["lra_lu"], loud["true_peak_dbfs"]))
    if res is None:
        print("  (audio too short to analyse)")
    elif res["silent"]:
        print("  audible    NONE: the whole soundtrack is below -50 dBFS")
        flags.append("soundtrack is silent")
    else:
        a0, a1 = res["audible"]
        span = a1 - a0
        print("  audible    %.2f-%.2f s of %.2f s (%.0f %%)   lead silence %.2f s   tail silence %.2f s" % (a0, a1, res["dur"], 100 * span / res["dur"], res["lead"], res["tail"]))
        if res["tail"] > 0.5:
            flags.append("silent tail %.2f s at the end (> 0.5 s): the music ends early or the file is longer than the track; refit it (voice.py music-fit) or end the picture sooner" % res["tail"])
        if res["lead"] > 0.5:
            flags.append("silence for the first %.2f s" % res["lead"])
        if res["dropouts"]:
            flags.append("digital-silence dropouts inside the film: " + ", ".join("%.2f-%.2f s" % d for d in res["dropouts"][:6]))
        on = res["onsets"]
        print("  onsets     %d sound onsets (>= 8 dB jump)%s" % (len(on), ": " + ", ".join("%.2f" % t for t in on[:16]) + (" ..." if len(on) > 16 else "") if on else ""))
        offs = res.get("cut_offsets")
        if offs:
            hit = [o for o in offs if abs(o[1]) <= 0.08]
            chance = min(1.0, len(on) * 0.16 / res["dur"])
            print("  cut sync   %d of %d cuts land within +-80 ms of a sound onset (%.0f %%; pros ~35 %%; chance level with %d onsets in %.0f s is ~%.0f %%)" % (len(hit), len(offs), 100.0 * len(hit) / len(offs), len(on), res["dur"], 100 * chance))
            near = [(c, d) for c, d in offs if 0.08 < abs(d) <= 0.3]
            if near:
                print("             near misses: " + ", ".join("cut %.2f s -> onset %+d ms" % (c, round(d * 1000)) for c, d in near[:8]) + "  (a hit 80-300 ms off the picture reads as late/early)")
        elif cut_times and not on:
            print("  cut sync   no onsets found: the sound has no hits to line up with the cuts")
    for f in flags:
        print("  FLAG       " + f)
    if not flags:
        print("  flags      none")


def compute_gates(a, dur, fps, nf, M, C, vs, au, cut_times, hold, final_dur, probe_ok=True):
    G = []
    std, rng, mean = ST["std"], ST["rng"], ST["mean"]
    n = len(std)
    # ---- G0
    why, st = [], "PASS"
    nonflat = sum(1 for v in std if v >= FLAT_STD)
    moving = sum(1 for v in M[1:] if v >= 0.35)
    if n == 0 or nonflat < max(1, 0.05 * n):
        why.append("BLANK: only %d of %d frames have picture content (std >= %.1f)" % (nonflat, n, FLAT_STD)); st = "FAIL"
    if n and max(mean) < 3:
        why.append("all frames are black"); st = "FAIL"
    if n > 1 and moving < max(2, 0.05 * (n - 1)):
        why.append("NO MOTION: only %d of %d frames differ from the previous one" % (moving, n - 1)); st = "FAIL"
    if a.expect is not None:
        tol = a.expect_tol
        if abs(dur - a.expect) > tol:
            why.append("duration %.2f s but --expect %.2f s (+-%.2f)" % (dur, a.expect, tol)); st = "FAIL"
        else:
            why.append("duration %.2f s matches --expect %.2f s" % (dur, a.expect))
    else:
        why.append("duration %.2f s (not checked: no --expect)" % dur)
    if a.expect_audio:
        if not au:
            why.append("NO AUDIO STREAM but --expect-audio"); st = "FAIL"
        else:
            why.append("audio stream present")
    else:
        why.append("audio %s" % ("present" if au else "none (not required)"))
    G.append(("G0", "render exists", st, "; ".join(why)))
    # ---- G2: runs of > 3 flat frames
    runs, s0 = [], None
    for i in range(n):
        flat = std[i] < FLAT_STD and rng[i] < FLAT_RNG
        if flat:
            s0 = i if s0 is None else s0
        elif s0 is not None:
            runs.append((s0, i - 1)); s0 = None
    if s0 is not None:
        runs.append((s0, n - 1))
    bad = [(s, e) for s, e in runs if e - s + 1 > FLAT_MAX_OK]
    ign = [(s, e) for s, e in runs if e - s + 1 <= FLAT_MAX_OK]
    if bad:
        d = "; ".join("%.2f-%.2f s (%d f, luma %.0f)" % (s / fps, (e + 1) / fps, e - s + 1, mean[s]) for s, e in bad[:8])
        G.append(("G2", "no empty frame", "FAIL", "flat-field runs of > %d frames: %s" % (FLAT_MAX_OK, d)))
    else:
        G.append(("G2", "no empty frame", "PASS", "no run of > %d flat frames%s" % (FLAT_MAX_OK, ("; %d short dip(s) ignored: %s" % (len(ign), ", ".join("%.2fs" % (s / fps) for s, _ in ign[:6]))) if ign else "")))
    # ---- G3
    share = final_dur / dur if dur else 0
    st, why = "PASS", []
    if a.hold_warn > 0 and hold > a.hold_warn:
        st = "FAIL"; why.append("end hold %.2f s > %.2f s" % (hold, a.hold_warn))
    elif hold < 0.6:
        why.append("end hold %.2f s: ends mid-motion (NOTE: fine when intended)" % hold)
    else:
        why.append("end hold %.2f s (0.6-%.1f)" % (hold, a.hold_warn))
    if cut_times:
        if share > 0.25:
            st = "FAIL"; why.append("final shot %.2f s = %.0f %% of the film (> 25 %%)" % (final_dur, 100 * share))
        else:
            why.append("final shot %.2f s = %.0f %% of the film (<= 25 %%)" % (final_dur, 100 * share))
    else:
        why.append("no cuts: final-shot share not computed")
    G.append(("G3", "end card hold, CTA share", st, "; ".join(why)))
    return G


def print_gates(G, M, fps):
    print("GATES")
    for gid, name, st, why in G:
        print("  %s %-26s %-4s  %s" % (gid, name, st, why))
    print("  G1 proof readable / G4 one hero per frame: by eye on the sheet.   G5 no page chrome: node lint.mjs index.html")
    if len(M) > 2:
        mm = sum(M[1:]) / (len(M) - 1)
        med, q1, q3 = HUMAN_MOTION
        band = "inside" if q1 <= mm <= q3 else ("below" if mm < q1 else "above")
        print("MOTION")
        print("  mean frame-to-frame luma change %.1f/255 (human-made films: median %.1f, IQR %.1f-%.1f): %s the human band" % (mm, med, q1, q3, band))
        if band == "below":
            print("  question: between the beats, what on screen is alive? (drift, creep, a caret, a loop), or is the film mostly held?")
        elif band == "above":
            print("  question: is the picture busy enough that the proof frame cannot be read? Which frame is the one to remember?")
        else:
            print("  question: is the motion spent where the story needs it, or spread evenly?")


def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("film")
    ap.add_argument("--out", default="look")
    ap.add_argument("--frames", type=int, default=16)
    ap.add_argument("--scene", type=float, default=0.3, help="scene score that alone makes a cut")
    ap.add_argument("--scene-low", type=float, default=0.12, help="lower scene score that counts when the picture also changed structurally")
    ap.add_argument("--freeze-min", type=float, default=0.6)
    ap.add_argument("--events", help="events.json from render.mjs (default: <film>.events.json if present)")
    ap.add_argument("--hold-warn", type=float, default=1.4, help="warn when the end hold exceeds this many seconds (0 = off)")
    ap.add_argument("--hold-eps", type=float, default=0.35, help="mean |frame diff| (0-255, 96x54 luma) below which the picture counts as held")
    ap.add_argument("--shown", type=int, default=12, help="max cuts shown in mid.jpg / strips.jpg")
    ap.add_argument("--expect", type=float, default=None, help="G0: expected film duration in seconds")
    ap.add_argument("--expect-tol", type=float, default=0.15, help="G0: duration tolerance in seconds")
    ap.add_argument("--expect-audio", action="store_true", help="G0: the film must contain an audio stream")
    ap.add_argument("--strict", action="store_true", help="exit 3 when any gate FAILs")
    a = ap.parse_args()
    if not os.path.isfile(a.film):
        die("film not found: " + a.film, 2)
    for t in ("ffmpeg", "ffprobe"):
        if not shutil.which(t):
            die(t + " not found")
    os.makedirs(a.out, exist_ok=True)
    font = next((f for f in FONTS if os.path.exists(f)), None)
    if not font:
        print("warn: no font found for timecodes; sheet will have none", file=sys.stderr)

    info = probe(a.film)
    vs = next((s for s in info["streams"] if s["codec_type"] == "video"), None)
    au = next((s for s in info["streams"] if s["codec_type"] == "audio"), None)
    if not vs:
        die("no video stream in " + a.film)
    dur = float(info["format"].get("duration") or vs.get("duration") or 0)
    n_, d_ = (vs.get("avg_frame_rate") or "0/1").split("/")
    fps = float(n_) / float(d_) if float(d_) else 0.0
    if dur <= 0 or fps <= 0:
        die("cannot determine duration/fps")
    nframes = int(vs.get("nb_frames") or round(dur * fps))
    W, H = vs["width"], vs["height"]

    # ---- contact sheet (frame-number select = exact, evenly spaced, centred in their slots)
    N = max(1, min(a.frames, nframes))
    idx = sorted({min(nframes - 1, int((k + 0.5) * nframes / N)) for k in range(N)})
    sel = "+".join("eq(n\\,%d)" % i for i in idx)
    cols = 4 if len(idx) > 4 else len(idx)
    rows = math.ceil(len(idx) / cols)
    tw = 480 if cols >= 4 else 640
    ff(["-i", a.film, "-an", "-vf", "select='%s',%sscale=%d:-2,tile=%dx%d:padding=4:margin=4:color=0x111111" % (sel, drawtext_filter(font), tw, cols, rows),
        "-frames:v", "1", "-q:v", "3", "-fps_mode", "passthrough", os.path.join(a.out, "sheet.jpg")])

    # ---- one decode pass: scene scores + freezedetect;  one tiny-luma pass: frame diffs + correlation
    r = ff(["-i", a.film, "-an", "-vf", "freezedetect=n=-50dB:d=%s,select='gte(scene\\,0)',metadata=print:file=-" % a.freeze_min, "-f", "null", "-"])
    scene, cur = {}, None
    for ln in r.stdout.splitlines():
        m = re.match(r"frame:(\d+)", ln)
        if m:
            cur = int(m.group(1))
        m = re.search(r"scene_score=([\d.]+)", ln)
        if m and cur is not None:
            scene[cur] = float(m.group(1))
    frozen, cur = [], None
    for kind, val in re.findall(r"freeze_(start|end): ([\d.]+)", r.stderr):
        v = float(val)
        if kind == "start":
            cur = v
        elif cur is not None:
            frozen.append((cur, v)); cur = None
    if cur is not None:
        frozen.append((cur, dur))
    frozen = [(s, e) for s, e in frozen if e - s >= a.freeze_min]
    M, C = analyse(a.film)
    if len(M) < 2:
        die("could not decode frames for analysis")
    nf = len(M)

    # ---- cuts
    detected = detect(M, C, scene, a.scene, a.scene_low)
    ev_path = find_events(a.film, a.events)
    ev_cuts, ev_kinds = events_to_cuts(ev_path, fps, nf) if ev_path else ([], {})
    if ev_path and not ev_cuts:
        print("note: %s has no cut/show/hide events; using detection" % ev_path, file=sys.stderr)
    cut_list = ev_cuts if ev_cuts else detected          # [(frame, source)]
    source = "events" if ev_cuts else "detected"
    cuts = [f / fps for f, _ in cut_list]
    unexplained = []
    if ev_cuts:
        evf = [f for f, _ in ev_cuts]
        unexplained = [(f, s) for f, s in detected if min(abs(f - e) for e in evf) > MERGE]

    with open(os.path.join(a.out, "cuts.txt"), "w") as f:
        f.write("# cuts from %s%s (time s, frame, timecode, source)\n" % (source, " " + ev_path if ev_cuts else " scene>=%s | scene>=%s+structure | pixel spike" % (a.scene, a.scene_low)))
        for (fr, s) in cut_list:
            f.write("%.3f\tframe %d\t%s\t%s\n" % (fr / fps, fr, tc(fr / fps), s))
        if not cut_list:
            f.write("none\n")
        if unexplained:
            f.write("# detected but not in events:\n")
            for fr, s in unexplained:
                f.write("%.3f\tframe %d\t%s\t%s\n" % (fr / fps, fr, tc(fr / fps), s))
    with open(os.path.join(a.out, "still.txt"), "w") as f:
        f.write("# stretches >= %.2fs with no picture change (start end duration)\n" % a.freeze_min)
        for s, e in frozen:
            f.write("%.3f\t%.3f\t%.2f\n" % (s, e, e - s))
        if not frozen:
            f.write("none\n")

    # ---- mid.jpg (2 frames before each cut) and strips.jpg (cut-1 | cut | cut+1)
    shown = [f for f, _ in cut_list]
    if len(shown) > a.shown:
        shown = [shown[int(i * len(shown) / a.shown)] for i in range(a.shown)]
    mid, strips = os.path.join(a.out, "mid.jpg"), os.path.join(a.out, "strips.jpg")
    for p in (mid, strips):
        if os.path.exists(p):
            os.remove(p)
    if shown:
        before = sorted({max(0, f - 2) for f in shown})
        sel = "+".join("eq(n\\,%d)" % i for i in before)
        c = min(len(before), 6)
        ff(["-i", a.film, "-an", "-vf", "select='%s',%sscale=320:-2,tile=%dx%d:padding=4:margin=4:color=0x111111" % (sel, drawtext_filter(font), c, math.ceil(len(before) / c)),
            "-frames:v", "1", "-q:v", "3", "-fps_mode", "passthrough", mid])
    srows = [f for f in shown if 1 <= f <= nf - 2]
    if srows:
        sel = "+".join("eq(n\\,%d)" % i for f in srows for i in (f - 1, f, f + 1))
        ff(["-i", a.film, "-an", "-vf", "select='%s',%sscale=256:-2,tile=3x%d:padding=3:margin=4:color=0x111111" % (sel, drawtext_filter(font), len(srows)),
            "-frames:v", "1", "-q:v", "3", "-fps_mode", "passthrough", strips])

    # ---- static-ish stretches and the end hold
    runs = runs_below(M, a.hold_eps)
    longest = max(runs, key=lambda r_: r_[1] - r_[0], default=None)
    hold = 0.0
    if runs and runs[-1][1] == nf - 1:
        hold = (nf - runs[-1][0]) / fps
    last_cut = max(cuts) if cuts else 0.0
    final_dur = dur - last_cut

    # ---- loudness
    loud = None
    if au:
        r = ff(["-i", a.film, "-vn", "-af", "ebur128=peak=true", "-f", "null", "-"], check=False)
        s = r.stderr[r.stderr.rfind("Summary:"):]
        g = lambda p: (re.search(p, s) or [None, None])[1]
        loud = {"integrated_lufs": g(r"I:\s+(-?[\d.]+) LUFS"), "lra_lu": g(r"LRA:\s+([\d.]+) LU"), "true_peak_dbfs": g(r"Peak:\s+(-?[\d.]+) dBFS")}

    # ---- report
    print("file        %s" % a.film)
    print("duration    %.2fs   fps %.3f   size %dx%d   codec %s   frames %d" % (dur, fps, W, H, vs.get("codec_name"), nframes))
    lst = ", ".join("%.2f" % t for t in cuts[:20]) + (" ..." if len(cuts) > 20 else "")
    if ev_cuts:
        print("cuts        %d from events (%s; %s): %s" % (len(cuts), os.path.basename(ev_path), ", ".join("%s %d" % kv for kv in sorted(ev_kinds.items())), lst))
        print("detected    %d by analysis; %s" % (len(detected), ("not in events: " + ", ".join("%.2f" % (f / fps) for f, _ in unexplained)) if unexplained else "all explained by events"))
    else:
        print("cuts        %d detected (scene>=%.2f | scene>=%.2f+structure | pixel spike)%s" % (len(cuts), a.scene, a.scene_low, ": " + lst if cuts else ""))
    print("shot length mean %.2fs over %d shots" % (dur / (len(cuts) + 1), len(cuts) + 1))
    if cuts:
        bounds = [0.0] + cuts + [dur]
        ls = [bounds[i + 1] - bounds[i] for i in range(len(bounds) - 1)]
        print("            min %.2fs  max %.2fs" % (min(ls), max(ls)))
    print("still       %s" % ("; ".join("%.2f-%.2fs (%.2fs)" % (s, e, e - s) for s, e in frozen) if frozen else "no frozen stretch >= %.1fs" % a.freeze_min))
    if longest:
        s0, e0 = (longest[0] - 1) / fps, (longest[1] + 1) / fps
        print("static-ish  longest %.2f-%.2fs (%.2fs, frame diff < %.2f/255; slow drift counts)" % (s0, e0, e0 - s0, a.hold_eps))
    else:
        print("static-ish  none (every frame changes by >= %.2f/255)" % a.hold_eps)
    print("final shot  %.2f-%.2fs (%.2fs)   end hold ~ %.2f s (picture unchanged for the last %d frames)" % (last_cut, dur, final_dur, hold, round(hold * fps)))
    if a.hold_warn > 0 and hold > a.hold_warn:
        print("WARNING     end hold %.2fs > %.2fs: the last element sits resolved from %.2fs to the end. Trim: ffmpeg -i %s -t %.2f -c copy trimmed.mp4  (or keep the exit moving)" % (hold, a.hold_warn, dur - hold, a.film, min(dur, dur - hold + 0.8)))
    if au:
        print("audio       %s %s Hz ch %s   integrated %s LUFS   LRA %s LU   true peak %s dBFS" % (au.get("codec_name"), au.get("sample_rate"), au.get("channels"), loud["integrated_lufs"], loud["lra_lu"], loud["true_peak_dbfs"]))
    else:
        print("audio       none")
    print("files       %s/sheet.jpg  cuts.txt  still.txt  %s" % (a.out, ("mid.jpg  " if shown else "(no mid.jpg: no cuts)") + ("strips.jpg" if srows else "")))

    # ---- audio audit, gates, motion note
    print()
    ares = audio_audit(a.film, dur, cuts) if au else None
    print_audio(ares, loud, au, cuts)
    G = compute_gates(a, dur, fps, nf, M, C, vs, au, cuts, hold, final_dur)
    print_gates(G, M, fps)
    mm = sum(M[1:]) / max(1, len(M) - 1)
    with open(os.path.join(a.out, "gates.json"), "w") as f:
        json.dump({"film": a.film, "duration": dur, "fps": fps, "gates": [{"id": g, "name": n, "status": st, "detail": w} for g, n, st, w in G],
                   "motion_mean_luma_diff": round(mm, 2), "human_band": {"median": HUMAN_MOTION[0], "q1": HUMAN_MOTION[1], "q3": HUMAN_MOTION[2]},
                   "audio": ({k: v for k, v in ares.items() if k not in ("env_n",)} if ares else None), "loudness": loud}, f, indent=1)
    if a.strict and any(st == "FAIL" for _, _, st, _ in G):
        sys.exit(3)


if __name__ == "__main__":
    main()