siftlode/backend/app/downloads/edit.py

"""Video editor (phase 2): per-user trim/crop derivatives via ffmpeg.

An edit derives a NEW per-user clip from an already-downloaded ready asset. It is never shared-
cached across users (the cache key embeds the user id), so it fully counts against the owner's
quota — but it still rides the same `MediaAsset`/`DownloadJob`/worker machinery as a download,
with the worker branching on the asset's `source_kind` to run ffmpeg instead of yt-dlp.

  * trim, fast       → stream copy (`-c copy`), instant, no quality loss, cuts SNAP to keyframes
                       (the in/out point can be off by a second or two)
  * trim, accurate   → re-encode (libx264 + aac), frame-accurate; cost scales with CLIP length
                       (the `-ss` seeks first), so a short clip is cheap even from a long source
  * crop (± trim)    → always re-encode (a filter can't be stream-copied), frame-accurate

`edit_spec = {trim?: {start_s, end_s}, crop?: {x, y, w, h}, accurate?: bool}`. `accurate` is the
per-edit user choice for a trim-only cut (ignored when a crop forces a re-encode anyway). `split`
is a frontend concept: the
UI fans a split out into N trim jobs, so there is one output file per job here.

Also builds the editor **filmstrip** — a single tiled sprite of the source video used as a visual
scrub track. Cached on the source asset's `storyboard_path` (reserved in phase 1) and reusable
for a player hover-preview later.
"""

import hashlib
import json
import math
import os
import queue
import shutil
import subprocess
import threading
import time
from pathlib import Path

from app import logs
from app.config import settings
from app.downloads.stated import StatedFailure

log = logs.get_logger(__name__)


def encode_thread_cap() -> int:
    """How many encoder threads a browser-safe re-encode may use. `download_ffmpeg_threads` when the
    admin pinned one (>0), else reserve a core for foreground work (max(1, cpu_count - 1)). Shared by
    the ffmpeg `-threads` flag and the child's `OMP_NUM_THREADS` so both honour the same budget."""
    n = settings.download_ffmpeg_threads
    if n > 0:
        return n
    return max(1, (os.cpu_count() or 2) - 1)


class EditAborted(Exception):
    """Raised by run_ffmpeg when the job was paused/canceled mid-encode."""


# --- edit spec ------------------------------------------------------------------------------

# SEC-13: ceiling on a join's cut-list. An accurate join emits two filters per segment into a single
# ffmpeg `filter_complex`, so "however many the caller sent" is an unbounded command line.
_MAX_SEGMENTS = 100


