#!/usr/bin/env python3
"""line_subs.py — one lyric line per cue, timed from WORD-level song timings.

WHEN TO USE THIS INSTEAD OF make_subtitles.py. That tool maps the lyric sheet onto
whisper's SEGMENT boundaries and keeps each segment's own start and end, replacing only
the text. It is the right tool when segments and lyric lines correspond. On a dense rap
they do not: one segment swallowed two or three sheet lines, which put FOUR display lines
on screen at once and left a line sung at 1:08 still showing at 1:13 beside the line
actually being sung. Here the song has word timings, so each lyric line gets its own in
and out from the first and last word it matches — and a cue then appears when its line
starts and leaves when it ends, which is the whole job.

THE TEXT IS ALWAYS THE SHEET'S, NEVER WHISPER'S. The sheet is what the song says; only
the TIMING comes from the transcript. Matching is fuzzy because whisper mishears sung
words ("openers" -> "soplers", "batting" -> "bedding"), and monotonic because a chorus
repeats four times and an unconstrained search pairs a line with the wrong repeat.

WRAPPING IS MEASURED, NOT COUNTED — this is the part that shipped broken. The limit was
42 characters, chosen because 42 is a round number. A 41-character line therefore stayed
on ONE line, rendered about 860px wide inside a 720px frame, and was clipped off BOTH
edges; the operator saw it on screen. Lowering the constant to 26 fixed that line and
still guesses, because a character is not a unit of width: at Optima 46, ten 'M's are
409px and ten 'i's are 128px — a factor of three. So the text is MEASURED with the real
font and wrapped to the real usable width, and then every emitted line is CHECKED
against that width before the file is written. A caption that cannot fit is a hard
failure here rather than a discovery in QuickTime.

Usage:
  line_subs.py --lyrics <lyrics.txt> --transcript <words.json> --out <subs.ass>
               [--play-res 720x1280] [--font Optima] [--font-file <path>] [--size 46]
               [--margin 40] [--outline 3] [--max-lines 2]
               [--offset N | --offset-from-cards build/bookends/cards.json]

Exit 0 written · 2 inputs unusable · 5 a cue cannot be made to fit
"""
from __future__ import annotations

import argparse
import difflib
import json
import os
import re
import sys

MIN_DUR = 0.8
# A caption that lands a hair early reads as on time; one that lands late never does.
LEAD_IN = 0.10
ASS_BREAK = "\\N"       # ASS's forced line break, literal backslash-N in the file
MATCH_FLOOR = 0.45
SEARCH_AHEAD = 40

# Where macOS keeps faces, plus the repo's own. Only used to turn a FAMILY NAME into a
# file to measure with — the .ass still names the family, and libass does its own lookup.
FONT_DIRS = ("/System/Library/Fonts", "/System/Library/Fonts/Supplemental",
             "/Library/Fonts", os.path.expanduser("~/Library/Fonts"))
FONT_EXT = (".ttc", ".ttf", ".otf", ".otc")


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


def _latin(text: str) -> str:
    """The transcript in the SHEET's alphabet. A Hinglish film's takes are transcribed
    in the song's own language, so the vocal-swap word stream is Devanagari while the
    lyric sheet is romanised; stripping to [a-z] turned every take word into nothing
    and "no lyric line could be matched" refused the captions of a finished film
    (film #3, 2026-09-06). vocal_brief already meets the two alphabets this way."""
    if re.search(r"[\u0900-\u097f]", text):
        from vocal_brief import norm_latin, transliterate
        return norm_latin(transliterate(text))
    return text


def norm(text: str) -> list[str]:
    return re.findall(r"[a-z']+", _latin(text).lower())


def lyric_lines(path: str) -> list[str]:
    """Read lyric sections and expand empty repeated-section placeholders.

    Song sheets commonly spell a chorus once and later use a bare ``[Hook]`` marker
    to mean "repeat the hook here".  Treating every bracketed line as a comment drops
    those repeats from the caption timeline: the matcher reaches the end of the sheet
    halfway through the song and every later vocal goes uncaptained.

    A repeated heading only expands when its new block is empty.  A heading with new
    text remains a real new section, and an empty first occurrence (for example an
    instrumental outro) contributes nothing.
    """
    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


# --------------------------------------------------------------------------
# measuring
# --------------------------------------------------------------------------

