#!/usr/bin/env python3
"""stem_check.py — six measurements on the Demucs vocal stem before anything is cut from it.

WHY. Under VOICE_SOURCE=stem every voice slice the model sings to is cut from
build/stems/vocals.wav, and singer_diarize embeds it to decide who sings each line. Until
now the only check on that file was that it EXISTED. A stem that is silence (Demucs
handed a track with no centred vocal), a truncated file (Demucs killed mid-write), a
wrong-song stem, or the mix copied back out under the stem's name would all flow straight
into the slices, and the first anyone would know is a night of renders singing to nothing.
The doctrine (gate-what-can-break): a gate must be able to detect a defect known to
exist — every check below has a manufactured fixture in rap-avatar-stem-check.test.ts.

Adapted from the six-point suite in the operator's StageDirector toolkit for WAV stems cut
from a MONO hook.wav (pick_hook writes -ac 1): the toolkit's stereo and MP3-bitrate checks
cannot fail here (Demucs duplicates the mono channel) and are replaced by a format check.
Thresholds are flags carrying the toolkit's defaults; the measured values are recorded in
`metrics` so the operator sees the margin, not just the verdict.

  1. exists     — both files present; size >= 0.9 x the PCM bytes the duration implies
  2. decodes    — the whole stream decodes with zero errors (ffmpeg -v error -f null)
  3. duration   — stem within 250 ms of hook.wav (a wrong-song stem; the sha sidecar
                  guards this by content, this measures it)
  4. format     — pcm codec, sample rate >= 44100, 1 or 2 channels
  5. level      — vocals mean > -45 dB and peak > -8 dB; instrumental mean > -35 dB
                  (THE real one: a silent or near-silent stem)
  6. distinct   — vocals are not a COPY of hook.wav or of the instrumental (same sha, or
                  correlation >= 0.995 at lag 0); a passthrough where Demucs output was
                  never produced and the input was copied. Measured by signal: two stems
                  of one song are always the same size and can sit within 0.3 dB

Usage:
  stem_check.py --song build/hook.wav --vocals build/stems/vocals.wav
                [--inst build/stems/_demucs/htdemucs/hook/no_vocals.wav]
                --out build/stems/stem-check.json [--verify-only] [--json]
                [--min-vocals-mean-db -45] [--min-vocals-peak-db -8] [--min-inst-mean-db -35]
Exit 0 pass · 5 a check failed (named on stderr) · 2 an input is missing.
`--out` is skipped (exit by the stored verdict) when it already names this stem's sha.
"""
from __future__ import annotations

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

FFMPEG = os.environ.get("FFMPEG_FULL") or os.environ.get("FFMPEG_BIN") or "ffmpeg"
FFPROBE = os.environ.get("FFPROBE_BIN") or "ffprobe"
SCHEMA_VERSION = 1


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


def probe(path: str) -> dict | None:
    r = subprocess.run([FFPROBE, "-v", "error", "-select_streams", "a:0",
                        "-show_entries", "stream=codec_name,sample_rate,channels,bits_per_sample,duration",
                        "-show_entries", "format=duration,size", "-of", "json", path],
                       capture_output=True, text=True)
    if r.returncode != 0:
        return None
    try:
        d = json.loads(r.stdout)
        st = (d.get("streams") or [{}])[0]
        fmt = d.get("format") or {}
        dur = fmt.get("duration") or st.get("duration")
        return {"seconds": float(dur) if dur else 0.0,
                "bytes": int(fmt.get("size") or os.path.getsize(path)),
                "codec": st.get("codec_name") or "",
                "sampleRate": int(st.get("sample_rate") or 0),
                "channels": int(st.get("channels") or 0),
                "bits": int(st.get("bits_per_sample") or 0) or 16}
    except (ValueError, KeyError, IndexError):
        return None


def decodes(path: str) -> tuple[bool, str]:
    r = subprocess.run([FFMPEG, "-v", "error", "-i", path, "-f", "null", "-"], capture_output=True, text=True)
    err = r.stderr.strip()
    return (r.returncode == 0 and not err), err[-300:]


def levels(path: str) -> tuple[float | None, float | None]:
    r = subprocess.run([FFMPEG, "-v", "info", "-i", path, "-af", "volumedetect", "-f", "null", "-"],
                       capture_output=True, text=True)
    mean = re.search(r"mean_volume:\s*(-?[\d.]+) dB", r.stderr)
    peak = re.search(r"max_volume:\s*(-?[\d.]+) dB", r.stderr)
    return (float(mean.group(1)) if mean else None, float(peak.group(1)) if peak else None)


