#!/usr/bin/env python3
"""One thumbnail per PLANNED SEGMENT — catch empty cuts before rendering.

check_cuts.py samples ACROSS cuts to find defects (black frames, frozen cuts).
This samples WITHIN each segment to judge content: is there actually a subject
in this shot, or does the in-point land on empty track, sky, or tarmac?

That is the failure this catches. When a generator reuses a clip it picks
in-points across the clip's full duration, and some of them land on nothing.
On action footage an empty frame reads as dead space, and the only way to see
it is to look at every segment before spending a render.

Frames are the MIDPOINT of each segment, so a segment that merely starts on a
transition still shows what it mostly is.

Labels need ImageMagick; without it the sheet is unlabeled and the index
mapping is printed instead (Homebrew ffmpeg has no drawtext).

Usage:
  audit_plan.py plan/cut_plan.json --out work/plan_audit.png
"""
import argparse, json, math, os, shutil, subprocess, sys, tempfile
from concurrent.futures import ThreadPoolExecutor
from pathlib import Path

COLS = 5
THUMB_W = 360
LABEL_H = 34


def default_workers():
    return max(2, min(8, (os.cpu_count() or 4) - 2))


def grab(src, t, dst):
    r = subprocess.run(
        ["ffmpeg", "-y", "-v", "error", "-ss", f"{t:.3f}", "-i", str(src),
         "-frames:v", "1", "-vf", f"scale={THUMB_W}:-2", str(dst)],
        capture_output=True, text=True)
    return dst if r.returncode == 0 and dst.exists() else None


def label(magick, img, text):
    """Caption strip under a thumbnail. Best-effort — never fails the sheet.

    -splice follows -gravity, so it must be `south` or the strip lands in the
    middle of the frame instead of below it.
    """
    r = subprocess.run(
        [magick, str(img), "-background", "#111318", "-gravity", "south",
         "-splice", f"0x{LABEL_H}", "-fill", "white", "-pointsize", "18",
         "-annotate", "+0+7", text, str(img)],
        capture_output=True, text=True)
    return r.returncode == 0


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("plan")
    ap.add_argument("--out", default="work/plan_audit.png")
    ap.add_argument("--at", choices=("mid", "in"), default="mid",
                    help="Sample the segment midpoint (default) or its "
                         "in-point. Use 'in' to check the exact cut frame.")
    ap.add_argument("--workers", type=int, default=default_workers())
    args = ap.parse_args()

    plan = json.loads(Path(args.plan).read_text())
    segs = plan.get("segments", [])
    if not segs:
        sys.exit(f"{args.plan} has no segments to audit.")

    out = Path(args.out)
    out.parent.mkdir(parents=True, exist_ok=True)
    magick = shutil.which("magick")
    work = Path(tempfile.mkdtemp(prefix="audit_", dir=str(out.parent)))

    def one(item):
        i, s = item
        t = s["in"] + (s["duration"] / 2 if args.at == "mid" else 0.0)
        dst = work / f"s{i:03d}.png"
        got = grab(s["clip"], t, dst)
        if got and magick:
            name = Path(s["clip"]).stem[:22]
            label(magick, dst, f"{i + 1}. {name} @{t:.1f}s")
        return i, s, got, t

    try:
        with ThreadPoolExecutor(max_workers=args.workers) as pool:
            results = list(pool.map(one, enumerate(segs)))

        missing = [(i, s) for i, s, got, _ in results if not got]
        frames = sorted(p for p in work.glob("s*.png"))
        if not frames:
            sys.exit("No frames could be read — are the mezzanine files built?")
        rows = math.ceil(len(frames) / COLS)
        tmp = out.with_name(out.stem + ".tmp" + out.suffix)
        r = subprocess.run(
            ["ffmpeg", "-y", "-v", "error", "-framerate", "1",
             "-pattern_type", "glob", "-i", str(work / "s*.png"),
             "-vf", f"tile={COLS}x{rows}:padding=4:color=#111318",
             "-frames:v", "1", str(tmp)], capture_output=True, text=True)
        if r.returncode != 0:
            tmp.unlink(missing_ok=True)
            sys.exit(f"tile failed:\n{r.stderr[-600:]}")
        tmp.rename(out)
    finally:
        shutil.rmtree(work, ignore_errors=True)

    print(f"Segment audit -> {out}  ({len(frames)}/{len(segs)} segments, "
          f"{COLS} per row, sampled at {args.at})")
    if not magick:
        print("\nUnlabeled (ImageMagick not installed) — index mapping:")
        for i, s, got, t in results:
            if got:
                print(f"  {i + 1:3d}  {Path(s['clip']).name} @{t:.2f}s"
                      f"  {s.get('note', '')}")
    if missing:
        print(f"\n{len(missing)} segment(s) produced no frame:", file=sys.stderr)
        for i, s in missing:
            print(f"  {i + 1}: {s['clip']} @{s['in']:.2f}s", file=sys.stderr)

    print("\nLOOK AT EVERY TILE. An in-point that landed on empty track, sky, "
          "or tarmac reads as dead space in the reel — fix it in the plan "
          "before rendering, not after.")


if __name__ == "__main__":
    main()