#!/usr/bin/env python3
"""sync_shift.py — slide a performance clip onto its bar. No re-render, no spend.

TRY THIS BEFORE YOU RE-RENDER ANYTHING. A clip whose mouth runs a steady 300ms ahead
of the vocal is not a bad take; it is a correctly-performed take in the wrong place.
Sliding costs nothing and takes seconds. A re-render costs ~100 minutes of a
single-slot shared queue and is roughly a coin flip on moderation — and if the drift
was a placement error, the new draw is just as likely to land somewhere else wrong.

THE SIGN, established by EXPERIMENT rather than by reading the correlator (getting
this backwards doubles every error rather than fixing it): head-trimming a clip by
200ms — which makes the mouth reach each word EARLIER — moved the reported offset from
+0ms to +200ms. Therefore POSITIVE = mouth EARLY, and the fix is to DELAY the video.
Re-run that experiment on any clip if you ever doubt it; it takes one ffmpeg call.

  positive offset (mouth early) -> hold the FIRST frame for `off`, then the clip
  negative offset (mouth late)  -> start the clip `off` in, hold the LAST frame to fill

The held frame lands ON a cut, where the eye already expects a change. That is why a
300ms hold reads as far less wrong than 300ms of lip lag running the whole shot.

TWO GUARDS, both of which exist because their absence produced a worse film:

  STABILITY. Only slide a clip whose sub-window offsets AGREE. A clip that drifts
  inside the take has a median that is an average of contradictions; sliding by it
  moves some seconds onto the bar and others further off. Observed: a window measured
  +350ms from a single unstable sample, was shifted -350ms, and landed at -350ms — the
  shift moved it twice as far as intended because the number was never real. Such a
  clip is reported for re-render, NOT silently shifted.

  HOLD CEILING. Beyond MAX_HOLD_MS the held frame becomes the more visible defect, so
  the clip is reported for re-render rather than quietly clamped and called fixed.

Audio is shifted WITH the video. The master mutes it, so it changes nothing on screen —
but the sync measurement reads the clip's audio as the proxy for its mouth, so shifting
only the video would leave the re-measurement showing no improvement and the tool would
be marking its own homework.

Usage:
  sync_shift.py --song <hook.wav> --selection <selection-<style>.json>
                --vocal-map <vocal-map.json> --stage <src-dir> --out <dst-dir>
                [--json <report>]

Every performance clip is written to --out: slid where the offset was steady, copied
unchanged where it was not, so the output directory is always a complete stage.
"""
from __future__ import annotations

import argparse
import json
import os as _os, sys as _sys
_sys.path.insert(0, _os.path.dirname(_os.path.abspath(__file__)))   # a script loaded by path (tests) still finds its siblings
import raplib  # noqa: E402
import os
import shutil
import subprocess
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from sync_profile import (MAX_SPREAD_MS, MIN_SPANS, SHORT_SPANS_MIN, WILD_MIN,  # noqa: E402
                          clip_resolver, profile_window, robust)

MAX_HOLD_MS = 400 if os.environ.get("RAP_BAR") == "keep" else 350   # beyond this the hold is worse than the drift
MIN_SHIFT_MS = 60        # below this it is inside the noise; leave it alone
# A steady offset (IQR spread at or under this) is slid even past MAX_HOLD_MS — see the
# branch below. RAP_STEADY_SLIDE=0 restores the old refuse-and-re-render behaviour.
STEADY_SLIDE = os.environ.get("RAP_STEADY_SLIDE", "1") != "0"
STEADY_SPREAD_MS = 75


def run(cmd):
    r = subprocess.run(cmd, capture_output=True, text=True)
    if r.returncode:
        raise SystemExit(f"ffmpeg failed:\n{r.stderr[-1500:]}")


def keep(src: str, dst: str) -> None:
    """Copy src to dst unless they are already the same file.

    --out-selection rewrites the selection onto the shifted clips, so a SECOND run
    resolves src to the very file it is about to write. shutil.copyfile raises
    SameFileError on that, which killed the re-run path the sync-gate itself tells
    the operator to take ("re-run --from slide"). Re-running must be a no-op, not a
    crash.
    """
    if os.path.abspath(src) != os.path.abspath(dst):
        shutil.copyfile(src, dst)


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


