#!/usr/bin/env python3
"""make_subtitles.py — clean, offset subtitles for a bookended film.

`rhyme-factory/scripts/make-captions.sh` already builds sing-along captions and is the
right tool when the lyric-line count is a clean multiple of the whisper-segment count.
This covers the two cases it cannot.

**The counts do not divide.** On a real film: 36 clean lines against 26 whisper
segments, whose first and last segments were ad-libs appearing in no lyric sheet at
all. A positional 1:1 map is only valid when the counts match; walking the sheet
sequentially against a song whose hook repeats three times is precisely how captions
drift a line and stay drifted.

So this does NOT re-time anything. Whisper's segment boundaries already correspond to
what is sung inside them; only the WORDS are wrong, and locally — "The WIC said sail
out" for "W I C C, say it loud", "David on the shoulder" for "Navy on the shoulder".
Each segment therefore keeps its own start and end, and only its text is replaced,
by consuming the next 1-3 lines of the sheet under a MONOTONIC cursor. Timing and text
cannot come apart, because the timing is never recomputed.

**Everything is late by the bookends.** A film that opens with a foreword and an ident
plays the song ~22s in. Pass `--offset-from-cards <cards.json>` and the shift is READ
from what make_bookends.py actually built, rather than typed and then quietly wrong the
next time a beat length changes.

A segment whose best match falls below `--min-score` keeps whisper's own text and is
reported, so a bad line is visible instead of silently confident.

Burning them is its own trap — see the `captions` stage in make-rap-mv.sh: `-ss` must
come AFTER `-i`, or ffmpeg rebases the output timeline to zero, libass looks for a cue
at t=0, and you get a clean render with no subtitles and no error.

Usage:
  make_subtitles.py --transcript … --lyrics … --out captions.ass
                    [--offset N | --offset-from-cards build/bookends/cards.json]
                    [--font Optima] [--size 42]
"""
from __future__ import annotations

import argparse
import difflib
import json
import re
import sys

# Ad-libs and vocalisations carry no lyric line. They are still SUNG, so a cue that
# says nothing is better than a cue that borrows the next verse's words.
ADLIB = re.compile(r"^[\s,\.]*((eh|yeah|oh|ay|hey|woo|na)\b[\s,\.]*)+$", re.I)


def toks(s: str) -> set[str]:
    return set(re.findall(r"[a-z0-9]+", s.lower()))


def score(a: str, b: str) -> float:
    """Token overlap OR character similarity, whichever is kinder.

    Token overlap alone is blind to the way whisper actually fails: it heard "The WIC
    said sail out" for "W I C C, say it loud", which shares almost no whole tokens and
    scored 0.04 — so the line went uncorrected AND the cursor stalled, pushing the
    whole hook one segment late. Compared as despaced characters the same pair is
    obviously the same words."""
    x, y = toks(a), toks(b)
    jac = len(x & y) / len(x | y) if x and y else 0.0
    fa = re.sub(r"[^a-z0-9]", "", a.lower())
    fb = re.sub(r"[^a-z0-9]", "", b.lower())
    ratio = difflib.SequenceMatcher(None, fa, fb).ratio() if fa and fb else 0.0
    return max(jac, ratio)


def lyric_lines(path: str) -> list[str]:
    """Expand a bare repeated section marker such as a later ``[Hook]``.

    The fallback caption path must interpret the same song-sheet structure as
    line_subs.py. Otherwise losing word timestamps also silently loses every repeated
    chorus from the subtitle track.
    """
    heading = re.compile(r"^\[([^]]+)\]\s*$")
    sections: list[tuple[str, list[str]]] = []
    current = ""
    lines: list[str] = []

    def finish() -> None:
        nonlocal lines
        if current or lines:
            sections.append((current.casefold().strip(), lines))
        lines = []

    for raw in open(path, encoding="utf-8"):
        text = raw.strip()
        if not text:
            continue
        match = heading.match(text)
        if match:
            finish()
            current = match.group(1)
            continue
        lines.append(text)
    finish()

    known: dict[str, list[str]] = {}
    expanded: list[str] = []
    for name, block in sections:
        if block:
            known[name] = block
            expanded.extend(block)
        elif name in known:
            expanded.extend(known[name])
    return expanded


def ass_time(t: float) -> str:
    t = max(0.0, t)
    h, rem = divmod(t, 3600)
    m, s = divmod(rem, 60)
    return f"{int(h)}:{int(m):02d}:{s:05.2f}"