def normalize_edit_spec(spec: dict | None) -> dict:
    """Canonicalize a raw edit spec: clamp/round trim, coerce crop to ints, drop empties.

    The result is what gets hashed (so two equivalent specs share a cache row) and stored."""
    spec = spec or {}
    out: dict = {}

    # Crop applies to both a single trim and a multi-segment join.
    crop = spec.get("crop") or {}
    if crop:
        try:
            c = {k: int(round(float(crop[k]))) for k in ("x", "y", "w", "h")}
        except (KeyError, TypeError, ValueError) as exc:
            # The clip still renders — uncropped. The user asked for a crop, got a whole frame,
            # and nothing anywhere called it a failure; this line is the only trace there is.
            log.warning(
                "the crop in an edit spec could not be read and was dropped",
                extra=logs.event("edit.spec.crop_dropped", reason=type(exc).__name__),
            )
            c = None
        if c and c["w"] > 0 and c["h"] > 0 and c["x"] >= 0 and c["y"] >= 0:
            out["crop"] = c

    # Multi-segment JOIN (cut-list → one concatenated file). Takes precedence over `trim`.
    segs = spec.get("segments")
    if isinstance(segs, list) and segs:
        norm: list[dict] = []
        unreadable = 0
        for s in segs:
            try:
                st = max(0.0, float((s or {}).get("start_s") or 0.0))
                end_raw = (s or {}).get("end_s")
                if end_raw is None:
                    continue
                en = float(end_raw)
            except (TypeError, ValueError):
                # silent-ok: counted, not logged here — one cut-list can drop several, and the
                # join that comes out is simply shorter than the one the user built. Reported
                # once after the loop.
                unreadable += 1
                continue
            if en > st:
                norm.append({"start_s": round(st, 3), "end_s": round(en, 3)})
        if unreadable:
            log.warning(
                "some segments of a cut list could not be read and were dropped",
                extra=logs.event("edit.spec.segments_dropped", dropped=unreadable, kept=len(norm)),
            )
        norm.sort(key=lambda x: x["start_s"])
        # SEC-13: an accurate join builds one ffmpeg `filter_complex` with two filters per segment,
        # so an unbounded list becomes an unbounded command line and an ffmpeg that never finishes.
        # The cap is far above any real cut-list (the UI's own splitter produces a handful) and the
        # excess is DROPPED rather than raising: the surplus segments are the attack, the first
        # _MAX_SEGMENTS are a legitimate edit.
        del norm[_MAX_SEGMENTS:]
        if norm:
            out["segments"] = norm
            # A join always chooses a codec path: accurate=filter-concat re-encode,
            # fast=demuxer-concat stream-copy (keyframe-snapped).
            out["accurate"] = bool(spec.get("accurate", True))
        return out

    # Single TRIM (one output file; the frontend fans a "separate" split out into N of these).
    trim = spec.get("trim") or {}
    if trim:
        # Guard the numeric coercion like the crop/segments branches do — a malformed value must
        # drop the trim (→ empty spec → 400 EditError), not raise an unhandled 500.
        try:
            start = max(0.0, float(trim.get("start_s") or 0.0))
            end_raw = trim.get("end_s")
            end = float(end_raw) if end_raw is not None else None
        except (TypeError, ValueError) as exc:
            # Either a 400 the user cannot act on, or — beside a crop — a full-length clip where
            # they asked for a cut. Both are worth one line saying the spec was the problem.
            log.warning(
                "the trim in an edit spec could not be read and was dropped",
                extra=logs.event("edit.spec.trim_dropped", reason=type(exc).__name__),
            )
            start, end = 0.0, None
        t: dict = {"start_s": round(start, 3)}
        if end is not None and end > start:
            t["end_s"] = round(end, 3)
        # A trim with only a start (open-ended) is valid (cut to the end).
        if t.get("start_s") or "end_s" in t:
            out["trim"] = t

    # `accurate` only changes behaviour for a trim-only cut (a crop always re-encodes). Default to
    # frame-accurate — an editor should cut where you asked; the user opts into fast/keyframe.
    if out.get("trim") and "crop" not in out:
        out["accurate"] = bool(spec.get("accurate", True))

    return out


def edit_sig(spec: dict) -> str:
    """Stable 24-char signature of a (normalized) edit spec — the per-user cache identity."""
    payload = json.dumps(normalize_edit_spec(spec), sort_keys=True, separators=(",", ":"))
    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:24]


def has_crop(spec: dict) -> bool:
    return bool(spec.get("crop"))


def needs_reencode(spec: dict) -> bool:
    """A crop always re-encodes; a trim re-encodes only when the user asked for an accurate cut."""
    return bool(spec.get("crop")) or bool(spec.get("accurate"))


def clip_duration(spec: dict, source_duration: int | None) -> int | None:
    """Duration of the derived clip (seconds), for display + progress totals."""
    segs = spec.get("segments")
    if segs:
        return max(0, round(sum(s["end_s"] - s["start_s"] for s in segs)))
    trim = spec.get("trim")
    if not trim:
        return source_duration
    start = trim.get("start_s") or 0.0
    end = trim.get("end_s")
    if end is None:
        end = source_duration
    if end is None:
        return None
    return max(0, round(end - start))


# --- ffmpeg: trim / crop --------------------------------------------------------------------

