#!/usr/bin/env python3
"""deliver.py — the finished cut at delivery resolution, with the captions burned in.

WHY THIS IS A STAGE AND NOT A ONE-OFF. The skill had no hi-res path at all, so the
1080p and 4K masters of one film were built by hand at the end of a long session — and
every hand-built step in this lane has cost something. This one cost three things, and
all three are now impossible here by construction:

  A PARTIAL UPSCALE SILENTLY ENCODES A SHORT FILM. 2934 frames go in; if only 1644 come
  out, ffmpeg's image sequence reader stops at the gap and produces a perfectly valid,
  perfectly wrong 68-second film. So the frame count is asserted before encoding and the
  encode is REFUSED on a mismatch.

  A RESTART MUST NOT REDO FINISHED WORK. The first 4K run was killed at 1644/2934 and
  the script began with `rm -rf`, which would have thrown away forty minutes on restart.
  Each frame is an independent unit; only frames with no output are queued, in a loop
  that stops if a pass makes no progress rather than spinning.

  `nohup … &` IS NOT DETACHED ENOUGH. A 1080p encode was killed mid-write and produced
  an unplayable file (`moov atom not found`) because the shell that started it was torn
  down. Long runs go through daemonize.py — a double fork with os.setsid(), because
  macOS HAS NO `setsid` BINARY; the "double-fork + setsid" recipe everyone quotes is
  Linux.

MODEL CHOICE IS PINNED, and one option is refused outright:

  realesr-animevideov3 at -s 3   1.4 s/frame   720->2160 in one pass, no rescale
  realesrgan-x4plus    at -s 4   20 s/frame    14x slower for no visible gain here
  realesrgan-x4plus    at -s 2   REFUSED       returns the right DIMENSIONS and the
                                               wrong framing — zoomed and cropped. It
                                               is a silently-wrong output, which is
                                               worse than an error, so it is rejected
                                               in code rather than warned about in prose.

Captions are burned with ffmpeg-full: the slim brew ffmpeg has no libass and will
SOFT-MUX them instead, which plays fine while the words are not in the pixels. The burn
is verified afterwards by asserting zero subtitle streams.

Usage:
  deliver.py --project <dir> --slug <s> --style <id> [--mode 1080p|4k|both]
             [--input <mp4>] [--subs <ass>] [--out-dir <dir>] [--fps 24] [--json]

Exit 0 delivered · 2 inputs unusable · 5 the output failed its own QC
"""
from __future__ import annotations

import argparse
import json
import os
import shutil
import subprocess
import sys
import time

FFMPEG_FULL = os.environ.get("FFMPEG_FULL", "/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg")
REALESRGAN = os.environ.get("REALESRGAN_BIN",
                            os.path.expanduser("~/.local/realesrgan/realesrgan-ncnn-vulkan"))
MODEL, SCALE = "realesr-animevideov3", 3
# See the docstring. Correct dimensions, wrong framing — never enable this.
BANNED = {("realesrgan-x4plus", 2)}
DURATION_TOLERANCE_S = 0.10          # one frame at 24fps is 0.042s; two is comfortable

_LOG: str | None = None
# Under --json, stdout carries ONE machine-readable object and nothing else. A --json
# mode whose stdout is interleaved with progress lines is not machine-readable, and the
# caller that discovers this discovers it as a parse error a long way from here.
_QUIET = False


def say(msg: str) -> None:
    line = f"{time.strftime('%H:%M:%S')}  {msg}"
    print(line, file=sys.stderr if _QUIET else sys.stdout, flush=True)
    if _LOG:
        with open(_LOG, "a", encoding="utf-8") as handle:
            handle.write(line + "\n")


def die(msg: str, code: int = 2) -> "None":
    say(f"FATAL: {msg}")
    raise SystemExit(code)


def probe(path: str, entries: str, stream: str | None = "v:0") -> str:
    argv = ["ffprobe", "-v", "error"]
    if stream:
        argv += ["-select_streams", stream]
    argv += ["-show_entries", entries, "-of", "csv=p=0", path]
    return subprocess.run(argv, capture_output=True, text=True).stdout.strip()


