#!/usr/bin/env python3
"""check_sync.py — prove each clip is synced to THE BAR IT SITS ON, before you cut.

Why this exists. On routes that return the SUPPLIED track as the clip's audio —
Seedance 2.x, measured repeatedly — lip sync stops being a
judgement call and becomes a measurement: correlate the clip's own audio envelope
against the song at that segment's timecode.

    genuinely synced to this bar : 0.96 - 0.99 at 0 ms offset
    rendered against another bar : 0.13 - 0.35

That gap is the whole point. A picture-only review — a contact strip, or an agent
reading frames — can only tell you a mouth is OPEN. It cannot tell you the mouth is
open to the RIGHT WORDS. On the WICC anthem a multi-agent pass picked six
"performance" clips out of an 85-clip library for the six lip-synced windows; every
one measured 0.13-0.26, and installing them would have put a man mouthing the wrong
lyrics into every hook of a film that had already been rebuilt once to remove exactly
that defect. Gate the cut here, before it is assembled — not after watching it back.

Two more things this catches for free:

  * OFFSET. A window scoring 0.72 at +575 ms had its picture running over half a
    second ahead of the vocal, invisible in two prior visual reviews. Pass
    --voice-dir to check the voice REFERENCES too: if those measure ~1.00 at 0 ms
    the fault is in the render, not your inputs. Absorb it by moving the CUT POINT
    between that segment and the previous one by the offset — the clip then starts
    where its audio belongs and the previous shot simply holds longer, which beats
    a frozen frame or a visible slip.
  * PADDING. A clip shorter than its segment has to be filled. On B-roll that is a
    retime and invisible; on a lip-synced segment it can only be a held frame,
    because retiming slides the mouth off the vocal — so a 2-3 s freeze on a chorus
    is a visible break, not a rounding error.

Manifest (JSON list, one entry per segment):

    [{"start": 45.0, "seconds": 10.0, "clip": "/abs/w05.mp4", "synced": true}, ...]

Usage:
  check_sync.py --song <track.mp3> --manifest <cut.json> [--voice-dir <dir>]
Exit 0 = every segment passes, 5 = at least one fails.
"""
from __future__ import annotations

import argparse
import array
import json
import os
import subprocess
import sys
import tempfile
import wave

SR = 8000
FRAME_HZ = 40                 # 25 ms analysis frames
# Below this the clip's audio is not the song at this segment — its mouth is moving
# to something else. Calibrated against real renders; genuine ones sit at 0.96-0.99.
SYNC_MIN = 0.60
if os.environ.get("RAP_BAR") == "keep":
    SYNC_MIN = 0.50   # the operator's relaxed bar (2026-08-23 "relax all"); cover/board judge the rest
MAX_HOLD = 0.60               # seconds of held frame tolerable on a synced segment
MAX_RETIME = 1.35             # slow-down beyond this stops being invisible on B-roll
OFFSET_WINDOW = 80            # +/- 2 s search, in analysis frames


def envelope(path: str, start: float = 0.0, dur: float | None = None) -> list[float]:
    """Speech-band RMS envelope — robust to codec, level and bitrate differences."""
    with tempfile.TemporaryDirectory() as tmp:
        wav = os.path.join(tmp, "e.wav")
        cmd = ["ffmpeg", "-v", "error", "-y"]
        if start:
            cmd += ["-ss", f"{start:.3f}"]
        cmd += ["-i", path]
        if dur:
            cmd += ["-t", f"{dur:.3f}"]
        cmd += ["-vn", "-ac", "1", "-ar", str(SR),
                "-af", "highpass=f=300,lowpass=f=3400", wav]
        if subprocess.run(cmd, capture_output=True).returncode != 0:
            return []
        try:
            with wave.open(wav) as f:
                raw = f.readframes(f.getnframes())
        except Exception:
            return []
    a = array.array("h")
    a.frombytes(raw)
    step = SR // FRAME_HZ
    return [(sum(x * x for x in a[i:i + step]) / step) ** 0.5
            for i in range(0, len(a) - step, step)]


def corr(a: list[float], b: list[float]) -> float:
    n = min(len(a), len(b))
    if n < 20:
        return 0.0
    a, b = a[:n], b[:n]
    ma, mb = sum(a) / n, sum(b) / n
    va = sum((x - ma) ** 2 for x in a) ** 0.5
    vb = sum((x - mb) ** 2 for x in b) ** 0.5
    if not va or not vb:
        return 0.0
    return sum((x - ma) * (y - mb) for x, y in zip(a, b)) / (va * vb)