# Every libx264 / aac re-encode in this package uses these, so a re-encoded file is always the
# phone-safe shape (`playable`): `-pix_fmt yuv420p` pins 8-bit 4:2:0 — without it libx264 keeps a
# 10-bit or 4:4:4 source's pixel format and writes H.264 High 10 / High 4:4:4, which browsers decode
# only patchily (the one safe H.264 is 8-bit 4:2:0).
X264_ARGS = ["-c:v", "libx264", "-preset", "veryfast", "-crf", "20", "-pix_fmt", "yuv420p"]
AAC_ARGS = ["-c:a", "aac", "-b:a", "192k"]
# The last step of every video filter chain a libx264 re-encode runs: 4:2:0 halves the chroma, so
# libx264 refuses an odd width or height ("width not divisible by 2") — measured on an odd source
# that is not 4:2:0 already (a 4:4:4 or RGB screen capture, 1365x767). A crop of a 4:2:0 source is
# rounded to its chroma grid by ffmpeg itself; this holds every other path to the encoder to the same
# even frame. Rounding down to even costs at most one pixel row/column.
EVEN_FRAME = "scale=trunc(iw/2)*2:trunc(ih/2)*2"

# The demuxers ffmpeg/ffprobe may use to open a library file — single-file containers only. Without
# it ffmpeg picks the demuxer from the file's CONTENT and NAME, and an upload's name is the user's:
# a playlist-type demuxer (HLS, DASH, concat) opens whatever local paths its entries name, so a
# crafted upload could copy another user's clip or a Plex file into its own converted asset. A file
# no demuxer here can open fails the probe, and an unprobeable upload is a download-only 'file'.
MEDIA_DEMUXERS = (
    "mov",  # mp4, m4a, mov, 3gp
    "matroska",  # mkv, webm
    "mpegts",
    "mpeg",
    "avi",
    "asf",
    "flv",
    "ogg",
    "mp3",
    "aac",
    "ac3",
    "eac3",
    "flac",
    "wav",
    "w64",
    "aiff",
    "caf",
    "amr",
)
INPUT_GUARD = ["-format_whitelist", ",".join(MEDIA_DEMUXERS)]
# A downloaded thumbnail is the remote site's bytes under the suffix yt-dlp gave it (`.png`, `.webp`,
# `.jpg` — `pipeline._THUMB_SUFFIXES`): only the single-image demuxers those open, so a "thumbnail"
# that is really a playlist cannot pull a local file into the poster. Anything else fails, and the
# poster falls back to a cut frame (`ensure_poster`).
THUMB_GUARD = ["-format_whitelist", "png_pipe,jpeg_pipe,webp_pipe"]


def build_edit_cmd(src: Path, dest: Path, spec: dict, out_ext: str) -> list[str]:
    """ffmpeg command for a trim/crop edit. `-progress pipe:1` streams machine-readable progress.

    Trim uses fast input seek (`-ss` before `-i`) + `-t duration`, which is unambiguous across
    ffmpeg versions. Trim-only stream-copies; a crop forces a re-encode (a filter can't be
    stream-copied)."""
    trim = spec.get("trim") or {}
    start = trim.get("start_s") or 0.0
    end = trim.get("end_s")
    crop = spec.get("crop")
    reencode = needs_reencode(spec)

    cmd = [
        "ffmpeg",
        "-y",
        "-hide_banner",
        "-loglevel",
        "error",
        "-nostdin",
        "-progress",
        "pipe:1",
        "-nostats",
    ]
    if start:
        cmd += ["-ss", f"{start:.3f}"]
    cmd += [*INPUT_GUARD, "-i", str(src)]
    if end is not None:
        dur = end - start
        if dur > 0:
            cmd += ["-t", f"{dur:.3f}"]

    if reencode:
        # Input -ss + re-encode is frame-accurate (decodes from the prior keyframe, discards up to
        # the exact cut). A crop adds the filter; an accurate trim only evens the frame.
        cropf = f"crop={crop['w']}:{crop['h']}:{crop['x']}:{crop['y']}," if crop else ""
        cmd += ["-vf", cropf + EVEN_FRAME, *X264_ARGS, *AAC_ARGS]
    else:
        cmd += ["-c", "copy", "-avoid_negative_ts", "make_zero"]

    if out_ext in ("mp4", "m4a", "mov"):
        cmd += ["-movflags", "+faststart"]
    cmd += [str(dest)]
    return cmd