class Ruler:
    """Measures a string in the font the burn will actually use.

    Falls back to a deliberately PESSIMISTIC per-character estimate when the font
    cannot be loaded, because the failure being prevented is a caption that is too
    wide. An optimistic fallback would reintroduce exactly the bug.
    """

    def __init__(self, family: str, size: int, path: str | None) -> None:
        self.family, self.size, self.font, self.source = family, size, None, "estimate"
        path = path or self._find(family)
        if not path:
            return
        try:
            from PIL import ImageFont
        except ImportError:
            return
        # Prefer the Bold face: the style below sets Bold=-1, and measuring Regular
        # under-reports a bold render.
        for index in (1, 0):
            try:
                font = ImageFont.truetype(path, size, index=index)
            except Exception:
                continue
            name = font.getname()
            if index == 0 or (len(name) > 1 and "bold" in str(name[1]).lower()):
                self.font, self.source = font, f"{os.path.basename(path)}#{index} {name}"
                return

    @staticmethod
    def _find(family: str) -> str | None:
        want = family.replace(" ", "").lower()
        for directory in FONT_DIRS:
            if not os.path.isdir(directory):
                continue
            for name in sorted(os.listdir(directory)):
                stem, ext = os.path.splitext(name)
                if ext.lower() in FONT_EXT and stem.replace(" ", "").lower() == want:
                    return os.path.join(directory, name)
        return None

    def width(self, text: str) -> float:
        if self.font is not None:
            return self.font.getlength(text)
        # ~0.62em is wide for a humanist sans; erring high keeps captions inside.
        return len(text) * self.size * 0.62


def wrap(text: str, ruler: Ruler, usable: float, max_lines: int) -> tuple[list[str], bool]:
    """Split into at most max_lines lines, each within `usable` px. Balanced, not greedy.

    Greedy wrapping packs the first line to the limit and orphans a word on the second,
    which looks broken on a sing-along card. This minimises the WIDEST line, so the two
    come out similar lengths and the widest is as narrow as it can be.

    Returns (lines, fits). `fits` false means even the best split overflows — the caller
    decides, and this script treats it as fatal.
    """
    if ruler.width(text) <= usable:
        return [text], True

    words = text.split()
    best: tuple[float, list[str]] | None = None
    for lines in _splits(words, max_lines):
        widest = max(ruler.width(line) for line in lines)
        if best is None or widest < best[0]:
            best = (widest, lines)
    if best is None:
        return [text], False
    return best[1], best[0] <= usable


def _splits(words: list[str], max_lines: int):
    """Every way of cutting `words` into 2..max_lines contiguous lines."""
    if max_lines < 2 or len(words) < 2:
        yield [" ".join(words)]
        return
    for count in range(2, max_lines + 1):
        yield from _cut(words, count)


def _cut(words: list[str], count: int):
    if count == 1:
        yield [" ".join(words)]
        return
    for i in range(1, len(words) - count + 2):
        for rest in _cut(words[i:], count - 1):
            yield [" ".join(words[:i])] + rest


# --------------------------------------------------------------------------
# timing
# --------------------------------------------------------------------------

def song_words(path: str) -> list[tuple[float, float, str]]:
    raw = json.load(open(path, encoding="utf-8"))
    segments = raw.get("segments") if isinstance(raw, dict) else raw
    words = []
    for segment in segments or []:
        for word in segment.get("words") or []:
            token = re.sub(r"[^a-z']", "", _latin(str(word.get("word", ""))).lower())
            if token:
                words.append((float(word["start"]), float(word["end"]), token))
    if not words:
        die(f"{path} has no WORD timings. Re-transcribe with --word_timestamps True; "
            "interpolating words across a sung line manufactures drift that is not in "
            "the audio, so this refuses rather than guessing.")
    return words


def time_lines(lines: list[str], words: list[tuple[float, float, str]]) -> list[tuple]:
    cues, cursor = [], 0
    for line in lines:
        want = norm(line)
        if not want:
            continue
        best = None
        for start in range(cursor, min(len(words), cursor + SEARCH_AHEAD)):
            for span in range(max(2, len(want) - 3), len(want) + 4):
                end = start + span
                if end > len(words):
                    break
                got = [w for _, _, w in words[start:end]]
                # TWO ALPHABETS, ONE LINE. Whole-token equality is the right test for
                # a sheet and a transcript in one spelling; a romanised sheet against
                # transliterated Devanagari takes ("saroj raj" / "saro raush", "manu
                # mukuru" / "mane mo kyu") shares almost no whole token and scored 0 of
                # 52 lines on film #3 (2026-09-06), while the same lines as character
                # strings score 0.67–0.85 and land in order. The character ratio is a
                # second vote; the token ratio still wins wherever it can.
                score = max(difflib.SequenceMatcher(None, want, got).ratio(),
                            difflib.SequenceMatcher(None, "".join(want), "".join(got)).ratio())
                if best is None or score > best[0]:
                    best = (score, start, end)
        if not best or best[0] < MATCH_FLOOR:
            print(f"  UNMATCHED (skipped): {line}")
            continue
        score, start, end = best
        t_in, t_out = words[start][0] - LEAD_IN, words[end - 1][1]
        if t_out - t_in < MIN_DUR:
            t_out = t_in + MIN_DUR
        cues.append([max(0.0, t_in), t_out, line, score])
        cursor = end

    # One line on screen at a time: a cue ends where the next begins.
    for i in range(len(cues) - 1):
        cues[i][1] = min(cues[i][1], cues[i + 1][0])
    return cues


