#!/usr/bin/env python3
"""sync_profile.py — the DELIVERY sync gate: where in the film do the lips drift?

WHY THIS EXISTS, in one sentence: `check_sync.py` reports ONE offset per window, and
a film can pass it on every window and still look broken all the way through.

That is not hypothetical. A 2-minute film was shipped with 15 of 16 windows "passing"
and the operator watched it and said the sync was bad. Both halves of the miss were
in the instrument, not the footage:

  1. THE BAR WAS THE WRONG BAR. `sync_verdict`-style gates use ~400ms, which is the
     "is this draw worth KEEPING" threshold — is the performer on the right bar of the
     song at all, or should this take be thrown away. The DELIVERY threshold is 80ms.
     Five windows sat between 100 and 350ms, sailed through a 400ms gate, and read as
     plainly late on screen. A keep-it gate must never be used as a ship-it gate.

  2. ONE NUMBER PER 8-SECOND WINDOW CANNOT SEE "some parts are okay, some are not".
     A window whose global best offset is 0ms can still wander in and out across its
     eight seconds. The operator's description of the defect — some bits fine, some
     not — is literally unrepresentable in the window gate's output.

So this measures a SHORT span slid across the film, and reports drift in FILM TIME,
which is the only coordinate the operator can act on.

It also reports two things the window gate structurally cannot:

  MOUTHING  the song has no vocal here but a performer is on screen. There is nothing
            to sync TO, so correlation is meaningless and the defect is visual: a man
            mouthing words the song does not sing. Fix with a cutaway, not a re-render.

  WANDERS   the sub-window offsets DISAGREE. This is the difference between a clip
            that is merely in the wrong place (slide it — free, seconds) and one whose
            performance drifts inside the take (only a re-render fixes it). Telling
            these apart is what stops an hour of a single-slot queue being spent on a
            problem that an ffmpeg shift would have fixed, and vice versa.

MEASUREMENT CAVEAT, stated because ignoring it invents defects: on a 2-second span the
correlator can lock onto the wrong syllable and return a confident ±1400ms. Those are
discarded (SPURIOUS_MS) rather than reported. A summary built from the raw mean is
polluted by them — always summarise with the robust median, never the mean.

Usage:
  sync_profile.py --song <hook.wav> --selection <selection-<style>.json>
                  --vocal-map <vocal-map.json> --stage <dir-of-wNN.mp4> [--json <out>]

Exit 5 when any performance window fails the delivery bar — same convention as
check_sync.py, so a runner can gate on it.
"""
from __future__ import annotations

import argparse
import json
import os
import statistics
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from check_sync import best_offset, envelope  # noqa: E402  (the proven implementation)

SPAN, STEP = 2.0, 0.5
SHIP_MS = 80             # DELIVERY bar (check_sync's own). NOT the ~400ms keep bar.
MARGINAL_MS = 200
CORR_FLOOR = 0.45
SPURIOUS_MS = 600        # a short span can lock onto the wrong syllable
MAX_SPREAD_MS = 150      # above this the offsets disagree: the take wanders
MIN_SPANS = 4            # fewer samples than this and the median is not a measurement
SHORT_SPANS_MIN = 2      # a SHORT window (one-line windows are 4-7 s; a 4 s window is 3
                         # spans) is still a measurement when its few spans AGREE. Calling
                         # 3 agreeing spans WANDERS while sync_shift refused to slide them
                         # left a gate nothing could end (New Era dry run, 2026-08-29).


def clip_resolver(sel: dict, stage: str):
    """performerClip -> a real path on disk.

    In a selection it is a clip ID resolved through clips[]; in a hand-built stage it
    is the filename stem. Support both, and FAIL LOUDLY when neither resolves — feeding
    an ID to ffmpeg as if it were a path is how `--verify-lip-sync` once scored every
    cut 0.00 and accused all 25 of them of the wrong words.
    """
    by_id = {c["id"]: c["path"] for c in sel.get("clips", []) if c.get("path")}

    def resolve(perf: str):
        p = by_id.get(perf) or os.path.join(stage, f"{perf}.mp4")
        return p if os.path.isfile(p) else None
    return resolve


