#!/usr/bin/env python3
"""vocal_map.py — measure where the song actually has a lead vocal.

WHY THIS EXISTS. A sync score answers "does this take follow the vocal". It can
never answer the question that shipped a film twice with a visible defect: "is he
MOUTHING when the song has no words?" On Great Indian Summer the performer was
rapping to camera through an instrumental at 0:18, through a two-second hole at
3:07, and through a drums-only outro at 3:14. Every one of those windows passed
`check_sync.py`, because there was nothing there for it to disagree with.

WHY NOT THE TRANSCRIPT. Whisper merges and pads segments on a sung track. On the
same film it reported a window that is audibly instrumental as **100% covered by
lyrics**. Asked for the gaps, it produced four; the signal shows more, and puts
them in different places. The transcript tells you what was sung, not when.

WHAT THIS MEASURES INSTEAD. A lead vocal is mixed centre, so it survives in the
mid channel (L+R) and largely cancels in the side channel (L-R). Comparing the
two inside the vocal band gives a per-moment "is someone singing" score that owes
nothing to a transcriber.

    centre_excess = max(rms(mid_band) - rms(side_band), 0)

TWO THINGS THAT MAKE THIS SILENTLY WRONG, both guarded below:

  * A MONO SOURCE. mid == side, so centre_excess is ~0 everywhere and the whole
    song reads as instrumental. `build/hook.wav` IS mono — it is a downmix — so
    the obvious file to reach for is the one that produces confident nonsense.
    Refused outright. Point this at the stereo original.
  * A FIXED THRESHOLD. The score is normalised per track, so a cutoff tuned on
    one song means nothing on the next. Derived per song here — see
    `derive_threshold`, and note that the obvious choice (Otsu) is wrong.

THIS MEASURES VOCAL ENERGY, NOT LYRICS. A held note or an "ooh" scores like a
sung word, and reverb keeps the score up past the last syllable. So the final cut
point takes the EARLIER of the signal's vocal-out and the transcript's last word
end (`--transcript`). Neither source is trusted alone: the transcript padded a
fully instrumental window to 100% coverage, and the signal still read 0.37 over a
drums-only outro.

WHAT IT FEEDS.
  * windows whose vocal coverage is below the threshold are marked SHOT-LED:
    they must be judged on the shot, not on a sync number they cannot earn, and
    they need a take where the mouth is not readable.
  * `cutOut` — snap the final cut there. On the reference film the grid put it at
    192.0s while the last lyric ended at 190.96, so the last second of a window
    hung over a drums-only outro with the performer still mouthing.

Usage:
  vocal_map.py --song <stereo track> [--plan build/plan.json]
               [--brief build/vocal-brief.json]   # lines with ends: silences + shotLed
               [--transcript build/transcript.json]
               [--out build/vocal-map.json] [--hop 0.25] [--json]

Calibrated against Great Indian Summer: finds the 17.25-19.50s hole behind the
0:18 defect, and puts the cut at 190.96s where it was placed by hand.

Exit 0 = written. Non-zero = the source cannot be measured (mono / silent side).
"""
from __future__ import annotations

import argparse
import json
import os
import re
import subprocess
import sys

import numpy as np

import raplib

SR = 44100
BAND_CENTRE_HZ = 1850   # 300-3400 Hz vocal band expressed as centre/width
BAND_WIDTH_HZ = 3100
DEFAULT_HOP = 0.25
# A stereo file whose side channel is this quiet relative to mid is dual-mono in
# everything but the header, and measures exactly like a true mono downmix.
DUAL_MONO_RATIO = 0.02
# A hallucinated block arrives after a long silence; below this a gap is just a phrase.
HALLUCINATION_GAP_S = 4.0
HALLUCINATION_MARGIN_S = 3.0   # reverb tail past the last sung word still reads as voice

# A SUNG LINE BREAK IS NOT AN INSTRUMENTAL. Word gaps run ~1.0-1.5s between lines all
# through a normal verse — treating those as vocal-free flagged 19 stretches on a song
# with three, and cutting away on every one of them would shred the film. A real break
# is longer. Measured on this song: line breaks 1.02-1.38s, real breaks 2.16/2.66/11.46s.
DEFAULT_MIN_WORD_GAP = 2.0

