#!/usr/bin/env python3
"""check_master.py — deterministic delivery gate for a finished rap MV.

Deliberately NOT whisper-based. Re-transcribing an 8-second rap over a music bed
to compare word onsets is exactly the dense-audio case that mis-times (see the
caption-bunching and caption-desync findings), so it would fail the film for the
transcriber's shortcomings rather than the film's. Everything checked here is
measurable with ffprobe:

  1. the master has a video AND an audio stream (a silent MV is the reference
     skill's `generate_audio: false` failure, arriving by a different door);
  2. master duration == the hook window's duration, within one frame — the same
     bar `music-video` asserts internally, re-checked on the delivered file;
  3. the master's audio duration matches its video duration within one frame, so
     the track cannot run out under the picture or vice versa;
  4. frame 0 is not blank — delegated to the brand-explainer frame-0 gate when it
     is reachable, because the first frame is the feed thumbnail and a black
     opening frame is a scroll-past.

The one thing ffprobe cannot see is whether the mouths are moving to the RIGHT
words, so check 5 delegates that to `check_sync.py` when the caller supplies the
cut's sync manifest (`--sync-manifest`). Sync is measurable — synced to this bar
scores 0.96-0.99, rendered against another bar 0.13-0.35 — and a master that was
never measured must say so rather than passing quietly.

Usage:
  check_master.py --master <master.mp4> --hook-json <hook.json>
                  [--fps 24] [--frame0] [--json]
                  [--expect-seconds <n>]
                  [--sync-manifest <cut.json>] [--song <track>] [--check-sync <path>]
Exit 0 = pass, 1 = fail, 2 = bad input.
"""
from __future__ import annotations

import argparse
import re
import json
import os
import subprocess
import sys
import os as _os, sys as _sys
_sys.path.insert(0, _os.path.dirname(_os.path.abspath(__file__)))
import raplib  # noqa: E402
import tempfile


def die(msg: str) -> None:
    print(f"check_master: {msg}", file=sys.stderr)
    raise SystemExit(2)