def vocal_fraction(silent, a: float, b: float) -> float:
    dead = sum(max(0.0, min(b, e) - max(a, s)) for s, e in silent)
    return 1.0 - dead / (b - a)


def profile_window(song: str, clip: str, start: float, end: float, silent):
    """Every measurable span in this window: (film_time, corr, offset_ms)."""
    out = []
    t = start
    while t + SPAN <= end + 1e-9:
        if vocal_fraction(silent, t, t + SPAN) < 0.4:
            out.append((t, None, None))          # no vocal: mouthing risk
        else:
            c, off = best_offset(envelope(song, t, SPAN), envelope(clip, t - start, SPAN))
            out.append((t, c, off))
        t += STEP
    return out


def robust(spans):
    """(median offset, n, spread, wild) — spurious lock-ons discarded, CLUSTERS kept.

    THE SPREAD IS AN INTERQUARTILE RANGE, NOT max-min. This function is called `robust`
    and its offset always was — a median ignores outliers — but the spread beside it was
    the least robust statistic available, so ONE disagreeing span vetoed a clip.

    Measured on a real window: seven spans read
        -75, +250, +250, +250, +250, +250, +250
    Six of them identical, a take steady at +250ms that a 250ms slide fixes perfectly.
    max-min called it 325ms and classified it WANDERS — "sliding cannot fix it" — so
    slide left it alone, it shipped at its full offset, and the operator saw it. Three
    re-renders were then spent chasing a defect the measurement had invented; two of
    those draws came back genuinely worse (1250ms spread, and one with no vocal at all).

    An IQR reads that same window as 0ms of spread, which is what it is. A clip that
    truly drifts has its middle half spread out too, so the WANDERS verdict still fires
    where it should — what it no longer does is fire on a single outlier span, which is
    exactly the case a median was chosen to survive.

    WILD SPANS ARE COUNTED, NOT SILENTLY EATEN (2026-08-24, both defects of one film):
    discarding every span beyond ±SPURIOUS_MS made a clip sitting at a steady -825ms
    read UNMEASURABLE (every span "spurious", w06 shipped 825ms late), and a take whose
    back half drifted to +1475/-650 read "+0ms ok" (the drifted spans discarded, the
    clean head voted alone, w08 reached the operator's ear). A LONE wild span is still
    dropped — the wrong-syllable lock-on this filter was built for — but when EVERY
    measured span is wild and they agree, that IS the offset; and the wild COUNT is
    returned so `classify` can name a take that drifts out beyond the search sanity
    window. Note the IQR alone can never see that: quartiles ignore tails by design,
    and the wild cluster IS the tail.
    """
    meas = [o for _, c, o in spans if c is not None and c >= CORR_FLOOR]
    sane = [o for o in meas if abs(o) <= SPURIOUS_MS]
    wild = [o for o in meas if abs(o) > SPURIOUS_MS]
    if sane:
        # the stable centre judges the offset; wild spans beside it are DRIFT EVIDENCE
        # (a lone one is the old lock-on case and stays discarded)
        return (int(round(statistics.median(sane))), len(sane), iqr_spread(sane),
                0 if len(wild) <= 1 else len(wild))
    if len(wild) >= 2:
        # every measured span is far off: not noise but a real, big offset — its own
        # spread decides whether it is steady (slidable) or wandering
        return int(round(statistics.median(wild))), len(wild), iqr_spread(wild), 0
    return None, 0, None, 0