def _concat_quote(path: Path) -> str:
    """Escape a path for a single-quoted `file '…'` line of an ffmpeg concat list.

    ffmpeg's quoting rule: inside single quotes EVERY character is literal except `'` itself, which
    is written `'\\''` (close the quote, emit an escaped quote, reopen). Backslashes are literal
    there — doubling them would corrupt a path that contains one. On-disk names have been
    ASCII-slugged since 0.51.0, but that change is FORWARD-ONLY: a pre-0.51.0 file still on disk can
    be named `Don't_….mp4`, and an unescaped apostrophe makes the whole list unparseable."""
    return path.as_posix().replace("'", "'\\''")


def build_concat_plan(src: Path, dest: Path, spec: dict, out_ext: str, staging: Path):
    """Plan a multi-segment JOIN (cut-list → one file). Returns (cmd, prep_files) where prep_files
    maps a path → text content the worker must write before running (a concat list, if any).

      * accurate/crop → filter_complex trim+concat, frame-accurate re-encode
      * fast          → concat demuxer with per-segment inpoint/outpoint, stream-copy
                        (keyframe-snapped, like the fast single trim)"""
    segs: list[dict] = spec["segments"]
    crop = spec.get("crop")
    prep: dict[Path, str] = {}
    head = [
        "ffmpeg",
        "-y",
        "-hide_banner",
        "-loglevel",
        "error",
        "-nostdin",
        "-progress",
        "pipe:1",
        "-nostats",
    ]

    if needs_reencode(spec):
        cropf = f",crop={crop['w']}:{crop['h']}:{crop['x']}:{crop['y']}" if crop else ""
        parts, labels = [], []
        for i, s in enumerate(segs):
            st, en = s["start_s"], s["end_s"]
            parts.append(
                f"[0:v]trim=start={st}:end={en},setpts=PTS-STARTPTS{cropf},{EVEN_FRAME}[v{i}]"
            )
            parts.append(f"[0:a]atrim=start={st}:end={en},asetpts=PTS-STARTPTS[a{i}]")
            labels.append(f"[v{i}][a{i}]")
        parts.append(f"{''.join(labels)}concat=n={len(segs)}:v=1:a=1[v][a]")
        cmd = head + [
            *INPUT_GUARD,
            "-i",
            str(src),
            "-filter_complex",
            ";".join(parts),
            "-map",
            "[v]",
            "-map",
            "[a]",
            *X264_ARGS,
            *AAC_ARGS,
        ]
    else:
        listp = staging / "concat.txt"
        lines = []
        for s in segs:
            lines.append(f"file '{_concat_quote(src)}'")
            lines.append(f"inpoint {s['start_s']}")
            lines.append(f"outpoint {s['end_s']}")
        prep[listp] = "\n".join(lines) + "\n"
        # The list is ours; the whitelist reaches the file it names too (ffmpeg hands it down).
        guard = ["-format_whitelist", "concat," + INPUT_GUARD[1]]
        cmd = head + ["-f", "concat", "-safe", "0", *guard, "-i", str(listp), "-c", "copy"]

    if out_ext in ("mp4", "m4a", "mov"):
        cmd += ["-movflags", "+faststart"]
    cmd += [str(dest)]
    return cmd, prep


def _parse_out_time(line: str) -> float | None:
    """Parse a `-progress` line into elapsed output seconds."""
    if line.startswith("out_time_us="):
        try:
            return int(line.split("=", 1)[1]) / 1_000_000
        # silent-ok: one line of ffmpeg's `-progress` stream, several per second. None means "this
        # line carried no usable time", which the caller already treats as "no progress yet".
        except ValueError:
            return None
    if line.startswith("out_time_ms="):  # (some builds mislabel this as microseconds)
        try:
            return int(line.split("=", 1)[1]) / 1_000_000
        # silent-ok: as above, the other spelling of the same line.
        except ValueError:
            return None
    return None