# ...but a sub-threshold gap is not NOTHING either. A 1.15s gap under an alley closeup
# shipped with the performer mouthing straight through it, and the operator caught it
# on screen (2026-08-24, w03) — the gap was real, just shorter than the auto-cover
# line. Gaps in [SHORT_GAP_MIN, min_word_gap) are therefore RECORDED as `shortGaps`
# (never auto-covered: that would shred the film on every line break) so the cover
# stage can print them as mouthing risks and an operator can cover one explicitly.
SHORT_GAP_MIN = 0.8


def _probe_channels(path: str) -> int:
    out = subprocess.run(
        ["ffprobe", "-v", "error", "-select_streams", "a:0",
         "-show_entries", "stream=channels", "-of", "csv=p=0", path],
        capture_output=True, text=True).stdout.strip()
    try:
        return int(out.splitlines()[0])
    except (ValueError, IndexError):
        return 0


def _channel(path: str, expr: str) -> np.ndarray:
    """One band-limited mono channel built by a pan expression over the source."""
    raw = subprocess.run(
        ["ffmpeg", "-v", "error", "-i", path, "-af",
         f"pan=mono|c0={expr},bandpass=f={BAND_CENTRE_HZ}:width_type=h:w={BAND_WIDTH_HZ}",
         "-ac", "1", "-ar", str(SR), "-f", "s16le", "-"],
        capture_output=True).stdout
    return np.frombuffer(raw, dtype="<i2").astype(np.float64) / 32768.0


def _rms(x: np.ndarray, hop: int) -> np.ndarray:
    n = len(x) // hop
    if n == 0:
        return np.zeros(0)
    return np.sqrt((x[: n * hop].reshape(n, hop) ** 2).mean(axis=1) + 1e-12)


def derive_threshold(scores: np.ndarray, fraction: float = 0.35) -> float:
    """A floor set relative to this track's own typical vocal level.

    A two-class split (Otsu, k-means) is the obvious choice and it is WRONG here,
    measured on a real song: the distribution is not bimodal. A rap track carries
    vocal roughly 90% of its length, so "absent" is a thin tail, not a second
    mode — percentiles on the reference film ran 10%:0.25, 50%:0.58, 90%:0.85, a
    smooth continuum. Otsu split the top of it and declared the whole song
    instrumental.

    So: take the median as "what a vocal sounds like on THIS track" and put the
    floor at a fraction of it. That scales with the song rather than the tuning
    session, which is the property a fixed 0.22 lacked. Calibration on the
    reference film: median 0.582 -> floor 0.204, against measured 0.07 in an
    instrumental hole and 0.58-0.86 under vocal.
    """
    med = float(np.median(scores))
    return max(med * fraction, 0.05)


def vocal_score(path: str, hop_sec: float = DEFAULT_HOP) -> tuple:
    """(times, score 0-1). High = a centre-panned lead vocal is present."""
    mid, side = _channel(path, "0.5*c0+0.5*c1"), _channel(path, "0.5*c0-0.5*c1")
    n = min(len(mid), len(side))
    if n == 0:
        raise SystemExit(f"vocal_map: no audio decoded from {path}")
    hop = int(SR * hop_sec)
    m, s = _rms(mid[:n], hop), _rms(side[:n], hop)
    k = min(len(m), len(s))
    m, s = m[:k], s[:k]

    if s.mean() < m.mean() * DUAL_MONO_RATIO:
        raise SystemExit(
            f"vocal_map: {os.path.basename(path)} has no usable side channel "
            f"(side/mid = {s.mean() / max(m.mean(), 1e-12):.4f}) — it is mono or "
            "dual-mono, so centre-vs-side cannot separate a vocal from the bed. "
            "Point this at the stereo original, not a downmix.")

    centre = np.maximum(m - s, 0.0)
    ref = np.percentile(centre, 97)
    if ref > 0:
        centre = centre / ref
    # deliberately NOT clipped to 1.0 — clipping creates a spike at the top of the
    # histogram that the threshold search then latches onto (see _otsu)
    return np.arange(k) * hop_sec, centre


