feat(downloads): editor backend — trim/crop derivatives (phase 2)

Per-user trim/crop clips derived from a finished download via ffmpeg, riding the same
MediaAsset/DownloadJob/worker/quota/GC machinery (asset source_kind='edit', per-user cache key):
- migration 0041: download_jobs job_kind/source_job_id/source_asset_id/edit_spec
- app/downloads/edit.py: spec normalize+sig, ffmpeg trim/crop cmd (fast stream-copy vs frame-
  accurate re-encode, per-edit 'accurate' toggle), progress+cooperative-cancel runner, filmstrip
- service.enqueue_edit; worker _process_edit branch; storage.edit_rel_path (.edits/{user} tree)
- routes: POST /edit, GET /{id}/storyboard(.jpg)

backend/app/downloads/edit.py

@@ -0,0 +1,260 @@
+"""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 logging
+import math
+import subprocess
+from pathlib import Path
+
+log = logging.getLogger("siftlode.edit")
+
+
+class EditAborted(Exception):
+    """Raised by run_ffmpeg when the job was paused/canceled mid-encode."""
+
+
+# --- edit spec ------------------------------------------------------------------------------
+
+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 = {}
+
+    trim = spec.get("trim") or {}
+    if trim:
+        start = max(0.0, float(trim.get("start_s") or 0.0))
+        end_raw = trim.get("end_s")
+        t: dict = {"start_s": round(start, 3)}
+        if end_raw is not None:
+            end = float(end_raw)
+            if 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
+
+    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):
+            c = None
+        if c and c["w"] > 0 and c["h"] > 0 and c["x"] >= 0 and c["y"] >= 0:
+            out["crop"] = c
+
+    # `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."""
+    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 --------------------------------------------------------------------
+
+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 += ["-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 re-encodes with no filter.
+        if crop:
+            cmd += ["-vf", f"crop={crop['w']}:{crop['h']}:{crop['x']}:{crop['y']}"]
+        cmd += [
+            "-c:v", "libx264", "-preset", "veryfast", "-crf", "20",
+            "-c:a", "aac", "-b:a", "192k",
+        ]
+    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 _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
+        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
+        except ValueError:
+            return None
+    return None
+
+
+def run_ffmpeg(cmd, total_s, on_progress, should_cancel) -> None:
+    """Run an ffmpeg edit, reporting 0–100 progress and honouring cooperative cancel.
+
+    Raises EditAborted if should_cancel() turns True mid-run, RuntimeError on a nonzero exit."""
+    proc = subprocess.Popen(
+        cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, bufsize=1
+    )
+    try:
+        assert proc.stdout is not None
+        for line in proc.stdout:
+            line = line.strip()
+            if should_cancel():
+                proc.terminate()
+                try:
+                    proc.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+                raise EditAborted
+            secs = _parse_out_time(line)
+            if secs is not None and total_s:
+                on_progress(max(0.0, min(99.0, secs * 100.0 / total_s)))
+    finally:
+        if proc.stdout:
+            proc.stdout.close()
+    ret = proc.wait()
+    if ret != 0:
+        err = (proc.stderr.read() if proc.stderr else "") or ""
+        raise RuntimeError(f"ffmpeg failed ({ret}): {err[:300]}")
+
+
+# --- 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",
+        "-i", str(src), "-frames:v", "1", "-q:v", "5", "-vf", vf, str(dest),
+    ]
+
+
+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)
+    try:
+        subprocess.run(cmd, capture_output=True, timeout=timeout_s, check=True)
+    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError) as exc:
+        log.info("storyboard gen skipped for asset %s: %s", asset.id, str(exc)[:120])
+        return None
+    if not dest.exists():
+        return None
+    asset.storyboard_path = rel  # caller commits
+    return {**geom, "rel": rel}

backend/app/downloads/service.py

@@ -12,10 +12,19 @@ from sqlalchemy import func, select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
+from app.downloads import edit as editmod
 from app.downloads import formats, quota
 from app.models import Channel, DownloadJob, MediaAsset, Video
 
 