# No output on `-progress pipe:1` for this long means ffmpeg is wedged (a stuck network source, a
# hung filter) — a download job may legitimately be slow, but it is never SILENT for minutes.
_FFMPEG_STALL_TIMEOUT_S = 600.0
# Hard cap after we ask the process to go away; past it we stop waiting on it altogether.
_FFMPEG_EXIT_GRACE_S = 10.0


def _pump(stream, sink: "queue.Queue[str | None]") -> None:
    """Read a text pipe to EOF into a queue (None = EOF). Runs in its own thread so the main loop
    can time out and poll cancel instead of blocking forever on a silent ffmpeg."""
    try:
        for line in stream:
            sink.put(line)
    # silent-ok: the pipe was closed under us by our OWN kill path — the expected end of a
    # cancelled or timed-out run, and the code that did the killing is the code that reports it.
    except (ValueError, OSError):
        pass
    finally:
        sink.put(None)


def _drain_tail(stream, sink: list[str]) -> None:
    """Consume a pipe to EOF, keeping only its tail.

    ffmpeg's stderr MUST be read *while it runs*: the OS pipe buffer is ~64KB, and once it fills,
    ffmpeg blocks forever on its next write — the process never exits, so `proc.wait()` never
    returns and the worker thread is gone for good. Reading it only after the exit (as this used
    to) is exactly the deadlock."""
    try:
        for line in stream:
            sink.append(line)
            if len(sink) > 200:
                del sink[:100]
    # silent-ok: same closed pipe as `_pump` above, and the tail collected so far is still handed
    # to whoever reports the failure.
    except (ValueError, OSError):
        pass


def escalate_kill(proc: subprocess.Popen, terminate, kill, grace_s: float, label: str) -> None:
    """terminate → wait(grace) → kill → wait(grace) escalation for a process we've given up on, so it
    is never waited on unboundedly. `terminate`/`kill` deliver the stop to whatever scope the caller
    owns — a single process (`proc.terminate`/`proc.kill`) or its whole group (`os.killpg`). No-op if
    the process already exited."""
    if proc.poll() is not None:
        return
    terminate()
    try:
        proc.wait(timeout=grace_s)
        return
    # silent-ok: the escalation below IS the handling of this timeout, and surviving THAT is what
    # the line under the second wait reports.
    except subprocess.TimeoutExpired:
        pass
    kill()
    try:
        proc.wait(timeout=grace_s)
    except subprocess.TimeoutExpired:
        # TRY400: the exception IS the message here. A TimeoutExpired's traceback is this
        # `wait` call and nothing else — it would add three frames and no fact the line lacks.
        log.error("%s pid %s survived SIGKILL", label, proc.pid)  # noqa: TRY400


def _stop(proc: subprocess.Popen) -> None:
    """Terminate, then kill — never wait unbounded on a process we've given up on. Safe to call on
    a process that already exited."""
    escalate_kill(proc, proc.terminate, proc.kill, grace_s=5, label="ffmpeg")


