#!/usr/bin/env python3
"""pick_hook.py — choose the CLIMAX window of a rap track, and refuse to be lazy.

The failure this gate exists to stop: taking the first N seconds because it is
easier. A song's opening is usually an intro, not the hook, and an 8-second clip
cut from an intro is a dead MV — the hero lip-sync render (OmniHuman) is built
from exactly this window, so a bad pick is paid for twice.

Method (deterministic, no numpy, no model):
  1. Decode the song to mono 8 kHz s16le via ffmpeg and compute per-window RMS in
     pure Python. Energy is measured, never guessed.
  2. Take candidate start times from the WHISPER TRANSCRIPT's segment starts —
     real word onsets, never a fixed grid. A song with no transcript segments is
     a hard failure: guessing block boundaries is what caused the caption-drift
     class of bugs, and it is not done here.
  3. Score each candidate window by energy (mean RMS, normalised against the
     track's peak window), word density (syllable-ish rate), and repetition (a
     line whose text recurs elsewhere in the song is the chorus/hook).
  4. Snap the end to the last word-end that fits, so no syllable is clipped.

THE GATE. If the winning window starts at the very top of the song, that is only
accepted when the opening is genuinely the loudest part of the track — proven by
number, and the proof is written into `reason`. Otherwise the script exits 3 and
prints the runner-up windows: the correct fix is to pick a later window or to
regenerate a song that opens on its hook, never to relax the check.

Usage:
  pick_hook.py --song <mp3|wav> --transcript <whisper.json> --out-dir <dir>
               [--duration 8] [--min-duration 6] [--ffmpeg ffmpeg] [--json]

Writes <out-dir>/hook.wav and <out-dir>/hook.json. Exit 0 = picked, 2 = bad
input (no transcript segments / unreadable audio), 3 = gate refused the pick.
"""
from __future__ import annotations

import argparse
import array
import json
import math
import os
import subprocess
import sys

SAMPLE_RATE = 8000
WINDOW_SEC = 0.25  # RMS resolution

# The opening is only allowed to win if it really is the loudest part of the
# track. 0.90 means "within 10% of the peak window" — generous enough for a song
# that genuinely opens hot, tight enough to catch a soft intro.
OPENING_PEAK_RATIO = 0.90
# Below this fraction of the song, a window is almost certainly an accident rather
# than an edit. 0.6 is deliberately permissive: a real climax cut of a 3-minute track
# is often 60-90s, and this gate is aimed at the 26% case, not at judging taste.
MIN_COVERAGE = 0.6

# A start below this is treated as "the top of the song" for gate purposes.
OPENING_START_SEC = 1.0


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