def source_facts(path: str) -> dict:
    width, height = probe(path, "stream=width,height").split(",")[:2]
    duration = float(probe(path, "format=duration", stream=None).splitlines()[0])
    # COUNTED, not derived. nb_frames is frequently absent on an ffmpeg-written mp4,
    # and duration x fps rounds — which is exactly the arithmetic that let a 2933-frame
    # master pass for 2934. Decoding a two-minute clip costs a few seconds and the whole
    # point of this stage is that the count is right.
    frames = count_frames(path)
    if not frames:
        die(f"could not count frames in {path}; ffprobe returned nothing", 2)
    return {"width": int(width), "height": int(height), "duration": duration,
            "frames": frames}


def count_frames(path: str) -> int:
    out = subprocess.run(["ffprobe", "-v", "error", "-count_frames", "-select_streams", "v:0",
                          "-show_entries", "stream=nb_read_frames", "-of", "csv=p=0", path],
                         capture_output=True, text=True).stdout.strip()
    return int(out.split(",")[0] or 0)


# --------------------------------------------------------------------------

def burn_args(subs: str | None, source_w: int, source_h: int) -> list[str]:
    """The subtitle filter, told the ORIGINAL canvas so libass scales rather than
    rendering 46pt type onto a 3840-tall frame."""
    if not subs:
        return []
    return ["-vf", f"subtitles={subs}:original_size={source_w}x{source_h}"]


def deliver_1080p(src: str, facts: dict, subs: str | None, out: str) -> None:
    say(f"1080p: lanczos from {facts['width']}x{facts['height']}")
    scale = "scale=1080:1920:flags=lanczos" if facts["height"] > facts["width"] \
        else "scale=1920:1080:flags=lanczos"
    chain = scale
    if subs:
        chain = f"{scale},subtitles={subs}:original_size={facts['width']}x{facts['height']}"
    run_ffmpeg(["-i", src, "-vf", chain, *ENCODE, out])


def deliver_4k(src: str, facts: dict, subs: str | None, out: str, work: str,
               fps: float) -> None:
    if (MODEL, SCALE) in BANNED:
        die(f"{MODEL} at -s {SCALE} is refused: it returns the correct dimensions and "
            f"the wrong framing")
    if not os.access(REALESRGAN, os.X_OK):
        die(f"no realesrgan-ncnn-vulkan at {REALESRGAN} (set REALESRGAN_BIN)", 2)

    src_dir, up_dir, todo = (os.path.join(work, d) for d in ("src", "up", "todo"))
    for directory in (src_dir, up_dir, todo):
        os.makedirs(directory, exist_ok=True)

    expected = facts["frames"]
    # CHECK THE DISK FIRST. This writes two PNG sequences — the source frames and the
    # upscaled ones, the latter SCALE^2 times the pixels — so a two-minute 9:16 film is
    # tens of gigabytes of scratch. Running out partway leaves a half-finished set and
    # an ffmpeg that died with "No space left on device" buried in a log; it happened
    # while testing this very function. Estimated generously: a 2160x3840 PNG of live
    # action runs 8-25MB.
    need = int(expected * (facts["width"] * facts["height"] * 3 * 0.5
                           + facts["width"] * SCALE * facts["height"] * SCALE * 3 * 0.5))
    free = shutil.disk_usage(work).free
    say(f"scratch estimate {need / 1e9:.1f}GB for {expected} frames; {free / 1e9:.1f}GB free")
    if free < need:
        die(f"not enough disk for the frame sets: need about {need / 1e9:.1f}GB, "
            f"{free / 1e9:.1f}GB free. Free some space or deliver 1080p only — running "
            f"out partway wastes the whole pass.", 2)
    if len(os.listdir(src_dir)) < expected:
        say(f"extracting {expected} frames")
        # -fps_mode passthrough == the old -vsync 0 (every source frame, no dup/drop).
        # ffmpeg 9 REMOVED -vsync outright (brew upgraded 2026-08-27 and this line
        # started dying with "Unrecognized option"); -fps_mode exists since ffmpeg 5.1,
        # so this spelling works on every toolchain the lane has ever run on.
        run_ffmpeg(["-i", src, "-fps_mode", "passthrough", os.path.join(src_dir, "%05d.png")])
    names = sorted(f for f in os.listdir(src_dir) if f.endswith(".png"))
    if len(names) != expected:
        die(f"extracted {len(names)} frames but the source has {expected}", 5)

    # RESUMABLE. Only frames with no output are queued; a pass that upscales nothing
    # stops the loop rather than spinning forever.
    while True:
        shutil.rmtree(todo, ignore_errors=True)
        os.makedirs(todo, exist_ok=True)
        missing = 0
        for name in names:
            done = os.path.join(up_dir, name)
            if os.path.exists(done) and os.path.getsize(done) > 0:
                continue
            source = os.path.join(src_dir, name)
            try:
                os.link(source, os.path.join(todo, name))       # hard link: no copy
            except OSError:
                shutil.copyfile(source, os.path.join(todo, name))
            missing += 1
        say(f"{expected - missing}/{expected} upscaled; {missing} to go")
        if missing == 0:
            break
        before = len(os.listdir(up_dir))
        subprocess.run([REALESRGAN, "-i", todo, "-o", up_dir, "-s", str(SCALE),
                        "-n", MODEL, "-f", "png"], cwd=os.path.dirname(REALESRGAN))
        if len(os.listdir(up_dir)) <= before:
            die("a whole pass upscaled nothing — stopping rather than looping", 5)
    shutil.rmtree(todo, ignore_errors=True)

    upscaled = len([f for f in os.listdir(up_dir) if f.endswith(".png")])
    if upscaled != expected:
        # THE GATE. ffmpeg's image reader stops at the first gap and writes a valid,
        # short film with no error anywhere.
        die(f"MISMATCH {upscaled}/{expected} upscaled — refusing to encode a short film", 5)

    say(f"all {expected} frames upscaled; encoding")
    # `-frames:v {expected}`, NOT `-shortest`. This encode takes its picture from the
    # image sequence and its sound from the master, and on a real film those two lengths
    # differ slightly — video 122.250s, audio 122.240s, which the master's own A/V
    # tolerance accepts. `-shortest` then truncated the PICTURE to the audio and produced
    # a 2933-frame file from 2934 frames of input. It shipped, and the log line said
    # "DONE 122.24s" as if that were the plan. Same lesson as the assembler's: state the
    # frame count you mean, never let a filter or a flag infer it.
    run_ffmpeg(["-framerate", str(fps), "-i", os.path.join(up_dir, "%05d.png"), "-i", src,
                "-map", "0:v", "-map", "1:a",
                *burn_args(subs, facts["width"], facts["height"]), *ENCODE,
                "-frames:v", str(expected), out])