+class EditError(Exception):
+    """Bad edit request (empty spec / source not ready); `reason` is an i18n-mappable key."""
+
+    def __init__(self, reason: str):
+        self.reason = reason
+        super().__init__(reason)
+
+
 def source_url(source_kind: str, source_ref: str) -> str:
     """The URL yt-dlp should fetch. YouTube stores the 11-char id; ad-hoc stores the URL."""
     if source_kind == "youtube":
@@ -121,3 +130,71 @@ def enqueue(
     db.commit()
     db.refresh(job)
     return job
+
+
+def _clip_title(source_title: str | None, display_name: str | None) -> str:
+    if display_name:
+        return display_name[:255]
+    base = source_title or "Clip"
+    return f"{base} (clip)"[:255]
+
+
+def enqueue_edit(
+    db: Session,
+    user_id: int,
+    source_job: DownloadJob,
+    edit_spec: dict,
+    display_name: str | None = None,
+) -> DownloadJob:
+    """Queue a phase-2 editor derivative (trim/crop) of `source_job` for `user_id`.
+
+    The derivative is per-user (never shared-cached): its asset uses `source_kind='edit'` with a
+    cache key that embeds the user id, so an identical re-edit by the same user is a cache hit but
+    it never dedups across users. Reuses the same worker/quota/GC path as a download.
+
+    Raises quota.QuotaExceeded (holdings cap) or EditError (empty spec / source not ready)."""
+    src_asset = db.get(MediaAsset, source_job.asset_id) if source_job.asset_id else None
+    if src_asset is None or src_asset.status != "ready" or not src_asset.rel_path:
+        raise EditError("source_not_ready")
+
+    spec = editmod.normalize_edit_spec(edit_spec)
+    if not spec:
+        raise EditError("empty_edit")
+
+    quota.check_enqueue(db, user_id)
+
+    sig = editmod.edit_sig(spec)
+    ref = f"{user_id}:{src_asset.id}"[:512]
+    asset = get_or_create_asset(db, "edit", ref, sig)
+    if not asset.title:
+        asset.title = _clip_title(src_asset.title, display_name)
+        asset.uploader = src_asset.uploader
+        asset.thumbnail_url = src_asset.thumbnail_url
+        asset.upload_date = src_asset.upload_date
+        asset.duration_s = editmod.clip_duration(spec, src_asset.duration_s)
+
+    job = DownloadJob(
+        user_id=user_id,
+        asset_id=asset.id,
+        job_kind="edit",
+        source_kind="edit",
+        source_ref=ref,
+        source_job_id=source_job.id,
+        source_asset_id=src_asset.id,
+        edit_spec=spec,
+        profile_snapshot={},
+        display_name=display_name or asset.title,
+        status="queued",
+        queue_pos=_next_queue_pos(db),
+    )
+    db.add(job)
+    asset.ref_count = (asset.ref_count or 0) + 1
+
+    if asset.status == "ready":  # identical clip already produced for this user → instant
+        job.status = "done"
+        job.progress = 100
+        asset.last_access_at = datetime.now(timezone.utc)
+
+    db.commit()
+    db.refresh(job)
+    return job

backend/app/downloads/storage.py

@@ -87,6 +87,15 @@ def rel_path(meta: MediaMeta, ext: str, layout: str = "plex") -> str:
     return f"{channel}/Season_{year}/{epname}"
 
 
+def edit_rel_path(user_id: int, asset_id: int, ext: str) -> str:
+    """On-disk path (relative to DOWNLOAD_ROOT) for a phase-2 editor derivative.
+
+    Kept in a per-user `.edits/` tree — device-downloadable via the file endpoint, but NOT part of
+    the Plex library (these are user clips, not canonical episodes; there are no .nfo/poster
+    sidecars). The name is system-decided and bound to the derivative asset id."""
+    return f".edits/{user_id}/clip_{asset_id}.{ext}"
+
+
 def abs_path(download_root: str, rel: str) -> Path:
     return Path(download_root) / rel