def best_offset(song_env: list[float], clip_env: list[float]) -> tuple[float, int]:
    """Best correlation and its offset in ms. A real match survives the search.

    SIGN: POSITIVE = the clip's mouth is EARLY (its event sits `off` before the song's;
    sync_shift delays the video to fix it). NEGATIVE = the mouth is LATE. A night was
    spent diagnosing "late" takes that were rushing (2026-08-23) — read it here, not
    from the word that happens to be next to the number in a log line."""
    best, at = 0.0, 0
    for off in range(-OFFSET_WINDOW, OFFSET_WINDOW + 1):
        s = song_env[max(0, off):] if off >= 0 else song_env
        c = clip_env if off >= 0 else clip_env[-off:]
        v = corr(s, c)
        if v > best:
            best, at = v, off
    return best, at * (1000 // FRAME_HZ)


def duration(path: str) -> float:
    r = subprocess.run(["ffprobe", "-v", "error", "-show_entries", "format=duration",
                        "-of", "csv=p=0", path], capture_output=True)
    try:
        return float(r.stdout.decode().strip())
    except ValueError:
        return 0.0


def _retimable(seg: dict) -> dict | None:
    """rate_fit's verdict for one manifest row: the take's words against its own voice
    slice. None when the row carries no slice, the store or rate_fit is unavailable, or
    the line is not straight (a real wander is still a refusal)."""
    voice = seg.get("voiceRef") or ""
    if not voice or not os.path.isfile(voice):
        return None
    try:
        import rate_fit
        from transcribe_clips import whisper_words
    except ImportError:
        return None
    try:
        cache = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(voice))),
                             "check-sync-tx")
        lang = os.environ.get("SONG_LANGUAGE") or "en"
        # PRIMED WITH THE WINDOW'S OWN LINES, both sides. Unprimed, the probe paired 6
        # of 14 words on a New Era window and fitted a rate 0.2 out (2026-08-30).
        prompt = (seg.get("lines") or "") or None
        want = whisper_words(voice, "small", cache, language=lang, prompt=prompt)["words"]
        got = whisper_words(seg["clip"], "small", cache, language=lang, prompt=prompt)["words"]
    except Exception:                     # noqa: BLE001 — a probe never kills the gate
        return None
    return rate_fit.retimable(want, got)


