#!/usr/bin/env python3
"""vocal_brief.py — what is actually SUNG inside each window, from a word-level
transcript aligned to the lyric sheet; the per-window truth the prompt must follow.

THE DEFECT THIS FIXES (operator, 2026-08-22): prompts are composed per STYLE and reused
verbatim for every window of that style, so a window that is mostly instrumental was
told "rapping directly to camera, mouth shaping the lyrics" for all 13 seconds — and the
model invented a vocal to fill it. "You are not listening to the audio. W01 has not much
vocals and you're telling it to do a rap video, so it's making it up."

WHAT THIS PRODUCES. For every window in the plan:
  * the lyric lines sung inside it, with absolute and window-relative times, WHO sings
    them (from the sheet's tags: Male / Female / Both / Duet) and HOW (rapped / sung);
  * the silent spans inside the window (no words, >= --min-silence);
  * vocal coverage, and a mode: `synced` (send the voice, direct the mouth line by
    line) or `shot-led` (coverage below --shot-led-below: send NO voice, lips closed).
make_plan.py --vocal-brief consumes it; the contract page shows it per window.

ALIGNMENT. The transcript is whisper in the song's OWN language (Devanagari for a Hindi
or Hinglish track — forcing English translates the words and loses them). Words are
transliterated to Latin and matched to the romanised lyric lines IN ORDER (monotone), so
a repeated hook line lands on its own repeat. A line that cannot be matched is reported
as UNHEARD rather than guessed — the review page shows exactly which.

Usage:
  vocal_brief.py --lyrics references/lyrics.txt --transcript build/transcript-hi.json \
                 --plan build/plan.json --out build/vocal-brief.json \
                 [--html build/vocal-brief.html] [--voice-dir build/voice]
"""
from __future__ import annotations

import argparse
import difflib
import html
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 re
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from lane_nav import inject_nav  # noqa: E402
from lane_page import page as shell  # noqa: E402

# --- Devanagari -> Latin, just enough for fuzzy matching against romanised lyrics -----
_V = {"अ": "a", "आ": "aa", "इ": "i", "ई": "ee", "उ": "u", "ऊ": "oo", "ऋ": "ri", "ए": "e",
      "ऐ": "ai", "ओ": "o", "औ": "au", "ऑ": "o", "ऍ": "e"}
_M = {"ा": "aa", "ि": "i", "ी": "ee", "ु": "u", "ू": "oo", "ृ": "ri", "े": "e", "ै": "ai",
      "ो": "o", "ौ": "au", "ॉ": "o", "ॅ": "e", "ं": "n", "ँ": "n", "ः": "h", "्": ""}
_C = {"क": "k", "ख": "kh", "ग": "g", "घ": "gh", "ङ": "ng", "च": "ch", "छ": "chh", "ज": "j",
      "झ": "jh", "ञ": "ny", "ट": "t", "ठ": "th", "ड": "d", "ढ": "dh", "ण": "n", "त": "t",
      "थ": "th", "द": "d", "ध": "dh", "न": "n", "प": "p", "फ": "ph", "ब": "b", "भ": "bh",
      "म": "m", "य": "y", "र": "r", "ल": "l", "व": "v", "श": "sh", "ष": "sh", "स": "s",
      "ह": "h", "क़": "q", "ख़": "kh", "ग़": "g", "ज़": "z", "ड़": "r", "ढ़": "rh", "फ़": "f", "य़": "y"}
_NUKTA = "़"
MAX_INTRA_LINE_GAP_S = 2.0   # default; --max-intra-gap (pack VOCAL_BRIEF_MAX_INTRA_GAP_S) raises it
                             # for a song that BREATHES mid-line. The Hanuman Chalisa holds 2.2 s
                             # between the halves of a chaupai, so no candidate span could cover a
                             # whole line: line 4 matched its second half at ratio 0.51 and its
                             # window opened on 3.9 s of silence (film #3, 2026-09-03). Keep it well
                             # under the song's real instrumental breaks (5.0 s there) so a break
                             # still splits lines.


def transliterate(word: str) -> str:
    out, i, chars = [], 0, list(word)
    while i < len(chars):
        ch = chars[i]
        nxt = chars[i + 1] if i + 1 < len(chars) else ""
        if ch in _V:
            out.append(_V[ch]); i += 1; continue
        if ch in _C or (ch + nxt) in _C:
            key = ch + nxt if (ch + nxt) in _C else ch
            i += len(key)
            base = _C[key]
            nxt = chars[i] if i < len(chars) else ""
            if nxt == _NUKTA:
                i += 1; nxt = chars[i] if i < len(chars) else ""
            if nxt in _M:
                out.append(base + _M[nxt]); i += 1
            elif nxt == "":
                out.append(base)          # word-final consonant: no inherent vowel
            else:
                out.append(base + "a")    # inherent vowel
            continue
        if ch in _M:
            out.append(_M[ch]); i += 1; continue
        if ch.isalpha():
            out.append(ch.lower())
        i += 1
    return re.sub(r"[^a-z]", "", "".join(out))


