From c4df92720b1f8cb27e535d0802606ba2b1e67f80 Mon Sep 17 00:00:00 2001
From: Claudio <claudio@hubris.network>
Date: Tue, 12 May 2026 00:03:15 +0200
Subject: [PATCH] feat(playback): pre-transcode HEVC videos in background;
 veryfast preset

Long videos blocked /playback for the entire encode duration. The fix
is to populate the cache before the user clicks, not when they click.

Changes:
- Extract ffprobe + ffmpeg helpers to services/video.py so the request
  handler and the background task share one sync implementation. The
  endpoint wraps calls in asyncio.to_thread; celery just calls them.
- New tasks/video.py with pretranscode_video. Idempotent: skips when
  the cache is already current and skips passthrough-safe sources
  (h264 in mp4/m4v/webm). 30-min task time limit so the long-tail
  files (3GP archive, multi-minute 1080p clips) still complete.
- scan_folder now dispatches pretranscode_video alongside
  generate_thumbnails / extract_metadata for any new video row.
- POST /library/maintenance/backfill-video-cache enqueues every
  active video so the existing library catches up.
- libx264 preset bumped from fast to veryfast. ~2x throughput on this
  CPU-only box, output a few % larger but well within disk budget.
- /playback simplifies to: cache check, passthrough if h264 in
  web-safe container, else sync transcode (still there as fallback
  for races against the queued task).

Once the backfill task drains, /playback should be near-instant for
every video. Any video added afterwards is pre-transcoded at scan
time, so the user keeps that property going forward.
---
 backend/app/routers/library.py |  28 +++++++
 backend/app/routers/photos.py  | 142 ++++-----------------------------
 backend/app/services/video.py  | 132 ++++++++++++++++++++++++++++++
 backend/app/tasks/celery.py    |   5 ++
 backend/app/tasks/scan.py      |  11 +++
 backend/app/tasks/video.py     |  62 ++++++++++++++
 6 files changed, 253 insertions(+), 127 deletions(-)
 create mode 100644 backend/app/services/video.py
 create mode 100644 backend/app/tasks/video.py