def correlation(a: str, b: str, sr: int = 8000, seconds: float = 120.0) -> float | None:
    """Pearson correlation of two files' first `seconds` at lag 0, mono, 8 kHz. Two copies
    of one signal read ~1.0; a vocal stem against its own instrumental reads near 0 (they
    are the two halves of the mix); a stem against the mix reads well under 0.99 because
    the mix carries the instrumental too. None when either cannot be decoded."""
    try:
        import numpy as np
    except ImportError:            # the gate must still answer on a box without numpy
        return None
    sig = []
    for path in (a, b):
        r = subprocess.run([FFMPEG, "-v", "error", "-t", f"{seconds:.1f}", "-i", path, "-vn", "-ac", "1",
                            "-ar", str(sr), "-f", "f32le", "-"], capture_output=True)
        x = np.frombuffer(r.stdout, dtype=np.float32)
        if x.size < sr:
            return None
        sig.append(x)
    n = min(sig[0].size, sig[1].size)
    x, y = sig[0][:n].astype(np.float64), sig[1][:n].astype(np.float64)
    x -= x.mean(); y -= y.mean()
    den = float(np.sqrt((x * x).sum() * (y * y).sum()))
    return float((x * y).sum() / den) if den > 0 else None


IDENTICAL_CORR = 0.995


def check_stems(song: str, vocals: str, inst: str | None = None, *, min_vocals_mean_db: float = -45.0,
                min_vocals_peak_db: float = -8.0, min_inst_mean_db: float = -35.0,
                max_drift_s: float = 0.25) -> dict:
    """The six checks. Pure apart from ffprobe/ffmpeg reads; never writes."""
    checks: list[dict] = []
    metrics: dict = {}

    def add(name: str, passed: bool, message: str, **data) -> None:
        checks.append({"name": name, "passed": bool(passed), "message": message, "data": data})

    song_p = probe(song) if os.path.isfile(song) else None
    voc_p = probe(vocals) if os.path.isfile(vocals) else None
    inst_p = probe(inst) if inst and os.path.isfile(inst) else None
    metrics["song"], metrics["vocals"], metrics["instrumental"] = song_p, voc_p, inst_p

    # 1. exists, and is as long in bytes as its header says it should be
    def expected_bytes(p: dict | None) -> int:
        return int(p["seconds"] * p["sampleRate"] * p["channels"] * (p["bits"] / 8)) if p and p["sampleRate"] else 0
    voc_ok = bool(voc_p) and voc_p["bytes"] >= 0.9 * expected_bytes(voc_p) > 0
    inst_ok = (inst is None) or (bool(inst_p) and inst_p["bytes"] >= 0.9 * expected_bytes(inst_p) > 0)
    add("exists", voc_ok and inst_ok,
        f"vocals {voc_p['bytes'] if voc_p else 0} B" + (f" · instrumental {inst_p['bytes']} B" if inst_p else "")
        + ("" if voc_ok and inst_ok else " — missing, empty, or shorter than its header says"),
        vocalsBytes=voc_p["bytes"] if voc_p else 0, expectedVocalsBytes=expected_bytes(voc_p))
    if not voc_p:
        return {"schemaVersion": SCHEMA_VERSION, "passedAll": False, "checks": checks, "metrics": metrics}

    # 2. decodes
    v_ok, v_err = decodes(vocals)
    i_ok, i_err = decodes(inst) if inst_p else (True, "")
    add("decodes", v_ok and i_ok, "every frame decodes" if v_ok and i_ok else f"decode errors: {v_err} {i_err}".strip())

    # 3. duration vs hook.wav
    if song_p:
        drift = abs(song_p["seconds"] - voc_p["seconds"])
        add("duration", drift <= max_drift_s,
            f"hook {song_p['seconds']:.2f} s · vocals {voc_p['seconds']:.2f} s · drift {drift * 1000:.0f} ms",
            driftMs=round(drift * 1000, 1), maxDriftMs=max_drift_s * 1000)
        metrics["driftMs"] = round(drift * 1000, 1)
    else:
        add("duration", False, f"hook.wav not readable at {song}")

    # 4. format: a PCM wav at the song's rate — not a 16 k mono cache file pointed at by mistake
    fmt_ok = voc_p["codec"].startswith("pcm") and voc_p["sampleRate"] >= 44100 and voc_p["channels"] in (1, 2)
    add("format", fmt_ok, f"{voc_p['codec']} {voc_p['sampleRate']} Hz {voc_p['channels']} ch",
        codec=voc_p["codec"], sampleRate=voc_p["sampleRate"], channels=voc_p["channels"])

    # 5. level — the check that catches a silent stem
    v_mean, v_peak = levels(vocals)
    i_mean, _ = levels(inst) if inst_p else (None, None)
    metrics.update({"vocalsMeanDb": v_mean, "vocalsPeakDb": v_peak, "instMeanDb": i_mean})
    lvl_ok = (v_mean is not None and v_mean > min_vocals_mean_db and v_peak is not None and v_peak > min_vocals_peak_db
              and (inst_p is None or (i_mean is not None and i_mean > min_inst_mean_db)))
    add("level", lvl_ok,
        f"vocals mean {v_mean} dB (floor {min_vocals_mean_db}) peak {v_peak} dB (floor {min_vocals_peak_db})"
        + (f" · instrumental mean {i_mean} dB (floor {min_inst_mean_db})" if inst_p else "")
        + ("" if lvl_ok else " — a silent or near-silent stem"),
        vocalsMeanDb=v_mean, vocalsPeakDb=v_peak, instMeanDb=i_mean)

    # 6. distinct — not the mix under another name, not the instrumental under another name.
    # Measured by SIGNAL, not by size or level: the two Demucs stems of one song are always
    # the same number of bytes, and a dense chorus can leave their mean levels within 0.3 dB
    # of each other (baby-nimbooda: vocals −16.4, instrumental −16.7) — a level-based test
    # failed a good stem on the first real film it met. Same sha, or correlation ≥ 0.995
    # at lag 0, is a copy; anything else is its own signal.
    voc_sha = sha256_file(vocals)
    song_sha = sha256_file(song) if song_p else ""
    same_as_song = bool(song_sha) and voc_sha == song_sha
    same_as_inst = bool(inst_p) and voc_sha == sha256_file(inst)
    corr_song = correlation(vocals, song) if song_p and not same_as_song else None
    corr_inst = correlation(vocals, inst) if inst_p and not same_as_inst else None
    copy_of_song = same_as_song or (corr_song is not None and corr_song >= IDENTICAL_CORR)
    copy_of_inst = same_as_inst or (corr_inst is not None and corr_inst >= IDENTICAL_CORR)
    distinct = not (copy_of_song or copy_of_inst)
    add("distinct", distinct,
        (f"its own signal (corr vs mix {corr_song:.3f}" + (f", vs instrumental {corr_inst:.3f}" if corr_inst is not None else "") + ")")
        if distinct and corr_song is not None else
        ("the vocal stem is its own signal" if distinct else
         "the vocal stem is the mix under another name" if copy_of_song else "the vocal stem is the instrumental under another name"),
        sameBytesAsSong=same_as_song, sameBytesAsInstrumental=same_as_inst,
        corrVsSong=None if corr_song is None else round(corr_song, 4), corrVsInstrumental=None if corr_inst is None else round(corr_inst, 4))
    metrics.update({"corrVsSong": None if corr_song is None else round(corr_song, 4),
                    "corrVsInstrumental": None if corr_inst is None else round(corr_inst, 4)})
    metrics["stemSha"], metrics["songSha"] = voc_sha, song_sha

    return {"schemaVersion": SCHEMA_VERSION, "passedAll": all(c["passed"] for c in checks),
            "stemSha": voc_sha, "songSha": song_sha, "checks": checks, "metrics": metrics}