_ONES = ["zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine", "ten",
         "eleven", "twelve", "thirteen", "fourteen", "fifteen", "sixteen", "seventeen",
         "eighteen", "nineteen"]
_TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety"]


def _num_words(n: int) -> str:
    """0..999999 in the words a singer says (whisper writes '300,000'; the sheet says
    'three hundred thousand'). Plain, no 'and'."""
    if n < 20:
        return _ONES[n]
    if n < 100:
        return _TENS[n // 10] + ("" if n % 10 == 0 else " " + _ONES[n % 10])
    if n < 1000:
        return _ONES[n // 100] + " hundred" + ("" if n % 100 == 0 else " " + _num_words(n % 100))
    return _num_words(n // 1000) + " thousand" + ("" if n % 1000 == 0 else " " + _num_words(n % 1000))


def norm_latin(s: str) -> str:
    s = s.lower()
    # Digits are sung as words. Whisper writes "300,000" and "191"; the sheet says
    # "three hundred thousand" and "a hundred ninety-one" — expanded here so the two meet.
    s = re.sub(r"\d[\d,]*", lambda m: " " + _num_words(int(m.group(0).replace(",", "")[:6] or 0)) + " ", s)
    s = re.sub(r"[^a-z ]", "", s)
    # collapse common romanisation variants so 'chup'/'chhup', 'kadam'/'kadham' meet
    s = re.sub(r"hh", "h", s)
    s = re.sub(r"aa", "a", s)
    s = re.sub(r"ee", "i", s)
    s = re.sub(r"oo", "u", s)
    s = re.sub(r"w", "v", s)
    s = re.sub(r"ph", "f", s)
    s = re.sub(r"(.)\1", r"\1", s)
    return re.sub(r" +", " ", s).strip()


# --- the lyric sheet ------------------------------------------------------------------
TAG_RE = re.compile(r"^\s*\[([^\]]+)\]\s*$")


def singer_voice(v) -> str:
    """A singers.json voice the sheet yields to: male/female/both, or a performer LETTER
    (a/b, exact lowercase — written by a letter anchor or an operator correction). An
    unanchored diarize run names its clusters "A"/"B" arbitrarily; those return "" so
    the sheet keeps ruling."""
    v = str(v or "")
    return v if v in ("male", "female", "both", "a", "b") else ""


def voice_of(tag: str) -> tuple[str, str]:
    """(who, how) from a section tag like '[Verse 2 - Male]' / '[Bridge - Duet, slow]'."""
    t = tag.lower()
    # A PERFORMER LETTER. Two singers of one gender (Baby Yeh Dosti: two boys) cannot be
    # told apart by male/female, so the sheet names the performer: '[Verse 1a - A]' and
    # '[Verse 1b - B]' — A is PORTRAIT, B is PORTRAIT_2 (the letters of the style
    # register's `performer`). '- Both' stays a unison; the letter must be the whole
    # token after the dash ('- A' or '- A, chant'), so 'Both' never reads as B.
    lm = re.search(r"-\s*([ab])\s*(?:,|$)", t)
    who = (lm.group(1) if lm else
           "both" if "both" in t else "duet" if "duet" in t else
           "female" if "female" in t else "male" if "male" in t else "lead")
    # `chant` — a repeated word the model cannot land on the beat (740 ms spread on Baby
    # Nimbooda's "nimbooda x3"; film #3 sees 450-480 ms on every chanted verse while sung
    # melody lands at 50-70 ms). make_plan renders such a window as a DANCE shot: no
    # lip-sync, the record's own vocal over it.
    how = ("chant" if re.search(r"-\s*[a-z]+\s*,\s*chant\b", t) else      # the MODIFIER '[… - Female, chant]', never a section name
           "sung softly" if "duet" in t or "slow" in t else
           "rapped" if who == "male" and "hook" not in t else "sung")
    return who, how


def parse_lyrics(path: str) -> list[dict]:
    lines, who, how, tag = [], "lead", "sung", ""
    for raw in open(path, encoding="utf-8"):
        raw = raw.strip()
        if not raw or raw.startswith("#"):
            # a `#` line is a NOTE, not a lyric: a sheet's provenance header was parsed as
            # eight unheard lines (Baby Yeh Dosti, 2026-09-06)
            continue
        m = TAG_RE.match(raw)
        if m:
            tag = m.group(1); who, how = voice_of(tag); continue
        text = re.sub(r"\([^)]*\)", "", raw).strip()      # (Dav!) ad-libs are not the line
        adlibs = [a.strip("!? ") for a in re.findall(r"\(([^)]*)\)", raw)]
        if adlibs:
            # A SHOUTED AD-LIB IS ITS OWN EVENT. "(Dav!) (Amisha!) do kadam" is sung as a
            # shout a beat BEFORE the line; quoting it inside the line put the names
            # 1.5 s late and the shout itself into a "lips closed" gap (contract audit,
            # 2026-08-22). It gets its own line to place; `host` links it to the line it
            # precedes so an unheard shout can still be seated just before it.
            lines.append({"text": " ".join(f"({a}!)" for a in adlibs), "match": norm_latin(" ".join(adlibs)),
                          "who": who, "how": "shouted", "tag": tag, "adlib": True})
        if text:
            lines.append({"text": text, "match": norm_latin(text), "who": who, "how": how, "tag": tag})
    return lines


# --- the transcript -------------------------------------------------------------------
def load_words(path: str) -> list[dict]:
    d = json.load(open(path, encoding="utf-8"))
    words = []
    for seg in d.get("segments", []):
        for w in seg.get("words", []):
            raw = w.get("word", "").strip()
            if not raw:
                continue
            if re.fullmatch(r",\d{3}", raw) and words and re.fullmatch(r"\d{1,3}", words[-1]["raw"]):
                # whisper wrote "300" then ",000": one number, sung as one phrase
                words[-1]["raw"] += raw
                words[-1]["t1"] = float(w["end"])
                words[-1]["lat"] = norm_latin(words[-1]["raw"])
                continue
            lat = transliterate(raw) if re.search(r"[ऀ-ॿ]", raw) else norm_latin(raw)
            words.append({"t0": float(w["start"]), "t1": float(w["end"]), "raw": raw,
                          "lat": norm_latin(lat)})
    return [w for w in words if w["lat"]]


LINE_SKIP_PENALTY_PER_WORD = 0.02
FREE_SKIPPED_WORDS = 2

# A fill word this close to a base word is the same word heard twice (or the same
# stretch heard differently): the base wins. Wider, and the first word after a base
# line's end is lost ("Pairon" at 80.0 s, 1.2 s after "…neeche" at 78.8 s).
FILL_DEDUP_S = 1.0


def load_word_list(path: str) -> list[dict]:
    """Words from transcribe_clips' {"words": [{"t", "e", "w"}]} shape (song-words.json), in the
    aligner's form. A MEASURED end (`e` with eFrom "stem" or "gemini" — `word_ends.py`) is
    the word's end. Whisper's own `e` is NOT used: whisper tiles a word's end to the next
    onset (377 of 428 words on a real stem), so it would stretch a fill word across an
    instrumental gap and lengthen the render; such a word keeps the 0.4 s rule, exactly as
    a schema-1 entry does, so a pack without WORD_ENDS is byte-identical to before."""
    d = json.load(open(path, encoding="utf-8"))
    ws = d.get("words") if isinstance(d, dict) else d
    out = []
    for w in ws or []:
        raw = str(w.get("w", w.get("word", ""))).strip()
        if not raw:
            continue
        t0 = float(w.get("t", w.get("start", 0.0)))
        t1 = w.get("t1", w.get("end"))
        if t1 is None and w.get("eFrom") in ("stem", "gemini") and w.get("e") is not None:
            t1 = w["e"]                                   # a measured end, not whisper's tiled one
        t1 = max(float(t1), t0) if t1 is not None else t0 + 0.4
        lat = transliterate(raw) if re.search(r"[ऀ-ॿ]", raw) else norm_latin(raw)
        out.append({"t0": t0, "t1": t1, "raw": raw, "lat": norm_latin(lat)})
    return [w for w in out if w["lat"]]


def merge_word_streams(base: list[dict], fill: list[dict], dedup_s: float = FILL_DEDUP_S) -> list[dict]:
    """The base transcript everywhere it heard something; the fill transcript in its
    silences. Two whisper passes over one kids' song (Baby Ram & Sita, 2026-09-02): the
    sheet-primed pass heard 110 words and NOTHING in 5-26 s, 80-103 s or 109-116 s — an
    opening hook, half a hook plus the bridge, and the final hook's first lines — while
    the unprimed word pass heard those (171 words) but drifted 4 s on the verse's first
    line. The takes cut from the base's placements sang its words at its times (w03,
    w11), so the base is right where it heard; the fill is trusted only where the base
    heard nothing within dedup_s. Pure; the result is sorted by onset."""
    keep = list(base)
    starts = sorted(w["t0"] for w in base)
    import bisect
    for w in fill:
        i = bisect.bisect_left(starts, w["t0"])
        near = [starts[k] for k in (i - 1, i) if 0 <= k < len(starts)]
        if any(abs(w["t0"] - t) < dedup_s for t in near):
            continue
        keep.append(dict(w, fill=True))
    keep.sort(key=lambda w: (w["t0"], w["t1"]))
    return keep


def align(lines: list[dict], words: list[dict], min_ratio: float) -> list[dict]:
    """Monotone: each line takes the best contiguous word span after the previous line.

    NEAR THE PREVIOUS LINE, NOT ANYWHERE AFTER IT. The sheet and the track run in the
    same order, so the next line's words are the next words sung — a line that whisper
    garbled has its true span right there, scoring 0.5, while the same words at the
    hook's next REPEAT score 0.85 forty seconds later. The unbounded search took the
    repeat, the cursor jumped past it, and the sixteen lines in between came back
    UNHEARD (the New Era film, 2026-08-29: whisper dropped "a hundred ninety-one" at
    18 s, the line landed at 44.7 s, 8/24 lines placed). So a candidate pays
    LINE_SKIP_PENALTY_PER_WORD for every transcript WORD it skips past (beyond
    FREE_SKIPPED_WORDS, a stray ad-lib) — skipping sung words is the sin; an
    instrumental break of any length costs nothing. A line with no candidate left
    above min_ratio is UNHEARD and the next line searches from the same place.
    """
    cursor = 0
    for line in lines:
        if line.get("adlib"):
            line.update({"start": None, "end": None, "heard": "", "ratio": 0.0})
            continue          # seated after alignment, never matched (too short: "Amisha" ~ "chashma")
        target = line["match"].replace(" ", "")
        n_words = max(2, len(line["match"].split()))
        best = (0.0, None, None)
        for i in range(cursor, len(words)):
            for span in range(max(1, n_words - 2), n_words + 4):
                j = i + span
                if j > len(words):
                    break
                # A sung line has no silence inside it. A span bridging a gap longer
                # than MAX_INTRA_LINE_GAP_S is a stray ad-lib glued to the real line —
                # the first run matched "अगा … Entry pe sab chup" as ONE line 4.3–25.5s.
                if any(words[k + 1]["t0"] - words[k]["t1"] > MAX_INTRA_LINE_GAP_S
                       for k in range(i, j - 1)):
                    continue
                cand = "".join(w["lat"] for w in words[i:j])
                r = difflib.SequenceMatcher(None, target, cand).ratio()
                # A weak match far past the cursor is a different line's words. The
                # same film: "Three hundred thousand pulled a seat up there" (whisper
                # heard none of it at 35 s) scored 0.50 on "A hundred ninety-one and
                # they" twenty-five words later, and hook 2 fell into the hole.
                skipped = max(0, i - cursor - FREE_SKIPPED_WORDS)
                adj = r - LINE_SKIP_PENALTY_PER_WORD * skipped
                if adj > best[0]:
                    best = (adj, i, j, r)
            # A strong match ends the search — but only once the scan is a couple of
            # seconds past it, so a 0.89 on "c up new era new" cannot pre-empt the 1.00
            # on "new era new era" that starts one word later.
            if best[0] > 0.85 and words[i]["t0"] > words[best[1]]["t0"] + 2.0:
                break
        if best[1] is not None and best[0] >= min_ratio:
            i, j = best[1], best[2]
            line.update({"start": round(words[i]["t0"], 2), "end": round(words[j - 1]["t1"], 2),
                         "heard": " ".join(w["raw"] for w in words[i:j]), "ratio": round(best[3], 2)})
            cursor = j
        else:
            line.update({"start": None, "end": None, "heard": "", "ratio": round(best[0], 2)})
    return lines


def seat_adlibs(lines: list[dict], words: list[dict] | None = None, before: float = 1.4) -> None:
    """An unheard shouted ad-lib sits in the beat before its host line, if that beat is free.

    Whisper in the song's language mishears a shouted name ("Dav! Amisha!" came back as
    "दूप में"), so the aligner leaves it unplaced; the energy map still shows voice
    there. Seat it in the `before` seconds ahead of the host line's start unless another
    placed line already covers that time — then leave it UNHEARD rather than guess.
    """
    for i, ln in enumerate(lines):
        if not ln.get("adlib") or ln.get("start") is not None:
            continue
        host = next((x for x in lines[i + 1:] if not x.get("adlib")), None)
        if not host or host.get("start") is None:
            continue
        lo, hi = host["start"] - 2.5, host["start"] - 0.05
        placed = [x for x in lines if x is not ln and x.get("start") is not None]
        free = lambda t0, t1: not any(x["start"] < t1 and x["end"] > t0 for x in placed)  # noqa: E731
        # words the aligner left unclaimed in the beat before the host line = the shout
        loose = [w for w in (words or []) if lo <= w["t0"] < hi and free(w["t0"], w["t1"])]
        if loose:
            ln.update({"start": round(loose[0]["t0"], 2), "end": round(loose[-1]["t1"], 2),
                       "heard": " ".join(w["raw"] for w in loose), "ratio": 0.0})
            continue
        a, b = round(host["start"] - before, 2), round(host["start"] - 0.05, 2)
        if a >= 0 and free(a, b):
            ln.update({"start": a, "end": b, "heard": "(seated before its line — not transcribed)",
                       "ratio": 0.0})


# --- who actually sings each line: the TRACK decides, not the sheet -------------------
MALE_F0_HZ = 185.0        # median fundamental below this reads as the male voice


def detect_voices(song: str, lines: list[dict], ffmpeg: str = "ffmpeg") -> None:
    """Override an ambiguous tag (both/duet/lead) with the voice heard in the line's span.

    The first couple film tagged its hook "[Hook - Both]"; the take split it — her voice
    on lines 1-2, his on 3-4 — and the brief put his face on her lines and hers on his.
    A per-line pitch median (band-passed autocorrelation on the mono mix) separates the
    two voices cleanly on this track: ~135-155 Hz him, ~245-370 Hz her. An explicit
    male/female tag is kept unless the track disagrees by a wide margin, and then the
    override is reported so the operator sees it.
    """
    try:
        import numpy as np
        import subprocess
        try:
            import scipy.signal as ss
        except ImportError:
            ss = None
    except ImportError:
        return
    sr = 16000
    raw = subprocess.run([ffmpeg, "-v", "error", "-i", song, "-ac", "1", "-ar", str(sr), "-f", "f32le", "-"],
                         capture_output=True).stdout
    if not raw:
        return
    m = np.frombuffer(raw, dtype=np.float32)
    if ss is not None:
        b, a = ss.butter(4, [80 / (sr / 2), 1000 / (sr / 2)], btype="band")
        m = ss.lfilter(b, a, m)
    lo, hi = int(sr / 400), int(sr / 80)
    for ln in lines:
        if ln.get("start") is None or ln.get("adlib"):
            continue
        seg = m[int(ln["start"] * sr):int(ln["end"] * sr)]
        vals = []
        for k in range(0, len(seg) - 2048, 512):
            w = seg[k:k + 2048] * np.hanning(2048)
            if (w ** 2).mean() < 1e-5:
                continue
            ac = np.correlate(w, w, "full")[2047:]
            ac = ac / (ac[0] + 1e-9)
            i = lo + int(np.argmax(ac[lo:hi]))
            if ac[i] > 0.5:
                vals.append(sr / i)
        if len(vals) < 12:
            continue
        v = np.array(vals)
        low = float((v < MALE_F0_HZ).mean())
        heard = "male" if low > 0.65 else "female" if low < 0.35 else "both"
        ln["heardVoice"] = heard
        ln["f0Hz"] = round(float(np.median(v)), 1)
        tag = ln["who"]
        if tag in ("a", "b"):
            # a performer letter is not a gender: a pitch median can neither confirm nor
            # dispute it (two boys, Baby Yeh Dosti)
            ln["whoFrom"] = f"sheet (performer {tag.upper()}); pitch is not a test of it ({heard}, {ln['f0Hz']} Hz)"
            continue
        # THE SHEET RULES. THE DETECTOR ONLY WARNS. On 2026-08-22 this detector read the
        # hook's first two lines at ~250 Hz, called them "female", and put her face on
        # HIS vocal for seven draws; the operator heard it in one play ("this is men's
        # vocal"). A pitch median cannot tell an octave error or a unison from a voice.
        # The lyric sheet is the author's statement of who sings; it is overridden only
        # by the operator (SINGER_DETECT=1 restores the old behaviour, logged).
        override = os.environ.get("SINGER_DETECT") == "1"
        disagree = heard in ("male", "female") and heard != tag
        if override and tag in ("both", "duet", "lead") and heard in ("male", "female"):
            ln["who"], ln["whoFrom"] = heard, f"track ({ln['f0Hz']} Hz; sheet said {tag}; SINGER_DETECT=1)"
        elif override and tag in ("male", "female") and disagree and (low > 0.85 or low < 0.15):
            ln["who"], ln["whoFrom"] = heard, f"track ({ln['f0Hz']} Hz; sheet said {tag} — OVERRIDDEN; SINGER_DETECT=1)"
        elif disagree:
            ln["whoFrom"] = f"sheet ({tag}); track pitch disagrees ({heard}, {ln['f0Hz']} Hz) — ADVISORY, not applied"
        else:
            ln["whoFrom"] = f"sheet, track agrees ({ln['f0Hz']} Hz)"


# --- per window -----------------------------------------------------------------------
def brief_windows(plan: dict, lines: list[dict], min_silence: float, shot_led_below: float) -> list[dict]:
    out = []
    for job in plan["jobs"]:
        s0 = float(job["startSec"]); s1 = s0 + float(job["seconds"])
        # a line that begins in the tail slack (past the covered end) is the NEXT
        # window's — silenced in the slice, so it is a tail fragment whatever its length
        covered_end = s1 - float(job.get("tailSec") or 0.0)
        spans = []
        for ln in lines:
            if ln["start"] is None or ln["end"] <= s0 or ln["start"] >= s1:
                continue
            a, b = max(ln["start"], s0), min(ln["end"], s1)
            if b - a < 0.15:
                # float slop: a line ending ON the window edge produced a 0.00 s span
                # ("Entry pe sab chup" on w01), and a zero-length span still directs a mouth
                continue
            spans.append({"start": round(a - s0, 2), "end": round(b - s0, 2), "absStart": round(a, 2),
                          "text": ln["text"], "who": ln["who"], "how": ln["how"],
                          "partial": bool(ln["start"] < s0 or ln["end"] > s1),
                          # THE TAIL OF A LINE THAT BEGAN BEFORE THE WINDOW. With render
                          # slack the head second is often the end of the previous line;
                          # directing "mouth shapes exactly <whole line>" for 0.76 s made
                          # the model sing that line first and land the real one a phrase
                          # late (w03, 2026-08-23, three of four draws). A head fragment is
                          # lips-closed for the face and not the judge's to measure.
                          # ... but only when the line BEGAN well before the window and
                          # most of it lies outside: a line that starts 10 ms before the
                          # edge (w02's "Entry pe sab chup" at 20.99 for a 21.0 window)
                          # is this window's first line, not a tail.
                          "partialHead": bool(ln["start"] < s0 - 0.25
                                              and (b - a) < 0.6 * (ln["end"] - ln["start"])),
                          # ... and the mirror: a line that BEGINS in the render's last
                          # second and mostly lies beyond it ("Sunehri chhat…" at 68.26
                          # in a render ending 69.0 — the operator: "it doesn't finish the
                          # song"). It belongs to the next window; here the shot merely
                          # ends as the line begins.
                          "partialTail": bool((ln["end"] > s1 + 0.25
                                               and (b - a) < 0.6 * (ln["end"] - ln["start"]))
                                              or ln["start"] >= covered_end - 0.15)})
        spans.sort(key=lambda x: x["start"])
        covered = sum(x["end"] - x["start"] for x in spans)
        coverage = round(covered / (s1 - s0), 3)
        silences, t = [], 0.0
        for x in spans:
            if x["start"] - t >= min_silence:
                silences.append({"start": round(t, 2), "end": x["start"]})
            t = max(t, x["end"])
        if (s1 - s0) - t >= min_silence:
            silences.append({"start": round(t, 2), "end": round(s1 - s0, 2)})
        whos = {x["who"] for x in spans}
        out.append({"id": job["id"], "startSec": s0, "seconds": float(job["seconds"]),
                    "coverage": coverage, "mode": "synced" if coverage >= shot_led_below else "shot-led",
                    "voices": sorted(whos), "spans": spans, "silences": silences})
    return out


def write_html(path: str, lines: list[dict], windows: list[dict], voice_dir: str | None,
               sung_past: dict | None = None) -> None:
    unheard = [l for l in lines if l["start"] is None]
    sheet = "".join(
        f'<tr><td>{html.escape(l["tag"])}</td><td>{html.escape(l["text"])}</td>'
        f'<td>{l["who"]} · {l["how"]}<br><small>{html.escape(l.get("whoFrom", ""))}</small></td>'
        f'<td>{"" if l["start"] is None else f"{l["start"]:.2f}–{l["end"]:.2f}s"}</td>'
        f'<td class="{"bad" if l["start"] is None else ""}">{html.escape(l["heard"]) or "UNHEARD"}'
        f' <small>({l["ratio"]})</small></td></tr>' for l in lines)
    if sung_past:
        # THE SONG SINGS PAST THE SHEET — a red row at the foot of the sheet, where the
        # operator already looks, not a line in a log nobody reads (film #3).
        sheet += (f'<tr class="bad"><td>—</td><td class="bad">SUNG PAST THE SHEET: {sung_past["seconds"]:.1f}s of singing '
                  f'after the last placed line — {html.escape(sung_past["advice"])}</td>'
                  f'<td>{sung_past["inSheet"]}/{sung_past["words"]} words in the sheet</td>'
                  f'<td>{sung_past["from"]:.2f}–{sung_past["to"]:.2f}s</td>'
                  f'<td class="bad">{html.escape(sung_past["sample"])} …</td></tr>')
    cards = []
    for w in windows:
        audio = ""
        if voice_dir:
            p = os.path.join(voice_dir, f'{w["id"]}.mp4')
            if os.path.isfile(p):
                audio = f'<audio controls preload="none" src="file://{html.escape(os.path.abspath(p))}"></audio>'
        rows = "".join(
            f'<tr><td>{x["start"]:.2f}–{x["end"]:.2f}s</td><td>{x["who"]} · {x["how"]}</td>'
            f'<td>{html.escape(x["text"])}{" <small>(partial)</small>" if x["partial"] else ""}</td></tr>'
            for x in w["spans"]) or '<tr><td colspan=3 class="bad">no words sung in this window</td></tr>'
        sil = ", ".join(f'{s["start"]:.1f}–{s["end"]:.1f}s' for s in w["silences"]) or "none"
        cards.append(f'''<article><h2>{w["id"]} <small>{w["startSec"]:.1f}s +{w["seconds"]:g}s</small>
 <span class="b {w["mode"]}">{w["mode"]} · {w["coverage"]:.0%} sung</span></h2>{audio}
<table>{rows}</table><p class="sil">lips closed: {sil}</p></article>''')
    body = f'''<h2>Lyric sheet → time</h2><table><tr><th>section</th><th>line</th><th>voice</th><th>time</th><th>heard as</th></tr>{sheet}</table>
<h2 style="margin-top:22px">Per window</h2>{"".join(cards)}'''
    doc = shell("Vocal brief — what is actually sung in each window",
                f"word-level transcript in the song's own language, aligned to the lyric sheet in order · "
                f"{len(lines) - len(unheard)}/{len(lines)} lines heard{(' · UNHEARD: ' + str(len(unheard))) if unheard else ''}",
                body, extra_css="table{font-size:13px}td{vertical-align:top}td.bad,.bad{color:var(--danger)}small{color:var(--ink3)}"
                                "article{border:1px solid var(--line);border-radius:10px;padding:14px;margin:14px 0;background:var(--panel)}"
                                "h2{font-size:16px;margin:0 0 8px}.b{font-size:11px;padding:2px 8px;border-radius:10px;background:var(--panel2);margin-left:8px}"
                                ".b.synced{background:#2f6b3a}.b.shot-led{background:#6b4a2f}audio{display:block;width:100%;margin:6px 0 8px}"
                                ".sil{color:var(--ink3);font-size:12.5px;margin:8px 0 0}")
    open(path, "w", encoding="utf-8").write(doc)
    inject_nav(path)


def main() -> None:
    ap = argparse.ArgumentParser()
    ap.add_argument("--lyrics", required=True)
    ap.add_argument("--transcript", required=True, help="whisper JSON with word timestamps, song's own language")
    ap.add_argument("--fill-words", action="append", default=[], metavar="JSON",
                    help="a further word pass ({\"words\": [{t, w}]}, e.g. song-words.json, stem-words.json) "
                         "that fills the transcript's silences — repeatable, applied in order; each fills only "
                         "what the ears before it left silent (merge_word_streams)")
    ap.add_argument("--plan", required=True)
    ap.add_argument("--out", required=True)
    ap.add_argument("--html", default="")
    ap.add_argument("--voice-dir", default="")
    ap.add_argument("--song", default="", help="the track (kept for the slice builder; no longer decides the singer)")
    ap.add_argument("--singers", default="",
                    help="singers.json from singer_diarize.py, VERIFIED BY EAR: who sings each line. "
                         "When present it is the only source of `who`; the sheet's tags are words only")
    ap.add_argument("--min-ratio", type=float, default=0.45)
    ap.add_argument("--max-intra-gap", type=float, default=MAX_INTRA_LINE_GAP_S,
                    help="the longest silence a single sheet line may span (pack "
                         "VOCAL_BRIEF_MAX_INTRA_GAP_S); a slow devotional line breathes longer "
                         "than a rap bar")
    ap.add_argument("--min-silence", type=float, default=1.0)
    ap.add_argument("--shot-led-below", type=float, default=0.30,
                    help="coverage below this sends NO voice: the window is a shot, not a performance")
    args = ap.parse_args()

    words = load_words(args.transcript)
    for fill_path in [f for f in args.fill_words if f and raplib.read_json(f) is not None]:   # empty = absent
        fill = load_word_list(fill_path)
        before = sum(1 for w in words if w.get("fill"))
        words = merge_word_streams(words, fill)
        used = sum(1 for w in words if w.get("fill")) - before
        print(f"vocal_brief: + {used} of {len(fill)} words from {os.path.basename(fill_path)} in the "
              f"silences left so far (--fill-words)", file=sys.stderr)
    globals()["MAX_INTRA_LINE_GAP_S"] = float(args.max_intra_gap)
    lines = align(parse_lyrics(args.lyrics), words, args.min_ratio)
    if any(w.get("fill") for w in words):
        filled = [l for l in lines if l.get("start") is not None
                  and any(w.get("fill") and abs(w["t0"] - l["start"]) < 0.05 for w in words)]
        if filled:
            print("vocal_brief: lines placed from the fill pass: "
                  + ", ".join(f"{l['start']:.1f}s \"{l['text'][:28]}\"" for l in filled), file=sys.stderr)
    seat_adlibs(lines, words)
    # WHO SINGS: the diarizer's answer, verified by the operator (singer_diarize.py →
    # singers.html → his corrections). The pitch detector that used to run here put her
    # face on his vocal for seven draws; it is no longer on the path (detect_voices stays
    # importable for the record, never called). With no singers file the sheet's tags
    # stand, and that is printed so nobody mistakes a guess for a measurement.
    if args.singers and os.path.isfile(args.singers):
        sd = json.load(open(args.singers, encoding="utf-8"))
        by_start = {round(float(r["start"]), 2): r for r in sd.get("lines", []) if r.get("start") is not None}
        applied = 0
        for ln in lines:
            if ln.get("start") is None:
                continue
            r = by_start.get(round(float(ln["start"]), 2))
            # a/b: the diarizer's clusters named from a letter ANCHOR (--anchor 42-50=a) or an
            # operator correction — exact lowercase. An UNANCHORED run names its clusters "A"/"B"
            # arbitrarily, and those must keep falling through so the sheet still rules.
            rv = singer_voice(r.get("voice")) if r else ""
            if r and rv:
                if ln["who"] != rv:
                    print(f"vocal_brief: {ln['start']:.2f}s {rv:6} <- singers.json "
                          f"({'operator' if r.get('by') == 'operator' else 'diarized, verified'}; sheet said {ln['who']}) | {ln['text'][:40]}",
                          file=sys.stderr)
                ln["who"], ln["whoFrom"] = rv, "singers.json"
                applied += 1
        print(f"vocal_brief: singer per line from {args.singers} ({applied} lines)", file=sys.stderr)
    else:
        print("vocal_brief: NO singers.json — the sheet's tags decide who sings (unverified). "
              "Run singer_diarize.py and verify singers.html before rendering.", file=sys.stderr)
    plan = json.load(open(args.plan, encoding="utf-8"))
    windows = brief_windows(plan, lines, args.min_silence, args.shot_led_below)
    placed_ends = [float(l["end"]) for l in lines if l.get("start") is not None]
    sung_past = raplib.sung_past_sheet(words, max(placed_ends) if placed_ends else None,
                                       open(args.lyrics, encoding="utf-8").read())
    doc = {"schemaVersion": 1, "lyrics": args.lyrics, "transcript": args.transcript,
           "lines": lines, "windows": windows, "sungPastSheet": sung_past}
    json.dump(doc, open(args.out, "w", encoding="utf-8"), indent=2)
    if args.html:
        write_html(args.html, lines, windows, args.voice_dir or None, sung_past)
    if sung_past:
        print(f"vocal_brief: ADVISORY — the song sings {sung_past['seconds']:.1f}s past the sheet's "
              f"last placed line ({sung_past['from']:.1f}–{sung_past['to']:.1f}s; "
              f"{sung_past['inSheet']}/{sung_past['words']} tail words are in the sheet): "
              f"{sung_past['advice']}", file=sys.stderr)
    unheard = [l["text"] for l in lines if l["start"] is None]
    print(f"vocal_brief: {len(lines) - len(unheard)}/{len(lines)} lyric lines placed in time"
          + (f"; UNHEARD: {unheard}" if unheard else ""), file=sys.stderr)
    for w in windows:
        print(f"  {w['id']}  {w['mode']:<8} {w['coverage']:>4.0%} sung  "
              f"{', '.join(w['voices']) or '-'}  silent: "
              + (", ".join(f"{s['start']:.1f}-{s['end']:.1f}" for s in w["silences"]) or "none"),
              file=sys.stderr)


if __name__ == "__main__":
    main()
