dtoro/mule-image
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(playback): pre-transcode HEVC videos in background; veryfast preset

Browse Source 
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.
This commit is contained in:
Claudio
2026-05-12 00:03:15 +02:00
parent 2a5270d399
commit c4df92720b
6 changed files with 253 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
backend/app/routers/library.py
View File

@@ -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

142
backend/app/routers/photos.py
View File

@@ -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')

132
backend/app/services/video.py Normal file
View File

@@ -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

5
backend/app/tasks/celery.py
View File

@@ -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

11
backend/app/tasks/scan.py
View File

@@ -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()

62
backend/app/tasks/video.py Normal file
View File

@@ -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,
}