def front_padding(cards_path: str) -> float:
    """Seconds of bookend before BODY. READ from the cards, never typed — it stays
    right when a beat length changes."""
    manifest = json.load(open(cards_path, encoding="utf-8"))
    blocks = {b["id"]: b for b in manifest["blocks"]}
    total = 0.0
    for element in manifest["order"]:
        if element == "BODY":
            break
        total += float(blocks[element]["seconds"])
    return round(total, 3)


def ts(seconds: float) -> str:
    h = int(seconds // 3600)
    m = int(seconds % 3600 // 60)
    return f"{h}:{m:02d}:{seconds % 60:05.2f}"


def main() -> None:
    ap = argparse.ArgumentParser()
    ap.add_argument("--lyrics", required=True)
    ap.add_argument("--transcript", required=True, help="whisper JSON WITH word timings")
    ap.add_argument("--out", required=True)
    ap.add_argument("--play-res", default="720x1280")
    ap.add_argument("--font", default="Optima")
    ap.add_argument("--font-file", default="", help="measure with this file explicitly")
    ap.add_argument("--size", type=int, default=46)
    ap.add_argument("--margin", type=int, default=40)
    ap.add_argument("--outline", type=int, default=3)
    ap.add_argument("--max-lines", type=int, default=2)
    ap.add_argument("--offset", type=float, default=0.0)
    ap.add_argument("--offset-from-cards", default="")
    args = ap.parse_args()

    try:
        play_x, play_y = (int(v) for v in args.play_res.lower().split("x"))
    except ValueError:
        die(f"--play-res must look like 720x1280, got {args.play_res!r}")

    if args.offset_from_cards:
        args.offset = front_padding(args.offset_from_cards)

    lines = lyric_lines(args.lyrics)
    if not lines:
        die(f"{args.lyrics} has no lyric lines")

    cues = time_lines(lines, song_words(args.transcript))
    if not cues:
        die("no lyric line could be matched to the transcript")

    ruler = Ruler(args.font, args.size, args.font_file or None)
    # The outline is drawn OUTSIDE the advance width, on both sides.
    usable = play_x - 2 * args.margin - 2 * args.outline

    rendered, overflow = [], []
    for t_in, t_out, text, score in cues:
        wrapped, fits = wrap(text, ruler, usable, args.max_lines)
        if not fits:
            overflow.append((text, max(ruler.width(line) for line in wrapped)))
        rendered.append((t_in + args.offset, t_out + args.offset, wrapped, score))

    if overflow:
        print(f"line_subs: REFUSED — {len(overflow)} cue(s) cannot fit {usable:.0f}px "
              f"at {args.font} {args.size} in {args.max_lines} line(s):", file=sys.stderr)
        for text, width in overflow:
            print(f"  {width:6.0f}px  {text}", file=sys.stderr)
        print("  Reduce --size, raise --max-lines, or shorten the line. Nothing was "
              "written — a caption clipped off both edges is what this prevents.",
              file=sys.stderr)
        raise SystemExit(5)

    head = (f"[Script Info]\nScriptType: v4.00+\nPlayResX: {play_x}\nPlayResY: {play_y}\n"
            # WrapStyle 0 keeps libass's own smart wrap as a backstop under the \N breaks.
            "WrapStyle: 0\n\n"
            "[V4+ Styles]\nFormat: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, "
            "OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, "
            "Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, "
            "MarginV, Encoding\n"
            f"Style: Song,{args.font},{args.size},&H00FFFFFF,&H00FFFFFF,&H00201408,&H90000000,"
            f"-1,0,0,0,100,100,0,0,1,{args.outline},2,2,{args.margin},{args.margin},96,1\n\n"
            "[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, "
            "Effect, Text\n")
    with open(args.out, "w", encoding="utf-8") as handle:
        handle.write(head)
        for t_in, t_out, wrapped, _ in rendered:
            text = ASS_BREAK.join(wrapped)      # \N is ASS's forced line break
            handle.write(f"Dialogue: 0,{ts(t_in)},{ts(t_out)},Song,,0,0,0,,{text}\n")

    widest = max((max(ruler.width(l) for l in w), " / ".join(w)) for _, _, w, _ in rendered)
    weakest = min(rendered, key=lambda c: c[3])
    print(f"line_subs: {len(rendered)} cues, one lyric line each -> {args.out}")
    print(f"  measured with {ruler.source}; usable {usable:.0f}px of {play_x}px")
    print(f"  widest line {widest[0]:.0f}px: {widest[1]}")
    print(f"  weakest match {weakest[3]:.2f}: {' / '.join(weakest[2])}")
    if args.offset:
        print(f"  offset {args.offset:+.3f}s")


if __name__ == "__main__":
    main()