ENCODE = ["-c:v", "libx264", "-preset", "medium", "-crf", "18", "-pix_fmt", "yuv420p",
          "-profile:v", "high", "-level", "5.2", "-c:a", "aac", "-b:a", "320k",
          "-movflags", "+faststart"]


def run_ffmpeg(argv: list[str]) -> None:
    proc = subprocess.run([FFMPEG_FULL, "-v", "error", "-y", *argv],
                          capture_output=True, text=True)
    if proc.returncode != 0:
        die(f"ffmpeg failed: {(proc.stdout + proc.stderr).strip()[-400:]}", 5)


def qc(out: str, facts: dict, expect_scale: int | None, subs: str | None) -> dict:
    """Measure the DELIVERED file. A log line saying DONE is not evidence."""
    if not os.path.isfile(out) or os.path.getsize(out) < 100_000:
        die(f"{out} is missing or implausibly small", 5)
    width, height = (int(v) for v in probe(out, "stream=width,height").split(",")[:2])
    duration = float(probe(out, "format=duration", stream=None).splitlines()[0])
    frames = count_frames(out)

    problems = []
    if expect_scale and (width, height) != (facts["width"] * expect_scale,
                                            facts["height"] * expect_scale):
        problems.append(f"dimensions {width}x{height}, expected "
                        f"{facts['width'] * expect_scale}x{facts['height'] * expect_scale}")
    if abs(duration - facts["duration"]) > DURATION_TOLERANCE_S:
        problems.append(f"duration {duration:.3f}s against source {facts['duration']:.3f}s")
    if frames != facts["frames"]:
        problems.append(f"{frames} frames against source {facts['frames']}")
    if not probe(out, "stream=codec_type", stream="a:0"):
        problems.append("no audio stream — a silent master")
    if subs:
        # A burn that silently SOFT-MUXED plays fine while the words are not in the
        # pixels. Zero subtitle streams is the proof that they are.
        streams = probe(out, "stream=index", stream="s")
        if streams:
            problems.append(f"subtitles were SOFT-MUXED, not burned "
                            f"({len(streams.splitlines())} stream(s)) — check ffmpeg-full "
                            f"has libass")
    if problems:
        for problem in problems:
            say(f"  QC FAIL: {problem}")
        die(f"{os.path.basename(out)} failed delivery QC", 5)
    return {"path": out, "width": width, "height": height, "duration": round(duration, 3),
            "frames": frames, "bytes": os.path.getsize(out)}