def run_ffmpeg(
    cmd, total_s, on_progress, should_cancel, stall_timeout_s=_FFMPEG_STALL_TIMEOUT_S
) -> None:
    """Run an ffmpeg edit, reporting 0–100 progress and honouring cooperative cancel.

    Both pipes are drained by threads (see `_drain_tail`) and the main loop polls on a 1s tick, so
    cancel is honoured within a second even while ffmpeg is quiet, and a wedged process is killed
    by the stall watchdog instead of pinning a worker thread forever.

    Raises EditAborted if should_cancel() turns True mid-run, RuntimeError on a nonzero exit or a
    stall."""
    proc = subprocess.Popen(
        cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, bufsize=1
    )
    err_tail: list[str] = []
    lines: queue.Queue[str | None] = queue.Queue()
    readers = [
        threading.Thread(target=_pump, args=(proc.stdout, lines), daemon=True),
        threading.Thread(target=_drain_tail, args=(proc.stderr, err_tail), daemon=True),
    ]
    for t in readers:
        t.start()
    try:
        last_output = time.monotonic()
        while True:
            try:
                line = lines.get(timeout=1.0)
            # silent-ok: not a failure — the one-second timeout is how this loop gets a turn to
            # poll for cancellation while ffmpeg is quiet.
            except queue.Empty:
                line = ""
            if line is None:  # stdout hit EOF — ffmpeg is done (or dying)
                break
            if line:
                last_output = time.monotonic()
                secs = _parse_out_time(line.strip())
                if secs is not None and total_s:
                    on_progress(max(0.0, min(99.0, secs * 100.0 / total_s)))
            if should_cancel():
                raise EditAborted
            if time.monotonic() - last_output > stall_timeout_s:
                raise StatedFailure(f"ffmpeg stalled: no progress for {int(stall_timeout_s)}s")
        try:
            ret = proc.wait(timeout=_FFMPEG_EXIT_GRACE_S)
        except subprocess.TimeoutExpired:  # pipes closed but the process lingers
            raise StatedFailure("ffmpeg did not exit after closing its output") from None
    except BaseException:
        # ONE exit path stops the process, so the invariant is unconditional: nothing leaves this
        # function with ffmpeg still running. Not just our own EditAborted/stall — `on_progress`
        # writes to the database, and an exception from THERE used to unwind past a live process,
        # orphaning it (still encoding, no one left to reap it) after a 10s join on its pipes.
        _stop(proc)
        raise
    finally:
        for t in readers:
            t.join(timeout=_FFMPEG_EXIT_GRACE_S)
        for pipe in (proc.stdout, proc.stderr):
            if pipe:
                pipe.close()
    if ret != 0:
        raise StatedFailure(f"ffmpeg failed ({ret}): {''.join(err_tail)[-300:]}")


# --- ffprobe ---------------------------------------------------------------------------------


def run_ffprobe_json(
    path: Path,
    *,
    show_streams: bool = False,
    show_format: bool = False,
    entries: str | None = None,
) -> dict | None:
    """One ffprobe call → its parsed JSON dict, or None on any failure (timeout, non-zero exit,
    missing binary, unparseable output). The SINGLE ffprobe-JSON-invocation point in the downloads
    package: the shared media probe (`probe.probe_json`: the stored facts and the phone-safe rule) goes
    through it, so the
    subprocess flags/timeout/error handling live in one place instead of drifting copies."""
    args = ["ffprobe", "-v", "error", *INPUT_GUARD]
    if show_streams:
        args.append("-show_streams")
    if show_format:
        args.append("-show_format")
    if entries:
        args += ["-show_entries", entries]
    args += ["-of", "json", str(path)]
    try:
        out = subprocess.run(args, capture_output=True, text=True, timeout=30, check=True).stdout
        return json.loads(out)
    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError, ValueError) as exc:
        # None makes every field it would have filled read as absent, and a file with no streams
        # and no duration is indistinguishable here from one that is not media at all.
        log.warning(
            "ffprobe could not read a file",
            extra=logs.event("media.ffprobe_failed", reason=type(exc).__name__),
        )
        return None


def probe_duration(path: Path) -> int:
    """Media duration in whole seconds via ffprobe, or 0 if unknown — a progress denominator for a
    re-encode when the yt-dlp info dict carried no `duration` (some URL/live extractions)."""
    try:
        out = subprocess.run(
            [
                "ffprobe",
                "-v",
                "error",
                *INPUT_GUARD,
                "-show_entries",
                "format=duration",
                "-of",
                "default=nw=1:nk=1",
                str(path),
            ],
            capture_output=True,
            text=True,
            timeout=30,
            check=True,
        ).stdout.strip()
        return int(float(out)) if out else 0
    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError, ValueError) as exc:
        # Zero is the denominator of the re-encode progress bar, so a failed probe leaves the user
        # watching a bar that never moves rather than a job that says it went wrong.
        log.info(
            "the duration probe failed; progress for this job has no total",
            extra=logs.event("media.duration_probe_failed", reason=type(exc).__name__),
        )
        return 0


# --- filmstrip (editor scrub track) ---------------------------------------------------------

_SB_COLS = 12
_SB_TILE_W = 160