def slack_plan(off_ms: int, head_sec: float, tail_sec: float) -> tuple[float, int]:
    """(in_sec, hold_ms): where to start reading the SOURCE, and how much of the
    correction still has to come from a held frame.

    The source may carry real frames around the window — `head_sec` before it (the
    assembly skips them) and `tail_sec` after. A mouth-EARLY take (+off) is fixed by
    showing frames from earlier in the source: in = head - off, real while head covers
    it. A mouth-LATE take (-off) by starting later: in = head + |off|; the window's END
    is then real frames while the tail covers it, a held last frame for the rest. Only
    the held remainder is measured against MAX_HOLD_MS. With no slack this is exactly the old
    behaviour (in = 0, hold = |off|)."""
    sec = abs(off_ms) / 1000.0
    if off_ms > 0:
        real = min(sec, max(0.0, head_sec))
        return round(head_sec - real, 4), int(round((sec - real) * 1000))
    if off_ms < 0:
        # The frames to advance INTO always exist (they are the clip's own); what the
        # tail slack buys is the END — without it the last |off| of the window is a
        # held last frame, with it the clip simply keeps playing.
        real = min(sec, max(0.0, tail_sec))
        return round(head_sec + sec, 4), int(round((sec - real) * 1000))
    return round(max(0.0, head_sec), 4), 0