def main() -> None:
    global _LOG
    ap = argparse.ArgumentParser()
    ap.add_argument("--project", required=True)
    ap.add_argument("--slug", required=True)
    ap.add_argument("--style", required=True)
    ap.add_argument("--mode", default="1080p", choices=("1080p", "4k", "both", "none"))
    ap.add_argument("--input", help="default: master_version.py latest")
    ap.add_argument("--subs", help="an .ass to burn; omit for no captions")
    ap.add_argument("--out-dir")
    ap.add_argument("--fps", type=float, default=24)
    ap.add_argument("--keep-frames", action="store_true")
    ap.add_argument("--json", action="store_true")
    args = ap.parse_args()

    global _QUIET
    _QUIET = args.json

    if args.mode == "none":
        print(json.dumps({"mode": "none", "delivered": []}))
        return

    _LOG = os.path.join(args.project, "build", f"deliver-{args.style}.log")
    os.makedirs(os.path.dirname(_LOG), exist_ok=True)

    src = args.input
    if not src:
        # Ask master_version rather than parsing a filename: nothing downstream should
        # decide what is newest by sorting strings.
        here = os.path.dirname(os.path.abspath(__file__))
        reply = subprocess.run(
            [sys.executable, os.path.join(here, "master_version.py"), "latest",
             "--project", args.project, "--slug", args.slug, "--style", args.style],
            capture_output=True, text=True)
        if reply.returncode != 0:
            die(f"could not resolve the latest master: {reply.stderr.strip()[-200:]}")
        src = json.loads(reply.stdout)["path"]
    if not os.path.isfile(src):
        die(f"input does not exist: {src}")
    if args.subs and not os.path.isfile(args.subs):
        die(f"subtitles do not exist: {args.subs}")
    if not os.access(FFMPEG_FULL, os.X_OK):
        die(f"no ffmpeg-full at {FFMPEG_FULL}. The slim brew ffmpeg has no libass and "
            f"SOFT-MUXES captions into invisibility.", 2)

    facts = source_facts(src)
    say(f"source: {os.path.basename(src)} {facts['width']}x{facts['height']} "
        f"{facts['duration']:.3f}s {facts['frames']} frames")

    out_dir = args.out_dir or os.path.join(args.project, "final", "deliverables")
    os.makedirs(out_dir, exist_ok=True)
    suffix = "-subtitled" if args.subs else ""
    # THE STYLE IS IN THE NAME. A film ships two variants that are meant to read as
    # different films, and masters are already versioned per style — deliverables that
    # left it out would have the second style silently overwrite the first.
    stem = f"{args.slug}-{args.style}"
    delivered = []

    if args.mode in ("1080p", "both"):
        out = os.path.join(out_dir, f"{stem}-1080p{suffix}.mp4")
        deliver_1080p(src, facts, args.subs, out)
        delivered.append(qc(out, facts, None, args.subs))
        say(f"1080p -> {out}")

    if args.mode in ("4k", "both"):
        out = os.path.join(out_dir, f"{stem}-4k-realesrgan{suffix}.mp4")
        # Per style: two 4K runs share nothing, and a shared scratch dir would have
        # one run's frames satisfy the other run's count check.
        work = os.path.join(args.project, "build", f"4k-{args.style}")
        deliver_4k(src, facts, args.subs, out, work, args.fps)
        delivered.append(qc(out, facts, SCALE, args.subs))
        say(f"4k -> {out}")
        if not args.keep_frames:
            for directory in ("src", "up", "todo"):
                shutil.rmtree(os.path.join(work, directory), ignore_errors=True)
            say("scratch frames removed")

    report = {"mode": args.mode, "source": src, "delivered": delivered}
    with open(os.path.join(args.project, "build", f"deliver-{args.style}.json"), "w",
              encoding="utf-8") as handle:
        json.dump(report, handle, indent=2)
    if args.json:
        print(json.dumps(report, indent=2))
    else:
        for item in delivered:
            say(f"OK {item['width']}x{item['height']} {item['duration']}s "
                f"{item['frames']}f {item['bytes'] / 1e6:.0f}MB")


if __name__ == "__main__":
    main()
