#!/usr/bin/env python3
"""word_ends.py — give every word in a words file its END (`e`), from the source the pack names.

WHY. Whisper hears where a word STARTS to within ~100 ms and that is the lane's clock
(`t`, never moved here). Where a word ENDS it hears poorly on singing: it closes the
word when the consonants stop, and a held vowel — "nimboodaaa…", a 2.5 s melisma —
goes on for seconds after. Downstream everything that needed a duration made one up
(0.4 s flat fill words, start-to-start gaps, "last heard" = last onset), and the
render length, which is sized by the singing, came out short on every held final note.

TWO SOURCES, named in the pack (`WORD_ENDS`), never mixed silently:

  stem    (the template's default) — `transcribe_clips.measured_ends`: the stem's RMS
          finds where the note actually stops — later than whisper on a held vowel,
          EARLIER where whisper tiled a word across silence to the next onset (377 of
          428 words on a real stem do that). Local, free, deterministic.
  gemini  — the whole audio (the vocal stem when the film has one, else hook.wav) goes
          to gemini-3.5-flash INLINE with the word list `[{i, t, w}]`, in batches; it
          answers `e` per index. Matching is by INDEX, so nothing is re-transcribed and
          no word moves. MEASURED (Hanuman Chalisa stem, 2026-09-05, 80 words): it tiled
          to the next onset on 69 of 80, and on the 8 words before a real silence it was
          LATE by 0.7–1.6 s every time (median +0.9 s) — an estimate, not a hearing. So it
          is selectable, not the default. No key = a hard stop that names
          WORD_ENDS=stem|whisper (exit 3) — a film must not quietly get worse ends.

WHAT IS PROMISED EITHER WAY: `t` unchanged; `t <= e <= next word's t` (a clamped end can
never push a word over its neighbour); words whose `e` moved carry `eFrom` and the
whisper value in `whisperE`; the words file is rewritten IN PLACE (every consumer reads
`e` from the same file it already reads) with an `ends` block that keys the result on
its inputs, so a second run is a no-op and a changed stem or model re-measures; a
report goes to --report with the per-word diff.

Usage:
  word_ends.py --words build/stem-words.json --audio build/stems/vocals.wav \
               --source gemini|stem [--report build/word-ends.json] [--model gemini-3.5-flash]
               [--batch 80] [--dry-run]
"""
from __future__ import annotations

import argparse
import hashlib
import json
import os
import subprocess
import sys
import tempfile

HERE = os.path.dirname(os.path.abspath(__file__))
sys.path.insert(0, HERE)
sys.path.insert(0, os.path.join(HERE, "..", "..", "dance-breakdown", "scripts"))

from transcribe_clips import measured_ends  # noqa: E402

DEFAULT_MODEL = "gemini-3.5-flash"
DEFAULT_BATCH = 40   # ~750 output tokens; thinking shares the output budget (see call_model)
MIN_WORD_S = 0.05


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


def probe_seconds(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 clamp_ends(words: list[dict], proposed: dict[int, float], source: str,
               total_s: float | None) -> tuple[list[dict], list[dict]]:
    """Apply proposed ends by index under the promise: t unchanged, t+MIN <= e <= next t.
    Returns (words, diff rows). Pure."""
    out, diff = [], []
    for i, w in enumerate(words):
        w = dict(w)
        t = float(w["t"])
        old_e = float(w.get("e", t))
        nxt = float(words[i + 1]["t"]) if i + 1 < len(words) else (total_s if total_s else None)
        if i in proposed:
            e = float(proposed[i])
            lo = t + MIN_WORD_S
            hi = nxt if nxt is not None else max(e, lo)
            e_clamped = round(min(max(e, lo), max(hi, lo)), 3)
            row = {"i": i, "w": w.get("w"), "t": t, "whisperE": round(old_e, 3),
                   f"{source}E": round(e, 3), "e": e_clamped,
                   "clamped": abs(e_clamped - e) > 1e-6}
            if abs(e_clamped - old_e) > 1e-6:
                w.setdefault("whisperE", round(old_e, 3))
                w["e"], w["eFrom"] = e_clamped, source
                row["applied"] = True
            else:
                row["applied"] = False
            diff.append(row)
        out.append(w)
    return out, diff


def encode_for_gemini(audio: str, out_dir: str) -> str:
    """Mono 64 kbps mp3: a 5-minute stem is ~2.4 MB, well under the inline part cap."""
    out = os.path.join(out_dir, "word-ends-audio.mp3")
    subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", audio, "-vn", "-ac", "1", "-ar", "22050",
                    "-b:a", "64k", out], check=True)
    return out