def storyboard_geometry(duration_s: int | None) -> dict:
    """Deterministic sprite geometry for a source duration (so meta is recomputable, unstored).

    ~1 frame / 5 s, clamped to fill a 12-wide grid of 24–120 tiles."""
    dur = max(1, int(duration_s or 1))
    count = max(24, min(120, round(dur / 5)))
    rows = math.ceil(count / _SB_COLS)
    count = _SB_COLS * rows  # fill the grid exactly
    return {
        "cols": _SB_COLS,
        "rows": rows,
        "count": count,
        "interval_s": dur / count,
        "tile_w": _SB_TILE_W,
    }


def build_storyboard_cmd(src: Path, dest: Path, duration_s: int | None, geom: dict) -> list[str]:
    """One-pass tiled sprite. fps picks `count` frames evenly across the whole clip."""
    dur = max(1, int(duration_s or 1))
    fps = geom["count"] / dur
    vf = f"fps={fps:.6f},scale={_SB_TILE_W}:-2,tile={geom['cols']}x{geom['rows']}"
    return [
        "ffmpeg",
        "-y",
        "-hide_banner",
        "-loglevel",
        "error",
        "-nostdin",
        *INPUT_GUARD,
        "-i",
        str(src),
        "-frames:v",
        "1",
        "-q:v",
        "5",
        "-vf",
        vf,
        str(dest),
    ]


def build_poster_cmd(src: Path, dest: Path, at_s: float) -> list[str]:
    """Grab one representative frame as a poster JPEG. `-ss` before `-i` seeks fast."""
    return [
        "ffmpeg",
        "-y",
        "-hide_banner",
        "-loglevel",
        "error",
        "-nostdin",
        "-ss",
        f"{max(0.0, at_s):.3f}",
        *INPUT_GUARD,
        "-i",
        str(src),
        "-frames:v",
        "1",
        "-q:v",
        "3",
        "-vf",
        "scale=640:-2",
        str(dest),
    ]


def build_thumbnail_jpg_cmd(src: Path, dest: Path) -> list[str]:
    """Decode a downloaded thumbnail (webp/png/…) to a single baseline JPEG frame."""
    return [
        "ffmpeg",
        "-y",
        "-hide_banner",
        "-loglevel",
        "error",
        "-nostdin",
        *THUMB_GUARD,
        "-i",
        str(src),
        "-frames:v",
        "1",
        "-update",
        "1",
        str(dest),
    ]


def _run_ffmpeg_best_effort(cmd: list[str], timeout_s: int) -> Exception | None:
    """Run a one-shot ffmpeg command, bounded by `timeout_s`. Returns None on success, or the
    exception on a timeout/non-zero-exit/OS error — never raises. Shared by the best-effort image
    steps (poster / thumbnail / storyboard) so the run+timeout+swallow policy lives in ONE place;
    each caller logs its own context from the returned exception. (The download/transcode path uses
    the richer `run_ffmpeg` instead, which streams progress and honours cooperative cancel.)"""
    try:
        subprocess.run(cmd, capture_output=True, timeout=timeout_s, check=True)
        return None
    # silent-ok: the exception is the RETURN VALUE. This helper exists so the three callers share
    # one run/timeout policy, and each logs the failure with the context only it has.
    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError) as exc:
        return exc


def _step_failure(err: BaseException) -> str:
    """What a best-effort image step's failure line says: the kind and, for ffmpeg, its exit
    status. Never `str(err)`: a CalledProcessError or TimeoutExpired quotes ffmpeg's argv, and an
    OSError its file name — the source path either way, which is built from the channel and the
    title."""
    code = getattr(err, "returncode", None)
    return f"{type(err).__name__} {code}" if code is not None else type(err).__name__


def _is_jpeg(path: Path) -> bool:
    """True if the file starts with the JPEG SOI marker (0xFF 0xD8 0xFF)."""
    try:
        with path.open("rb") as f:
            return f.read(3) == b"\xff\xd8\xff"
    # silent-ok: False only means "do not copy this straight through" — the caller then goes the
    # ffmpeg route, which opens the same file and reports it properly if it really is unreadable.
    except OSError:
        return False