def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("--song", required=True)
    ap.add_argument("--vocals", required=True)
    ap.add_argument("--inst", default="")
    ap.add_argument("--out", default="")
    ap.add_argument("--verify-only", action="store_true", help="exit by the stored report; run nothing")
    ap.add_argument("--json", action="store_true", help="print the report to stdout")
    ap.add_argument("--min-vocals-mean-db", type=float, default=-45.0)
    ap.add_argument("--min-vocals-peak-db", type=float, default=-8.0)
    ap.add_argument("--min-inst-mean-db", type=float, default=-35.0)
    a = ap.parse_args()
    out = a.out or os.path.join(os.path.dirname(os.path.abspath(a.vocals)), "stem-check.json")

    if not os.path.isfile(a.vocals):
        print(f"stem_check: no vocal stem at {a.vocals}", file=sys.stderr)
        return 2
    prior = None
    if os.path.isfile(out):
        try:
            prior = json.load(open(out, encoding="utf-8"))
        except ValueError:
            prior = None
    if a.verify_only:
        if not prior:
            print(f"stem_check: --verify-only but no report at {out}", file=sys.stderr)
            return 2
        if prior.get("stemSha") != sha256_file(a.vocals):
            print(f"stem_check: the report at {out} is for a different stem (sha changed) — run without --verify-only", file=sys.stderr)
            return 2
        report = prior
    elif prior and prior.get("stemSha") == sha256_file(a.vocals) and prior.get("passedAll") is not None:
        report = prior      # measured already, same bytes: the verdict stands
    else:
        report = check_stems(a.song, a.vocals, a.inst or None, min_vocals_mean_db=a.min_vocals_mean_db,
                             min_vocals_peak_db=a.min_vocals_peak_db, min_inst_mean_db=a.min_inst_mean_db)
        report["song"], report["vocals"], report["instrumental"] = os.path.abspath(a.song), os.path.abspath(a.vocals), (os.path.abspath(a.inst) if a.inst else None)
        os.makedirs(os.path.dirname(os.path.abspath(out)), exist_ok=True)
        tmp = out + ".tmp"
        with open(tmp, "w", encoding="utf-8") as fh:
            json.dump(report, fh, indent=1)
        os.replace(tmp, out)

    if a.json:
        print(json.dumps(report, indent=1))
    failed = [c for c in report["checks"] if not c["passed"]]
    for c in report["checks"]:
        print(f"  {'PASS' if c['passed'] else 'FAIL'}  {c['name']:9s} {c['message']}", file=sys.stderr)
    if failed:
        print(f"stem_check: FAILED {', '.join(c['name'] for c in failed)} — see {out}", file=sys.stderr)
        return 5
    print(f"stem_check: the vocal stem passed all six checks → {out}", file=sys.stderr)
    return 0


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