diff --git a/backend/app/routers/library.py b/backend/app/routers/library.py
index baf9ed6..6cf4470 100644
--- a/backend/app/routers/library.py
+++ b/backend/app/routers/library.py
@@ -842,6 +842,34 @@ async def trigger_backfill_phashes(current_user: User = Depends(get_current_user
         return {"status": "error", "message": str(e)}
 
 
+@router.post("/maintenance/backfill-video-cache")
+async def trigger_backfill_video_cache(
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    """Pre-transcode every active video in the library so /playback hits
+    the cache on first user click instead of paying the encode cost
+    inline. Idempotent — pretranscode_video skips photos whose cache is
+    already populated and current. CPU-bound; runs on the low-priority
+    queue so it doesn't fight thumbnails or other user-facing tasks."""
+    from app.tasks.video import pretranscode_video
+    result = await db.execute(
+        select(Photo.id, Photo.filepath).where(
+            Photo.media_type == 'video',
+            Photo.is_discarded.is_(False),
+        )
+    )
+    rows = result.all()
+    queued = 0
+    for photo_id, filepath in rows:
+        try:
+            pretranscode_video.delay(photo_id, filepath)
+            queued += 1
+        except Exception as e:
+            logger.warning(f"failed to queue pretranscode for {photo_id}: {e}")
+    return {"status": "queued", "count": queued}
+
+
 @router.post("/maintenance/start-watcher")
 async def start_file_watcher(current_user: User = Depends(get_current_user)):
     """Start the filesystem watcher. Uses a Redis lock so only one
diff --git a/backend/app/routers/photos.py b/backend/app/routers/photos.py
index 6392693..d161374 100644
--- a/backend/app/routers/photos.py
+++ b/backend/app/routers/photos.py
@@ -14,7 +14,6 @@ import asyncio
 import base64
 import json
 import os
-import subprocess
 import logging
 
 logger = logging.getLogger(__name__)
@@ -28,6 +27,7 @@ from app.models.tags import photo_tags
 from app.schemas.photos import PhotoResponse, PhotoUpdate, PhotoListResponse, BulkAction
 from app.services.exif_writer import ExifWriteError, write_taken_at
 from app.services.date_guess import has_date_warning as compute_date_warning
+from app.services import video as video_service
 from app.dependencies import (
     get_current_user, get_current_user_media, get_user_photo,
     get_user_or_shared_heap, get_user_or_shared_folder,
@@ -854,23 +854,6 @@ async def get_original(
     )
 
 
-# Cached H.264/MP4 transcodes for /playback. iPhone shoots HEVC Main 10 by
-# default and Chrome/Firefox can't decode 10-bit HEVC reliably, so anything
-# that isn't already h264 in a web-safe container gets transcoded once and
-# served from this directory thereafter.
-_VIDEO_CACHE_DIR = Path('/data/video-cache')
-_VIDEO_CACHE_DIR.mkdir(parents=True, exist_ok=True)
-
-# Video codecs that play in <video> across the major browsers without
-# re-encoding. AV1 / VP9 are technically web-safe in webm but we only have
-# h264 source material in practice; expand if that changes.
-_PLAYBACK_OK_VCODECS = {'h264', 'avc1'}
-# Container extensions we trust to passthrough when the codec is OK. .mov
-# is excluded — Chrome/Firefox refuse to play even h264 inside a .mov
-# container reliably, so we always remux .mov to .mp4 via the cache path.
-_PLAYBACK_OK_EXTS = {'.mp4', '.m4v', '.webm'}
-
-
 def _serve_file_with_range(
     path: str,
     request: Request,
@@ -920,97 +903,6 @@ def _serve_file_with_range(
     )
 
 
-async def _ffprobe_video_codec(path: str) -> Optional[str]:
-    """Return the video stream's codec_name (e.g. 'hevc', 'h264'), or None
-    on probe failure. Used to decide passthrough vs transcode in /playback."""
-    def _run():
-        return subprocess.run(
-            [
-                'ffprobe', '-v', 'error',
-                '-select_streams', 'v:0',
-                '-show_entries', 'stream=codec_name',
-                '-of', 'default=noprint_wrappers=1:nokey=1',
-                path,
-            ],
-            capture_output=True, text=True, timeout=10,
-        )
-    try:
-        result = await asyncio.to_thread(_run)
-    except (subprocess.TimeoutExpired, OSError) as e:
-        logger.warning(f"ffprobe failed for {path}: {e}")
-        return None
-    if result.returncode != 0:
-        logger.warning(
-            f"ffprobe returned {result.returncode} for {path}: "
-            f"{(result.stderr or '').strip()[:200]}"
-        )
-        return None
-    out = (result.stdout or '').strip().lower()
-    return out or None
-
-
-async def _transcode_to_h264_mp4(src: str, dst: str) -> bool:
-    """Transcode `src` to H.264 8-bit MP4 at `dst`. Returns True on success.
-
-    -pix_fmt yuv420p forces 8-bit output so 10-bit HEVC sources still play
-    on browsers that lack 10-bit decode. Audio is re-encoded to AAC because
-    the iPhone 16's APAC stream isn't decodable in browsers, and even when
-    the source audio is already AAC the cost of re-encoding is negligible
-    next to the video pass. +faststart moves the moov atom to the front
-    of the file so playback can start before the whole download completes.
-    Atomic via tmp file + os.replace so a failed run never leaves a
-    half-written .mp4 in the cache.
-    """
-    tmp = dst + '.tmp'
-    def _run():
-        return subprocess.run(
-            [
-                'ffmpeg', '-y', '-loglevel', 'error',
-                '-i', src,
-                '-map', '0:v:0',
-                '-map', '0:a:0?',
-                '-c:v', 'libx264',
-                '-preset', 'fast',
-                '-crf', '23',
-                '-pix_fmt', 'yuv420p',
-                '-c:a', 'aac',
-                '-b:a', '160k',
-                '-movflags', '+faststart',
-                # tmp filename ends in `.tmp`, which ffmpeg can't map to
-                # an output muxer — force the mp4 muxer explicitly so the
-                # name is just storage scratch, not a format hint.
-                '-f', 'mp4',
-                tmp,
-            ],
-            capture_output=True, text=True, timeout=600,
-        )
-    try:
-        result = await asyncio.to_thread(_run)
-    except (subprocess.TimeoutExpired, OSError) as e:
-        logger.error(f"ffmpeg transcode failed for {src}: {e}")
-        try:
-            os.remove(tmp)
-        except OSError:
-            pass
-        return False
-    if result.returncode != 0:
-        logger.error(
-            f"ffmpeg returned {result.returncode} for {src}: "
-            f"{(result.stderr or '').strip()[:500]}"
-        )
-        try:
-            os.remove(tmp)
-        except OSError:
-            pass
-        return False
-    try:
-        os.replace(tmp, dst)
-    except OSError as e:
-        logger.error(f"failed to publish transcoded {dst}: {e}")
-        return False
-    return True
-
-
 @router.get("/{photo_id}/playback")
 async def get_playback(
     photo_id: str,
@@ -1022,20 +914,17 @@ async def get_playback(
 
     iPhone .mov files are HEVC Main 10 (codec_tag hvc1), which Chrome and
     Firefox cannot decode reliably — Safari is the only browser that
-    handles 10-bit HEVC out of the box. This endpoint transcodes to H.264
-    8-bit MP4 on first hit, caches under /data/video-cache/{id}.mp4, and
-    serves with HTTP Range like /original. Web-safe inputs (h264 in
-    mp4/webm) skip the transcode and stream the original.
-
-    First-hit latency for an HEVC video is dominated by ffmpeg — typically
-    a few seconds per video-second on CPU. Subsequent hits serve straight
-    from the cache."""
+    handles 10-bit HEVC out of the box. New video rows are pre-transcoded
+    by `pretranscode_video` from scan_folder, so the typical hit here
+    serves straight from `/data/video-cache/{id}.mp4`. The sync
+    transcode-on-miss path stays as a fallback for backfill races and
+    pre-existing rows that haven't run through the celery task yet."""
     photo = await _get_photo_with_share_fallback(photo_id, current_user, db)
     if not os.path.exists(photo.filepath):
         raise HTTPException(status_code=404, detail="File not found")
 
     src_path = photo.filepath
-    cache_path = _VIDEO_CACHE_DIR / f'{photo.id}.mp4'
+    cache_path = video_service.cache_path_for(photo.id)
 
     # Source-newer-than-cache invalidates the cache. Covers in-place file
     # replacement (re-upload via NC) without leaving stale playback bytes.
@@ -1051,21 +940,20 @@ async def get_playback(
 
     # Passthrough fast path: source is already h264 in a web-safe container.
     ext = Path(src_path).suffix.lower()
-    if ext in _PLAYBACK_OK_EXTS:
-        codec = await _ffprobe_video_codec(src_path)
-        if codec in _PLAYBACK_OK_VCODECS:
+    if ext in video_service.PLAYBACK_OK_EXTS:
+        codec = await asyncio.to_thread(video_service.ffprobe_video_codec, src_path)
+        if codec in video_service.PLAYBACK_OK_VCODECS:
             return _serve_file_with_range(
                 src_path,
                 request,
                 _INLINE_MEDIA_TYPES.get(ext, 'video/mp4'),
             )
 
-    # Transcode-and-cache path. Sync inside the request because the
-    # browser's <video> can't deal with a 202 response — better to make
-    # the user wait once than to ship a UX that pretends the video isn't
-    # there. If this becomes a bottleneck for long videos, lift it into
-    # a celery task with an async polling endpoint.
-    ok = await _transcode_to_h264_mp4(src_path, str(cache_path))
+    # Cache miss + needs transcode: sync fallback. Long videos are the
+    # painful case — they're why pretranscode_video runs at scan time.
+    ok = await asyncio.to_thread(
+        video_service.transcode_to_h264_mp4, src_path, str(cache_path),
+    )
     if not ok:
         raise HTTPException(status_code=500, detail="Video transcoding failed")
     return _serve_file_with_range(str(cache_path), request, 'video/mp4')
diff --git a/backend/app/services/video.py b/backend/app/services/video.py
new file mode 100644
index 0000000..54c5b0b
--- /dev/null
+++ b/backend/app/services/video.py
@@ -0,0 +1,132 @@
+"""Shared video helpers used by the /playback endpoint and the
+pretranscode celery task.
+
+The actual ffmpeg/ffprobe work is sync (subprocess.run); FastAPI
+handlers wrap calls in asyncio.to_thread, celery just calls them
+directly. Keeping a single sync implementation avoids drift between
+the request-time fallback and the background pre-transcode."""
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+
+logger = logging.getLogger(__name__)
+
+
+# On-disk cache of browser-playable transcodes. Backed by /data which is
+# the persistent volume in mulita-backend / mulita-worker-light.
+VIDEO_CACHE_DIR = Path('/data/video-cache')
+VIDEO_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+# Codecs the browser can play in <video> across Chrome / Firefox / Safari
+# without re-encoding. h264 covers everything practical we have on disk;
+# add av1 / vp9 here if the source library ever picks those up.
+PLAYBACK_OK_VCODECS = {'h264', 'avc1'}
+
+# Container extensions that we trust to passthrough when the codec is
+# OK. .mov is intentionally excluded — Chrome and Firefox refuse to
+# play even h264-in-mov reliably, so .mov always goes through the cache.
+PLAYBACK_OK_EXTS = {'.mp4', '.m4v', '.webm'}
+
+
+def cache_path_for(photo_id: str) -> Path:
+    """Where the transcoded MP4 lives for a given photo id."""
+    return VIDEO_CACHE_DIR / f'{photo_id}.mp4'
+
+
+def ffprobe_video_codec(path: str) -> Optional[str]:
+    """Return the video stream's codec_name (lowercased) or None on
+    probe failure. ~50ms for typical files."""
+    try:
+        result = subprocess.run(
+            [
+                'ffprobe', '-v', 'error',
+                '-select_streams', 'v:0',
+                '-show_entries', 'stream=codec_name',
+                '-of', 'default=noprint_wrappers=1:nokey=1',
+                path,
+            ],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (subprocess.TimeoutExpired, OSError) as e:
+        logger.warning("ffprobe failed for %s: %s", path, e)
+        return None
+    if result.returncode != 0:
+        logger.warning(
+            "ffprobe rc=%s for %s: %s",
+            result.returncode, path, (result.stderr or '').strip()[:200],
+        )
+        return None
+    return ((result.stdout or '').strip().lower()) or None
+
+
+def needs_transcode(src_path: str) -> bool:
+    """True when /playback would have to encode rather than passthrough.
+    Uses extension first (cheap), only ffprobes when the container is
+    plausibly web-safe."""
+    ext = Path(src_path).suffix.lower()
+    if ext not in PLAYBACK_OK_EXTS:
+        return True
+    return ffprobe_video_codec(src_path) not in PLAYBACK_OK_VCODECS
+
+
+def transcode_to_h264_mp4(src: str, dst: str, *, timeout: int = 3600) -> bool:
+    """Transcode `src` to H.264 8-bit MP4 at `dst`. Returns True on
+    success.
+
+    -pix_fmt yuv420p forces 8-bit output so 10-bit HEVC sources still
+    play on browsers without 10-bit decode. Audio is always re-encoded
+    to AAC because iPhone 16 ships APAC audio that browsers can't
+    decode, and the audio pass is cheap next to the video pass.
+    +faststart relocates the moov atom so progressive playback works.
+
+    Atomic publish via tmp + os.replace so a failed run never leaves a
+    half-written .mp4 in the cache. -f mp4 forces the muxer because the
+    .tmp suffix isn't a format hint ffmpeg recognises."""
+    tmp = dst + '.tmp'
+    try:
+        result = subprocess.run(
+            [
+                'ffmpeg', '-y', '-loglevel', 'error',
+                '-i', src,
+                '-map', '0:v:0',
+                '-map', '0:a:0?',
+                '-c:v', 'libx264',
+                '-preset', 'veryfast',
+                '-crf', '23',
+                '-pix_fmt', 'yuv420p',
+                '-c:a', 'aac',
+                '-b:a', '160k',
+                '-movflags', '+faststart',
+                '-f', 'mp4',
+                tmp,
+            ],
+            capture_output=True, text=True, timeout=timeout,
+        )
+    except (subprocess.TimeoutExpired, OSError) as e:
+        logger.error("ffmpeg failed for %s: %s", src, e)
+        try:
+            os.remove(tmp)
+        except OSError:
+            pass
+        return False
+    if result.returncode != 0:
+        logger.error(
+            "ffmpeg rc=%s for %s: %s",
+            result.returncode, src, (result.stderr or '').strip()[:500],
+        )
+        try:
+            os.remove(tmp)
+        except OSError:
+            pass
+        return False
+    try:
+        os.replace(tmp, dst)
+    except OSError as e:
+        logger.error("failed to publish transcoded %s: %s", dst, e)
+        return False
+    return True
diff --git a/backend/app/tasks/celery.py b/backend/app/tasks/celery.py
index 7439001..93a42d8 100644
--- a/backend/app/tasks/celery.py
+++ b/backend/app/tasks/celery.py
@@ -18,6 +18,7 @@ celery_app = Celery(
     include=[
         'app.tasks.scan',
         'app.tasks.thumbs',
+        'app.tasks.video',
         'app.tasks.vision',
         'app.services.metadata',   # extract_metadata lives here
     ]
@@ -52,6 +53,10 @@ celery_app.conf.update(
         'scan_folder': {'queue': 'low'},
         'scan_all_source_roots': {'queue': 'low'},
         'backfill_gps': {'queue': 'low'},
+        # Pre-transcode HEVC videos in the background so /playback is a
+        # cache hit on first user click. CPU-heavy but tolerant of the
+        # low-priority queue (it doesn't block any user-facing flow).
+        'pretranscode_video': {'queue': 'low'},
         # `watch_folders` is retired (file events come from NC webhooks)
         # but the task definition still exists as a no-op shim for any
         # in-flight apply_async. Route it to the default queue so the
diff --git a/backend/app/tasks/scan.py b/backend/app/tasks/scan.py
index 27f8d9b..6e15a01 100644
--- a/backend/app/tasks/scan.py
+++ b/backend/app/tasks/scan.py
@@ -20,6 +20,7 @@ from app.database import AsyncSessionLocal
 from app.models import Photo, Folder, SourceRoot
 from app.config import settings
 from app.tasks.thumbs import generate_thumbnails
+from app.tasks.video import pretranscode_video
 from app.services.metadata import extract_metadata
 from app.services.date_guess import has_date_warning
 
@@ -195,6 +196,7 @@ async def _scan_folder_async(folder_path: str, source_root_id: Optional[str], ta
                     # Defer task dispatch until AFTER commit so workers don't
                     # query for rows that aren't visible to other sessions yet.
                     pending_dispatch: list[str] = []
+                    pending_video_pretranscode: list[tuple[str, str]] = []
 
                     for filename in batch:
                         filepath = os.path.join(root, filename)
@@ -316,6 +318,13 @@ async def _scan_folder_async(folder_path: str, source_root_id: Optional[str], ta
                             # below; otherwise the worker can race the writer
                             # and see "Photo not found".
                             pending_dispatch.append(photo.id)
+                            if photo.media_type == 'video':
+                                # Pre-transcode HEVC and other non-web-safe
+                                # videos at scan time so the user doesn't
+                                # pay the encode cost on first <video> click.
+                                pending_video_pretranscode.append(
+                                    (photo.id, filepath)
+                                )
 
                             processed_files += 1
                             progress_set(REDIS_KEY_PROCESSED, processed_files)
@@ -344,6 +353,8 @@ async def _scan_folder_async(folder_path: str, source_root_id: Optional[str], ta
                     for photo_id in pending_dispatch:
                         generate_thumbnails.delay(photo_id)
                         extract_metadata.delay(photo_id)
+                    for vid_photo_id, vid_path in pending_video_pretranscode:
+                        pretranscode_video.delay(vid_photo_id, vid_path)
 
             # Update folder scan timestamp
             folder.last_scanned = datetime.utcnow()
diff --git a/backend/app/tasks/video.py b/backend/app/tasks/video.py
new file mode 100644
index 0000000..9f30f52
--- /dev/null
+++ b/backend/app/tasks/video.py
@@ -0,0 +1,62 @@
+"""Background pre-transcode for video photos so /playback is a cache
+hit on first user click. Dispatched from scan_folder when a new video
+row is created, and from the backfill admin endpoint for the existing
+library."""
+from __future__ import annotations
+
+import logging
+import os
+
+from celery import shared_task
+
+from app.services.video import (
+    PLAYBACK_OK_EXTS,
+    PLAYBACK_OK_VCODECS,
+    cache_path_for,
+    ffprobe_video_codec,
+    transcode_to_h264_mp4,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+@shared_task(
+    name='pretranscode_video',
+    # Override the 10-minute global task_time_limit. Long videos (30+ min
+    # raw clips, the occasional .3gp from the 2016 archive) can legitimately
+    # take half an hour to transcode on this CPU-only box.
+    time_limit=1800,
+    soft_time_limit=1740,
+)
+def pretranscode_video(photo_id: str, src_path: str):
+    """Idempotent: skip if cache exists and is newer than source, skip
+    if source is already a passthrough-safe codec/container.
+
+    Reports the outcome as a status string so the admin backfill can
+    summarise. The /playback endpoint also falls back to a sync
+    transcode if the cache miss races a queued task."""
+    if not os.path.exists(src_path):
+        logger.debug("pretranscode skip — source missing: %s", src_path)
+        return {'status': 'missing', 'photo_id': photo_id}
+
+    cache_path = cache_path_for(photo_id)
+    if cache_path.exists():
+        try:
+            if os.path.getmtime(src_path) <= os.path.getmtime(cache_path):
+                return {'status': 'cached', 'photo_id': photo_id}
+            cache_path.unlink()
+        except OSError:
+            pass
+
+    ext = os.path.splitext(src_path)[1].lower()
+    if ext in PLAYBACK_OK_EXTS:
+        codec = ffprobe_video_codec(src_path)
+        if codec in PLAYBACK_OK_VCODECS:
+            return {'status': 'passthrough', 'photo_id': photo_id, 'codec': codec}
+
+    ok = transcode_to_h264_mp4(src_path, str(cache_path))
+    return {
+        'status': 'transcoded' if ok else 'failed',
+        'photo_id': photo_id,
+    }