def thumbnail_to_jpg(src: Path | None, dest: Path, timeout_s: int = 30) -> Path | None:
    """Turn a downloaded thumbnail (webp / png / jpeg — whatever the source shipped) into a real
    baseline JPEG for the `<name>.jpg` poster + og:image share sidecar.

    Deliberately NOT yt-dlp's `FFmpegThumbnailsConvertor` (whose `-bsf:v mjpeg2jpeg` path crashes on
    some already-JPEG thumbnails, e.g. Reddit's, and used to fail the entire download). A thumbnail
    that is already JPEG is copied as-is; anything else is decoded via ffmpeg. Best-effort: returns
    None on any failure, so the caller falls back to a cut video frame (`ensure_poster`) and the
    download still succeeds."""
    if src is None or not src.exists():
        return None
    if _is_jpeg(src):  # already JPEG (e.g. Facebook) — no decode/re-encode needed
        try:
            shutil.copyfile(src, dest)
            return dest
        except OSError as exc:
            log.info(
                "thumbnail copy failed (%s); poster falls back to a cut frame", _step_failure(exc)
            )
            return None
    err = _run_ffmpeg_best_effort(build_thumbnail_jpg_cmd(src, dest), timeout_s)
    if err is not None:
        log.info(
            "thumbnail->jpg conversion failed (%s); poster falls back to a cut frame",
            _step_failure(err),
        )
        return None
    return dest if dest.exists() else None


def ensure_poster(asset, download_root: str, timeout_s: int = 30) -> str | None:
    """Generate a poster frame for a ready asset that has no thumbnail (e.g. a direct media URL
    like a reddit HLS manifest, which yt-dlp can't get a thumbnail for). Written as the media's
    `<base>.jpg` sidecar — so Plex uses it too and `delete_asset_files` cleans it up — and returned
    as a rel path (or None on failure). Best-effort + time-bounded; a few seconds in (or 10% of a
    short clip) dodges black intro frames."""
    if not asset.rel_path:
        return None
    root = Path(download_root)
    src = root / asset.rel_path
    if not src.exists():
        return None
    rel = str(Path(asset.rel_path).with_suffix(".jpg"))
    dest = root / rel
    if dest.exists():
        return rel
    at = min(3.0, (asset.duration_s or 10) * 0.1)
    err = _run_ffmpeg_best_effort(build_poster_cmd(src, dest, at), timeout_s)
    if err is not None:
        log.info("poster gen skipped for asset %s: %s", asset.id, _step_failure(err))
        return None
    return rel if dest.exists() else None


def ensure_storyboard(asset, download_root: str, timeout_s: int = 90) -> dict | None:
    """Return the filmstrip meta for a ready source asset, generating the sprite on first use.

    Best-effort + time-bounded: for a very long/high-res source the one-pass decode can be slow,
    so it's capped by `timeout_s`; on timeout/failure we return None and the editor falls back to
    a plain timeline (no filmstrip). Caches the sprite path on `asset.storyboard_path`.

    Returns None (caller should NOT commit) if generation didn't happen; otherwise a meta dict and
    sets `asset.storyboard_path` (caller commits)."""
    if not asset.rel_path:
        return None
    geom = storyboard_geometry(asset.duration_s)
    root = Path(download_root)
    rel = f".storyboards/asset-{asset.id}.jpg"
    dest = root / rel

    if asset.storyboard_path and (root / asset.storyboard_path).exists():
        return {**geom, "rel": asset.storyboard_path}

    src = root / asset.rel_path
    if not src.exists():
        return None
    dest.parent.mkdir(parents=True, exist_ok=True)
    cmd = build_storyboard_cmd(src, dest, asset.duration_s, geom)
    err = _run_ffmpeg_best_effort(cmd, timeout_s)
    if err is not None:
        log.info("storyboard gen skipped for asset %s: %s", asset.id, _step_failure(err))
        return None
    if not dest.exists():
        return None
    asset.storyboard_path = rel  # caller commits
    return {**geom, "rel": rel}