def shift(src: str, dst: str, off_ms: int, window_sec: float,
          head_sec: float = 0.0, tail_sec: float = 0.0) -> None:
    # Same-file guard: on a re-run src resolves to the shifted clip, which is dst. ffmpeg
    # reading and writing one path truncates it to garbage — a silent corruption, unlike
    # the SameFileError the copy path at least raised. Stage through a temp and move.
    if os.path.abspath(src) == os.path.abspath(dst):
        tmp = dst + ".shift.tmp.mp4"
        shift(src, tmp, off_ms, window_sec, head_sec, tail_sec)
        os.replace(tmp, dst)
        return
    in_sec, hold_ms = slack_plan(off_ms, head_sec, tail_sec)
    hold = hold_ms / 1000.0
    vf = [f"trim=start={in_sec},setpts=PTS-STARTPTS"] if in_sec > 0 else []
    af = [f"atrim=start={in_sec},asetpts=PTS-STARTPTS"] if in_sec > 0 else []
    if hold_ms and off_ms > 0:        # mouth early, slack exhausted -> hold the first frame
        vf.append(f"tpad=start_duration={hold}:start_mode=clone")
        af.append(f"adelay={hold_ms}|{hold_ms}")
    elif off_ms < 0:                  # mouth late -> any shortfall holds the last frame
        vf.append(f"tpad=stop_duration={max(hold, 0.5)}:stop_mode=clone")
        af.append("apad")
    run(["ffmpeg", "-v", "error", "-y", "-i", src,
         *(["-vf", ",".join(vf)] if vf else []), *(["-af", ",".join(af)] if af else []),
         "-t", f"{window_sec}", "-c:v", "libx264", "-preset", "medium", "-crf", "18",
         "-pix_fmt", "yuv420p", "-c:a", "aac", "-b:a", "192k", dst])




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("--out", required=True)
    ap.add_argument("--json")
    ap.add_argument("--out-selection",
                    help="write a selection pointing at the shifted clips. Without this "
                         "the assembler keeps using the ORIGINAL paths and the slide "
                         "never reaches the film.")
    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))
    os.makedirs(a.out, exist_ok=True)

    resolve = clip_resolver(sel, a.stage)
    rows, rerender, rewritten = [], [], {}
    for s in sel["vocalMap"]:
        perf, start = s.get("performerClip"), float(s["start"])
        if not perf:
            continue
        if s.get("lipSyncExempt"):
            # a no-voice window has nothing to slide to; calling it "needs re-render"
            # sent two silent intros to the re-render list (2026-08-24)
            src0 = resolve(perf)
            if src0 is not None:
                keep(src0, os.path.join(a.out, f"{perf}.mp4"))
                rewritten[perf] = os.path.join(a.out, f"{perf}.mp4")
            print(f"{perf:<6} {start:7.1f}s      -   no vocal — lip-sync exempt", file=sys.stdout)
            continue
        src = resolve(perf)
        if src is None:
            raise SystemExit(f"performer clip {perf!r} does not resolve to a file on disk")
        dst = os.path.join(a.out, f"{perf}.mp4")
        rewritten[perf] = dst
        # AT LEAST the whole window (the old start+8 cap hid drift in the tail of longer
        # windows) and AT LEAST 8s (a short window's clip usually carries slack past its
        # end, and correlating there measures the same offset — capping a 3s window to
        # 3 spans put it under MIN_SPANS and left it unshifted at its full offset).
        end = min(max(start + 8.0, float(s["end"])), song_end)
        head, tail = float(s.get("headSec") or 0.0), float(s.get("tailSec") or 0.0)
        window_sec = float(s["end"]) - start
        # MEASURE THE WINDOW, NOT THE FILE. With head slack the clip's frame 0 is
        # head seconds BEFORE the window; measured raw it reads +head early and "needs
        # re-render". Align first (a frame-exact cut from head), then measure that.
        measured = src
        if head > 0:
            measured = os.path.join(a.out, f"{perf}.aligned.mp4")
            shift(src, measured, 0, duration(src) - head, head, tail)
        off, n, spread, wild = robust(profile_window(a.song, measured, start, end, silent))
        if measured != src:
            os.remove(measured)

        def settle(note_):
            # No slide: still cut the window out of its slack (head skipped, tail kept
            # for the assembler to ignore) so the film never sees the raw head.
            if head > 0 or tail > 0:
                shift(src, dst, 0, window_sec + tail, head, tail)
            else:
                keep(src, dst)
            return note_
        # How much of a correction the held frame would have to carry once the real
        # slack is used up — that, not the raw offset, is what the ceiling is about.
        hold_needed = slack_plan(off, head, tail)[1] if off is not None else None
        if wild >= WILD_MIN:
            # SLIDE FIXES ONLY A STEADY OFFSET. A wild cluster means part of the take
            # runs >600ms off while the clean part votes the median — sliding by that
            # median fixes the head and ships the tail (w08, 2026-08-24). Warn here;
            # the delivery gate (sync_profile) holds the verdict and the accept flow.
            print(f"{perf}: {wild} span(s) lock beyond the sanity window mid-take — "
                  f"slide addresses only the steady part; the sync-gate will judge this "
                  f"window (listen, then --accept there if the take is fine)",
                  file=sys.stderr)
        if off is None:
            note = settle("UNMEASURABLE — needs re-render")
            rerender.append((perf, start, None))
        elif n < SHORT_SPANS_MIN and off is not None and abs(off) <= MAX_HOLD_MS and not wild:
            # a single measurable span cannot prove stability; the driver already
            # verified the take on its OWN sung lines. A small steady offset defers to
            # that verdict. (Two or three AGREEING spans are a measurement and slide
            # below — one-line windows are 4-7 s, and the old MIN_SPANS floor left
            # every one of them unshifted while the sync gate failed them: New Era
            # dry run, 2026-08-29.)
            note = settle(f"only {n} span(s) measurable at {off:+d}ms — short window, "
                          f"the driver's own-lines verdict stands; left unshifted")
        elif n < SHORT_SPANS_MIN or spread > MAX_SPREAD_MS:
            note = settle(f"WANDERS (spread {spread}ms over {n} spans) — needs re-render")
            rerender.append((perf, start, off))
        elif abs(off) < MIN_SHIFT_MS:
            note = settle("already on the bar")
        elif hold_needed > MAX_HOLD_MS and not (STEADY_SLIDE and spread <= STEADY_SPREAD_MS):
            note = settle(f"needs re-render (a {hold_needed}ms hold would show"
                          + (f"; slack {head:g}s/{tail:g}s covers the rest" if head or tail else "") + ")")
            rerender.append((perf, start, off))
        elif hold_needed > MAX_HOLD_MS:
            # STEADY OFFSET PAST THE CEILING — SLIDE IT ANYWAY (2026-08-29). Four takes
            # sat at a rock-steady +300..+650ms (spread <= 50ms over 14-15 spans); the
            # ceiling refused them and they SHIPPED early — the operator heard it
            # ("out of sync from the silk shirt"). Delayed by exactly the median, all
            # four re-measured at 0ms with zero wander. A steady offset is a placement
            # error; the held frame is the lesser defect and `cover` can hide it
            # (COVER_SPANS over the hold). Only a WANDERING take truly needs a re-render.
            shift(src, dst, off, (window_sec + tail) if (head or tail) else duration(src), head, tail)
            new, _, _, _ = robust(profile_window(a.song, dst, start, end, silent))
            note = (f"shifted {-off:+d}ms -> {new:+d}ms" if new is not None else "shifted") + (
                f" (STEADY past the {MAX_HOLD_MS}ms ceiling — {hold_needed}ms held; hide it with a "
                f"COVER_SPANS cutaway over the window's first {hold_needed/1000:.2f}s)")
            rows.append({"clip": perf, "beforeMs": off, "afterMs": new, "heldMs": hold_needed})
            print(f"{perf:<6} {start:7.1f}s  {off:+5d}ms  {note}")
            continue
        else:
            # THE CLIP'S OWN LENGTH, NOT THE ANALYSIS WINDOW. `end` is deliberately
            # capped at start + 8s above — that is how much song we CORRELATE against,
            # and it has nothing to do with how long the output should be. Passing
            # `end - start` truncated every slid clip to eight seconds.
            #
            # It was invisible for as long as windows WERE 8s, and then it was invisible
            # again because only a clip that actually slides goes through here: the
            # others are copied whole, so four windows came out 14s and the one slid
            # window came out 8s. Downstream that surfaced as
            #   assembly drift: built 64.000s vs planned 70.000s
            # which names the cutter and blames frame-exactness, and is really a source
            # clip that is six seconds shorter than the config says it is.
            #
            # Same disease as the Runway 10s cap and the 12s library ceiling: a fixed
            # number describing a thing that varies.
            shift(src, dst, off, (window_sec + tail) if (head or tail) else duration(src), head, tail)
            new, _, _, _ = robust(profile_window(a.song, dst, start, end, silent))
            real_ms = abs(off) - hold_needed
            note = (f"shifted {-off:+d}ms -> {new:+d}ms" if new is not None else "shifted") + (
                f" ({real_ms}ms from real frames, {hold_needed}ms held)" if (head or tail) else "")
            rows.append({"clip": perf, "beforeMs": off, "afterMs": new})
            print(f"{perf:<6} {start:7.1f}s  {off:+5d}ms  {note}")
            continue
        print(f"{perf:<6} {start:7.1f}s  "
              + (f"{off:+5d}ms" if off is not None else "    -  ") + f"  {note}")

    if rerender:
        print("\nStill need a 12s padded re-render — sliding cannot fix these:")
        for perf, start, off in rerender:
            print(f"  {perf} at {start:.0f}s — "
                  + (f"{off:+d}ms" if off is not None else "unmeasurable"))
    if a.out_selection:
        for c in sel.get("clips", []):
            if c["id"] in rewritten:
                c["path"] = rewritten[c["id"]]
                _d = raplib.probe_seconds(c["path"])   # the assembler clamps its in-point on durationSec
                if _d:
                    c["durationSec"] = round(_d, 3)
        # a shifted copy's frame 0 IS the window's start (the measured offset included
        # the lead-in); the assembler honours headSec since 2026-08-31, so it is spent
        for w in sel.get("vocalMap", []):
            if w.get("performerClip") in rewritten:
                w["headSec"] = 0.0
        json.dump(sel, open(a.out_selection, "w"), indent=1)
        print(f"\nselection rewritten onto the shifted clips -> {a.out_selection}")
    if a.json:
        json.dump({"shifted": rows,
                   "needsRerender": [{"clip": p, "startSec": s, "offsetMs": o}
                                     for p, s, o in rerender]},
                  open(a.json, "w"), indent=1)
    return 0


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