def iqr_spread(vals: list) -> int:
    """Spread of the MIDDLE HALF, in ms. Immune to one span locking on somewhere odd."""
    if len(vals) < 4:
        return max(vals) - min(vals)          # too few to quartile; be strict
    ordered = sorted(vals)
    q1 = statistics.median(ordered[: len(ordered) // 2])
    q3 = statistics.median(ordered[(len(ordered) + 1) // 2:])
    return int(round(q3 - q1))


# A take whose spans lock OUT beyond the ±SPURIOUS_MS sanity window mid-take, while a
# clean part votes a steady offset. Calibrated on the real film (2026-08-24): the
# wandering take showed exactly 3 wild spans; an operator-verified good clip ALSO
# showed 3 (a repeated lyric line lets 2s spans lock a phrase early/late — its ±1275ms
# locks mirror the repeat interval). No statistic separates those two cleanly, and the
# costs are asymmetric: a false alarm is one listen + one `--accept` (durable,
# md5-keyed), a miss is a shipped defect the operator finds on screen. So this FIRES
# ON BOTH and the accept file is the ear's verdict. Two wild spans stay quiet: one
# confusing moment smears across overlapping spans (SPAN 2.0 / STEP 0.5).
WILD_MIN = 3


def classify(off, n, spread, wild=0):
    if off is None:
        return "UNMEASURABLE", "re-render (no readable vocal correlation)"
    if wild >= WILD_MIN:
        return "WANDERS", (f"{wild} of {n + wild} spans lock beyond ±{SPURIOUS_MS}ms "
                           f"mid-take — drift, or a repeated-phrase lock-on. LISTEN at "
                           f"the times below; --accept if the take is fine")
    if n < SHORT_SPANS_MIN or spread > MAX_SPREAD_MS:
        return "WANDERS", "re-render (drifts inside the take; sliding cannot fix it)"
    if abs(off) <= SHIP_MS:
        return "ok", ""
    if abs(off) <= MARGINAL_MS:
        return "MARGINAL", "slide it (sync_shift.py)"
    return "OFF-BAR", "slide it (sync_shift.py), or re-render if the hold would show"


def clip_md5(path: str) -> str:
    import hashlib
    h = hashlib.md5()
    with open(path, "rb") as fh:
        for block in iter(lambda: fh.read(1 << 20), b""):
            h.update(block)
    return h.hexdigest()


def load_accepts(path: str | None) -> list:
    if not path or not os.path.isfile(path):
        return []
    try:
        return json.load(open(path, encoding="utf-8")).get("accepts", [])
    except (OSError, ValueError):
        return []


def find_accept(accepts: list, clip_id: str, path: str):
    """The accept that covers THIS clip's CURRENT bytes, or None.

    md5-keyed on purpose: an accept is a human's verdict about one specific file
    (2026-08-24: a WANDERS verdict on a spliced window was measured sub-span by
    sub-span and accepted deliberately). Change the clip and the verdict is void."""
    for a in accepts:
        if a.get("clip") == clip_id and a.get("md5") == clip_md5(path):
            return a
    return None


def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("--song", required=True)
    ap.add_argument("--selection", required=True)
    ap.add_argument("--vocal-map", required=True)
    ap.add_argument("--stage", required=True)
    ap.add_argument("--json")
    ap.add_argument("--ship-ms", type=int, default=SHIP_MS)
    ap.add_argument("--accepts", help="sync-accepts.json — a failing window with a matching "
                    "{clip, md5, reason} entry is reported ACCEPTED and does not fail the "
                    "gate. md5-keyed: the accept dies with the file it judged.")
    ap.add_argument("--accept", metavar="CLIP",
                    help="write-mode: record a deliberate accept for CLIP (with --reason) "
                         "into --accepts (default <build>/sync-accepts.json) and exit. The "
                         "2026-08-24 825ms ship happened because the old gate's accept was "
                         "an implicit, silent re-run; this one is explicit and auditable.")
    ap.add_argument("--reason", help="required with --accept: why the human judged it fine")
    a = ap.parse_args()

    sel = json.load(open(a.selection, encoding="utf-8"))
    silent = [(float(g["start"]), float(g["end"]))
              for g in json.load(open(a.vocal_map, encoding="utf-8")).get("silentStretches", [])]
    song_end = float(sel.get("songEnd", 1e9))

    resolve = clip_resolver(sel, a.stage)

    if a.accept:
        # WRITE-MODE: record one deliberate accept and exit.
        if not a.reason:
            print("--accept needs --reason: the reason IS the audit trail", file=sys.stderr)
            return 2
        path = resolve(a.accept)
        if path is None:
            print(f"--accept {a.accept}: does not resolve to a file on disk", file=sys.stderr)
            return 2
        accepts_path = a.accepts or os.path.join(
            os.path.dirname(os.path.abspath(a.selection)), "sync-accepts.json")
        accepts = load_accepts(accepts_path)
        accepts = [x for x in accepts if x.get("clip") != a.accept]   # re-accept replaces
        import datetime
        accepts.append({"clip": a.accept, "md5": clip_md5(path), "reason": a.reason,
                        "date": datetime.date.today().isoformat()})
        json.dump({"_comment": "Deliberate per-window accepts of sync-gate verdicts, "
                               "md5-keyed to the exact clip judged. sync_profile --accepts "
                               "downgrades a matching failure to ACCEPTED; a changed clip "
                               "voids its accept.",
                   "accepts": accepts}, open(accepts_path, "w", encoding="utf-8"), indent=1)
        print(f"accepted {a.accept} ({a.reason}) -> {accepts_path}")
        return 0

    accepts = load_accepts(a.accepts)
    report, failures, unresolved = [], 0, []
    print(f"{'window':<8} {'film time':>12} {'offset':>9} {'spread':>8}  verdict")
    for s in sel["vocalMap"]:
        perf, start = s.get("performerClip"), float(s["start"])
        if not perf:
            continue                              # B-roll window: no mouth on screen
        if s.get("lipSyncExempt"):
            print(f"{perf:<8} {start:8.1f}{'':>8} {'-':>9} {'-':>8}  EXEMPT"
                  "  -> intentional visual montage")
            report.append({"clip": perf, "startSec": start, "offsetMs": None,
                           "spans": 0, "spreadMs": None, "verdict": "EXEMPT",
                           "action": "intentional visual montage"})
            continue
        clip = resolve(perf)
        if clip is None:
            unresolved.append(perf)
            continue
        # AT LEAST the whole window, AT LEAST 8s. The old start+8 cap left the last
        # 1.5s of every longer window unmeasured — w08's worst second lived there —
        # while a bare window-end cap starves a SHORT window of spans (a 3s window is
        # 3 spans, under MIN_SPANS); the clip's slack past a short window correlates
        # at the same offset, so measuring into it is free statistical power.
        end = min(max(start + 8.0, float(s["end"])), song_end)
        spans = profile_window(a.song, clip, start, end, silent)
        off, n, spread, wild = robust(spans)
        verdict, action = classify(off, n, spread, wild)
        mouthing = [t for t, c, o in spans if c is None]
        accepted = None
        if verdict != "ok":
            accepted = find_accept(accepts, perf, clip)
            if accepted is None:
                failures += 1
        m, sec = int(start // 60), start - int(start // 60) * 60
        shown = f"ACCEPTED (was {verdict})" if accepted else verdict
        shown_action = accepted["reason"] if accepted else action
        print(f"{perf:<8} {m}:{sec:05.2f}{'':>4} "
              f"{(f'{off:+d}ms' if off is not None else '   -'):>9} "
              f"{(f'{spread}ms' if spread is not None else '  -'):>8}  {shown}"
              + (f"  -> {shown_action}" if shown_action else ""))
        if mouthing:
            print(f"{'':<8} {'':>12} {'':>9} {'':>8}  MOUTHING at "
                  f"{', '.join(f'{t:.1f}s' for t in mouthing)} — no vocal; use a cutaway")
        wild_at = [t for t, c, o in spans
                   if c is not None and c >= CORR_FLOOR and abs(o) > SPURIOUS_MS]
        if wild:
            print(f"{'':<8} {'':>12} {'':>9} {'':>8}  wild spans at "
                  f"{', '.join(f'{t:.1f}s' for t in wild_at)} (film time) — listen there")
        report.append({"clip": perf, "startSec": start, "offsetMs": off, "spans": n,
                       "spreadMs": spread, "wildSpans": wild, "wildAt": wild_at,
                       "verdict": verdict, "action": action, "mouthingAt": mouthing,
                       **({"accepted": accepted["reason"]} if accepted else {})})

    print(f"\n{len(report)} performance windows; {failures} fail the {a.ship_ms}ms delivery bar")
    if a.json:
        json.dump({"shipBarMs": a.ship_ms, "windows": report,
                   "unresolved": unresolved}, open(a.json, "w"), indent=1)
    if unresolved:
        # Silence here would read as "every window passed". It is the opposite.
        print(f"REFUSING: {len(unresolved)} performer clip(s) did not resolve to a file "
              f"on disk: {', '.join(unresolved)}", file=sys.stderr)
        return 6
    return 5 if failures else 0


if __name__ == "__main__":
    raise SystemExit(main())