def main() -> None:
    ap = argparse.ArgumentParser()
    ap.add_argument("--transcript", required=True)
    ap.add_argument("--lyrics", required=True)
    ap.add_argument("--offset", type=float, default=0.0)
    ap.add_argument("--offset-from-cards", default="",
                    help="read the front matter from a bookends cards.json instead of "
                         "typing it: every block before BODY is added up")
    ap.add_argument("--out", required=True)
    ap.add_argument("--min-score", type=float, default=0.34)
    ap.add_argument("--max-lines", type=int, default=3)
    # Optima at 42: a didone (the usual display face on these cards) has hairline
    # horizontals that disappear at subtitle size over moving picture. 42 is not
    # arbitrary either — at 52 a sung couplet wrapped to FOUR screen lines and ate the
    # lower third; at 42 each lyric line fits one screen line and the couplet is two.
    ap.add_argument("--font", default="Optima")
    ap.add_argument("--size", type=int, default=42)
    args = ap.parse_args()

    if args.offset_from_cards:
        m = json.load(open(args.offset_from_cards, encoding="utf-8"))
        blocks = {b["id"]: b for b in m["blocks"]}
        front = 0.0
        for el in m["order"]:
            if el == "BODY":
                break
            front += float(blocks[el]["seconds"])
        args.offset = round(front, 3)

    raw = json.load(open(args.transcript, encoding="utf-8"))
    segs = raw.get("segments") if isinstance(raw, dict) else raw
    lyrics = lyric_lines(args.lyrics)

    cur, cues, report = 0, [], []
    for s in segs:
        heard = (s.get("text") or "").strip()
        if not heard:
            continue
        if ADLIB.match(heard):
            report.append((s["start"], 1.0, "ad-lib", heard))
            continue
        # Consume 1..max_lines of the sheet from the cursor, keeping whichever run
        # matches what was heard best. The cursor only ever moves forward, so a
        # repeated hook cannot pull the captions back to an earlier verse.
        best_k, best_s = 0, 0.0
        for k in range(1, args.max_lines + 1):
            if cur + k > len(lyrics):
                break
            v = score(heard, " ".join(lyrics[cur:cur + k]))
            if v > best_s:
                best_k, best_s = k, v
        # Also find the best match ANYWHERE in the sheet. The audio repeats its hook
        # more often than the sheet lists it, so the cursor runs out of hooks while
        # the singer is still singing them — and a merely-passable forward match then
        # wins by default. It happened: a hook repeat took the OUTRO couplet at 0.35
        # simply because that was what lay ahead. A forward match now has to be
        # genuinely better, not just present.
        any_k, any_s, any_i = 0, 0.0, 0
        for i in range(len(lyrics)):
            for k in range(1, args.max_lines + 1):
                if i + k > len(lyrics):
                    break
                v = score(heard, " ".join(lyrics[i:i + k]))
                if v > any_s:
                    any_k, any_s, any_i = k, v, i

        if best_k and best_s >= args.min_score and best_s >= any_s - 0.15:
            text = "\\N".join(l.rstrip(",") for l in lyrics[cur:cur + best_k])
            cur += best_k
            report.append((s["start"], best_s, "matched", text.replace("\\N", " / ")))
            cues.append((s["start"] + args.offset, s["end"] + args.offset, text))
            continue
        # Reuse the better line from elsewhere WITHOUT moving the cursor: matching on
        # content is safe for a repeated chorus, and a correct repeat beats both a
        # wrong forward line and whisper's mangled version of the same words.
        if any_k and any_s >= args.min_score:
            text = "\\N".join(l.rstrip(",") for l in lyrics[any_i:any_i + any_k])
            report.append((s["start"], any_s, "reused", text.replace("\\N", " / ")))
        else:
            # Keep what was actually heard rather than borrowing the wrong line.
            text = heard
            report.append((s["start"], best_s, "KEPT WHISPER", heard))
        cues.append((s["start"] + args.offset, s["end"] + args.offset, text))

    head = f"""[Script Info]
ScriptType: v4.00+
PlayResX: 720
PlayResY: 1280
WrapStyle: 0
ScaledBorderAndShadow: yes

[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, OutlineColour, BackColour, Bold, Italic, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
Style: Song,{args.font},{args.size},&H00FFFFFF,&H00201408,&H96000000,-1,0,1,3,2,2,26,26,86,1

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
"""
    body = "".join(
        f"Dialogue: 0,{ass_time(a)},{ass_time(b)},Song,,0,0,0,,{t}\n" for a, b, t in cues)
    open(args.out, "w", encoding="utf-8").write(head + body)

    kept = sum(1 for _, _, k, _ in report if k == "KEPT WHISPER")
    print(f"make_subtitles: {len(cues)} cues -> {args.out} (offset {args.offset:+.3f}s)",
          file=sys.stderr)
    for t, sc, kind, text in report:
        mark = "  " if kind == "matched" else "!!"
        print(f" {mark} {t + args.offset:7.2f}  {sc:.2f} {kind:<13} {text[:60]}",
              file=sys.stderr)
    if cur < len(lyrics):
        print(f"  NOTE: {len(lyrics) - cur} lyric line(s) never used — "
              f"{lyrics[cur][:44]!r}…", file=sys.stderr)
    if kept:
        print(f"  {kept} cue(s) kept whisper's own words; check those lines by eye.",
              file=sys.stderr)


if __name__ == "__main__":
    main()