def gemini_prompt(batch: list[dict], total_s: float) -> str:
    return (
        "You are a karaoke time-coder listening to an isolated vocal track "
        f"({total_s:.1f} s long).\n"
        "Below is a list of sung words, each with the exact second it STARTS (t). Those start "
        "times are correct and must not be questioned. For EVERY word, listen and give the exact "
        "second the word ENDS (e): the moment the singer stops sounding it and the note is over.\n\n"
        "CRITICAL — HELD NOTES: when the singer stretches a word, holds a vowel, or sings a run / "
        "meend / alaap on it, e MUST extend across the ENTIRE held duration, until the very next "
        "word begins. A short functional word may last 0.2–0.5 s; a held emotional word can last "
        "2–4 s. Never distribute durations evenly. e must be greater than t and must not exceed the "
        "next word's t.\n\n"
        "Words:\n" + json.dumps(batch, ensure_ascii=False) + "\n\n"
        "Output ONLY a JSON array with one object per word, same order: [{\"i\": int, \"e\": float}]"
    )


def gemini_ends(words: list[dict], audio: str, model: str, batch_size: int, dry_run: bool,
                say=lambda m: print(m, file=sys.stderr)) -> tuple[dict[int, float], dict]:
    """Ask Gemini for the end of every word, by index, in batches. Returns (ends, meta)."""
    from breakdown import api_keys, call_model, COOLDOWN_S  # noqa: E402  (dance-breakdown plumbing)
    keys = api_keys()
    if not keys:
        say("word_ends: WORD_ENDS=gemini but no Gemini key (GEMINI_API_KEYS / GOOGLE_API_KEY, or "
            ".env.local). The film must not quietly get whisper's ends instead: set WORD_ENDS=stem "
            "(local, free) or WORD_ENDS=whisper in the pack, or export a key.")
        raise SystemExit(3)
    total_s = probe_seconds(audio)
    audio_b64, audio_bytes = "", 0
    if not dry_run:   # a dry run touches nothing: no encode, no upload, no call
        tmp = tempfile.mkdtemp(prefix="word-ends-")
        mp3 = encode_for_gemini(audio, tmp)
        with open(mp3, "rb") as fh:
            import base64
            audio_b64 = base64.b64encode(fh.read()).decode()
        audio_bytes = os.path.getsize(mp3)
    ends: dict[int, float] = {}
    batches = [words[k:k + batch_size] for k in range(0, len(words), batch_size)]
    cooldown: dict[str, float] = {}
    meta = {"model": model, "batches": len(batches), "audioBytes": audio_bytes,
            "cooldownS": COOLDOWN_S}
    for bi, batch in enumerate(batches):
        listing = [{"i": k + bi * batch_size, "t": float(w["t"]), "w": w["w"]} for k, w in enumerate(batch)]
        prompt = gemini_prompt(listing, total_s)
        if dry_run:
            say(f"word_ends: DRY RUN batch {bi + 1}/{len(batches)} — {len(listing)} words, "
                f"audio {total_s:.1f}s would go inline as mono 64 kbps mp3, prompt {len(prompt)} chars; no call made")
            continue
        parts = [{"inlineData": {"mimeType": "audio/mpeg", "data": audio_b64}}, {"text": prompt}]
        say(f"word_ends: batch {bi + 1}/{len(batches)} ({len(listing)} words) → {model}")
        answer = call_model(keys, model, parts, cooldown, max_output_tokens=16384)
        rows = answer if isinstance(answer, list) else answer.get("words", []) if isinstance(answer, dict) else []
        for row in rows:
            try:
                i, e = int(row["i"]), float(row["e"])
            except (KeyError, TypeError, ValueError):
                continue
            if 0 <= i < len(words):
                ends[i] = e
    meta["answered"] = len(ends)
    return ends, meta