def stem_score(stem_path: str, hop_sec: float = DEFAULT_HOP) -> tuple:
    """(times, score 0-1) from the SEPARATED VOCAL STEM — the energy map for a song whose
    stereo carries no side information. A 1975 dual-mono recording (Baby Yeh Dosti,
    2026-09-06) has side/mid = 0.0001: centre-vs-side sees nothing, but the stem IS the
    vocal, so its loudness curve stands in for `vocal_score` (same normalisation:
    the 97th percentile is 1.0)."""
    raw = subprocess.run(
        ["ffmpeg", "-v", "error", "-i", stem_path, "-ac", "1", "-ar", str(SR),
         "-f", "s16le", "-"], capture_output=True).stdout
    x = np.frombuffer(raw, dtype="<i2").astype(np.float64) / 32768.0
    if len(x) == 0:
        raise SystemExit(f"vocal_map: no audio decoded from stem {stem_path}")
    hop = int(SR * hop_sec)
    r = _rms(x, hop)
    ref = np.percentile(r, 97)
    if ref > 0:
        r = r / ref
    return np.arange(len(r)) * hop_sec, r


def word_stretches(words: list, song_end: float, min_sec: float) -> list:
    """Vocal-free stretches taken from WORD TIMINGS — the reliable source.

    THE ENERGY MAP CANNOT FIND THESE. It measures vocal ENERGY, and a reverb tail, a
    held note, an "ooh" or a vocal-shaped synth all score like singing. On this film it
    reported `silentStretches: []` and `vocalOut: 111.5` for a song whose last sung word
    is at 98.54s — so the map said "sings all the way through", every window was pinned
    with a performer, and the operator watched a man mouthing over thirteen seconds of
    instrumental outro. Three separate stretches, 18s in all, none of them found.

    `cover_mouthing.py`'s own docstring says "TRUST THE TRANSCRIPT, NOT AN ENERGY MAP,
    for where the vocal actually stops" — and then reads its stretches from this file,
    which was computing them from the energy map. The lesson had been applied to the
    consumer and never to the producer feeding it.

    A gap runs from a word's MEASURED end to the next word's start. Only an `e` from a
    measuring source counts (eFrom "stem" or "gemini", `word_ends.py`): whisper tiles a
    word's end to the next onset (377 of 428 words on a real stem), so its `e` would
    ERASE real gaps — "gansagar" tiled 4.1 s across 3.3 s of silence — while the same
    measurement shows "roop" truly held 3.9 s, which start-to-start had called silence.
    Without a measured end the gap is start-to-start as before: over by one word's
    length, the safe direction (a cutaway a beat too long is invisible, a mouth moving
    to nothing is not), and byte-identical for a pack without WORD_ENDS.
    """
    def end_of(w: dict) -> float:
        e = w.get("e")
        measured = w.get("eFrom") in ("stem", "gemini")
        return max(float(e), float(w["t"])) if (e is not None and measured) else float(w["t"])
    out = []
    for a, b in zip(words, words[1:]):
        gap = float(b["t"]) - end_of(a)
        if gap >= min_sec:
            out.append({"start": round(end_of(a), 2), "end": round(float(b["t"]), 2),
                        "seconds": round(gap, 2), "source": "words"})
    if words and song_end - end_of(words[-1]) >= min_sec:
        out.append({"start": round(end_of(words[-1]), 2), "end": round(song_end, 2),
                    "seconds": round(song_end - end_of(words[-1]), 2),
                    "source": "words"})
    return out


# make_plan/vocal_brief send a window WITHOUT a voice below this coverage; the map must
# draw the same line or select_cut and plan_coherence #12 see two different films.
BRIEF_SHOT_LED_BELOW = 0.30


def brief_stretches(lines: list, song_end: float, min_sec: float) -> list:
    """Vocal-free stretches from the BRIEF's placed lyric lines — the best source of all.

    The brief (`vocal_brief.py`) aligns the lyric SHEET to a transcript in the song's own
    language, so every line has a start AND an end, and a line that is in the sheet
    cannot be a hallucination. Word timings (above) have no ends and are start-to-start;
    the energy map cannot see words at all. So when the brief exists it wins:

        head   — 0 to the first placed line's start
        gaps   — a line's end to the next line's start, when >= min_sec
        tail   — the last placed line's end to the song's end

    Unplaced lines (`start` None — the aligner could not hear them) are skipped rather
    than guessed at. Measured on the Hinglish couple MV: the 20.99s wordless intro that
    the energy map scored as 1.11x vocal comes out as one 20.99s head stretch.
    """
    placed = sorted((float(l["start"]), float(l["end"])) for l in lines
                    if l.get("start") is not None and l.get("end") is not None)
    out = []

    def add(a: float, b: float) -> None:
        if b - a >= min_sec:
            out.append({"start": round(a, 2), "end": round(b, 2),
                        "seconds": round(b - a, 2), "source": "brief"})
    if not placed:
        add(0.0, song_end)
        return out
    add(0.0, placed[0][0])
    for (_, a_end), (b_start, _) in zip(placed, placed[1:]):
        add(a_end, b_start)
    add(placed[-1][1], song_end)
    return out