def main() -> None:
    ap = argparse.ArgumentParser()
    ap.add_argument("--song", required=True)
    ap.add_argument("--manifest", required=True)
    ap.add_argument("--voice-dir", help="voice-reference MP4s, named <index>.mp4 — "
                                        "checked too, to localise any offset")
    ap.add_argument("--json-out")
    ap.add_argument("--no-sync", default="", metavar="REASON",
                    help="report REASON and pass without measuring. AUDIO_MODE=vocal-swap: the\n"
                         "film carries each take's OWN voice, so correlating a take against the\n"
                         "RECORD measures the swap, not the sync, and prints alarming false\n"
                         "failures (Baby Ram & Sita w05, 2026-09-01: 'NOT SYNCED' on a window\n"
                         "whose audio matched its own take at corr 0.97).")
    ap.add_argument("--offset-advisory", action="store_true",
                    help="report a steady offset instead of failing on it. THE STAGE "
                         "THAT FIXES AN OFFSET RUNS AFTER THIS ONE: `slide` takes up "
                         "anything within a held frame for free, and `sync-gate` judges "
                         "what is left at the 80ms delivery bar. Failing here on 100ms "
                         "refuses a film that the next stage would have fixed, and the "
                         "operator never gets to see it at all. Use at `select`, where "
                         "the only fatal question is whether the take is on this bar; "
                         "leave it off for delivery checks, where 80ms is the point.")
    args = ap.parse_args()

    segments = json.load(open(args.manifest, encoding="utf-8"))
    report, failures = [], []

    for i, seg in enumerate(segments):
        clip = seg["clip"]
        if not os.path.isfile(clip):
            failures.append(i)
            report.append({"segment": i, "issues": [f"clip missing: {clip}"]})
            continue
        if args.no_sync:
            # --no-sync skips the MEASUREMENT, not the manifest: a parked or voided take
            # must still be caught here, not three stages later in the assembler
            report.append({"segment": i, "clip": os.path.basename(clip), "issues": [],
                           "notMeasured": args.no_sync})
            continue
        clip_len = duration(clip)
        gap = seg["seconds"] - clip_len
        row = {"segment": i, "clip": os.path.basename(clip),
               "gap": round(gap, 2)}
        issues = []

        if seg.get("synced"):
            span = min(seg["seconds"], clip_len)
            # READ THE CLIP FROM ITS HEAD. A raw take carries headSec of lead-in that the
            # assembler skips; reading it from 0 scored every record-mode window ~0.5 s
            # late and refused a cut whose takes were on the bar (film #3, 2026-09-06).
            c, off = best_offset(envelope(args.song, seg["start"], span),
                                 envelope(clip, float(seg.get("headSec") or 0.0), span))
            row["corr"], row["offset_ms"] = round(c, 3), off
            if c < SYNC_MIN:
                # A TIME-STRETCHED TAKE CANNOT CORRELATE, and `slide` runs next. The
                # same reasoning as --offset-advisory: at `select` the fatal question is
                # whether the take is performing THIS bar, and a take singing every word
                # on a straight line at 1.1-1.35x is — it is simply slow, which rate_fit
                # retimes for free one stage later. Refusing it here refuses a film the
                # next stage would have fixed (New Era: 6 of 15 windows, 2026-08-30).
                fitted = _retimable(seg)
                if fitted:
                    row.setdefault("notes", []).append(
                        f"corr {c:.2f} — sung at {fitted['rate']:.2f}x the track "
                        f"(a straight line: residual {fitted['residualMs']}ms over "
                        f"{fitted['pairs']} words); rate_fit in `slide` retimes it")
                    row["rate"] = round(fitted["rate"], 3)
                else:
                    issues.append(
                        f"NOT SYNCED to this bar (corr {c:.2f} < {SYNC_MIN}) — its mouth "
                        f"is moving to different words")
            elif abs(off) > 80:
                note = (f"synced but {off:+d} ms out — move the cut point before it by "
                        f"{off}ms rather than freezing a frame")
                # Advisory at `select`, fatal at delivery. Same measurement, different
                # question: here it is "can this take be used", and `slide` has not run
                # yet. Fatal at both ends deadlocks the film — select refuses 100ms, and
                # the stage that would have taken up 100ms for nothing never runs.
                (row.setdefault("notes", []) if args.offset_advisory else issues).append(note)
            if gap > MAX_HOLD:
                issues.append(f"needs a {gap:.1f}s held frame on a performance segment")
        elif gap > 0.08:
            ratio = seg["seconds"] / clip_len if clip_len else 99
            row["retime"] = round(ratio, 2)
            if ratio > MAX_RETIME:
                issues.append(f"needs a {ratio:.2f}x slow-down to fill the segment")

        row["issues"] = issues
        report.append(row)
        if issues:
            failures.append(i)

    if args.no_sync:
        print(f"check_sync: NOT MEASURED — {args.no_sync}"
              + (f"; {len(failures)} clip(s) MISSING" if failures else f"; {len(report)} clip(s) present"),
              file=sys.stderr)
        for r in report:
            if r["issues"]:
                print(f"  FAIL seg{r['segment']:02d} <- " + "; ".join(r["issues"]))
        if getattr(args, "json_out", ""):
            json.dump(report, open(args.json_out, "w", encoding="utf-8"), indent=1)
        raise SystemExit(1 if failures else 0)

    for r in report:
        # An advisory note is not a pass and not a failure — it is work for the next
        # stage, and printing it as a bare "ok" is how a 575ms window reaches delivery
        # with nobody having read anything.
        tag = "FAIL" if r["issues"] else ("note" if r.get("notes") else "ok  ")
        extra = (f" corr={r['corr']:.2f}@{r['offset_ms']:+d}ms" if "corr" in r
                 else (f" retime={r['retime']}x" if "retime" in r else ""))
        trailer = r["issues"] or r.get("notes") or []
        print(f"  {tag} seg{r['segment']:02d} {r.get('clip','?'):<22}"
              f" gap={r.get('gap', 0):+.2f}s{extra}"
              + ("  <- " + "; ".join(trailer) if trailer else ""))

    if args.voice_dir and os.path.isdir(args.voice_dir):
        print("\n  voice references (if these are clean, an offset is the render's fault):")
        for i, seg in enumerate(segments):
            v = os.path.join(args.voice_dir, f"{i:02d}.mp4")
            if not (seg.get("synced") and os.path.isfile(v)):
                continue
            c, off = best_offset(envelope(args.song, seg["start"], seg["seconds"]),
                                 envelope(v, float(seg.get("headSec") or 0.0), seg["seconds"]))
            print(f"    seg{i:02d} corr={c:.2f} @ {off:+d} ms"
                  + ("" if abs(off) <= 50 else "   <- the REFERENCE is misaligned"))

    if args.json_out:
        json.dump(report, open(args.json_out, "w"), indent=2)

    if failures:
        print(f"\ncheck_sync: {len(failures)} segment(s) FAILED: {failures}",
              file=sys.stderr)
        raise SystemExit(5)
    print("\ncheck_sync: every segment passes", file=sys.stderr)


if __name__ == "__main__":
    main()