def decode_rms(song: str, ffmpeg: str) -> list[float]:
    """Per-WINDOW_SEC RMS of the whole track (PURE measurement, no heuristics)."""
    cmd = [ffmpeg, "-v", "error", "-nostdin", "-i", song,
           "-ac", "1", "-ar", str(SAMPLE_RATE), "-f", "s16le", "-"]
    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    if proc.returncode != 0 or not proc.stdout:
        die(f"could not decode audio: {song}\n{proc.stderr.decode('utf-8', 'replace')[:400]}")
    samples = array.array("h")
    samples.frombytes(proc.stdout[: len(proc.stdout) // 2 * 2])
    per = int(SAMPLE_RATE * WINDOW_SEC)
    out: list[float] = []
    for i in range(0, len(samples) - per + 1, per):
        acc = 0
        for s in samples[i:i + per]:
            acc += s * s
        out.append(math.sqrt(acc / per))
    if not out:
        die(f"audio too short to analyse: {song}")
    return out


def window_energy(rms: list[float], start: float, end: float) -> float:
    a = max(0, int(start / WINDOW_SEC))
    b = min(len(rms), max(a + 1, int(end / WINDOW_SEC)))
    seg = rms[a:b]
    return sum(seg) / len(seg) if seg else 0.0


def normalise_text(t: str) -> str:
    return " ".join("".join(c.lower() if c.isalnum() or c.isspace() else " " for c in t).split())


def load_segments(path: str) -> list[dict]:
    """Accept a bare list, or whisper's {'segments': [...]} envelope."""
    with open(path, encoding="utf-8") as fh:
        data = json.load(fh)
    segs = data.get("segments") if isinstance(data, dict) else data
    if not isinstance(segs, list) or not segs:
        die(f"no transcript segments in {path} — whisper the song first; "
            "block boundaries are never guessed here")
    out = []
    for s in segs:
        try:
            start, end = float(s["start"]), float(s["end"])
        except (KeyError, TypeError, ValueError):
            continue
        if end > start:
            out.append({"start": start, "end": end, "text": str(s.get("text", "")).strip()})
    if not out:
        die(f"transcript in {path} has no usable start/end pairs")
    return sorted(out, key=lambda s: s["start"])


def score_candidates(segs: list[dict], rms: list[float], duration: float,
                     min_duration: float, must_include: str = "") -> list[dict]:
    track_end = len(rms) * WINDOW_SEC
    peak = max(window_energy(rms, t, t + duration)
               for t in [i * WINDOW_SEC for i in range(max(1, len(rms) - int(duration / WINDOW_SEC)))]) or 1.0

    # Repetition by TOKEN OVERLAP, not exact text. Whisper does not segment a
    # repeated chorus identically -- on the first WICC song it emitted the hook as
    # one long segment the first time and as two shorter ones the second time, so
    # exact matching scored repetition 0.00 everywhere and the picker chose a verse.
    # Overlap catches the same line however it happens to be cut up. Matches are
    # only counted across a time gap, so the neighbouring halves of one delivery
    # cannot vouch for each other.
    tokens = [set(normalise_text(s["text"]).split()) for s in segs]

    def repetition_of(i: int) -> float:
        a = tokens[i]
        if len(a) < 3:
            return 0.0
        best = 0.0
        for j, b in enumerate(tokens):
            if i == j or len(b) < 3:
                continue
            if abs(segs[j]["start"] - segs[i]["start"]) < 8.0:
                continue
            overlap = len(a & b) / min(len(a), len(b))
            best = max(best, overlap)
        return min(1.0, best / 0.6)

    cands: list[dict] = []
    for idx, s in enumerate(segs):
        start = s["start"]
        if start + min_duration > track_end:
            continue
        end_limit = min(start + duration, track_end)
        # snap the end to the last word/segment end that fits
        ends = [x["end"] for x in segs if start < x["end"] <= end_limit]
        end = max(ends) if ends else end_limit
        if end - start < min_duration:
            end = end_limit
        if end - start < min_duration:
            continue

        energy = window_energy(rms, start, end) / peak
        words = sum(len(x["text"].split()) for x in segs
                    if x["start"] >= start - 0.01 and x["end"] <= end + 0.01)
        density = min(1.0, words / max(1e-6, (end - start)) / 4.0)  # ~4 words/s saturates
        # the window's repetition = the strongest repeated line inside it
        repeat = max(
            (repetition_of(k) for k, x in enumerate(segs)
             if x["start"] >= start - 0.01 and x["end"] <= end + 0.01),
            default=repetition_of(idx),
        )

        cands.append({
            "start": round(start, 3),
            "end": round(end, 3),
            "durationSec": round(end - start, 3),
            "text": s["text"],
            "energy": round(energy, 4),
            "density": round(density, 4),
            "repeat": round(repeat, 4),
            "score": round(0.55 * energy + 0.25 * density + 0.20 * repeat, 4),
        })
    if not cands:
        die("no candidate window long enough — the song is shorter than --min-duration")

    # A hard content requirement the energy scorer cannot know about: for a branded
    # piece (a club anthem, a product line) the clip is worthless if it does not
    # contain the name, however loud the alternative is. Filter, do not weight —
    # a bonus would let a louder nameless window still win.
    if must_include:
        want = normalise_text(must_include).split()
        kept = []
        for c in cands:
            window_text = normalise_text(" ".join(
                x["text"] for x in segs
                if x["start"] >= c["start"] - 0.01 and x["end"] <= c["end"] + 0.01))
            if all(w in window_text.split() for w in want):
                kept.append(c)
        if not kept:
            die(f"no {duration:g}s window contains {must_include!r}. Either the song never says "
                f"it intelligibly (check the transcript — a model that cannot pronounce the name "
                f"is a REJECT, re-roll the song), or relax --must-include.", 3)
        cands = kept
    return sorted(cands, key=lambda c: (-c["score"], c["start"]))


def main() -> None:
    ap = argparse.ArgumentParser()
    ap.add_argument("--song", required=True)
    ap.add_argument("--transcript", required=True)
    ap.add_argument("--out-dir", required=True)
    ap.add_argument("--duration", type=float, default=8.0)
    ap.add_argument("--min-duration", type=float, default=6.0)
    ap.add_argument("--ffmpeg", default=os.environ.get("FFMPEG_BIN", "ffmpeg"))
    ap.add_argument("--json", action="store_true", help="print the result JSON to stdout")
    ap.add_argument("--must-include", default=os.environ.get("HOOK_MUST_INCLUDE", ""),
                    help="only consider windows whose words include ALL of these (e.g. a club or "
                         "product name). Filters rather than weights, so a louder window that omits "
                         "the name cannot win.")
    ap.add_argument("--from-start-ok", action="store_true",
                    help="operator override: you have LISTENED and the opening really is the hook. "
                         "Records the override in hook.json rather than hiding it.")
    ap.add_argument("--short-ok", action="store_true",
                    help="accept a window that covers only a small fraction of the "
                         "song (see MIN_COVERAGE) — records the choice rather than "
                         "letting a default make it")
    ap.add_argument("--full-track", action="store_true",
                    help="operator override: the film covers the WHOLE song, not a climax window. "
                         "Nothing else expresses this — --duration is a CEILING on a scored window, "
                         "not a length, and --from-start-ok only waives the refusal when the winner "
                         "already starts at the top. Without this flag the only way to cover a whole "
                         "track was to hand-edit hook.json, which no re-run then respects. Records "
                         "the override in hook.json.")
    args = ap.parse_args()
    # THE DEFAULT FULL-TRACK PACK COULD NEVER PASS THIS STAGE. HOOK_FULL_TRACK=1 leaves
    # HOOK_SECONDS unset, the runner passes --duration 0, and candidate scoring — which
    # runs BEFORE the full-track override and is only used to RECORD the pick the
    # override replaces — collapsed every window to zero length and died with "the song
    # is shorter than --min-duration" on a 132s song. Every earlier film dodged it by
    # hardcoding HOOK_SECONDS; the first pack to trust the default hit it immediately.
    # On the full-track path a non-positive duration means "unset": score candidates at
    # the stock window purely for the record.
    if args.full_track and args.duration <= 0:
        args.duration = 8.0

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

    rms = decode_rms(args.song, args.ffmpeg)
    segs = load_segments(args.transcript)
    cands = score_candidates(segs, rms, args.duration, args.min_duration, args.must_include)
    best = cands[0]

    # ---- THE COVERAGE GATE ------------------------------------------------
    #
    # NOTHING USED TO COMPARE THE FILM'S LENGTH TO THE SONG'S, and that let a whole
    # film be built from 26% of its track without one word of warning: a 32s request
    # against a 112-second song produced four clips covering 21.0-50.0s, every gate
    # green, and the operator found it by watching. A window is a legitimate choice;
    # taking one BY ACCIDENT, because HOOK_SECONDS defaulted or a pack forgot it, is
    # not — and the two are indistinguishable from the inside.
    #
    # So say the fraction out loud, always, and refuse a small one unless it was
    # asked for explicitly.
    track_len_s = round(len(rms) * WINDOW_SEC, 3)
    if not args.full_track and track_len_s > 0:
        covered = min(args.duration, track_len_s) / track_len_s
        print(f"pick_hook: this film would cover {covered:.0%} of a {track_len_s:g}s song "
              f"({args.duration:g}s window).", file=sys.stderr)
        if covered < MIN_COVERAGE and not args.short_ok:
            die(f"a {args.duration:g}s window covers only {covered:.0%} of a {track_len_s:g}s "
                f"song — the film would discard {track_len_s - args.duration:.0f}s of it.\n"
                f"  * For a music video of THIS song, set HOOK_FULL_TRACK=1 in the pack "
                f"(the default) and the film covers the whole track.\n"
                f"  * If a short clip really is what you want, pass --short-ok, which "
                f"records the choice in hook.json instead of leaving it to a default.", 4)

    # ---- THE GATE ---------------------------------------------------------
    peak_window = max(window_energy(rms, i * WINDOW_SEC, i * WINDOW_SEC + args.duration)
                      for i in range(max(1, len(rms) - int(args.duration / WINDOW_SEC)))) or 1.0
    override = False
    if args.full_track:
        # A SCORED window is the wrong instrument for a list-song. Scoring finds the
        # loudest, densest, most-repeated stretch — which is a chorus — and everything
        # outside it is discarded. In a song whose verses are each a separate joke,
        # that silently throws away half the material: measured on a real 191.56s
        # track, the winning window began at 114s and dropped verses 1 and 2 whole.
        # The candidates are still scored and recorded below, so the pick this
        # REPLACES stays visible in hook.json rather than being lost.
        track_len = round(len(rms) * WINDOW_SEC, 3)
        best = {"start": 0.0, "end": track_len, "durationSec": track_len,
                "text": (segs[0]["text"].strip() if segs else ""),
                "energy": 1.0, "density": 0.0, "repeat": 1.0, "score": 1.0}
        override = True
        reason = (f"full-track by OPERATOR OVERRIDE (--full-track): the film covers the whole "
                  f"{track_len:g}s song rather than a climax window, so no section is discarded. "
                  f"The scored winner this replaces was "
                  f"{cands[0]['start']:.2f}s-{cands[0]['end']:.2f}s.")
    elif best["start"] < OPENING_START_SEC:
        opening = window_energy(rms, 0.0, args.duration) / peak_window
        if opening < OPENING_PEAK_RATIO and args.from_start_ok:
            override = True
            reason = (f"opening accepted by OPERATOR OVERRIDE (--from-start-ok): the first "
                      f"{args.duration:g}s measures only {opening:.0%} of the track's peak window "
                      f"energy; the operator confirms by ear that this is the hook")
        elif opening < OPENING_PEAK_RATIO:
            alts = "\n".join(
                f"    {c['start']:7.2f}s  score={c['score']:.3f}  energy={c['energy']:.3f}  {c['text'][:56]!r}"
                for c in cands[1:5])
            print(
                "pick_hook: REFUSED — the winning window is the top of the song, but the opening is "
                f"only {opening:.0%} of the track's peak energy (needs >= {OPENING_PEAK_RATIO:.0%}).\n"
                "  This is the 'just cut 0-N seconds' failure: the song has a soft intro, so the\n"
                "  opening is not the hook.\n"
                "  FIX: pass --from-start-ok only if you have listened and the opening IS the hook,\n"
                "  or regenerate a song that opens on its hook. Runner-up windows:\n" + alts,
                file=sys.stderr)
            raise SystemExit(3)
        else:
            reason = (f"opening-is-peak: the first {args.duration:g}s measures {opening:.0%} of the "
                      f"track's peak window energy (>= {OPENING_PEAK_RATIO:.0%}), so the song opens on its hook")
    else:
        reason = (f"climax at {best['start']:.2f}s: energy={best['energy']:.2f} of peak, "
                  f"density={best['density']:.2f}, repetition={best['repeat']:.2f} — "
                  f"beat {cands[1]['score'] if len(cands) > 1 else 0:.3f} runner-up")

    os.makedirs(args.out_dir, exist_ok=True)
    hook_wav = os.path.join(args.out_dir, "hook.wav")
    cut = [args.ffmpeg, "-y", "-v", "error", "-nostdin",
           "-ss", f"{best['start']:.3f}", "-i", args.song,
           "-t", f"{best['durationSec']:.3f}",
           "-ac", "1", "-ar", "44100", "-c:a", "pcm_s16le", hook_wav]
    proc = subprocess.run(cut, stderr=subprocess.PIPE)
    if proc.returncode != 0:
        die(f"ffmpeg trim failed:\n{proc.stderr.decode('utf-8', 'replace')[:400]}")

    result = {
        "schemaVersion": 1,
        "song": os.path.abspath(args.song),
        "hookWav": os.path.abspath(hook_wav),
        "start": best["start"],
        "end": best["end"],
        "durationSec": best["durationSec"],
        "text": best["text"],
        "reason": reason,
        "operatorOverride": override,
        "candidates": cands[:5],
    }
    with open(os.path.join(args.out_dir, "hook.json"), "w", encoding="utf-8") as fh:
        json.dump(result, fh, indent=2)
        fh.write("\n")

    print(f"pick_hook: {best['start']:.2f}s -> {best['end']:.2f}s "
          f"({best['durationSec']:.2f}s)  {reason}", file=sys.stderr)
    if args.json:
        print(json.dumps(result, indent=2))


if __name__ == "__main__":
    main()