def brief_window_coverage(brief_windows: list) -> dict:
    """{window id: (coverage, shotLed)} exactly as the brief computed it.

    The brief's `coverage` is sum(spans)/seconds rounded to 3dp and its `mode` is
    `synced` iff coverage >= 0.30 — reproduced here from the same fields so the map
    and the brief cannot disagree at the boundary on their own artifacts."""
    out = {}
    for w in brief_windows:
        secs = float(w.get("seconds") or 0)
        spans = w.get("spans") or []
        cov = round(sum(float(x["end"]) - float(x["start"]) for x in spans) / secs, 3) if secs else 0.0
        out[w["id"]] = (cov, cov < BRIEF_SHOT_LED_BELOW)
    return out


def drop_hallucinated_tail(words: list, lyrics_path: str | None,
                           vocal_out: float | None = None) -> list:
    """Whisper invents words over silence — and they land at the END, where they do most
    harm.

    Measured here: the song's last sung word is "way" at 98.54s, and whisper then emitted
    "thank you for watching" at 110-111s. That pushed `lyricsOut` to 116s, LATER than the
    energy map's 111.5s — so the `min(vocalOut, lyricsOut)` guard that exists precisely
    to catch a too-generous energy reading silently chose the energy reading instead.

    A lyric sheet settles it: trailing words that appear nowhere in the song's own words
    are not the song. Without a sheet, nothing is dropped — a guess here would be worse
    than the artefact.

    AND THE TAIL MUST SIT OVER SILENCE. A hallucination is whisper inventing words where
    nothing is sung, so the signal's own vocal-out (`vocal_out`) corroborates it: a tail
    that BEGINS while the energy map still hears a voice is a sung passage the sheet
    failed to match, not an invention. Measured 2026-08-22 on a Hinglish song: the word
    pass runs whisper forced to English, so not one word of the final hook (93-102s)
    matched the romanised sheet, the whole hook was dropped as "hallucinated", and the
    film would have been cut at 89s with 18 seconds of singing left. The original case
    (invented words at 110s, vocal-out 111.5s with reverb tail) still drops, hence the
    3s margin.
    """
    if not lyrics_path or not os.path.isfile(lyrics_path):
        return words
    sheet = set(re.findall(r"[a-z']+", open(lyrics_path, encoding="utf-8").read().lower()))
    if not sheet or len(words) < 2:
        return words

    # JUDGE THE TRAILING RUN, NOT THE LAST WORD. Walking back word by word stops at the
    # first one that happens to be in the sheet, and "thank you FOR watching" contains
    # "for" — a word the lyrics use elsewhere. One ordinary word anchored the whole
    # hallucination and lyricsOut stayed at 111.08s instead of 98.54s.
    #
    # A hallucination arrives as a BLOCK after a long silence, so look at the run after
    # the last big gap and judge it as a whole.
    gap_at = max(range(1, len(words)),
                 key=lambda i: float(words[i]["t"]) - float(words[i - 1]["t"]))
    if float(words[gap_at]["t"]) - float(words[gap_at - 1]["t"]) < HALLUCINATION_GAP_S:
        return words
    tail = words[gap_at:]
    if vocal_out is not None and float(tail[0]["t"]) < vocal_out - HALLUCINATION_MARGIN_S:
        return words          # the voice is still going where this tail starts
    known = sum(1 for x in tail
                if re.sub(r"[^a-z']", "", x["w"].lower()) in sheet)
    if known / len(tail) < 0.5:
        return words[:gap_at]
    return words