def ffprobe_json(path: str, ffprobe: str) -> dict:
    proc = subprocess.run(
        [ffprobe, "-v", "error", "-show_format", "-show_streams", "-of", "json", path],
        stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    if proc.returncode != 0:
        die(f"ffprobe failed on {path}: {proc.stderr.decode('utf-8', 'replace')[:200]}")
    return json.loads(proc.stdout.decode("utf-8", "replace"))


SYNC_CHECK = "cut-synced-to-song"


def run_sync_check(args: argparse.Namespace, config_song: str, record) -> None:
    """Check 5: every synced segment's own audio correlates with the song at its
    own timecode. Measured by check_sync.py, which is invoked as a subprocess so
    there is exactly one implementation of the correlation.

    The SKIP/FAIL boundary is the whole design here. A check that could not run is a
    SKIP — "PASS" for something that never executed is worse than no check at all.
    But a manifest the CALLER NAMED and that is missing or malformed is a FAIL: that
    is a broken invocation, not an unavailable check, and letting a mis-wired runner
    report PASS is how a film ships with its sync never measured. Hence the
    existence/parse checks come FIRST, before the tool/song/no-segments SKIPs.
    """
    if not args.sync_manifest:
        record(SYNC_CHECK, True,
               "NOT RUN — no --sync-manifest given; sync was not proved", skipped=True)
        return
    if not os.path.isfile(args.sync_manifest):
        record(SYNC_CHECK, False,
               f"--sync-manifest names {args.sync_manifest}, which does not exist — the caller "
               "asked for this check, so a broken path is a failure, not a skip")
        return
    try:
        segments = json.load(open(args.sync_manifest, encoding="utf-8"))
    except Exception as exc:
        record(SYNC_CHECK, False, f"--sync-manifest {args.sync_manifest} is not valid JSON: {exc}")
        return
    if not isinstance(segments, list) or not all(
            isinstance(s, dict) and {"clip", "start", "seconds"} <= set(s) for s in segments):
        record(SYNC_CHECK, False,
               f"--sync-manifest {args.sync_manifest} is not a list of "
               "{start, seconds, clip[, synced]} objects")
        return

    tool = args.check_sync or os.path.join(os.path.dirname(os.path.abspath(__file__)), "check_sync.py")
    if not os.path.isfile(tool):
        record(SYNC_CHECK, True, f"NOT RUN — check_sync.py not found at {tool}", skipped=True)
        return

    # The manifest's `start` values are in the timebase of the file the cut was
    # planned against — config["song"], the HOOK WAV, not the project's full
    # soundtrack. Correlating against the wrong file collapses every score and looks
    # exactly like a genuine sync failure. --song is the explicit escape hatch for a
    # manifest authored in another timebase (e.g. window starts against the full
    # track); it is never inferred.
    if getattr(args, "no_sync", ""):
        # AUDIO_MODE=vocal-swap: the master's audio at every synced window IS the take's
        # own voice (vocal_swap.py), so correlating it against the record measures the
        # swap, not the sync — sync is exact by construction there (2026-08-31).
        record(SYNC_CHECK, True, f"NOT RUN — {args.no_sync}", skipped=True)
        return
    song = args.song or config_song
    if not song or not os.path.isfile(song):
        record(SYNC_CHECK, True, "NOT RUN — no song to correlate against"
               + (f" (looked at {song})" if song else "; pass --song or --config"), skipped=True)
        return

    synced = [s for s in segments if s.get("synced")]
    if not synced:
        record(SYNC_CHECK, True,
               "NOT RUN — no synced segment in the manifest; nothing to prove", skipped=True)
        return

    with tempfile.TemporaryDirectory() as tmp:
        report_path = os.path.join(tmp, "sync.json")
        proc = subprocess.run(
            [sys.executable, tool, "--song", song, "--manifest", args.sync_manifest,
             "--json-out", report_path],
            stdout=subprocess.PIPE, stderr=subprocess.PIPE)
        rows = []
        try:
            rows = json.load(open(report_path, encoding="utf-8"))
        except Exception:
            rows = []
    out = proc.stdout.decode("utf-8", "replace")
    err = proc.stderr.decode("utf-8", "replace")

    if proc.returncode == 0:
        corrs = [r["corr"] for r in rows if isinstance(r, dict) and "corr" in r]
        offsets = [abs(r["offset_ms"]) for r in rows if isinstance(r, dict) and "offset_ms" in r]
        detail = f"{len(synced)} synced segment(s)"
        if corrs:
            detail += f", min corr {min(corrs):.2f}"
        if offsets:
            detail += f", max offset {max(offsets)}ms"
        record(SYNC_CHECK, True, detail)
        return
    if proc.returncode == 5:
        # Carry the failing segments through verbatim — which window and what it
        # measured is the whole actionable content.
        bad = [line.strip() for line in out.splitlines() if line.strip().startswith("FAIL")]
        record(SYNC_CHECK, False,
               "check_sync refused: " + ("; ".join(bad) if bad else out.strip()[-300:]))
        return
    record(SYNC_CHECK, False,
           f"check_sync exited {proc.returncode}: " + ((err or out).strip()[-300:] or "no output"))


def true_peak_dbtp(master: str) -> float | None:
    """ffmpeg ebur128 true peak of the master's audio, or None when unmeasurable."""
    try:
        r = subprocess.run(["ffmpeg", "-nostats", "-i", master, "-vn", "-af", "ebur128=peak=true",
                            "-f", "null", "-"], capture_output=True, text=True, timeout=300)
    except (OSError, subprocess.TimeoutExpired):
        return None
    m = re.findall(r"Peak:\s*(-?[0-9.]+) dBFS", r.stderr or "")
    return float(m[-1]) if m else None


def contact_sheet(master: str, out: str, width: int, cols: int, fps: float) -> str:
    """The whole film as one frame a second, in a grid. Returns the path, or "".

    THE DEFECT CLASS THIS IS FOR is invisible to every other instrument in this lane.
    Sync, lyric coverage and correlation all measure AUDIO; none of them can see a
    cricket bat hanging unsupported in mid-air, a stump materialising out of a hand, or
    extra figures walking in from the frame edges. An operator found all three on
    delivered cuts that had passed every automated gate.

    Sampling density is the whole point. The library strips used to take three frames at
    15/50/85%, and on the clip where a bat floated for two seconds those three frames
    read as a perfectly ordinary "picks up the bat" — the moment it drifts unsupported
    falls between the samples. One frame a second shows the move.

    One ffmpeg pass, so a two-minute film costs about two seconds.
    """
    os.makedirs(os.path.dirname(os.path.abspath(out)) or ".", exist_ok=True)
    duration = 0.0
    try:
        duration = float(subprocess.run(
            ["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of",
             "csv=p=0", master], capture_output=True, text=True).stdout.strip())
    except ValueError:
        pass
    rows = max(1, -(-int(duration or 1) // max(1, cols)))
    proc = subprocess.run(
        [os.environ.get("FFMPEG_BIN", "ffmpeg"), "-v", "error", "-y", "-i", master,
         "-vf", f"fps=1,scale={width}:-1,tile={cols}x{rows}:margin=2:padding=2",
         "-frames:v", "1", "-q:v", "4", out],
        capture_output=True, text=True)
    return out if proc.returncode == 0 and os.path.isfile(out) else ""


def main() -> None:
    ap = argparse.ArgumentParser()
    ap.add_argument("--master", required=True)
    ap.add_argument("--hook-json", required=True)
    ap.add_argument("--config", default="",
                    help="the mv config build_mv_config.py emitted. Its songEnd is the PLAN OF "
                         "RECORD: it may sit a frame or two under the raw hook length when the "
                         "cut cadence required a tail trim. Preferred over hook.json when given.")
    ap.add_argument("--fps", type=float, default=24.0)
    ap.add_argument("--expect-seconds", type=float, default=None,
                    help="assert the master is THIS long instead of the hook window's length. For "
                         "a WRAPPED film (ident + title + body + end card), whose length is the "
                         "bookend plan's, not the hook's — plan-covers-hook then SKIPs, because a "
                         "wrapped film has no hook window to cover.")
    ap.add_argument("--sync-manifest", default="",
                    help="the cut's check_sync manifest: a JSON list of "
                         "{start, seconds, clip[, synced]}. Named-but-missing FAILS.")
    ap.add_argument("--check-sync", default="",
                    help="path to check_sync.py (default: the sibling of this script)")
    ap.add_argument("--song", default="",
                    help="the track the manifest's start values are timed against. Defaults to "
                         "the config's \"song\" (the HOOK WAV) — never the full soundtrack.")
    ap.add_argument("--no-sync", default="", metavar="REASON",
                    help="skip the sync correlation and record REASON (AUDIO_MODE=vocal-swap: "
                         "the master carries the takes' own voices, so sync is by construction)")
    ap.add_argument("--vocal-brief", default="", help="build/vocal-brief.json — singing over a faceless section is refused")
    ap.add_argument("--cutaways", default="", help="build/cutaways-<sid>.json — the covers that are intended")
    ap.add_argument("--frame0", action="store_true",
                    help="also run the brand-explainer frame-0 blank gate")
    ap.add_argument("--contact-sheet", default="",
                    help="write a whole-film contact sheet here (one frame a second). "
                         "The picture defects nothing else in this lane can see live in it.")
    ap.add_argument("--sheet-width", type=int, default=160)
    ap.add_argument("--sheet-cols", type=int, default=8)
    ap.add_argument("--ffprobe", default=os.environ.get("FFPROBE_BIN", "ffprobe"))
    ap.add_argument("--json", action="store_true")
    args = ap.parse_args()

    for p in (args.master, args.hook_json):
        if not os.path.isfile(p):
            die(f"not found: {p}")

    hook = json.load(open(args.hook_json, encoding="utf-8"))
    hook_len = float(hook["durationSec"])
    config: dict = {}
    if args.config and os.path.isfile(args.config):
        config = json.load(open(args.config, encoding="utf-8"))
    planned = float(config["songEnd"]) if "songEnd" in config else hook_len
    tol = 1.0 / args.fps

    probe = ffprobe_json(args.master, args.ffprobe)
    streams = probe.get("streams", [])
    video = [s for s in streams if s.get("codec_type") == "video"]
    audio = [s for s in streams if s.get("codec_type") == "audio"]

    failures: list[str] = []
    checks: list[dict] = []

    def record(name: str, ok: bool, detail: str, skipped: bool = False) -> None:
        # A check that did not run is reported as SKIP, never PASS. A green tick
        # for something that never executed is worse than no check at all.
        checks.append({"check": name, "ok": ok, "detail": detail, "skipped": skipped})
        if not ok:
            failures.append(f"{name}: {detail}")

    record("has-video", bool(video), f"{len(video)} video stream(s)")
    record("has-audio", bool(audio),
           f"{len(audio)} audio stream(s)" + ("" if audio else " — a SILENT master"))

    # SHAPE. Every other check here measures TIME — duration, frames, alignment — and a
    # film can pass all of them while being the wrong shape entirely. A 9:16 project cut
    # its portrait clips into a 1920x1080 master because build_mv_config defaults to
    # landscape and nothing passed it the project's resolution; `bookends` then cropped
    # that landscape frame back to portrait, and the delivered film was an extreme
    # close-up of a nose and a mouth. Duration matched. Frame count matched. Streams
    # were present. Nothing looked.
    if video:
        got_w, got_h = int(video[0].get("width") or 0), int(video[0].get("height") or 0)
        if config.get("width") and config.get("height"):
            want_w, want_h = int(config["width"]), int(config["height"])
            record("shape-matches-config", (got_w, got_h) == (want_w, want_h),
                   f"master {got_w}x{got_h} vs config {want_w}x{want_h}"
                   + ("" if (got_w, got_h) == (want_w, want_h)
                      else " — the film is the WRONG SHAPE; the clips have been cropped "
                           "to fit and there is no way to tell from any duration check"))
        else:
            record("shape-matches-config", True,
                   f"NOT RUN — no --config with width/height; master is {got_w}x{got_h}, "
                   f"check the orientation by eye", skipped=True)

    total = float(probe.get("format", {}).get("duration", 0) or 0)
    if args.expect_seconds is not None:
        # A wrapped film is asserted against the bookend plan's total, not the hook.
        # The hook check is REPLACED, and plan-covers-hook is reported NOT RUN rather
        # than dropped: a check that stopped applying still has to say so out loud.
        record("duration-matches-expected", abs(total - args.expect_seconds) <= tol,
               f"master {total:.3f}s vs expected {args.expect_seconds:.3f}s "
               f"(tolerance {tol:.3f}s = 1 frame)")
        record("plan-covers-hook", True,
               f"NOT RUN — --expect-seconds {args.expect_seconds:.3f}s given; a wrapped film has "
               "no hook window to cover", skipped=True)
    else:
        record("duration-matches-plan", abs(total - planned) <= tol,
               f"master {total:.3f}s vs planned {planned:.3f}s (tolerance {tol:.3f}s = 1 frame)")
        # the plan itself must not have quietly walked away from the hook
        record("plan-covers-hook", hook_len - planned <= 6 * tol,
               f"planned {planned:.3f}s vs hook {hook_len:.3f}s "
               f"(tail trim {(hook_len - planned) * args.fps:.0f} frame(s), limit 6)")

    if video and audio:
        vd = float(video[0].get("duration") or total)
        ad = float(audio[0].get("duration") or total)
        record("audio-video-aligned", abs(vd - ad) <= tol,
               f"video {vd:.3f}s vs audio {ad:.3f}s (tolerance {tol:.3f}s)")

    if args.frame0:
        gate = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(
            os.path.abspath(__file__)))), "brand-explainer", "scripts", "check_frame0.py")
        if os.path.isfile(gate):
            # --from-video: the gate takes a FRAME by default and opened the .mp4 with
            # PIL (UnidentifiedImageError, New Era dry run 2026-08-29).
            proc = subprocess.run([sys.executable, gate, "--from-video", args.master],
                                  stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
            record("frame-0-not-blank", proc.returncode == 0,
                   proc.stdout.decode("utf-8", "replace").strip()[-300:] or "ok")
        else:
            record("frame-0-not-blank", True,
                   f"NOT RUN — gate not found at {gate}; check frame 0 by eye", skipped=True)

    run_sync_check(args, str(config.get("song", "")), record)

    sheet = ""
    if args.contact_sheet:
        sheet = contact_sheet(args.master, args.contact_sheet, args.sheet_width,
                             args.sheet_cols, args.fps)
        # ADVISORY, deliberately. Nothing automated can look at this; it is evidence for
        # a human, and a machine "PASS" beside it would invite exactly the skim it
        # exists to prevent. It is recorded as a skipped check so the summary says
        # plainly that a human still has to look.
        record("picture-defects-by-eye", True,
               f"contact sheet at {sheet} — SOMEONE MUST LOOK AT IT" if sheet
               else "contact sheet could not be built", skipped=True)

    # SINGING OVER NO FACE (film3 item 10, cut time). For every film second: the record
    # sings (the brief's lines) and the picture is a section with no performer — a gap,
    # an outro, a shot-led window — and no cutaway record intends it. A recorded cover
    # 4b. NOT CLIPPING. Measured on the ENCODED master (aac overshoots a clipped mix): a
    # true peak above −0.1 dBTP means the mix already clips before the polish stage can
    # normalise it (Baby Nimbooda v1, 2026-09-04: +0.1 dBTP, 2 clipped samples, PASSed).
    # This is the "is it broken" bar, not the −1 dBTP delivery bar — that one belongs to
    # final_qc after polish (delivery-bar-at-the-wrong-stage).
    tp = true_peak_dbtp(args.master)
    if tp is None:
        record("master-not-clipping", True, "NOT RUN — true peak unmeasurable", skipped=True)
    else:
        record("master-not-clipping", tp <= -0.1,
               f"true peak {tp:+.1f} dBTP" + ("" if tp <= -0.1 else " — the mix clips; lower it before polish"))

    # is a decision; an unrecorded one is a face missing.
    if args.vocal_brief and _os.path.isfile(args.vocal_brief) and config.get("vocalMap"):
        blines = (json.load(open(args.vocal_brief, encoding="utf-8")).get("lines") or [])
        faced = [(float(w["start"]), float(w["end"])) for w in config["vocalMap"] if w.get("performerClip")]
        intended = []
        if args.cutaways and _os.path.isfile(args.cutaways):
            intended = [(float(c.get("startSec") or 0), float(c.get("endSec") or 0))
                        for c in (json.load(open(args.cutaways, encoding="utf-8")).get("cutaways") or [])]
        # Bounded to the film: `planned` is the config's songEnd, the plan of record for
        # this master. A proof copy (or a hook cut) is shorter than the song; what the
        # song sings after the master ends is not a faceless section, it is not in the film.
        hits = raplib.singing_over_nothing(blines, faced, intended, film_end=planned)
        record("no-singing-over-a-faceless-section", not hits,
               "every sung second has a face, or a recorded cutaway" if not hits else
               "; ".join(f"\u201c{h['text'][:30]}\u201d {h['from']:.1f}-{h['to']:.1f}s ({h['seconds']:.1f}s) sings over a "
                         f"section with no face and no cutaway record" for h in hits[:4]))
    elif args.vocal_brief:
        record("no-singing-over-a-faceless-section", True, "NOT RUN — no vocalMap in --config", skipped=True)

    result = {"master": os.path.abspath(args.master), "ok": not failures, "checks": checks,
              **({"contactSheet": sheet} if sheet else {})}
    if args.json:
        print(json.dumps(result, indent=2))
    for c in checks:
        mark = "SKIP" if c["skipped"] else ("PASS" if c["ok"] else "FAIL")
        print(f"  {mark}  {c['check']}: {c['detail']}", file=sys.stderr)
    skipped = [c["check"] for c in checks if c["skipped"]]
    if failures:
        print(f"check_master: FAILED ({len(failures)})", file=sys.stderr)
        raise SystemExit(1)
    if skipped:
        print(f"check_master: PASS ({len(skipped)} check(s) NOT RUN: {', '.join(skipped)})",
              file=sys.stderr)
    else:
        print("check_master: PASS", file=sys.stderr)


if __name__ == "__main__":
    main()