def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("--words", required=True, help="a words file {words:[{t,e?,w}], ...} — rewritten in place")
    ap.add_argument("--audio", required=True, help="the audio the words were heard in (stem, else hook.wav)")
    ap.add_argument("--source", required=True, choices=["gemini", "stem"])
    ap.add_argument("--report", default="", help="per-word diff (default: <words dir>/word-ends.json)")
    ap.add_argument("--model", default=os.environ.get("WORD_ENDS_MODEL", DEFAULT_MODEL))
    ap.add_argument("--batch", type=int, default=DEFAULT_BATCH)
    ap.add_argument("--dry-run", action="store_true")
    a = ap.parse_args()

    doc = json.load(open(a.words, encoding="utf-8"))
    words = doc.get("words") if isinstance(doc, dict) else doc
    if not isinstance(words, list):
        print(f"word_ends: {a.words} has no words list", file=sys.stderr)
        return 2
    if not os.path.isfile(a.audio):
        print(f"word_ends: audio not on disk: {a.audio}", file=sys.stderr)
        return 2
    key = {"source": a.source, "model": a.model if a.source == "gemini" else None,
           "audioSha": sha256_file(a.audio),
           "onsetsSha": hashlib.sha256(json.dumps([[w["t"], w["w"]] for w in words]).encode()).hexdigest()}
    prior = doc.get("ends") if isinstance(doc, dict) else None
    if prior and all(prior.get(k) == v for k, v in key.items()) and not a.dry_run:
        print(f"word_ends: {a.words} already carries {a.source} ends for these inputs — nothing to do",
              file=sys.stderr)
        return 0

    total_s = probe_seconds(a.audio)
    if a.source == "stem":
        new_words = measured_ends(words, a.audio, hard_cap_s=total_s or None)
        proposed = {i: float(w["e"]) for i, w in enumerate(new_words) if w.get("eFrom") == "stem"}
        meta = {"method": "rms-measured-end"}
        if a.dry_run:
            print(f"word_ends: DRY RUN stem — {len(proposed)} of {len(words)} words would move", file=sys.stderr)
            return 0
    else:
        proposed, meta = gemini_ends(words, a.audio, a.model, a.batch, a.dry_run)
        if a.dry_run:
            return 0
    words2, diff = clamp_ends(words, proposed, a.source, total_s or None)
    applied = sum(1 for d in diff if d.get("applied"))
    doc2 = dict(doc) if isinstance(doc, dict) else {"words": None}
    doc2["words"] = words2
    doc2["schema"] = max(int(doc2.get("schema") or 1), 2)
    doc2["ends"] = {**key, **meta, "applied": applied, "proposed": len(proposed)}
    tmp = a.words + ".tmp"
    with open(tmp, "w", encoding="utf-8") as fh:
        json.dump(doc2, fh, ensure_ascii=False)
    os.replace(tmp, a.words)
    report = a.report or os.path.join(os.path.dirname(os.path.abspath(a.words)), "word-ends.json")
    with open(report, "w", encoding="utf-8") as fh:
        json.dump({"schemaVersion": 1, "words": a.words, "audio": a.audio, **doc2["ends"],
                   "diff": diff}, fh, ensure_ascii=False, indent=1)
    held = sum(1 for w in words2 if float(w.get("e", w["t"])) - float(w["t"]) >= 1.0)
    print(f"word_ends: {a.source} ends on {applied}/{len(words)} words ({held} held ≥1 s) → {a.words}; "
          f"diff → {report}", file=sys.stderr)
    return 0


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