def stem_stretches(stem_path: str, hop_sec: float, min_sec: float) -> list:
    """Vocal-free stretches measured on the SEPARATED VOCAL STEM (demucs vocals.wav).

    The brief's line ends come from an aligner that can misplace them wherever whisper
    went deaf (it missed 0-30s of a Hinglish track outright), and the centre-vs-side
    measure needs stereo. The stem needs neither: it IS the vocal, mono is fine, and
    silence on it is silence. Reverb tails keep RMS up past a sung word, which errs
    long on the vocal side — the safe direction for deciding where NOT to cover.

    Threshold: 40dB below the stem's own loudest hop — per-track relative, like
    `derive_threshold`, because an absolute floor tuned on one mix lies on the next.
    """
    raw = subprocess.run(
        ["ffmpeg", "-v", "error", "-i", stem_path, "-ac", "1", "-ar", str(SR),
         "-f", "s16le", "-"], capture_output=True).stdout
    x = np.frombuffer(raw, dtype="<i2").astype(np.float64) / 32768.0
    if len(x) == 0:
        raise SystemExit(f"vocal_map: no audio decoded from stem {stem_path}")
    hop = int(SR * hop_sec)
    r = _rms(x, hop)
    db = 20 * np.log10(np.maximum(r, 1e-9))
    present = db > (float(db.max()) - 40.0)
    times = np.arange(len(r)) * hop_sec
    out = stretches(times, present, min_sec, hop_sec)
    for g in out:
        g["source"] = "stem"
    return out


def merge_new_stretches(base: list, extra: list) -> list:
    """Append the `extra` stretches that do not overlap anything already in `base`."""
    def overlaps(a, b):
        return min(float(a["end"]), float(b["end"])) > max(float(a["start"]), float(b["start"]))
    merged = list(base)
    for g in extra:
        if not any(overlaps(g, h) for h in merged):
            merged.append(g)
    return sorted(merged, key=lambda g: float(g["start"]))


def stretches(times: np.ndarray, present: np.ndarray, min_sec: float,
              hop_sec: float) -> list:
    """Contiguous runs where the vocal is absent, longer than min_sec."""
    out, start = [], None
    for i, on in enumerate(present):
        if not on and start is None:
            start = times[i]
        elif on and start is not None:
            if times[i] - start >= min_sec:
                out.append({"start": round(float(start), 2),
                            "end": round(float(times[i]), 2),
                            "seconds": round(float(times[i] - start), 2)})
            start = None
    if start is not None:
        end = float(times[-1] + hop_sec)
        if end - start >= min_sec:
            out.append({"start": round(float(start), 2), "end": round(end, 2),
                        "seconds": round(end - float(start), 2)})
    return out


