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.
This commit is contained in:
Claudio
@@ -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
|
||||
|
||||
@@ -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')
|
||||
|
||||
Reference in New Issue
Block a user