def main() -> None:
    ap = argparse.ArgumentParser()
    ap.add_argument("--song", required=True, help="the STEREO source, not hook.wav")
    ap.add_argument("--plan", help="plan.json — score each window it defines")
    ap.add_argument("--out", help="default <plan dir>/vocal-map.json")
    ap.add_argument("--hop", type=float, default=DEFAULT_HOP)
    ap.add_argument("--min-gap", type=float, default=1.0,
                    help="shortest vocal-free stretch worth reporting")
    ap.add_argument("--shot-led-under", type=float, default=0.55,
                    help="window vocal coverage below this is shot-led")
    ap.add_argument("--transcript", help="whisper transcript.json — used only for "
                    "the last WORD end, which the signal cannot see through reverb")
    ap.add_argument("--min-word-gap", type=float, default=DEFAULT_MIN_WORD_GAP,
                    help="a WORD gap this long is an instrumental; shorter is a line "
                         f"break (default {DEFAULT_MIN_WORD_GAP}s)")
    ap.add_argument("--words", help="word-level transcript {words:[{t,w}]} — THE source "
                    "for vocal-free stretches; the energy map cannot see them")
    ap.add_argument("--lyrics", help="lyrics.txt — trailing transcript words absent from "
                    "it are whisper hallucinating over silence, and are dropped")
    ap.add_argument("--brief", help="vocal_brief.py build/vocal-brief.json — when given, "
                    "the silences and each window's shotLed come from the brief's placed "
                    "lyric lines (the energy map is still computed, for comparison)")
    ap.add_argument("--stem", help="separated vocal stem (demucs vocals.wav; mono is fine) "
                    "— RMS-silent stretches it finds that the brief/words missed are "
                    "added (source: 'stem'). The brief's ends come from an aligner that "
                    "goes wherever whisper went deaf; the stem cannot be argued with")
    ap.add_argument("--threshold", type=float, help="override the derived floor")
    ap.add_argument("--json", action="store_true")
    args = ap.parse_args()

    ch = _probe_channels(args.song)
    if ch < 2:
        raise SystemExit(
            f"vocal_map: {os.path.basename(args.song)} has {ch} channel(s). This "
            "measurement is centre-vs-side and is meaningless in mono — it would "
            "report the whole song as instrumental. Use the stereo original.")

    energy_source = "centre-vs-side"
    try:
        times, score = vocal_score(args.song, args.hop)
    except SystemExit as exc:
        # DUAL-MONO: no side channel to subtract. With a separated stem the measure
        # moves to the stem; without one the old refusal stands (it says what to do).
        if not (args.stem and os.path.isfile(args.stem)):
            raise
        print(f"vocal_map: {str(exc).splitlines()[0][:110]} — measuring the vocal STEM instead", file=sys.stderr)
        times, score = stem_score(args.stem, args.hop)
        energy_source = "stem"
    thresh = args.threshold if args.threshold is not None else derive_threshold(score)
    present = score > thresh
    gaps = stretches(times, present, args.min_gap, args.hop)
    vocal_out = float(times[np.max(np.nonzero(present))] + args.hop) if present.any() else 0.0
    song_end = float(times[-1] + args.hop) if len(times) else 0.0
    brief = (json.load(open(args.brief, encoding="utf-8"))
             if args.brief and os.path.isfile(args.brief) else None)
    brief_lines = [l for l in (brief or {}).get("lines", []) if l.get("start") is not None]
    words = []
    sung_past = None
    if args.words and os.path.isfile(args.words):
        words = json.load(open(args.words, encoding="utf-8")).get("words", [])
        # THE SONG SINGS PAST THE SHEET? Measured on the words BEFORE the tail drop:
        # the drop removes an invented block over silence; a sung repeat the sheet
        # does not carry must survive to be named (film #3: 50 s of reprise, five
        # windows planned no-voice, nothing said so until the plan was read by hand).
        if brief_lines and args.lyrics and os.path.isfile(args.lyrics):
            sung_past = raplib.sung_past_sheet(
                words, max(float(l["end"]) for l in brief_lines),
                open(args.lyrics, encoding="utf-8").read())
        words = drop_hallucinated_tail(words, args.lyrics, vocal_out)
    short_gaps: list = []

    def split_short(all_gaps: list) -> list:
        """Partition: real stretches stay `gaps`, the [SHORT_GAP_MIN, min_word_gap)
        band becomes `shortGaps` — recorded, never auto-covered."""
        nonlocal short_gaps
        short_gaps = [g for g in all_gaps if g["seconds"] < args.min_word_gap]
        return [g for g in all_gaps if g["seconds"] >= args.min_word_gap]

    if brief_lines:
        # THE BRIEF WINS over both. Its lines have ends, are in the song's own language,
        # and come from the lyric sheet, so they cannot be hallucinated.
        gaps = split_short(brief_stretches(brief_lines, song_end, SHORT_GAP_MIN))
    elif words:
        # WORDS WIN. The energy map is kept in the document for comparison, but a stretch
        # the words say is silent IS silent, whatever the reverb tail scores.
        gaps = split_short(word_stretches(words, song_end, SHORT_GAP_MIN))
    if args.stem and os.path.isfile(args.stem):
        # The stem CROSS-CHECKS the winner: stretches it hears that the brief/words
        # missed are appended, never replacing what a stronger source already placed.
        sg = stem_stretches(args.stem, args.hop, SHORT_GAP_MIN)
        gaps = merge_new_stretches(gaps, [g for g in sg if g["seconds"] >= args.min_word_gap])

        def overlaps_any(g, others):
            return any(min(float(g["end"]), float(h["end"]))
                       > max(float(g["start"]), float(h["start"])) for h in others)
        # a short inside an already-recorded REAL stretch is the same silence twice
        short_gaps = merge_new_stretches(
            short_gaps, [g for g in sg if g["seconds"] < args.min_word_gap
                         and not overlaps_any(g, gaps)])
    # The signal measures vocal ENERGY, which is not the same as LYRICS — a held
    # note or an "ooh" scores like a sung word. It is also weakest exactly where a
    # decision matters most: on the reference film the drums-only outro still read
    # 0.37 because of reverb tail. The transcript is unreliable for coverage (it
    # padded a fully instrumental window to 100%) but it is reliable for the last
    # moment a WORD was sung, so take the earlier of the two for the final cut.
    lyrics_out = None
    if brief_lines:
        lyrics_out = round(max(float(l["end"]) for l in brief_lines), 3)
    elif words:
        lyrics_out = round(float(words[-1]["t"]), 3)
    elif args.transcript and os.path.isfile(args.transcript):
        segs = json.load(open(args.transcript, encoding="utf-8")).get("segments", [])
        if segs:
            lyrics_out = round(max(float(s.get("end", 0.0)) for s in segs), 3)

    doc = {
        "schemaVersion": 1,
        "song": os.path.abspath(args.song),
        "songSeconds": round(float(times[-1] + args.hop), 3) if len(times) else 0.0,
        "hopSeconds": args.hop,
        "threshold": round(thresh, 4),
        "energySource": energy_source,          # centre-vs-side, or the vocal stem on a dual-mono song
        "thresholdMethod": "fixed" if args.threshold is not None else "median-fraction",
        "vocalOut": round(vocal_out, 3),
        "lyricsOut": lyrics_out,
        "cutOut": round(min(x for x in (vocal_out, lyrics_out) if x), 3)
                  if lyrics_out else round(vocal_out, 3),
        "silentStretches": gaps,
        "silentStretchSource": "brief" if brief_lines else "words" if words else "energy",
        # ADVISORY, never a refusal: sung words after the sheet's last placed line.
        "sungPastSheet": sung_past,
        # Sub-min_word_gap gaps: real, short, NEVER auto-covered (every line break lives
        # here). The cover stage prints the ones inside each window as mouthing risks;
        # an operator covers one explicitly (cover_mouthing.py --span) when a take
        # mouths through it — the defect an alley closeup shipped with on 2026-08-24.
        "shortGaps": short_gaps,
        "energyStretches": stretches(times, present, args.min_gap, args.hop),
        "windows": [],
    }

    by_brief = brief_window_coverage((brief or {}).get("windows", [])) if brief else {}
    if args.plan:
        plan = json.load(open(args.plan, encoding="utf-8"))
        for job in plan.get("jobs", []):
            start = float(job.get("startSec", 0.0))
            secs = float(job.get("seconds", 0.0))
            m = (times >= start) & (times < start + secs)
            cov = float(present[m].mean()) if m.any() else 0.0
            row = {
                "id": job.get("id"),
                "window": job.get("window"),
                "startSec": start,
                "seconds": secs,
                "vocalCoverage": round(cov, 3),
                "shotLed": cov < args.shot_led_under,
            }
            if job.get("id") in by_brief:
                # The brief's line coverage, judged at make_plan's own 0.30 line, so the
                # window that was sent without a voice is the window marked shot-led.
                bcov, led = by_brief[job["id"]]
                row.update({"energyShotLed": row["shotLed"], "briefCoverage": bcov,
                            "shotLed": led, "shotLedSource": "brief"})
            doc["windows"].append(row)

    out = args.out or os.path.join(
        os.path.dirname(os.path.abspath(args.plan)) if args.plan else ".",
        "vocal-map.json")
    with open(out, "w", encoding="utf-8") as fh:
        json.dump(doc, fh, indent=2)
    if sung_past:
        print(f"vocal_map: 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)

    if args.json:
        print(json.dumps(doc, indent=2))
    else:
        led = [w["id"] for w in doc["windows"] if w["shotLed"]]
        print(f"vocal-map: floor {thresh:.3f} ({doc['thresholdMethod']}) · vocal energy "
              f"ends {vocal_out:.2f}s"
              + (f" · last lyric {lyrics_out:.2f}s" if lyrics_out else "")
              + f" · cut at {doc['cutOut']:.2f}s · {len(gaps)} vocal-free stretch(es)")
        for g in gaps:
            print(f"  silent {g['start']:7.2f} - {g['end']:7.2f}  ({g['seconds']:.2f}s)"
                  + (f"  [{g['source']}]" if g.get("source") else ""))
        for g in short_gaps:
            print(f"  short  {g['start']:7.2f} - {g['end']:7.2f}  ({g['seconds']:.2f}s)"
                  f"  — not auto-covered; a take mouthing through it is a defect")
        if doc["windows"]:
            print(f"  shot-led windows ({len(led)}): {', '.join(led) or 'none'}")
        print(f"  wrote {out}")


if __name__ == "__main__":
    main()
