From ded570cac88b2dfedbd652e9c5e8a571e1be10c6 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Thu, 3 Sep 2026 14:35:48 -0400
Subject: [PATCH 1/4] feat: lightbox video player, and transcode formats the
 browser can't play
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two problems with video support, fixed together because the second one
needs a place in the first one's UI to report itself.

**The player was a dialog around a picture.** `.modal-content` is a #222
panel with a 2em pad and a rounded border; wrapping that around a black
`<video>` — itself a bordered rectangle — reads as a frame inside a frame,
and the title row above it added a second band of chrome. It is now a
lightbox, modelled on InvokeAI 7's preview stage: a media card that
shrink-wraps the video at whatever aspect ratio the clip has, sitting
straight on the backdrop, with the filename as a caption below and the
close button floating over the corner.

It also sat ~40px low on iPad. `.modal-overlay` is `position: fixed;
height: 100vh`, and after a fullscreen exit iPadOS keeps the taller
fullscreen-sized layout viewport — so both resolve against a viewport
that is partly off the screen and the flex centring puts the player below
the middle of it. The modal now consumes `--visible-viewport-height`, the
variable panel-anchor.js already publishes for exactly this and that
swiper.css already uses for the photo itself.

**Most of a real video collection will not play in a browser.** DivX/XviD
`.avi`, MPEG-2 `.vob` and `.mpg` off DVDs, `.wmv`, HEVC and 10-bit H.264
in `.mkv` — `<video>` shows a black rectangle for all of them, and the
player's only answer was a download link. `video_transcode.py` converts
them to one H.264/AAC MP4 in the per-user cache directory, which the
existing FileResponse path then serves with Range support, so the result
is fully seekable and instant on every replay.

Notes on the shape of it:

* **Remux before re-encode.** Much of that collection is packaged wrongly
  rather than encoded wrongly: H.264/AAC in an `.mkv` only needs its
  streams copied into an MP4, which takes seconds where a real encode
  takes minutes. The two streams are decided independently, so the common
  H.264-plus-AC-3 case re-encodes only the audio.
* **Every unknown re-encodes.** An unparsed pixel format or codec means
  we cannot *prove* a copy would play, and the cost of guessing wrong is
  the exact black rectangle this removes. Note `yuv420p10le` contains
  `yuv420p`: a substring test would call 10-bit copy-safe.
* **A file, not a pipe.** A StreamingResponse off ffmpeg's stdout starts
  faster but has no Range support, so the scrubber cannot seek, and every
  replay pays again.
* **Jobs live only while somebody is watching.** Conversions run one at a
  time, so opening several unplayable clips in a row would otherwise
  queue them all. The player's progress poll doubles as the liveness
  signal and a job nobody has polled for 45s is killed — closing the
  player is what that looks like from here.
* The cache is bounded by bytes (these are whole movies, not the stills
  next door) and swept LRU after each conversion; deleting an album drops
  its conversions along with its frames.

Triggered automatically: a known-bad container skips the
black-rectangle-then-error round trip, and anything else is attempted
first and converted on the `<video>` element's own error — which is what
catches the cases no container list predicts, like HEVC in Firefox.

The shared mixed image/video album fixture moved to `fixtures.py`, where
conftest already picks fixtures up, so the new suite does not have to
import it from another test module.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GwzC2csXxZkd9HsD8A2t7h
---
 .../backend/metadata_modules/slide_summary.py |   5 +
 photomap/backend/routers/album.py             |  28 +-
 photomap/backend/routers/search.py            | 110 ++-
 photomap/backend/video.py                     |  89 +++
 photomap/backend/video_cache.py               |   4 +-
 photomap/backend/video_transcode.py           | 685 ++++++++++++++++++
 photomap/frontend/static/css/video-player.css | 209 +++++-
 .../frontend/static/javascript/video-badge.js |   8 +
 .../static/javascript/video-player.js         | 296 +++++++-
 .../templates/modules/video-player-modal.html |  49 +-
 tests/backend/conftest.py                     |  25 +-
 tests/backend/fixtures.py                     |  99 +++
 tests/backend/test_video_serving.py           |  95 +--
 tests/backend/test_video_transcode.py         | 632 ++++++++++++++++
 tests/frontend/video-badge.test.js            |   7 +
 .../frontend/video-player-integration.test.js |   6 +
 tests/frontend/video-player.test.js           | 297 +++++++-
 17 files changed, 2420 insertions(+), 224 deletions(-)
 create mode 100644 photomap/backend/video_transcode.py
 create mode 100644 tests/backend/test_video_transcode.py

diff --git a/photomap/backend/metadata_modules/slide_summary.py b/photomap/backend/metadata_modules/slide_summary.py
index 03b39960..5e6c14f1 100644
--- a/photomap/backend/metadata_modules/slide_summary.py
+++ b/photomap/backend/metadata_modules/slide_summary.py
@@ -30,5 +30,10 @@ class SlideSummary(BaseModel):
     # something displayable — the extracted still — so existing consumers that
     # just want a picture keep working unchanged.
     video_url: str = ""
+    # Where to ask for a browser-playable conversion of ``video_url``, for the
+    # (common) case where the browser cannot decode the original. Empty for
+    # images, and empty from a server predating conversion support — the
+    # player treats that as "no conversion available" and offers a download.
+    video_transcode_url: str = ""
     # Duration / fps / resolution / codec / container, when known.
     video_info: dict | None = None
diff --git a/photomap/backend/routers/album.py b/photomap/backend/routers/album.py
index be0a8eb7..46a3ae83 100644
--- a/photomap/backend/routers/album.py
+++ b/photomap/backend/routers/album.py
@@ -22,6 +22,7 @@
 from ..encoders import default_encoder_spec, default_min_search_score
 from ..util import json_safe
 from ..video_cache import VideoFrameCache
+from ..video_transcode import TranscodeCache
 
 
 class UmapEpsSetRequest(BaseModel):
@@ -248,16 +249,27 @@ def _cleanup_derived_index(album: Album | None) -> None:
 
 
 def _cleanup_video_frames(album_key: str) -> None:
-    """Remove an album's extracted video stills when the album goes away.
+    """Remove an album's derived video files when the album goes away.
 
-    The frame cache lives in the per-user cache directory, keyed by album, so
-    nothing else would ever reclaim it. Never raises: a failure here costs
-    disk space, not correctness.
+    Both caches live in the per-user cache directory, keyed by album, so
+    nothing else would ever reclaim them. The converted copies matter more
+    than the stills: those are whole movies, and the size-budget sweeper only
+    runs when something new is converted — an album deleted and never replaced
+    would otherwise leave gigabytes behind indefinitely.
+
+    Each cache is cleared independently so a failure on one still reclaims the
+    other. Never raises: a failure here costs disk space, not correctness.
     """
-    try:
-        VideoFrameCache(album_key).clear()
-    except Exception as e:
-        logger.warning(f"Could not clear video frame cache for '{album_key}': {e}")
+    for cache_name, factory in (
+        ("frame", VideoFrameCache),
+        ("conversion", TranscodeCache),
+    ):
+        try:
+            factory(album_key).clear()
+        except Exception as e:
+            logger.warning(
+                f"Could not clear video {cache_name} cache for '{album_key}': {e}"
+            )
 
 
 def _album_public_dict(album: Album) -> dict[str, Any]:
diff --git a/photomap/backend/routers/search.py b/photomap/backend/routers/search.py
index 73a4f244..2b912981 100644
--- a/photomap/backend/routers/search.py
+++ b/photomap/backend/routers/search.py
@@ -28,6 +28,7 @@
 from ..metadata_modules import SlideSummary, video_external_link_html
 from ..util import is_cuda_oom
 from ..video_cache import VideoFrameCache
+from ..video_transcode import TranscodeCache, TranscodeStatus, request_transcode
 from .album import (
     AlbumDep,
     EmbeddingsDep,
@@ -537,28 +538,19 @@ async def serve_image(album_key: str, path: str, album_config: AlbumDep):
         return FileResponse(image_path)
 
 
-@search_router.get("/videos/{album_key}/{path:path}", tags=["Search"])
-async def serve_video(
-    album_key: str, path: str, album_config: AlbumDep
-) -> FileResponse:
-    """Serve a video file's bytes for playback.
-
-    A separate route rather than a widened ``/images/`` allowlist.
-    ``SUPPORTED_EXTENSIONS`` guards ``serve_image`` against the
-    ``add_album(image_paths=["/etc"])`` -> ``GET /images/<key>/passwd``
-    arbitrary-file-read chain; widening it to admit videos would have loosened
-    that guard as a side effect.  Two routes, two allowlists, neither able to
-    serve the other's file types.
+def _resolve_album_video(album_key: str, path: str, album_config) -> Path:
+    """Resolve ``path`` inside ``album_key`` to a video on disk, or raise.
 
-    Returns a ``FileResponse`` specifically: Starlette implements HTTP Range
-    on it, which is what makes the ``<video>`` scrubber able to seek.  A
-    ``StreamingResponse`` (as the HEIC conversion path uses) has no range
-    support and would silently break seeking.
+    Every video route shares this preamble, and the sharing is the point: the
+    checks are the arbitrary-file-read defense, not a convenience. Duplicating
+    them per route is how one of them ends up missing the ``is_video`` gate
+    and turns ``add_album(image_paths=["/etc"])`` into ``GET
+    /prepare_video/<key>/passwd``.
     """
     # A NUL byte makes Path.resolve() raise ValueError (while .exists() merely
     # returns False), and validate_image_access below calls resolve() — so
     # without this the request escapes every handler as a 500 with a traceback
-    # instead of the 403/404 this route is designed to return.
+    # instead of the 403/404 these routes are designed to return.
     if "\x00" in path:
         raise HTTPException(status_code=404, detail="Video not found")
 
@@ -575,6 +567,29 @@ async def serve_video(
     if not video_path.exists() or not video_path.is_file():
         raise HTTPException(status_code=404, detail="File not found")
 
+    return video_path
+
+
+@search_router.get("/videos/{album_key}/{path:path}", tags=["Search"])
+async def serve_video(
+    album_key: str, path: str, album_config: AlbumDep
+) -> FileResponse:
+    """Serve a video file's bytes for playback.
+
+    A separate route rather than a widened ``/images/`` allowlist.
+    ``SUPPORTED_EXTENSIONS`` guards ``serve_image`` against the
+    ``add_album(image_paths=["/etc"])`` -> ``GET /images/<key>/passwd``
+    arbitrary-file-read chain; widening it to admit videos would have loosened
+    that guard as a side effect.  Two routes, two allowlists, neither able to
+    serve the other's file types.
+
+    Returns a ``FileResponse`` specifically: Starlette implements HTTP Range
+    on it, which is what makes the ``<video>`` scrubber able to seek.  A
+    ``StreamingResponse`` (as the HEIC conversion path uses) has no range
+    support and would silently break seeking.
+    """
+    video_path = _resolve_album_video(album_key, path, album_config)
+
     return FileResponse(
         video_path,
         media_type=video_media_type(video_path),
@@ -587,6 +602,59 @@ async def serve_video(
     )
 
 
+@search_router.post("/prepare_video/{album_key}/{path:path}", tags=["Search"])
+async def prepare_video(
+    album_key: str, path: str, album_config: AlbumDep
+) -> TranscodeStatus:
+    """Ensure a browser-playable copy of this video exists, and report progress.
+
+    POST because the first call starts work, but it is idempotent and doubles
+    as the poll: the player calls it about once a second while its progress
+    panel is up, and those calls are also what tell the backend somebody is
+    still waiting (see ``video_transcode``'s abandonment rule). Returns
+    immediately in every case; the conversion runs on a worker thread.
+
+    Only ``state == "ready"`` carries a ``url``, and it points at
+    ``/transcoded_video/`` rather than the original — the source bytes are
+    exactly what the browser could not play.
+    """
+    video_path = _resolve_album_video(album_key, path, album_config)
+    status = await asyncio.to_thread(request_transcode, album_key, video_path)
+    if status.state == "ready":
+        quoted_album = quote(album_key, safe="")
+        quoted_path = quote(path, safe="/")
+        status.url = f"transcoded_video/{quoted_album}/{quoted_path}"
+    return status
+
+
+@search_router.get("/transcoded_video/{album_key}/{path:path}", tags=["Search"])
+async def serve_transcoded_video(
+    album_key: str, path: str, album_config: AlbumDep
+) -> FileResponse:
+    """Serve the converted copy of a video, if one has been produced.
+
+    Guarded by the same resolution as the original bytes rather than by the
+    cache key alone: the cache is addressed by a digest of the *source* path,
+    so serving straight from it would let anyone who can name a file get its
+    converted contents without passing the album's access check.
+
+    A ``FileResponse`` again, for Range support — being able to seek is most
+    of the reason the conversion is written to disk instead of piped.
+    """
+    video_path = _resolve_album_video(album_key, path, album_config)
+    cached = await asyncio.to_thread(TranscodeCache(album_key).get, video_path)
+    if cached is None:
+        raise HTTPException(
+            status_code=404, detail="This video has not been converted for playback"
+        )
+
+    return FileResponse(
+        cached,
+        media_type="video/mp4",
+        headers={"Cache-Control": "private, max-age=3600"},
+    )
+
+
 @search_router.post(
     "/download_images_zip/{album_key}",
     tags=["Search"],
@@ -805,6 +873,14 @@ def create_slide_url(slide_metadata: SlideSummary, album_key: str) -> None:
         # The playable bytes get their own field.
         slide_metadata.image_url = f"video_frame/{quoted_album}/{slide_metadata.index}"
         slide_metadata.video_url = f"videos/{quoted_album}/{quoted_path}"
+        # Where the player asks for a playable copy when the original turns
+        # out not to be one. Handed over rather than assembled in the frontend
+        # so the route shape stays a backend concern, and so a payload from an
+        # older server (empty string) degrades to the download-only fallback
+        # instead of a 404 the player would have to interpret.
+        slide_metadata.video_transcode_url = (
+            f"prepare_video/{quoted_album}/{quoted_path}"
+        )
         slide_metadata.description += video_external_link_html(
             slide_metadata.video_url
         )
diff --git a/photomap/backend/video.py b/photomap/backend/video.py
index dac5998d..36b52bfc 100644
--- a/photomap/backend/video.py
+++ b/photomap/backend/video.py
@@ -437,3 +437,92 @@ def extract_video_frame(
 
     logger.warning(f"Could not extract a frame from {path}; skipping it.")
     return None
+
+
+# Wall-clock ceiling for a bare ``-i`` probe.  No decoding happens, so this is
+# only ever hit by an input ffmpeg cannot open at all (a dead network mount).
+PROBE_TIMEOUT_SECONDS = 30.0
+
+# "    Stream #0:1[0x2](und): Audio: aac (LC) (mp4a / 0x6134706D), 48000 Hz, ..."
+_STREAM_AUDIO_RE = re.compile(
+    r"^\s*Stream #\d+:\d+.*?: Audio:\s*(?P<codec>[A-Za-z0-9_.\-]+)"
+)
+# The pixel format token on a video stream line: "yuv420p", "yuvj420p",
+# "yuv420p10le", "yuv444p".  Anything this does not match is reported as
+# ``None``, which every caller must read as "not known to be safe" rather than
+# "absent" — the transcoder's copy decision depends on it.
+_PIX_FMT_RE = re.compile(r"\byuvj?\d{3}p(?:\d{1,2}(?:le|be))?\b")
+
+
+class StreamProbe(BaseModel):
+    """What the streams inside a container are, as far as ffmpeg reports them.
+
+    Distinct from :class:`VideoInfo`, which describes a video *as a slide* —
+    duration, frame rate, display geometry.  This describes it *as something
+    to remux or re-encode*: which codecs are in there and whether the pixel
+    format is one a browser's H.264 decoder will accept.
+
+    Every field is optional for the same reason ``VideoInfo``'s are: a banner
+    this does not recognize must degrade one field.  Here that degradation is
+    load-bearing rather than cosmetic, so it degrades in the *conservative*
+    direction — an unparsed ``video_pix_fmt`` is ``None``, and
+    :func:`~photomap.backend.video_transcode.plan_for` re-encodes rather than
+    copies when it cannot prove the format is safe.
+    """
+
+    duration: float | None = None
+    has_video: bool = False
+    video_codec: str | None = None
+    video_pix_fmt: str | None = None
+    has_audio: bool = False
+    audio_codec: str | None = None
+
+
+def probe_streams(path: Path) -> StreamProbe | None:
+    """Report the streams inside ``path``.  ``None`` if ffmpeg could not run.
+
+    Runs ffmpeg with an input and no output.  That exits non-zero — "At least
+    one output file must be specified" — which is why the return code is
+    ignored: the banner is printed to stderr before the complaint, and the
+    banner is the entire point.  ffprobe would be the obvious tool, but
+    ``imageio-ffmpeg`` ships only the ffmpeg binary.
+
+    The banner is passed through :func:`_strip_metadata_blocks` first, for the
+    reason documented there: stream and duration lines are ffmpeg's own
+    report, while the ``Metadata:`` blocks above them are attacker-controlled
+    file tags that would otherwise be able to spoof a codec.
+    """
+    result = _run_ffmpeg(
+        ["-nostdin", "-hide_banner", "-i", str(path)], PROBE_TIMEOUT_SECONDS
+    )
+    if result is None or isinstance(result, _FfmpegUnavailable):
+        return None
+
+    report = _strip_metadata_blocks(result.stderr.decode("utf-8", errors="replace"))
+    probe = StreamProbe()
+
+    if m := _DURATION_RE.search(report):
+        try:
+            probe.duration = (
+                int(m.group("h")) * 3600 + int(m.group("m")) * 60 + float(m.group("s"))
+            )
+        except (ValueError, OverflowError):
+            pass
+
+    for line in report.splitlines():
+        if not probe.has_video:
+            m = _STREAM_VIDEO_RE.match(line)
+            # Cover art embedded in an audio file presents as a video stream;
+            # transcoding it would produce a one-frame "video".
+            if m and _ATTACHED_PIC not in line.lower():
+                probe.has_video = True
+                probe.video_codec = m.group("codec")
+                if pm := _PIX_FMT_RE.search(line):
+                    probe.video_pix_fmt = pm.group(0)
+                continue
+        if not probe.has_audio:
+            if m := _STREAM_AUDIO_RE.match(line):
+                probe.has_audio = True
+                probe.audio_codec = m.group("codec")
+
+    return probe
diff --git a/photomap/backend/video_cache.py b/photomap/backend/video_cache.py
index be3d6529..b89b45cf 100644
--- a/photomap/backend/video_cache.py
+++ b/photomap/backend/video_cache.py
@@ -142,7 +142,7 @@ def _path_digest(video_path: Path) -> str:
     ).hexdigest()
 
 
-def _album_dirname(album_key: str) -> str:
+def album_dirname(album_key: str) -> str:
     """A guaranteed-safe single path component for ``album_key``.
 
     Album keys are user input and end up as a directory name that ``clear()``
@@ -175,7 +175,7 @@ def __init__(self, album_key: str, root: Path | None = None) -> None:
 
     @property
     def directory(self) -> Path:
-        return self._root / _album_dirname(self.album_key)
+        return self._root / album_dirname(self.album_key)
 
     @staticmethod
     def key_for(video_path: Path, mtime: float | None = None) -> str:
diff --git a/photomap/backend/video_transcode.py b/photomap/backend/video_transcode.py
new file mode 100644
index 00000000..336e0ca2
--- /dev/null
+++ b/photomap/backend/video_transcode.py
@@ -0,0 +1,685 @@
+"""On-demand conversion of videos the browser refuses to play.
+
+A typical personal video collection is mostly *not* web-playable: DivX/XviD
+``.avi``, MPEG-2 ``.vob`` and ``.mpg`` off DVDs, ``.wmv``, HEVC and 10-bit
+H.264 in ``.mkv``.  ``<video>`` shows a black rectangle for all of them.  This
+module turns any of them into one H.264/AAC MP4 in the per-user cache
+directory, which the existing ``FileResponse`` path then serves with Range
+support — so the result is fully seekable and instant on every replay.
+
+**Remux before re-encode.**  Most of that collection is not actually encoded
+wrongly, it is *packaged* wrongly: an ``.mkv`` or ``.avi`` holding H.264 video
+and AAC audio needs its streams copied into an MP4 container and nothing
+more.  That is I/O-bound and finishes in seconds on a file a real re-encode
+would spend minutes on, so the two cases are decided per stream —
+:func:`plan_for` can copy the video and re-encode only the audio, or the
+reverse.
+
+**Why a cache file and not a pipe.**  Piping ffmpeg's stdout into a
+``StreamingResponse`` starts faster but has no Range support, so the scrubber
+cannot seek and the duration is unknown; and every replay pays for the
+conversion again.  Writing the file first costs a wait on the first play,
+which is what the player's progress readout is for.
+
+**Abandonment.**  Conversions run one at a time on a single worker thread, so
+a user opening several unplayable clips in a row would otherwise queue every
+one of them and watch the last sit behind minutes of work they no longer
+want.  A job is therefore only kept alive while a client is asking about it:
+:func:`request_transcode` doubles as the poll, and a job nobody has polled for
+``ABANDON_AFTER_SECONDS`` is killed and its partial output discarded.  Closing
+the player is what abandonment looks like from here.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+import tempfile
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import IO, Literal
+
+from platformdirs import user_cache_dir
+from pydantic import BaseModel
+
+from .video import StreamProbe, ffmpeg_exe, probe_streams
+from .video_cache import VideoFrameCache, album_dirname
+
+logger = logging.getLogger(__name__)
+
+# Name of the cache directory under the per-user cache root.  Deliberately a
+# sibling of ``video_frames`` rather than a subdirectory of it: the frame
+# cache's sweeper deletes everything in its own tree that is not a current
+# ``.jpg``, and a converted movie is neither.
+TRANSCODE_CACHE_DIRNAME = "video_transcodes"
+
+# Total size the converted-video cache is allowed to reach before the oldest
+# entries are reclaimed.  Videos are orders of magnitude larger than the
+# stills next door, so this cache is bounded by bytes rather than swept
+# against the index the way ``VideoFrameCache.prune`` is.
+MAX_TRANSCODE_CACHE_BYTES = 8 * 1024**3
+
+# Streams that can be copied into an MP4 rather than re-encoded.
+#
+# H.264 only, and only in 8-bit 4:2:0.  Every browser decodes that; 10-bit
+# (``yuv420p10le``, routine in modern ``.mkv`` rips) and 4:2:2/4:4:4 are
+# rejected by the very decoders this exists to satisfy, so a copy would
+# produce a valid MP4 that still shows a black rectangle.  HEVC is absent for
+# the same reason it is absent from ``WEB_PLAYABLE_EXTENSIONS``: Safari plays
+# it and nothing else does.
+COPYABLE_VIDEO_CODECS: frozenset[str] = frozenset({"h264"})
+COPYABLE_VIDEO_PIX_FMTS: frozenset[str] = frozenset({"yuv420p", "yuvj420p"})
+# AAC only. MP4 can legally carry MP3 and current browsers do decode it, but
+# it is the one audio path with a history of silence rather than an error in
+# Safari — and the failure this whole module exists to remove is exactly "the
+# file loads and plays nothing". Re-encoding audio runs at a hundred times
+# realtime, so copying it saves seconds on a job whose cost is the video.
+COPYABLE_AUDIO_CODECS: frozenset[str] = frozenset({"aac"})
+
+# x264 settings.  ``veryfast``/CRF 23 is the point where a wait the user is
+# watching a progress bar through stops being the dominant cost; slower
+# presets buy file size this cache does not care about.
+X264_PRESET = "veryfast"
+X264_CRF = "23"
+AAC_BITRATE = "160k"
+
+# No progress line for this long means ffmpeg is wedged — a truncated file, a
+# stalled network mount — rather than merely slow.  ffmpeg emits a progress
+# block roughly twice a second whenever it is making any headway at all.
+STALL_TIMEOUT_SECONDS = 180.0
+
+# Absolute ceilings, scaled off the source duration: a two-hour movie
+# legitimately takes far longer than a ten-second clip, and neither should run
+# forever.
+JOB_TIMEOUT_PER_SECOND = 20.0
+MIN_JOB_TIMEOUT_SECONDS = 600.0
+MAX_JOB_TIMEOUT_SECONDS = 6 * 3600.0
+
+# How often the watchdog samples the stall / deadline / abandonment clocks.
+WATCHDOG_INTERVAL_SECONDS = 2.0
+
+# A job nobody has asked about for this long is dropped.  The player polls
+# about once a second while its progress panel is up, so this is only reached
+# by a client that has genuinely gone away.
+ABANDON_AFTER_SECONDS = 45.0
+
+# How long a failure is remembered.  Without this a permanently unconvertible
+# file re-runs ffmpeg on every poll — several times a second.  It expires
+# because failure is also transient (a full disk, a mount that came back), and
+# a permanent record would mean one unlucky moment disables a video for the
+# life of the process.  Mirrors ``video_cache``'s failure memory.
+FAILURE_MEMORY_SECONDS = 300.0
+
+TranscodeState = Literal["queued", "running", "ready", "failed", "unavailable"]
+
+
+class TranscodePlan(BaseModel):
+    """How a particular file has to be converted.
+
+    ``copy_video``/``copy_audio`` are per-stream because the common cases are
+    mixed: an ``.mkv`` of H.264 video with AC-3 audio needs the video copied
+    and only the audio re-encoded, which is nearly as cheap as a pure remux.
+    """
+
+    copy_video: bool
+    has_audio: bool
+    copy_audio: bool
+    duration: float | None = None
+
+    @property
+    def is_remux(self) -> bool:
+        """True when no stream is being re-encoded — seconds, not minutes."""
+        return self.copy_video and (not self.has_audio or self.copy_audio)
+
+
+class TranscodeStatus(BaseModel):
+    """What to tell a client asking about a conversion.
+
+    ``url`` is deliberately absent: this module knows nothing about routes.
+    The router fills it in when ``state`` is ``"ready"``.
+    """
+
+    state: TranscodeState
+    progress: float = 0.0
+    detail: str | None = None
+    url: str | None = None
+
+
+def plan_for(probe: StreamProbe | None) -> TranscodePlan:
+    """Decide what has to be re-encoded, from what the probe could determine.
+
+    Every unknown resolves to "re-encode".  A probe that returned ``None``, a
+    codec line the banner parser did not match, an unrecognized pixel format —
+    all of them mean *we cannot prove a copy would play*, and the cost of
+    guessing wrong is the exact black rectangle this module exists to remove.
+    Re-encoding when a copy would have done merely wastes time once, and the
+    result is cached.
+    """
+    if probe is None:
+        return TranscodePlan(copy_video=False, has_audio=True, copy_audio=False)
+
+    copy_video = (
+        (probe.video_codec or "").lower() in COPYABLE_VIDEO_CODECS
+        and (probe.video_pix_fmt or "").lower() in COPYABLE_VIDEO_PIX_FMTS
+    )
+    copy_audio = (probe.audio_codec or "").lower() in COPYABLE_AUDIO_CODECS
+    return TranscodePlan(
+        copy_video=copy_video,
+        has_audio=probe.has_audio,
+        copy_audio=probe.has_audio and copy_audio,
+        duration=probe.duration,
+    )
+
+
+def ffmpeg_args(source: Path, target: Path, plan: TranscodePlan) -> list[str]:
+    """The ffmpeg argument list for ``plan``, writing ``target``."""
+    args = [
+        "-nostdin",
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        # mkstemp has already created the output file, so ffmpeg must be told
+        # it may overwrite it — without this it blocks on a y/n prompt whose
+        # stdin is /dev/null and dies.
+        "-y",
+        "-i",
+        str(source),
+        # Exactly one video and at most one audio stream.  A ``.mkv`` rip
+        # routinely carries five audio tracks and a pile of subtitle streams,
+        # most of which MP4 cannot hold at all; mapping explicitly is what
+        # keeps the mux from failing on them.  The trailing "?" makes the
+        # audio stream optional, so a silent clip is not an error.
+        "-map",
+        "0:v:0",
+        "-map",
+        "0:a:0?",
+    ]
+
+    if plan.copy_video:
+        args += ["-c:v", "copy"]
+    else:
+        args += [
+            "-c:v",
+            "libx264",
+            "-preset",
+            X264_PRESET,
+            "-crf",
+            X264_CRF,
+            # Browsers decode 8-bit 4:2:0 and nothing else reliably, so the
+            # output format is pinned rather than inherited from the source.
+            "-pix_fmt",
+            "yuv420p",
+            # Correct non-square pixels, for the same reason the still-frame
+            # extractor does: DVD rips, .vob, .mpg and AVCHD .m2ts are all
+            # anamorphic, and a 720x480 SAR 32:27 source plays back squashed
+            # to 1.50 instead of 1.778 if the sample aspect is dropped.  Only
+            # on the re-encode path — a stream copy carries the source's own
+            # aspect metadata through untouched.
+            "-vf",
+            "scale=iw*sar:ih",
+        ]
+
+    if not plan.has_audio:
+        args += ["-an"]
+    elif plan.copy_audio:
+        args += ["-c:a", "copy"]
+    else:
+        args += ["-c:a", "aac", "-b:a", AAC_BITRATE, "-ac", "2"]
+
+    args += [
+        # Put the moov atom at the front.  Without it the browser has to fetch
+        # the end of the file before it can play or seek anywhere, which over
+        # a Range request is an extra round trip on every single open.
+        "-movflags",
+        "+faststart",
+        # Interleaving a copied video stream with a re-encoded audio one can
+        # buffer a lot of packets on a source with sparse audio; the default
+        # queue is small enough that ffmpeg aborts on it.
+        "-max_muxing_queue_size",
+        "4096",
+        # Machine-readable progress on stdout, and the human progress line
+        # off, so the reader loop below sees one and only one format.
+        "-progress",
+        "pipe:1",
+        "-nostats",
+        # The container is stated rather than inferred, because the output is
+        # a mkstemp ".tmp" name that no muxer would recognize.
+        "-f",
+        "mp4",
+        str(target),
+    ]
+    return args
+
+
+def transcode_cache_root() -> Path:
+    """Root of the per-user converted-video cache."""
+    return Path(user_cache_dir("photomap", "photomap")) / TRANSCODE_CACHE_DIRNAME
+
+
+class TranscodeCache:
+    """Converted videos for one album, addressed by source video path.
+
+    Keyed identically to :class:`~photomap.backend.video_cache.VideoFrameCache`
+    — ``<path digest>-<mtime digest>`` — so an edited video invalidates its
+    conversion for free, and so the album-scoped directory can be dropped
+    wholesale when the album is deleted.
+    """
+
+    def __init__(self, album_key: str, root: Path | None = None) -> None:
+        if not album_key:
+            raise ValueError("Album key must not be empty")
+        self.album_key = album_key
+        self._root = root if root is not None else transcode_cache_root()
+
+    @property
+    def directory(self) -> Path:
+        return self._root / album_dirname(self.album_key)
+
+    @staticmethod
+    def key_for(video_path: Path, mtime: float | None = None) -> str:
+        return VideoFrameCache.key_for(video_path, mtime)
+
+    def path_for(self, video_path: Path, mtime: float | None = None) -> Path:
+        return self.directory / f"{self.key_for(video_path, mtime)}.mp4"
+
+    def get(self, video_path: Path, mtime: float | None = None) -> Path | None:
+        """The converted file, if one has already been produced."""
+        path = self.path_for(video_path, mtime)
+        return path if path.is_file() else None
+
+    def clear(self) -> None:
+        """Drop this album's conversions entirely (album deletion)."""
+        shutil.rmtree(self.directory, ignore_errors=True)
+
+
+def sweep_transcode_cache(
+    keep: Path | None = None,
+    budget: int = MAX_TRANSCODE_CACHE_BYTES,
+    root: Path | None = None,
+) -> int:
+    """Evict least-recently-used conversions until the cache fits ``budget``.
+
+    Recency is the file's mtime, which :func:`request_transcode` refreshes on
+    every cache hit — so a clip watched repeatedly outlives one converted
+    once and forgotten, regardless of when either was produced.
+
+    ``keep`` is never evicted: it is the file the caller has just produced and
+    is about to serve, and on a cache whose budget is smaller than a single
+    movie it would otherwise be deleted before it could be played.
+    """
+    base = root if root is not None else transcode_cache_root()
+    if not base.is_dir():
+        return 0
+
+    entries: list[tuple[float, int, Path]] = []
+    total = 0
+    keep_resolved = keep.resolve() if keep else None
+    for path in base.rglob("*.mp4"):
+        try:
+            stat = path.stat()
+        except OSError:
+            continue
+        total += stat.st_size
+        if keep_resolved is not None and path.resolve() == keep_resolved:
+            continue
+        entries.append((stat.st_mtime, stat.st_size, path))
+
+    if total <= budget:
+        return 0
+
+    removed = 0
+    entries.sort(key=lambda item: item[0])
+    for _mtime, size, path in entries:
+        if total <= budget:
+            break
+        try:
+            path.unlink()
+        except OSError as e:
+            logger.debug(f"Could not evict cached conversion {path}: {e}")
+            continue
+        total -= size
+        removed += 1
+    return removed
+
+
+@dataclass
+class _Job:
+    """One conversion, from the moment it is requested until it is forgotten."""
+
+    state: TranscodeState = "queued"
+    progress: float = 0.0
+    detail: str | None = None
+    last_polled: float = field(default_factory=time.monotonic)
+    finished_at: float | None = None
+
+
+_jobs: dict[str, _Job] = {}
+_jobs_lock = threading.Lock()
+_executor: ThreadPoolExecutor | None = None
+_executor_lock = threading.Lock()
+
+
+def _worker_pool() -> ThreadPoolExecutor:
+    """The single worker every conversion runs on.
+
+    One worker, not several: ffmpeg saturates whatever cores it is given, so
+    a second concurrent encode does not finish two videos any sooner — it just
+    makes the one the user is actually waiting on take twice as long.
+    """
+    global _executor
+    with _executor_lock:
+        if _executor is None:
+            _executor = ThreadPoolExecutor(
+                max_workers=1, thread_name_prefix="video-transcode"
+            )
+        return _executor
+
+
+def _scoped_key(album_key: str, key: str) -> str:
+    # NUL cannot appear in either half, so no album key can be crafted to
+    # collide with another album's entry.
+    return f"{album_key}\x00{key}"
+
+
+def _forget_stale_jobs(now: float) -> None:
+    """Drop finished entries nobody can still be waiting on. Caller holds the lock."""
+    for scoped, job in list(_jobs.items()):
+        if job.finished_at is not None and now - job.finished_at > FAILURE_MEMORY_SECONDS:
+            del _jobs[scoped]
+
+
+def request_transcode(
+    album_key: str, video_path: Path, root: Path | None = None
+) -> TranscodeStatus:
+    """Ensure a playable conversion of ``video_path`` exists, and report progress.
+
+    Idempotent, and doubles as the poll: calling it repeatedly is how a client
+    both starts a conversion and watches it, and each call is what keeps the
+    job from being treated as abandoned.  Returns immediately in every case —
+    the conversion itself runs on the worker pool.
+    """
+    if ffmpeg_exe() is None:
+        return TranscodeStatus(
+            state="unavailable",
+            detail="Video conversion needs ffmpeg, which is not available on this system.",
+        )
+
+    cache = TranscodeCache(album_key, root=root)
+    try:
+        mtime = video_path.stat().st_mtime
+    except OSError as e:
+        logger.warning(f"Could not stat {video_path} for conversion: {e}")
+        return TranscodeStatus(
+            state="failed", detail="The video file could not be read."
+        )
+
+    key = cache.key_for(video_path, mtime)
+    target = cache.path_for(video_path, mtime)
+    if target.is_file():
+        # Refresh the LRU stamp so a clip that keeps being watched keeps its
+        # place ahead of one converted once and never opened again.
+        try:
+            os.utime(target, None)
+        except OSError:
+            pass
+        return TranscodeStatus(state="ready", progress=1.0)
+
+    scoped = _scoped_key(album_key, key)
+    now = time.monotonic()
+    with _jobs_lock:
+        _forget_stale_jobs(now)
+        job = _jobs.get(scoped)
+        if job is not None:
+            job.last_polled = now
+            if job.state in ("queued", "running"):
+                return TranscodeStatus(state=job.state, progress=job.progress)
+            if job.state == "failed":
+                return TranscodeStatus(state="failed", detail=job.detail)
+            # "ready" with no file on disk means the cache was swept or wiped
+            # under us; fall through and rebuild it.
+        _jobs[scoped] = _Job()
+
+    _worker_pool().submit(_run_job, scoped, video_path, target)
+    return TranscodeStatus(state="queued")
+
+
+def _update(scoped: str, **fields: object) -> _Job | None:
+    with _jobs_lock:
+        job = _jobs.get(scoped)
+        if job is None:
+            return None
+        for name, value in fields.items():
+            setattr(job, name, value)
+        return job
+
+
+def _abandoned(scoped: str, now: float) -> bool:
+    with _jobs_lock:
+        job = _jobs.get(scoped)
+        return job is None or now - job.last_polled > ABANDON_AFTER_SECONDS
+
+
+def _drop(scoped: str) -> None:
+    with _jobs_lock:
+        _jobs.pop(scoped, None)
+
+
+def _job_timeout(duration: float | None) -> float:
+    scaled = (duration or 0.0) * JOB_TIMEOUT_PER_SECOND
+    return min(max(scaled, MIN_JOB_TIMEOUT_SECONDS), MAX_JOB_TIMEOUT_SECONDS)
+
+
+def _run_job(scoped: str, source: Path, target: Path) -> None:
+    """Worker body: probe, convert, publish.  Never raises."""
+    try:
+        if _abandoned(scoped, time.monotonic()):
+            # Queued behind another conversion for long enough that whoever
+            # asked has gone; do not burn the CPU on it.
+            _drop(scoped)
+            return
+
+        plan = plan_for(probe_streams(source))
+        _update(scoped, state="running", progress=0.0)
+        logger.info(
+            f"Converting {source.name} for playback "
+            f"({'remux' if plan.is_remux else 're-encode'})"
+        )
+        error = _run_ffmpeg_transcode(scoped, source, target, plan)
+    except Exception as e:  # pragma: no cover - defensive
+        logger.exception(f"Unexpected failure converting {source}")
+        error = str(e)
+
+    if error is _ABANDONED:
+        _drop(scoped)
+        return
+    if error:
+        _update(
+            scoped, state="failed", detail=error, finished_at=time.monotonic()
+        )
+        return
+
+    _update(scoped, state="ready", progress=1.0, finished_at=time.monotonic())
+    try:
+        sweep_transcode_cache(keep=target, root=target.parent.parent)
+    except Exception as e:  # pragma: no cover - defensive
+        logger.warning(f"Could not sweep the conversion cache: {e}")
+
+
+# Distinct from an error string: the job was dropped on purpose and must not
+# be recorded as a failure the client would then be shown.
+_ABANDONED = "\x00abandoned"
+
+
+def _run_ffmpeg_transcode(
+    scoped: str, source: Path, target: Path, plan: TranscodePlan
+) -> str | None:
+    """Run ffmpeg into ``target``.  ``None`` on success, else a message."""
+    exe = ffmpeg_exe()
+    if exe is None:
+        return "Video conversion needs ffmpeg, which is not available on this system."
+
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        # mkstemp, not a name derived from the key: two threads converting the
+        # same video would otherwise interleave into one file and os.replace
+        # would publish the mixture.  (The single worker makes that unreachable
+        # today; it costs nothing to not depend on that.)
+        fd, tmp_name = tempfile.mkstemp(
+            dir=target.parent, prefix=f"{target.stem}.", suffix=".tmp"
+        )
+        os.close(fd)
+    except OSError as e:
+        return f"Could not write to the conversion cache: {e}"
+    tmp_path = Path(tmp_name)
+
+    # stderr goes to a file rather than a pipe.  Nothing drains it while the
+    # progress stream on stdout is being read, and a pipe that fills blocks
+    # ffmpeg forever — the deadlock ``video._run_ffmpeg`` avoids by using
+    # communicate().  A conversion cannot use communicate(): its whole point
+    # is reporting progress while the child is still running.
+    #
+    # The ``with`` covers every exit, including one nothing here anticipated:
+    # a conversion that escaped through an unexpected exception would
+    # otherwise leak the handle, and on Windows leave the temp file itself
+    # behind for as long as the process lives.
+    with tempfile.TemporaryFile() as stderr_file:
+        return _drive_ffmpeg(scoped, exe, source, tmp_path, target, plan, stderr_file)
+
+
+def _drive_ffmpeg(
+    scoped: str,
+    exe: str,
+    source: Path,
+    tmp_path: Path,
+    target: Path,
+    plan: TranscodePlan,
+    stderr_file: IO[bytes],
+) -> str | None:
+    """Spawn ffmpeg, follow its progress, and publish the result."""
+    kwargs: dict[str, object] = {}
+    if hasattr(subprocess, "CREATE_NO_WINDOW"):  # Windows only
+        kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
+
+    try:
+        proc = subprocess.Popen(
+            [exe, *ffmpeg_args(source, tmp_path, plan)],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=stderr_file,
+            **kwargs,
+        )
+    except OSError as e:
+        tmp_path.unlink(missing_ok=True)
+        return f"Could not start ffmpeg: {e}"
+
+    stop = threading.Event()
+    last_beat = [time.monotonic()]
+    deadline = time.monotonic() + _job_timeout(plan.duration)
+    killed_for = [""]
+
+    def watchdog() -> None:
+        while not stop.wait(WATCHDOG_INTERVAL_SECONDS):
+            now = time.monotonic()
+            if now - last_beat[0] > STALL_TIMEOUT_SECONDS:
+                killed_for[0] = "stalled"
+            elif now > deadline:
+                killed_for[0] = "timeout"
+            elif _abandoned(scoped, now):
+                killed_for[0] = "abandoned"
+            else:
+                continue
+            proc.kill()
+            return
+
+    watcher = threading.Thread(target=watchdog, daemon=True)
+    watcher.start()
+
+    total_us = (plan.duration or 0.0) * 1_000_000
+    try:
+        # readline, not iteration: a buffered iterator holds lines back, which
+        # would both stall the progress readout and make the stall detector
+        # fire on a conversion that is working perfectly.
+        for raw in iter(proc.stdout.readline, b""):
+            last_beat[0] = time.monotonic()
+            line = raw.decode("utf-8", errors="replace").strip()
+            if not line.startswith("out_time_us=") or total_us <= 0:
+                continue
+            try:
+                done = float(line.split("=", 1)[1])
+            except ValueError:
+                continue
+            # Never reports 1.0: only the file landing in place means done,
+            # and ffmpeg's last block arrives before the faststart rewrite.
+            _update(scoped, progress=max(0.0, min(0.999, done / total_us)))
+    finally:
+        stop.set()
+        try:
+            proc.stdout.close()
+        except OSError:
+            pass
+        returncode = proc.wait()
+        watcher.join(timeout=WATCHDOG_INTERVAL_SECONDS * 2)
+
+    # What ffmpeg actually produced decides, not what the watchdog intended.
+    # The watchdog samples on a timer, so it can wake and fire in the moment
+    # between the last progress line and the process exiting cleanly — and a
+    # finished conversion must be published even if the client walked away a
+    # fraction of a second before it landed. Throwing it out there would mean
+    # re-running the whole encode on the next request for no reason.
+    try:
+        succeeded = (
+            returncode == 0 and tmp_path.is_file() and tmp_path.stat().st_size > 0
+        )
+    except OSError:
+        succeeded = False
+
+    if succeeded:
+        try:
+            os.replace(tmp_path, target)
+        except OSError as e:
+            tmp_path.unlink(missing_ok=True)
+            return f"Could not publish the converted video: {e}"
+        return None
+
+    tmp_path.unlink(missing_ok=True)
+
+    if killed_for[0] == "abandoned":
+        logger.info(f"Abandoned the conversion of {source.name}; nobody is waiting.")
+        return _ABANDONED
+    if killed_for[0] == "stalled":
+        return "Converting this video stalled; the file may be truncated."
+    if killed_for[0] == "timeout":
+        return "Converting this video took too long and was stopped."
+
+    detail = _stderr_tail(stderr_file)
+    logger.warning(f"ffmpeg could not convert {source}: {detail or returncode}")
+    return detail or "This video could not be converted for playback."
+
+
+# Cap on how much of ffmpeg's complaint is shown to the user.  It goes into a
+# panel in the player, not a log.
+_MAX_DETAIL_CHARS = 200
+
+
+def _stderr_tail(handle: IO[bytes]) -> str | None:
+    """ffmpeg's last complaint, short enough to show in the player."""
+    try:
+        handle.seek(0)
+        text = handle.read().decode("utf-8", errors="replace")
+    except OSError:
+        return None
+    lines = [line.strip() for line in text.splitlines() if line.strip()]
+    if not lines:
+        return None
+    return lines[-1][:_MAX_DETAIL_CHARS]
+
+
+def _reset_jobs_for_tests() -> None:
+    """Test seam: forget every job so a fresh registry can be exercised."""
+    with _jobs_lock:
+        _jobs.clear()
diff --git a/photomap/frontend/static/css/video-player.css b/photomap/frontend/static/css/video-player.css
index 40202d61..9eeb584b 100644
--- a/photomap/frontend/static/css/video-player.css
+++ b/photomap/frontend/static/css/video-player.css
@@ -1,60 +1,194 @@
 /* video-player.css */
 /* Modal video player, opened from the play badge on a video still. */
 
-/* The base .modal-content caps at 600px, which letterboxes a 1080p clip into
-   a stamp. The player gets a much wider box and a darker backdrop. */
+/* A lightbox, not a dialog: the media card sits straight on the backdrop.
+   `.modal-content` is not used at all here — see the template. */
 #videoPlayerModal {
-  background: rgba(0, 0, 0, 0.82);
+  /* --visible-viewport-height is published by panel-anchor.js when iPadOS
+     strands the layout viewport after a fullscreen exit: `position: fixed`
+     and `100vh` both resolve against that stranded viewport, so the flex
+     centring below puts the whole player *below* the middle of the screen,
+     and its bottom edge off it. This is the same variable swiper.css consumes
+     for the photo itself, and it is unset (falling back to 100dvh) on every
+     browser that does not have the bug. */
+  height: var(--visible-viewport-height, 100dvh);
+  background: rgba(0, 0, 0, 0.92);
+  flex-direction: column;
+  gap: 12px;
+  /* Room for the close button, which floats over the backdrop's top-right. */
+  padding: 24px;
+  box-sizing: border-box;
 }
 
-.video-player-content {
-  width: min(92vw, 1400px);
-  max-width: min(92vw, 1400px);
-  padding: 2.2em 1.2em 1.2em;
+/* Floats over the backdrop rather than sitting inside the frame: a control
+   drawn on top of the picture is one more thing between the viewer and the
+   video, and the corner of a shrink-wrapped frame moves with every clip's
+   aspect ratio. */
+.video-player-close {
+  position: absolute;
+  top: 12px;
+  right: 16px;
+  z-index: 2;
   display: flex;
-  flex-direction: column;
-  gap: 0.75em;
+  align-items: center;
+  justify-content: center;
+  width: 40px;
+  height: 40px;
+  padding: 0;
+  background: rgba(255, 255, 255, 0.1);
+  border: none;
+  border-radius: 50%;
+  color: #fff;
+  font: inherit;
+  font-size: 1.6rem;
+  line-height: 1;
+  cursor: pointer;
+  transition: background 0.15s;
+}
+
+.video-player-close:hover,
+.video-player-close:focus-visible {
+  background: rgba(255, 255, 255, 0.22);
 }
 
+/* The media card. Shrink-wraps its <video>, so the border traces the picture
+   at any aspect ratio instead of letterboxing it inside a fixed panel.
+
+   The min sizes matter only for the moments when there is nothing to size
+   against — no poster, no metadata yet, or an error before either arrived —
+   and stop the frame collapsing to a sliver behind the overlay panels. */
+.video-player-frame {
+  position: relative;
+  display: flex;
+  min-width: min(320px, 78vw);
+  min-height: 180px;
+  max-width: 100%;
+  background: #000;
+  border: 1px solid rgba(255, 255, 255, 0.14);
+  border-radius: 12px;
+  box-shadow: 0 24px 80px rgba(0, 0, 0, 0.55);
+  /* Clips the native control bar to the rounded corners. */
+  overflow: hidden;
+}
+
+/* `width`/`height: auto` with only maxima set is what makes the element size
+   itself from the video's (or poster's) intrinsic aspect ratio, which is in
+   turn what the frame shrink-wraps. Setting `width: 100%` here instead would
+   pin the frame to the cap and put black bars back inside it. */
+.video-player-element {
+  display: block;
+  width: auto;
+  height: auto;
+  max-width: min(94vw, 1600px);
+  /* The overlay's own 24px padding top and bottom, plus the caption row and
+     its gap. Resolved against the visible viewport for the reason given
+     above. */
+  max-height: calc(var(--visible-viewport-height, 100dvh) - 104px);
+  background: #000;
+}
+
+/* The filename, as a caption on the backdrop rather than a title bar above
+   the video — a row of chrome attached to the frame is most of what made the
+   old player read as a dialog. */
 .video-player-title {
-  color: #ddd;
-  font-size: 0.95rem;
+  flex: none;
+  max-width: min(94vw, 1600px);
+  color: #bbb;
+  font-size: 0.9rem;
   text-align: center;
   overflow-wrap: anywhere;
+  /* Clamped to two lines because the video's max-height above subtracts a
+     fixed allowance for this row. A long filename broken at arbitrary
+     characters on a narrow screen would otherwise run to four or five lines
+     and push the bottom of the picture back off the display — the exact
+     problem the visible-viewport height is here to fix. */
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
 }
 
 .video-player-title:empty {
   display: none;
 }
 
-.video-player-element {
-  width: 100%;
-  /* Leave room for the title and close button so the controls are never
-     pushed off the bottom of a short viewport. */
-  max-height: 78vh;
-  background: #000;
-  border-radius: 6px;
-  display: block;
+/* ===== Overlay panels (conversion progress, and failure) ===== */
+
+/* Drawn over the frame, never in place of the video, so the poster stays
+   visible behind the scrim and the frame keeps the clip's aspect ratio. */
+.video-player-panel {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 14px;
+  padding: 24px;
+  box-sizing: border-box;
+  /* Heavy enough that the status text reads over an arbitrary frame — a
+     bright or busy still shows straight through a lighter scrim — but not so
+     heavy that the poster stops being visible. The point of overlaying rather
+     than replacing the video is that the user keeps looking at the clip they
+     asked for. */
+  background: rgba(0, 0, 0, 0.82);
+  color: #eee;
+  text-align: center;
+  text-shadow: 0 1px 3px rgba(0, 0, 0, 0.9);
 }
 
-.video-player-element[hidden] {
+.video-player-panel[hidden] {
   display: none;
 }
 
-/* Shown when the container is one browsers cannot play, or when the <video>
-   element reports an error. */
-.video-player-fallback {
-  padding: 2em 1em;
-  text-align: center;
-  color: #ddd;
+.video-player-panel-message {
+  margin: 0;
+  overflow-wrap: anywhere;
 }
 
-.video-player-fallback[hidden] {
-  display: none;
+.video-player-panel-note {
+  margin: 0;
+  color: #aaa;
+  font-size: 0.85rem;
+  /* Reserves the line so the panel does not jump when the first percentage
+     replaces an empty string. */
+  min-height: 1em;
 }
 
-.video-player-fallback p {
-  margin: 0 0 1em;
+.video-player-bar {
+  width: min(320px, 76%);
+  height: 6px;
+  border-radius: 999px;
+  /* Opaque, not translucent: over a light frame a translucent trough is
+     brighter than the fill and the bar reads backwards. */
+  background: #2c2c2c;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.6);
+  overflow: hidden;
+}
+
+.video-player-bar-fill {
+  width: 0;
+  height: 100%;
+  border-radius: inherit;
+  background: #6ea8fe;
+  transition: width 0.3s ease;
+}
+
+/* A source whose duration ffmpeg could not determine gives no percentage to
+   show, so the bar sweeps rather than lying about progress it does not have. */
+.video-player-bar--indeterminate .video-player-bar-fill {
+  width: 35%;
+  animation: video-player-sweep 1.4s ease-in-out infinite;
+}
+
+@keyframes video-player-sweep {
+  from {
+    transform: translateX(-120%);
+  }
+  to {
+    transform: translateX(340%);
+  }
 }
 
 .video-player-download {
@@ -74,3 +208,18 @@
 .video-player-download[hidden] {
   display: none;
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .video-player-close,
+  .video-player-bar-fill {
+    transition: none;
+  }
+
+  /* Still distinguishable from a real 100%: dimmed, and paired with the
+     "unknown duration" wording in the panel above it. */
+  .video-player-bar--indeterminate .video-player-bar-fill {
+    width: 100%;
+    animation: none;
+    opacity: 0.45;
+  }
+}
diff --git a/photomap/frontend/static/javascript/video-badge.js b/photomap/frontend/static/javascript/video-badge.js
index 6362fe22..fde76452 100644
--- a/photomap/frontend/static/javascript/video-badge.js
+++ b/photomap/frontend/static/javascript/video-badge.js
@@ -190,6 +190,14 @@ export function applyVideoOverlay(slideEl, data) {
           url: data.video_url || "",
           filename: data.filename || "",
           playable: videoInfo.playable !== false,
+          // The extracted still. The player shows it while a conversion
+          // runs, and sizes its frame from it before any metadata has
+          // arrived — without it the frame has no aspect ratio to take.
+          poster: data.image_url || "",
+          // Where the player asks for a browser-playable copy when the
+          // original turns out not to be one. Empty from a server predating
+          // conversion support, which the player reads as "download only".
+          transcodeUrl: data.video_transcode_url || "",
           globalIndex: Number(slideEl.dataset.globalIndex ?? -1),
         },
       })
diff --git a/photomap/frontend/static/javascript/video-player.js b/photomap/frontend/static/javascript/video-player.js
index 6b646416..673e796c 100644
--- a/photomap/frontend/static/javascript/video-player.js
+++ b/photomap/frontend/static/javascript/video-player.js
@@ -8,6 +8,13 @@
  * slide. Swiper destroys slide DOM nodes as the user navigates
  * (`trimShuffleBacklog`, `enforceHighWaterMark`, `resetAllSlides`), and a
  * detached `<video>` goes on playing audio.
+ *
+ * A container the browser cannot decode is not a dead end: the player asks
+ * the backend to convert the file (see `video_transcode.py`), shows the
+ * conversion's progress over the poster, and plays the result. That poll is
+ * also the backend's liveness signal — it drops a job nobody is asking about
+ * — so closing the player has to stop the polling, which is what the
+ * `session` counter below is for.
  */
 
 import { state } from "./state.js";
@@ -15,9 +22,15 @@ import { state } from "./state.js";
 let modal = null;
 let videoEl = null;
 let titleEl = null;
+let closeBtn = null;
 let fallbackEl = null;
 let fallbackMessageEl = null;
 let downloadLinkEl = null;
+let progressEl = null;
+let progressMessageEl = null;
+let progressBarEl = null;
+let progressFillEl = null;
+let progressPercentEl = null;
 let initialized = false;
 
 // Whether the slideshow was running when the player opened. Restored rather
@@ -25,47 +38,119 @@ let initialized = false;
 // doesn't silently start it.
 let slideshowWasRunning = false;
 
+/**
+ * Bumped on every open and every close.
+ *
+ * Every conversion poll captures the value it started under and abandons
+ * itself the moment it no longer matches. Without that, a response in flight
+ * when the user closes the player — or navigates to a *different* video —
+ * lands afterwards and starts playing the wrong clip into a dismissed modal.
+ */
+let session = 0;
+let pollTimer = null;
+
+// What the currently open request is about, so the async conversion path can
+// still name the file and offer the original for download.
+let current = null;
+
+// Whether the element is playing a converted copy. Decides what an `error`
+// means: the first one sends us to the converter, a second one (from the
+// conversion itself) is a real dead end and must not loop.
+let usingConversion = false;
+
+// How often to ask the backend how the conversion is going. Comfortably
+// inside its abandonment window, which is measured in tens of seconds.
+const POLL_INTERVAL_MS = 1000;
+
 export function isVideoPlayerOpen() {
   return Boolean(modal?.classList.contains("visible"));
 }
 
+/** The subject of a message, when the filename is not known. */
+function subject() {
+  return current?.filename || "This video";
+}
+
 function showFallback(message, url) {
   if (!fallbackEl) {
     return;
   }
+  if (progressEl) {
+    progressEl.hidden = true;
+  }
   fallbackMessageEl.textContent = message;
   if (downloadLinkEl) {
     downloadLinkEl.href = url || "#";
     downloadLinkEl.hidden = !url;
   }
   fallbackEl.hidden = false;
+  // The native control bar would otherwise show through the scrim, offering
+  // transport controls for something that is not going to play.
+  if (videoEl) {
+    videoEl.controls = false;
+  }
+}
+
+/**
+ * Show the conversion panel.
+ *
+ * @param {string} message what is happening, in words
+ * @param {number|null} progress 0..1, or null when the backend cannot say
+ *   (a source whose duration ffmpeg could not determine). A sweeping bar is
+ *   honest about that; a bar sitting at 0% reads as stuck.
+ */
+function showProgress(message, progress) {
+  if (!progressEl) {
+    return;
+  }
+  if (fallbackEl) {
+    fallbackEl.hidden = true;
+  }
+  const known = typeof progress === "number" && Number.isFinite(progress) && progress > 0;
+  const percent = known ? Math.round(progress * 100) : 0;
+
+  progressMessageEl.textContent = message;
+  progressBarEl?.classList.toggle("video-player-bar--indeterminate", !known);
+  progressBarEl?.setAttribute("aria-valuenow", String(percent));
+  if (progressFillEl) {
+    // Cleared rather than set to 0% in the indeterminate case: the sweep
+    // animation supplies the width, and an inline one would override it.
+    progressFillEl.style.width = known ? `${percent}%` : "";
+  }
+  if (progressPercentEl) {
+    progressPercentEl.textContent = known ? `${percent}%` : "";
+  }
+  progressEl.hidden = false;
   if (videoEl) {
-    videoEl.hidden = true;
+    videoEl.controls = false;
   }
 }
 
-function hideFallback() {
+function hidePanels() {
   if (fallbackEl) {
     fallbackEl.hidden = true;
   }
+  if (progressEl) {
+    progressEl.hidden = true;
+  }
   if (videoEl) {
-    videoEl.hidden = false;
+    videoEl.controls = true;
   }
 }
 
 /**
  * Start playing as soon as the player opens.
  *
- * This runs inside the click on the play badge — window events dispatch
- * synchronously, so the gesture's transient user activation is still live —
- * which is what lets playback start *with sound* instead of being refused by
- * the browser's autoplay policy.
+ * On the direct path this runs inside the click on the play badge — window
+ * events dispatch synchronously, so the gesture's transient user activation
+ * is still live — which is what lets playback start *with sound* instead of
+ * being refused by the browser's autoplay policy.
  *
- * A rejection here is not a playback failure and must not raise the error
- * fallback. It means either the browser declined anyway (NotAllowedError, on
- * a stricter policy or a synthetic open) or the load was torn down while
- * still pending (AbortError, from closing the modal quickly). In both cases
- * the native controls are right there for the user.
+ * On the conversion path the activation is long gone by the time the file is
+ * ready, so the browser may well decline. That is not a failure and must not
+ * raise the error fallback: the clip is loaded, the controls are right there,
+ * and the user presses play. The same is true of an AbortError from the load
+ * being torn down while still pending (closing the modal quickly).
  */
 function startPlayback() {
   const started = videoEl?.play?.();
@@ -74,7 +159,15 @@ function startPlayback() {
   });
 }
 
-/** Stop playback and release the stream. */
+/** Point the element at `url` and start it. */
+function playFrom(url) {
+  hidePanels();
+  videoEl.src = url;
+  startPlayback();
+  focusPlayer();
+}
+
+/** Stop playback and release the stream, leaving the modal as it is. */
 function teardownVideo() {
   if (!videoEl) {
     return;
@@ -86,16 +179,124 @@ function teardownVideo() {
   videoEl.load();
 }
 
-export function openVideoPlayer({ url, filename, playable = true } = {}) {
+/**
+ * Focus the video, so Space reaches playback — or the close button when there
+ * is nothing to play.
+ *
+ * shouldIgnoreKeyEvent() lets Space through to the player precisely so the
+ * native controls can pause, but a focused <button> activates on Space, so
+ * focusing the close button while a clip is playing hands it the key instead
+ * and Space *dismisses the player* mid-clip. Verified in Chromium: close
+ * button focused, Space fires the button's click; video focused, Space
+ * toggles playback.
+ *
+ * With no src there is nothing for Space to drive and the native controls are
+ * hidden behind a panel, so the close button is the right target.
+ */
+function focusPlayer() {
+  const target = videoEl?.getAttribute("src") ? videoEl : closeBtn;
+  target?.focus?.();
+}
+
+/**
+ * Ask the backend for a playable copy, and follow it until it is ready.
+ *
+ * @param {number} mySession the session this belongs to; anything else means
+ *   the player has moved on and this must stop silently.
+ */
+async function pollConversion(mySession, endpoint) {
+  let status;
+  try {
+    // POST because the first call starts work — but it is idempotent, and
+    // repeating it is both how progress is read and how the backend knows
+    // somebody is still waiting.
+    const response = await fetch(endpoint, { method: "POST" });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    status = await response.json();
+  } catch (err) {
+    if (mySession !== session) {
+      return;
+    }
+    console.debug("Video conversion request failed:", err);
+    showFallback(`${subject()} could not be prepared for playback.`, current?.url || "");
+    return;
+  }
+
+  if (mySession !== session) {
+    return;
+  }
+
+  if (status.state === "ready" && status.url) {
+    usingConversion = true;
+    playFrom(status.url);
+    return;
+  }
+
+  if (status.state === "queued" || status.state === "running") {
+    showProgress(
+      status.state === "queued" ? "Waiting to convert this video…" : "Converting this video for playback…",
+      status.progress
+    );
+    pollTimer = setTimeout(() => pollConversion(mySession, endpoint), POLL_INTERVAL_MS);
+    return;
+  }
+
+  // "failed", "unavailable", and the should-not-happen "ready" with no URL.
+  // The original file is still offered: it may well play in another
+  // application even though no browser will touch it.
+  showFallback(status.detail || `${subject()} could not be converted for playback.`, current?.url || "");
+}
+
+/** Hand this video to the backend converter. */
+function beginConversion(mySession) {
+  const endpoint = current?.transcodeUrl;
+  if (!endpoint) {
+    // An older server, or a payload with no conversion route. Behave the way
+    // the player did before conversion existed.
+    showFallback(`${subject()} is in a format your browser cannot play.`, current?.url || "");
+    return;
+  }
+
+  // Release the original first. It is still streaming bytes that nothing can
+  // decode, and on a large file over a slow mount that competes for
+  // bandwidth with the conversion's own reads.
+  teardownVideo();
+  showProgress("Preparing this video for playback…", null);
+  focusPlayer();
+  pollConversion(mySession, endpoint);
+}
+
+export function openVideoPlayer({ url, filename, playable = true, poster = "", transcodeUrl = "" } = {}) {
   if (!modal) {
     return;
   }
 
+  // Supersede anything the previous open left in flight before touching any
+  // shared state below.
+  const mySession = ++session;
+  clearTimeout(pollTimer);
+  pollTimer = null;
+  current = { url, filename, transcodeUrl };
+  usingConversion = false;
+
   if (titleEl) {
     titleEl.textContent = filename || "";
   }
 
-  hideFallback();
+  // The extracted still, which the frame sizes itself from and which stays
+  // visible behind the conversion panel. Removed rather than left stale when
+  // there is none, or the previous clip's frame shows behind this one.
+  if (videoEl) {
+    if (poster) {
+      videoEl.setAttribute("poster", poster);
+    } else {
+      videoEl.removeAttribute("poster");
+    }
+  }
+
+  hidePanels();
 
   // Mark the modal open before anything can start streaming. closeVideoPlayer
   // early-returns when the modal is not visible, so a close arriving between
@@ -105,14 +306,13 @@ export function openVideoPlayer({ url, filename, playable = true } = {}) {
 
   if (!url) {
     showFallback("This video is unavailable.", "");
+    focusPlayer();
   } else if (playable === false) {
-    // The static hint says browsers generally can't play this container. Say
-    // so up front rather than showing a black rectangle, but still offer the
-    // file — see the error handler for the cases the hint gets wrong.
-    showFallback(`${filename || "This video"} is in a format your browser probably cannot play.`, url);
+    // The container is one browsers generally cannot decode. Skip the
+    // black-rectangle-then-error round trip and convert straight away.
+    beginConversion(mySession);
   } else {
-    videoEl.src = url;
-    startPlayback();
+    playFrom(url);
   }
 
   // Snapshot before pausing, and restore rather than force-start on close.
@@ -121,20 +321,6 @@ export function openVideoPlayer({ url, filename, playable = true } = {}) {
   // Otherwise the arrow keys change slides behind the modal while the user is
   // trying to scrub.
   state.swiper?.keyboard?.disable?.();
-
-  // Focus the video, not the close button.
-  //
-  // shouldIgnoreKeyEvent() lets Space through to the player precisely so the
-  // native controls can pause — but a focused <button> activates on Space, so
-  // focusing the close button hands it the key instead and Space *dismisses
-  // the player* mid-clip. Verified in Chromium: close button focused, Space
-  // fires the button's click; video focused, Space toggles playback.
-  //
-  // When the fallback is showing there is no video to drive, and the element
-  // is hidden (an unfocusable element would silently leave focus on <body>),
-  // so the close button is the right target there.
-  const focusTarget = videoEl && !videoEl.hidden ? videoEl : modal.querySelector(".modal-close");
-  focusTarget?.focus?.();
 }
 
 export function closeVideoPlayer() {
@@ -142,9 +328,18 @@ export function closeVideoPlayer() {
     return;
   }
 
+  // Strands any conversion poll in flight, and tells the backend — which
+  // treats the absence of polls as abandonment — that this job can be dropped.
+  session++;
+  clearTimeout(pollTimer);
+  pollTimer = null;
+
   teardownVideo();
+  videoEl?.removeAttribute("poster");
   modal.classList.remove("visible");
-  hideFallback();
+  hidePanels();
+  current = null;
+  usingConversion = false;
 
   state.swiper?.keyboard?.enable?.();
   if (slideshowWasRunning) {
@@ -163,13 +358,19 @@ export function initializeVideoPlayer() {
   }
   videoEl = document.getElementById("videoPlayerElement");
   titleEl = document.getElementById("videoPlayerTitle");
+  closeBtn = document.getElementById("videoPlayerCloseBtn");
   fallbackEl = document.getElementById("videoPlayerFallback");
   fallbackMessageEl = document.getElementById("videoPlayerFallbackMessage");
   downloadLinkEl = document.getElementById("videoPlayerDownloadLink");
+  progressEl = document.getElementById("videoPlayerProgress");
+  progressMessageEl = document.getElementById("videoPlayerProgressMessage");
+  progressBarEl = document.getElementById("videoPlayerProgressBar");
+  progressFillEl = document.getElementById("videoPlayerProgressFill");
+  progressPercentEl = document.getElementById("videoPlayerProgressPercent");
 
-  document.getElementById("videoPlayerCloseBtn")?.addEventListener("click", closeVideoPlayer);
+  closeBtn?.addEventListener("click", closeVideoPlayer);
 
-  // Click the backdrop to dismiss, but not a click inside the panel.
+  // Click the backdrop to dismiss, but not a click on the frame.
   modal.addEventListener("click", (e) => {
     if (e.target === modal) {
       closeVideoPlayer();
@@ -184,7 +385,13 @@ export function initializeVideoPlayer() {
     if (!url) {
       return; // teardown clears src, which fires error; not a real failure
     }
-    showFallback(`${titleEl?.textContent || "This video"} could not be played in your browser.`, url);
+    if (usingConversion) {
+      // The converted copy is H.264/AAC in an MP4. If *that* will not play,
+      // nothing the backend can produce will, and re-converting would loop.
+      showFallback(`${subject()} could not be played even after conversion.`, current?.url || url);
+      return;
+    }
+    beginConversion(session);
   });
 
   // A playing video must not be left behind by navigation: the modal would
@@ -206,8 +413,19 @@ export function _resetVideoPlayerForTests() {
   modal = null;
   videoEl = null;
   titleEl = null;
+  closeBtn = null;
   fallbackEl = null;
   fallbackMessageEl = null;
   downloadLinkEl = null;
+  progressEl = null;
+  progressMessageEl = null;
+  progressBarEl = null;
+  progressFillEl = null;
+  progressPercentEl = null;
   slideshowWasRunning = false;
+  clearTimeout(pollTimer);
+  pollTimer = null;
+  session = 0;
+  current = null;
+  usingConversion = false;
 }
diff --git a/photomap/frontend/templates/modules/video-player-modal.html b/photomap/frontend/templates/modules/video-player-modal.html
index af2e211e..61c1f052 100644
--- a/photomap/frontend/templates/modules/video-player-modal.html
+++ b/photomap/frontend/templates/modules/video-player-modal.html
@@ -1,9 +1,20 @@
-<!-- Modal video player. Opened by the play badge on a video still. -->
-<div id="videoPlayerModal" class="modal-overlay">
-  <div class="modal-content video-player-content">
-    <button class="modal-close" id="videoPlayerCloseBtn" aria-label="Close video player">&times;</button>
-    <div class="video-player-title" id="videoPlayerTitle"></div>
+<!-- Modal video player. Opened by the play badge on a video still.
 
+     Deliberately NOT built on `.modal-content`. That is a #222 panel with a
+     2em pad and a rounded border, and wrapping it around a black <video> —
+     itself a bordered rectangle — reads as a frame inside a frame. This is a
+     lightbox instead: the media card sits directly on the dimmed backdrop,
+     the way InvokeAI's preview stage does, with the filename as a caption
+     below it rather than a title row above it. -->
+<div id="videoPlayerModal" class="modal-overlay video-player-overlay">
+  <button class="video-player-close" id="videoPlayerCloseBtn" aria-label="Close video player">&times;</button>
+
+  <!-- Shrink-wraps the video: the border and shadow hug the picture at
+       whatever aspect ratio the clip turns out to have, instead of boxing a
+       portrait phone video into a landscape panel. The min-height in the CSS
+       is what keeps it from collapsing to nothing in the moment before a
+       poster or any metadata has arrived. -->
+  <div class="video-player-frame" id="videoPlayerFrame">
     <!-- The <video> lives here permanently rather than being created per
          open, so its listeners are wired once. Its src is set on open and
          cleared on close — leaving a src behind keeps the browser streaming
@@ -27,11 +38,31 @@
       tabindex="0"
     ></video>
 
-    <!-- Shown instead of the player when the container is one browsers
-         cannot play, or when the <video> reports an error. -->
-    <div class="video-player-fallback" id="videoPlayerFallback" hidden>
-      <p id="videoPlayerFallbackMessage"></p>
+    <!-- Both panels are absolutely positioned OVER the frame rather than
+         replacing the video. The poster stays visible underneath, so the
+         frame keeps the clip's own aspect ratio and the user is looking at
+         the video they asked for while it converts, not at a grey box. -->
+    <div class="video-player-panel video-player-progress" id="videoPlayerProgress" hidden>
+      <p class="video-player-panel-message" id="videoPlayerProgressMessage"></p>
+      <div
+        class="video-player-bar"
+        id="videoPlayerProgressBar"
+        role="progressbar"
+        aria-valuemin="0"
+        aria-valuemax="100"
+        aria-valuenow="0"
+      >
+        <div class="video-player-bar-fill" id="videoPlayerProgressFill"></div>
+      </div>
+      <p class="video-player-panel-note" id="videoPlayerProgressPercent"></p>
+    </div>
+
+    <!-- Shown when the video cannot be played and cannot be converted either. -->
+    <div class="video-player-panel video-player-fallback" id="videoPlayerFallback" hidden>
+      <p class="video-player-panel-message" id="videoPlayerFallbackMessage"></p>
       <a id="videoPlayerDownloadLink" class="video-player-download" href="#" download>Download the video</a>
     </div>
   </div>
+
+  <div class="video-player-title" id="videoPlayerTitle"></div>
 </div>
diff --git a/tests/backend/conftest.py b/tests/backend/conftest.py
index 1340dba7..7222f89e 100644
--- a/tests/backend/conftest.py
+++ b/tests/backend/conftest.py
@@ -4,7 +4,7 @@
 import yaml
 
 # Import fixtures so they're available to all tests
-from fixtures import client, new_album, new_media_album  # noqa: F401
+from fixtures import client, mixed_album, new_album, new_media_album  # noqa: F401
 
 
 @pytest.fixture(autouse=True)
@@ -28,6 +28,29 @@ def isolate_video_frame_cache(tmp_path_factory, monkeypatch):
     return root
 
 
+@pytest.fixture(autouse=True)
+def isolate_video_transcode_cache(tmp_path_factory, monkeypatch):
+    """The same isolation for converted videos, for the same reason.
+
+    ``TranscodeCache`` also defaults to ``platformdirs.user_cache_dir`` and is
+    also constructed inside the routes with no seam, and deleting an album
+    ``rmtree``s its directory. The stakes are higher here than for stills:
+    these files are whole movies.
+
+    The job registry is reset alongside it. Jobs are module-level state keyed
+    by album and content digest, so a test that leaves a "failed" entry behind
+    would make the next test's request return that stale failure instead of
+    starting work.
+    """
+    from photomap.backend import video_transcode
+
+    root = tmp_path_factory.mktemp("video_transcodes")
+    monkeypatch.setattr(video_transcode, "transcode_cache_root", lambda: root)
+    video_transcode._reset_jobs_for_tests()
+    yield root
+    video_transcode._reset_jobs_for_tests()
+
+
 @pytest.fixture(autouse=True)
 def isolate_user_data_dir(tmp_path_factory, monkeypatch):
     """Keep derived board-album indexes out of the real user data directory.
diff --git a/tests/backend/fixtures.py b/tests/backend/fixtures.py
index 1ed81224..0b0eb1af 100644
--- a/tests/backend/fixtures.py
+++ b/tests/backend/fixtures.py
@@ -6,9 +6,15 @@
 import time
 from pathlib import Path
 
+import numpy as np
 import pytest
 from fastapi.testclient import TestClient
 
+from photomap.backend.embeddings import _open_npz_file
+from photomap.backend.util import atomic_savez
+from photomap.backend.video import VIDEO_METADATA_KEY, ffmpeg_exe
+from photomap.backend.video_cache import VideoFrameCache
+
 
 @pytest.fixture
 def client() -> TestClient:
@@ -157,3 +163,96 @@ def media_fixture_path(name: str) -> Path:
 def count_test_media():
     """Count the number of test videos in the fixtures directory."""
     return len([f for f in TEST_MEDIA_DIR.iterdir() if f.is_file()])
+
+
+# --------------------------------------------------------------------------
+# Mixed image/video album
+#
+# Shared rather than owned by test_video_serving because several suites need
+# the same album: serving bytes, serving stills, and converting an unplayable
+# file all want one album holding one photo and one video. Importing a fixture
+# from another *test* module works but makes ruff read every use of it as a
+# redefinition (F811); fixtures.py is where conftest already picks fixtures up
+# from, so nothing has to import it at all.
+# --------------------------------------------------------------------------
+
+ENCODER_SPEC = "openai-clip:ViT-B/32"
+EMBEDDING_DIM = 8
+
+requires_ffmpeg = pytest.mark.skipif(
+    ffmpeg_exe() is None, reason="no bundled ffmpeg binary on this platform"
+)
+
+
+def _write_synthetic_index(index_path, files, metadatas):
+    """Write an .npz with the given files, bypassing the real encoder."""
+    rng = np.random.default_rng(0)
+    embeddings = rng.random((len(files), EMBEDDING_DIM)).astype(np.float32)
+    embeddings /= np.linalg.norm(embeddings, axis=1, keepdims=True)
+    index_path.parent.mkdir(parents=True, exist_ok=True)
+    atomic_savez(
+        index_path,
+        embeddings=embeddings,
+        filenames=np.array([f.resolve().as_posix() for f in files]),
+        modification_times=np.array(
+            [float(i + 1) for i in range(len(files))], dtype=float
+        ),
+        metadata=np.array(metadatas, dtype=object),
+        model_id=np.array(ENCODER_SPEC),
+        embedding_dim=np.array(EMBEDDING_DIM),
+    )
+    _open_npz_file.cache_clear()
+
+
+VIDEO_INFO = {
+    "duration": 2.0,
+    "fps": 10.0,
+    "width": 64,
+    "height": 64,
+    "codec": "h264",
+    "container": "mov,mp4,m4a,3gp,3g2,mj2",
+    "playable": True,
+}
+
+
+@pytest.fixture
+def mixed_album(client, tmp_path):
+    """An album holding one photo and one video, with a synthetic index.
+
+    Files are ordered so the video sorts to index 0 and the photo to index 1
+    (modification_times drive the lexsort).
+    """
+    media_dir = tmp_path / "mixed"
+    media_dir.mkdir()
+
+    video = media_dir / "clip.mp4"
+    shutil.copy(media_fixture_path("clip.mp4"), video)
+    photo = media_dir / "building1.jpeg"
+    shutil.copy(
+        media_fixture_path("../test_images/building1.jpeg").resolve(), photo
+    )
+
+    index_path = media_dir / "photomap_index" / "embeddings.npz"
+    _write_synthetic_index(
+        index_path,
+        [video, photo],
+        [{VIDEO_METADATA_KEY: dict(VIDEO_INFO)}, {"Make": "TestCam"}],
+    )
+
+    album = {
+        "key": "mixed_album",
+        "name": "Mixed Album",
+        "image_paths": [media_dir.as_posix()],
+        "index": index_path.as_posix(),
+        "umap_eps": 0.1,
+        "description": "",
+        "encoder_spec": ENCODER_SPEC,
+    }
+    try:
+        # Inside the try: a failure here would otherwise leak the album past
+        # teardown and poison every later test using this fixture.
+        assert client.post("/add_album/", json=album).status_code == 201
+        yield {**album, "video": video, "photo": photo, "media_dir": media_dir}
+    finally:
+        VideoFrameCache(album["key"]).clear()
+        client.delete(f"/delete_album/{album['key']}")
diff --git a/tests/backend/test_video_serving.py b/tests/backend/test_video_serving.py
index de499a0b..ed0db233 100644
--- a/tests/backend/test_video_serving.py
+++ b/tests/backend/test_video_serving.py
@@ -8,101 +8,18 @@
 
 from __future__ import annotations
 
-import shutil
 from io import BytesIO
 
-import numpy as np
-import pytest
-from fixtures import media_fixture_path
+from fixtures import (
+    ENCODER_SPEC,
+    _write_synthetic_index,
+    requires_ffmpeg,
+)
 from PIL import Image
 
-from photomap.backend.embeddings import _open_npz_file
-from photomap.backend.util import atomic_savez
-from photomap.backend.video import VIDEO_METADATA_KEY, ffmpeg_exe
+from photomap.backend.video import VIDEO_METADATA_KEY
 from photomap.backend.video_cache import VideoFrameCache
 
-ENCODER_SPEC = "openai-clip:ViT-B/32"
-EMBEDDING_DIM = 8
-
-requires_ffmpeg = pytest.mark.skipif(
-    ffmpeg_exe() is None, reason="no bundled ffmpeg binary on this platform"
-)
-
-
-def _write_synthetic_index(index_path, files, metadatas):
-    """Write an .npz with the given files, bypassing the real encoder."""
-    rng = np.random.default_rng(0)
-    embeddings = rng.random((len(files), EMBEDDING_DIM)).astype(np.float32)
-    embeddings /= np.linalg.norm(embeddings, axis=1, keepdims=True)
-    index_path.parent.mkdir(parents=True, exist_ok=True)
-    atomic_savez(
-        index_path,
-        embeddings=embeddings,
-        filenames=np.array([f.resolve().as_posix() for f in files]),
-        modification_times=np.array(
-            [float(i + 1) for i in range(len(files))], dtype=float
-        ),
-        metadata=np.array(metadatas, dtype=object),
-        model_id=np.array(ENCODER_SPEC),
-        embedding_dim=np.array(EMBEDDING_DIM),
-    )
-    _open_npz_file.cache_clear()
-
-
-VIDEO_INFO = {
-    "duration": 2.0,
-    "fps": 10.0,
-    "width": 64,
-    "height": 64,
-    "codec": "h264",
-    "container": "mov,mp4,m4a,3gp,3g2,mj2",
-    "playable": True,
-}
-
-
-@pytest.fixture
-def mixed_album(client, tmp_path):
-    """An album holding one photo and one video, with a synthetic index.
-
-    Files are ordered so the video sorts to index 0 and the photo to index 1
-    (modification_times drive the lexsort).
-    """
-    media_dir = tmp_path / "mixed"
-    media_dir.mkdir()
-
-    video = media_dir / "clip.mp4"
-    shutil.copy(media_fixture_path("clip.mp4"), video)
-    photo = media_dir / "building1.jpeg"
-    shutil.copy(
-        media_fixture_path("../test_images/building1.jpeg").resolve(), photo
-    )
-
-    index_path = media_dir / "photomap_index" / "embeddings.npz"
-    _write_synthetic_index(
-        index_path,
-        [video, photo],
-        [{VIDEO_METADATA_KEY: dict(VIDEO_INFO)}, {"Make": "TestCam"}],
-    )
-
-    album = {
-        "key": "mixed_album",
-        "name": "Mixed Album",
-        "image_paths": [media_dir.as_posix()],
-        "index": index_path.as_posix(),
-        "umap_eps": 0.1,
-        "description": "",
-        "encoder_spec": ENCODER_SPEC,
-    }
-    try:
-        # Inside the try: a failure here would otherwise leak the album past
-        # teardown and poison every later test using this fixture.
-        assert client.post("/add_album/", json=album).status_code == 201
-        yield {**album, "video": video, "photo": photo, "media_dir": media_dir}
-    finally:
-        VideoFrameCache(album["key"]).clear()
-        client.delete(f"/delete_album/{album['key']}")
-
-
 # --------------------------------------------------------------------------
 # /videos/ — byte serving and range support
 # --------------------------------------------------------------------------
diff --git a/tests/backend/test_video_transcode.py b/tests/backend/test_video_transcode.py
new file mode 100644
index 00000000..80a107c3
--- /dev/null
+++ b/tests/backend/test_video_transcode.py
@@ -0,0 +1,632 @@
+"""Converting videos the browser cannot play.
+
+Three layers, deliberately separated:
+
+* the **decision** (``probe_streams`` -> ``plan_for`` -> ``ffmpeg_args``),
+  which is pure and tested against captured banners with no ffmpeg at all;
+* the **cache and job registry**, tested against the filesystem;
+* the **routes**, tested through the app, including the guards that stop
+  ``/prepare_video/<key>/passwd`` from becoming an arbitrary-file-read.
+
+Only the two end-to-end tests need a real ffmpeg binary.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+import pytest
+from fixtures import (
+    ENCODER_SPEC,
+    VIDEO_INFO,
+    _write_synthetic_index,
+    media_fixture_path,
+    requires_ffmpeg,
+)
+
+from photomap.backend import video as video_module
+from photomap.backend import video_transcode
+from photomap.backend.video import StreamProbe, ffmpeg_exe, probe_streams
+from photomap.backend.video_cache import VideoFrameCache
+from photomap.backend.video_transcode import (
+    TranscodeCache,
+    ffmpeg_args,
+    plan_for,
+    request_transcode,
+    sweep_transcode_cache,
+)
+
+# --------------------------------------------------------------------------
+# probe_streams — what is actually inside the container
+# --------------------------------------------------------------------------
+
+# Captured from the bundled ffmpeg. Parser tests run against fixed strings so
+# they need no binary.
+MODERN_BANNER = """Input #0, matroska,webm, from 'modern.mkv':
+  Metadata:
+    ENCODER         : Lavf61.1.100
+  Duration: 00:00:04.02, start: 0.000000, bitrate: 110 kb/s
+  Stream #0:0: Video: h264 (High), yuv420p(progressive), 320x240 [SAR 1:1 DAR 4:3], 15 fps, 15 tbr, 1k tbn
+  Stream #0:1: Audio: aac (LC), 44100 Hz, mono, fltp
+At least one output file must be specified
+"""
+
+TEN_BIT_BANNER = """Input #0, matroska,webm, from 'hdr.mkv':
+  Duration: 00:00:10.00, start: 0.000000, bitrate: 900 kb/s
+  Stream #0:0: Video: h264 (High 10), yuv420p10le(tv, progressive), 1920x1080, 24 fps, 24 tbr, 1k tbn
+  Stream #0:1: Audio: ac3, 48000 Hz, 5.1, fltp, 448 kb/s
+At least one output file must be specified
+"""
+
+OLD_AVI_BANNER = """Input #0, avi, from 'old.avi':
+  Duration: 00:00:04.07, start: 0.000000, bitrate: 118 kb/s
+  Stream #0:0: Video: mpeg4 (Simple Profile) (xvid / 0x64697678), yuv420p, 320x240, 15 fps, 15 tbr, 15 tbn
+  Stream #0:1: Audio: mp3 (U[0][0][0] / 0x0055), 44100 Hz, mono, fltp, 64 kb/s
+At least one output file must be specified
+"""
+
+SILENT_BANNER = """Input #0, mov,mp4,m4a,3gp,3g2,mj2, from 'silent.mp4':
+  Duration: 00:00:02.00, start: 0.000000, bitrate: 40 kb/s
+  Stream #0:0[0x1](und): Video: h264 (High) (avc1 / 0x61766331), yuv420p, 64x64, 10 fps, 10 tbr, 10240 tbn
+At least one output file must be specified
+"""
+
+COVER_ART_BANNER = """Input #0, ogg, from 'song.ogg':
+  Duration: 00:03:20.00, start: 0.000000, bitrate: 128 kb/s
+  Stream #0:0: Video: mjpeg (attached pic), yuvj420p(pc), 500x500, 90k tbr
+  Stream #0:1: Audio: vorbis, 44100 Hz, stereo, fltp, 128 kb/s
+At least one output file must be specified
+"""
+
+
+class _FakeRun:
+    """Stands in for ``subprocess.CompletedProcess`` with a canned banner."""
+
+    def __init__(self, banner: str) -> None:
+        self.stderr = banner.encode()
+        self.stdout = b""
+        self.returncode = 1
+
+
+@pytest.fixture
+def banner(monkeypatch):
+    """Make ``probe_streams`` see whatever banner a test hands it."""
+
+    def install(text: str) -> None:
+        monkeypatch.setattr(
+            video_module, "_run_ffmpeg", lambda args, timeout: _FakeRun(text)
+        )
+
+    return install
+
+
+def test_probe_reads_codecs_pixel_format_and_duration(banner):
+    banner(MODERN_BANNER)
+    probe = probe_streams(Path("modern.mkv"))
+    assert probe.duration == pytest.approx(4.02)
+    assert probe.has_video and probe.video_codec == "h264"
+    assert probe.video_pix_fmt == "yuv420p"
+    assert probe.has_audio and probe.audio_codec == "aac"
+
+
+def test_probe_distinguishes_ten_bit_from_eight_bit(banner):
+    """The whole point of parsing the pixel format.
+
+    ``yuv420p10le`` contains ``yuv420p`` as a substring, so a naive contains
+    test would call a 10-bit stream copy-safe — and browsers do not decode it,
+    which is the exact black rectangle this feature exists to remove.
+    """
+    banner(TEN_BIT_BANNER)
+    probe = probe_streams(Path("hdr.mkv"))
+    assert probe.video_codec == "h264"
+    assert probe.video_pix_fmt == "yuv420p10le"
+
+
+def test_probe_reports_a_silent_file_as_having_no_audio(banner):
+    banner(SILENT_BANNER)
+    probe = probe_streams(Path("silent.mp4"))
+    assert probe.has_video is True
+    assert probe.has_audio is False
+    assert probe.audio_codec is None
+
+
+def test_probe_ignores_cover_art_as_a_video_stream(banner):
+    """An audio file with embedded art must not look like a video to convert."""
+    banner(COVER_ART_BANNER)
+    probe = probe_streams(Path("song.ogg"))
+    assert probe.has_video is False
+    assert probe.video_codec is None
+    assert probe.audio_codec == "vorbis"
+
+
+def test_probe_returns_none_when_ffmpeg_is_unavailable(monkeypatch):
+    monkeypatch.setattr(
+        video_module, "_run_ffmpeg", lambda args, timeout: video_module.FFMPEG_UNAVAILABLE
+    )
+    assert probe_streams(Path("anything.mkv")) is None
+
+
+def test_probe_of_garbage_reports_nothing_rather_than_raising(banner):
+    banner("this is not an ffmpeg banner at all")
+    probe = probe_streams(Path("junk.bin"))
+    assert probe.has_video is False and probe.duration is None
+
+
+# --------------------------------------------------------------------------
+# plan_for — remux when possible, re-encode when not
+# --------------------------------------------------------------------------
+
+
+def test_plan_remuxes_h264_aac(banner):
+    banner(MODERN_BANNER)
+    plan = plan_for(probe_streams(Path("modern.mkv")))
+    assert plan.copy_video and plan.copy_audio
+    assert plan.is_remux is True
+    assert plan.duration == pytest.approx(4.02)
+
+
+def test_plan_re_encodes_ten_bit_video_and_ac3_audio(banner):
+    banner(TEN_BIT_BANNER)
+    plan = plan_for(probe_streams(Path("hdr.mkv")))
+    assert plan.copy_video is False
+    assert plan.copy_audio is False
+    assert plan.is_remux is False
+
+
+def test_plan_re_encodes_an_old_codec(banner):
+    banner(OLD_AVI_BANNER)
+    plan = plan_for(probe_streams(Path("old.avi")))
+    assert plan.copy_video is False
+    # MP4 can legally carry MP3 and browsers do decode it, but Safari has a
+    # history of playing it as silence. Audio re-encodes at ~100x realtime, so
+    # copying it saves nothing worth the risk.
+    assert plan.copy_audio is False
+
+
+def test_plan_copies_video_even_when_only_the_audio_is_wrong():
+    """The common .mkv case: H.264 picture, AC-3 sound.
+
+    Copying the video and re-encoding only the audio is nearly as cheap as a
+    pure remux, so the two streams are decided independently.
+    """
+    plan = plan_for(
+        StreamProbe(
+            has_video=True,
+            video_codec="h264",
+            video_pix_fmt="yuv420p",
+            has_audio=True,
+            audio_codec="ac3",
+            duration=90.0,
+        )
+    )
+    assert plan.copy_video is True
+    assert plan.copy_audio is False
+    assert plan.is_remux is False
+
+
+def test_a_silent_h264_file_is_a_remux(banner):
+    banner(SILENT_BANNER)
+    plan = plan_for(probe_streams(Path("silent.mp4")))
+    assert plan.has_audio is False
+    assert plan.is_remux is True
+
+
+def test_plan_re_encodes_hevc():
+    """Safari plays HEVC and nothing else does, so it is never copied."""
+    plan = plan_for(
+        StreamProbe(
+            has_video=True, video_codec="hevc", video_pix_fmt="yuv420p", has_audio=False
+        )
+    )
+    assert plan.copy_video is False
+
+
+def test_an_unparsed_pixel_format_is_re_encoded():
+    """The conservative direction, and the one that matters.
+
+    A copy we cannot prove is safe risks producing a valid MP4 that still
+    shows a black rectangle. Re-encoding when a copy would have done merely
+    wastes time once, and the result is cached.
+    """
+    plan = plan_for(
+        StreamProbe(has_video=True, video_codec="h264", video_pix_fmt=None)
+    )
+    assert plan.copy_video is False
+
+
+def test_a_failed_probe_re_encodes_everything():
+    plan = plan_for(None)
+    assert plan.copy_video is False
+    assert plan.copy_audio is False
+    assert plan.duration is None
+
+
+# --------------------------------------------------------------------------
+# ffmpeg_args
+# --------------------------------------------------------------------------
+
+
+def _args(**kwargs) -> list[str]:
+    plan = video_transcode.TranscodePlan(**kwargs)
+    return ffmpeg_args(Path("/in/clip.mkv"), Path("/out/clip.tmp"), plan)
+
+
+def test_copy_path_re_encodes_nothing():
+    args = _args(copy_video=True, has_audio=True, copy_audio=True)
+    assert "-c:v" in args and args[args.index("-c:v") + 1] == "copy"
+    assert args[args.index("-c:a") + 1] == "copy"
+    # A stream copy carries the source's own aspect metadata through; applying
+    # a filter to it is not even possible.
+    assert "-vf" not in args
+
+
+def test_encode_path_pins_a_browser_decodable_format():
+    args = _args(copy_video=False, has_audio=True, copy_audio=False)
+    assert args[args.index("-c:v") + 1] == "libx264"
+    assert args[args.index("-pix_fmt") + 1] == "yuv420p"
+    assert args[args.index("-c:a") + 1] == "aac"
+
+
+def test_encode_path_corrects_non_square_pixels():
+    """DVD rips, .vob, .mpg and AVCHD .m2ts are all anamorphic."""
+    args = _args(copy_video=False, has_audio=False, copy_audio=False)
+    assert args[args.index("-vf") + 1] == "scale=iw*sar:ih"
+
+
+def test_a_silent_source_drops_audio_explicitly():
+    args = _args(copy_video=True, has_audio=False, copy_audio=False)
+    assert "-an" in args
+    assert "-c:a" not in args
+
+
+def test_every_plan_maps_one_video_and_an_optional_audio_stream():
+    """A .mkv rip routinely carries five audio tracks and a pile of subtitle
+    streams MP4 cannot hold; mapping explicitly is what keeps the mux from
+    failing on them."""
+    for kwargs in (
+        {"copy_video": True, "has_audio": True, "copy_audio": True},
+        {"copy_video": False, "has_audio": False, "copy_audio": False},
+    ):
+        args = _args(**kwargs)
+        assert args[args.index("0:v:0") - 1] == "-map"
+        assert args[args.index("0:a:0?") - 1] == "-map"
+
+
+def test_every_plan_front_loads_the_index_and_states_the_container():
+    args = _args(copy_video=True, has_audio=True, copy_audio=True)
+    # Without faststart the browser fetches the end of the file before it can
+    # play or seek — an extra round trip on every open.
+    assert args[args.index("-movflags") + 1] == "+faststart"
+    # The output is a mkstemp ".tmp" name no muxer would recognize.
+    assert args[args.index("-f") + 1] == "mp4"
+    assert args[-1] == "/out/clip.tmp"
+    assert "-progress" in args and args[args.index("-progress") + 1] == "pipe:1"
+
+
+# --------------------------------------------------------------------------
+# TranscodeCache
+# --------------------------------------------------------------------------
+
+
+def test_cache_paths_are_album_scoped_and_mp4(tmp_path):
+    a = TranscodeCache("album-one", root=tmp_path)
+    b = TranscodeCache("album-two", root=tmp_path)
+    video = tmp_path / "clip.mkv"
+    video.write_bytes(b"x")
+
+    assert a.path_for(video).suffix == ".mp4"
+    assert a.path_for(video).parent != b.path_for(video).parent
+    assert a.path_for(video).parent.parent == tmp_path
+
+
+def test_editing_the_source_invalidates_its_conversion(tmp_path):
+    """Keying on (path, mtime) is what makes invalidation free."""
+    cache = TranscodeCache("album", root=tmp_path)
+    video = tmp_path / "clip.mkv"
+    video.write_bytes(b"x")
+
+    before = cache.path_for(video)
+    import os
+
+    os.utime(video, (1000, 1000))
+    after = cache.path_for(video)
+    assert before != after
+
+
+def test_get_returns_none_until_something_is_converted(tmp_path):
+    cache = TranscodeCache("album", root=tmp_path)
+    video = tmp_path / "clip.mkv"
+    video.write_bytes(b"x")
+    assert cache.get(video) is None
+
+    target = cache.path_for(video)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(b"converted")
+    assert cache.get(video) == target
+
+
+def test_clear_drops_the_album_directory(tmp_path):
+    cache = TranscodeCache("album", root=tmp_path)
+    cache.directory.mkdir(parents=True)
+    (cache.directory / "a.mp4").write_bytes(b"x")
+
+    cache.clear()
+    assert not cache.directory.exists()
+
+
+def test_an_empty_album_key_is_refused(tmp_path):
+    with pytest.raises(ValueError):
+        TranscodeCache("", root=tmp_path)
+
+
+# --------------------------------------------------------------------------
+# sweep_transcode_cache
+# --------------------------------------------------------------------------
+
+
+def _make_conversion(root: Path, album: str, name: str, size: int, mtime: float) -> Path:
+    import os
+
+    path = root / album / f"{name}.mp4"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(b"\0" * size)
+    os.utime(path, (mtime, mtime))
+    return path
+
+
+def test_sweep_does_nothing_under_budget(tmp_path):
+    _make_conversion(tmp_path, "a", "one", 100, 1000)
+    assert sweep_transcode_cache(budget=1000, root=tmp_path) == 0
+
+
+def test_sweep_evicts_least_recently_used_first(tmp_path):
+    old = _make_conversion(tmp_path, "a", "old", 100, 1000)
+    middle = _make_conversion(tmp_path, "a", "middle", 100, 2000)
+    fresh = _make_conversion(tmp_path, "b", "fresh", 100, 3000)
+
+    removed = sweep_transcode_cache(budget=150, root=tmp_path)
+
+    assert removed == 2
+    assert not old.exists() and not middle.exists()
+    assert fresh.exists()
+
+
+def test_sweep_never_evicts_the_file_just_produced(tmp_path):
+    """On a budget smaller than a single movie the new file is the oldest
+    thing there by mtime only by accident; evicting it would delete the very
+    conversion the caller is about to serve."""
+    keep = _make_conversion(tmp_path, "a", "keep", 500, 1000)
+    other = _make_conversion(tmp_path, "a", "other", 500, 5000)
+
+    sweep_transcode_cache(keep=keep, budget=100, root=tmp_path)
+
+    assert keep.exists()
+    assert not other.exists()
+
+
+def test_sweep_tolerates_a_missing_root(tmp_path):
+    assert sweep_transcode_cache(root=tmp_path / "nope") == 0
+
+
+# --------------------------------------------------------------------------
+# request_transcode — the job registry
+# --------------------------------------------------------------------------
+
+
+def test_request_reports_unavailable_without_ffmpeg(monkeypatch, tmp_path):
+    monkeypatch.setattr(video_transcode, "ffmpeg_exe", lambda: None)
+    status = request_transcode("album", tmp_path / "clip.mkv", root=tmp_path)
+    assert status.state == "unavailable"
+    assert "ffmpeg" in (status.detail or "")
+
+
+def test_request_is_an_instant_hit_when_already_converted(monkeypatch, tmp_path):
+    monkeypatch.setattr(video_transcode, "ffmpeg_exe", lambda: "/bin/true")
+    video = tmp_path / "clip.mkv"
+    video.write_bytes(b"x")
+    cache = TranscodeCache("album", root=tmp_path)
+    target = cache.path_for(video)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(b"converted")
+
+    status = request_transcode("album", video, root=tmp_path)
+    assert status.state == "ready"
+    assert status.progress == 1.0
+
+
+def test_request_fails_cleanly_when_the_source_is_gone(monkeypatch, tmp_path):
+    monkeypatch.setattr(video_transcode, "ffmpeg_exe", lambda: "/bin/true")
+    status = request_transcode("album", tmp_path / "missing.mkv", root=tmp_path)
+    assert status.state == "failed"
+
+
+def _await_conversion(album_key: str, video: Path, root: Path, timeout: float = 180.0):
+    """Poll the way the player does, until the job reaches a terminal state."""
+    deadline = time.monotonic() + timeout
+    while True:
+        status = request_transcode(album_key, video, root=root)
+        if status.state in ("ready", "failed", "unavailable"):
+            return status
+        assert time.monotonic() < deadline, f"conversion never finished: {status}"
+        time.sleep(0.05)
+
+
+@requires_ffmpeg
+def test_an_unplayable_file_becomes_a_playable_one(tmp_path):
+    """End to end: XviD/MP3 in an AVI is what a browser refuses outright."""
+    exe = ffmpeg_exe()
+    source = tmp_path / "old.avi"
+    subprocess.run(
+        [exe, "-y", "-loglevel", "error",
+         "-f", "lavfi", "-i", "testsrc=size=160x120:rate=10:duration=2",
+         "-f", "lavfi", "-i", "sine=frequency=440:duration=2",
+         "-c:v", "mpeg4", "-vtag", "xvid", "-c:a", "libmp3lame", str(source)],
+        check=True,
+    )
+
+    status = _await_conversion("album", source, tmp_path / "cache")
+    assert status.state == "ready", status.detail
+
+    converted = TranscodeCache("album", root=tmp_path / "cache").get(source)
+    assert converted is not None and converted.stat().st_size > 0
+    result = probe_streams(converted)
+    assert result.video_codec == "h264"
+    assert result.video_pix_fmt == "yuv420p"
+    assert result.audio_codec == "aac"
+
+
+@requires_ffmpeg
+def test_a_mismatched_container_is_only_remuxed(tmp_path):
+    """H.264/AAC in a .mkv is packaged wrongly, not encoded wrongly."""
+    exe = ffmpeg_exe()
+    source = tmp_path / "modern.mkv"
+    subprocess.run(
+        [exe, "-y", "-loglevel", "error",
+         "-f", "lavfi", "-i", "testsrc=size=160x120:rate=10:duration=2",
+         "-f", "lavfi", "-i", "sine=frequency=440:duration=2",
+         "-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac", str(source)],
+        check=True,
+    )
+    assert plan_for(probe_streams(source)).is_remux is True
+
+    status = _await_conversion("album", source, tmp_path / "cache")
+    assert status.state == "ready", status.detail
+    assert TranscodeCache("album", root=tmp_path / "cache").get(source) is not None
+
+
+@requires_ffmpeg
+def test_a_file_ffmpeg_cannot_read_fails_rather_than_hanging(tmp_path):
+    source = tmp_path / "notavideo.mkv"
+    source.write_bytes(b"this is not a video" * 100)
+
+    status = _await_conversion("album", source, tmp_path / "cache", timeout=60)
+    assert status.state == "failed"
+    assert status.detail
+
+
+@requires_ffmpeg
+def test_a_remembered_failure_is_not_retried_on_every_poll(tmp_path):
+    """Without this a permanently unconvertible file re-runs ffmpeg several
+    times a second for as long as the player is open."""
+    source = tmp_path / "notavideo.mkv"
+    source.write_bytes(b"nope" * 100)
+    assert _await_conversion("album", source, tmp_path / "cache", timeout=60).state == "failed"
+
+    calls = []
+    original = video_transcode._worker_pool
+
+    def spy():
+        calls.append(1)
+        return original()
+
+    video_transcode._worker_pool = spy
+    try:
+        again = request_transcode("album", source, root=tmp_path / "cache")
+    finally:
+        video_transcode._worker_pool = original
+
+    assert again.state == "failed"
+    assert calls == []
+
+
+# --------------------------------------------------------------------------
+# Routes
+# --------------------------------------------------------------------------
+
+
+def _prepare_until_done(client, url: str, timeout: float = 180.0) -> dict:
+    deadline = time.monotonic() + timeout
+    while True:
+        response = client.post(url)
+        assert response.status_code == 200, response.text
+        body = response.json()
+        if body["state"] in ("ready", "failed", "unavailable"):
+            return body
+        assert time.monotonic() < deadline, f"never finished: {body}"
+        time.sleep(0.05)
+
+
+def test_prepare_video_rejects_a_still_image(client, mixed_album):
+    """The same guard as /videos/: two routes, two allowlists, neither able to
+    serve the other's file types."""
+    response = client.post("/prepare_video/mixed_album/building1.jpeg")
+    assert response.status_code == 403
+
+
+def test_prepare_video_404s_for_a_file_outside_the_album(client, mixed_album):
+    assert client.post("/prepare_video/mixed_album/../../etc/passwd").status_code == 404
+
+
+def test_prepare_video_404s_on_a_nul_byte(client, mixed_album):
+    """Path.resolve() raises ValueError on a NUL, which would otherwise escape
+    as a 500 with a traceback."""
+    assert client.post("/prepare_video/mixed_album/clip%00.mp4").status_code == 404
+
+
+def test_prepare_video_404s_for_a_missing_file(client, mixed_album):
+    assert client.post("/prepare_video/mixed_album/nope.mp4").status_code == 404
+
+
+def test_transcoded_video_404s_before_anything_is_converted(client, mixed_album):
+    response = client.get("/transcoded_video/mixed_album/clip.mp4")
+    assert response.status_code == 404
+
+
+def test_transcoded_video_rejects_a_still_image(client, mixed_album):
+    """Guarded by the album resolution, not by the cache key alone — the cache
+    is addressed by a digest of the source path, so serving straight from it
+    would skip the access check."""
+    assert client.get("/transcoded_video/mixed_album/building1.jpeg").status_code == 403
+
+
+@requires_ffmpeg
+def test_prepare_then_serve_round_trip(client, mixed_album):
+    body = _prepare_until_done(client, "/prepare_video/mixed_album/clip.mp4")
+    assert body["state"] == "ready", body
+    # Only the converted copy is offered: the source bytes are exactly what
+    # the browser could not play.
+    assert body["url"] == "transcoded_video/mixed_album/clip.mp4"
+
+    served = client.get(f"/{body['url']}")
+    assert served.status_code == 200
+    assert served.headers["content-type"] == "video/mp4"
+    # Being able to seek is most of the reason this is a file and not a pipe.
+    assert served.headers.get("accept-ranges") == "bytes"
+    assert len(served.content) > 0
+
+
+@requires_ffmpeg
+def test_deleting_an_album_reclaims_its_conversions(client, tmp_path):
+    """These are whole movies; the size-budget sweeper only runs when
+    something new is converted, so an album deleted and never replaced would
+    otherwise leave them behind indefinitely."""
+    media_dir = tmp_path / "solo"
+    media_dir.mkdir()
+    video = media_dir / "clip.mp4"
+    shutil.copy(media_fixture_path("clip.mp4"), video)
+
+    index_path = media_dir / "photomap_index" / "embeddings.npz"
+    _write_synthetic_index(index_path, [video], [{"photomap_video": dict(VIDEO_INFO)}])
+    album = {
+        "key": "solo_album",
+        "name": "Solo",
+        "image_paths": [media_dir.as_posix()],
+        "index": index_path.as_posix(),
+        "umap_eps": 0.1,
+        "description": "",
+        "encoder_spec": ENCODER_SPEC,
+    }
+    assert client.post("/add_album/", json=album).status_code == 201
+    try:
+        body = _prepare_until_done(client, "/prepare_video/solo_album/clip.mp4")
+        assert body["state"] == "ready", body
+        directory = TranscodeCache("solo_album").directory
+        assert directory.is_dir()
+    finally:
+        client.delete("/delete_album/solo_album")
+        VideoFrameCache("solo_album").clear()
+
+    assert not directory.exists()
diff --git a/tests/frontend/video-badge.test.js b/tests/frontend/video-badge.test.js
index 39e731d8..4949d75e 100644
--- a/tests/frontend/video-badge.test.js
+++ b/tests/frontend/video-badge.test.js
@@ -18,6 +18,8 @@ const VIDEO_DATA = {
   filename: "clip.mp4",
   media_type: "video",
   video_url: "videos/album/clip.mp4",
+  video_transcode_url: "prepare_video/album/clip.mp4",
+  image_url: "video_frame/album/3",
   video_info: { duration: 7.4, fps: 30, playable: true },
 };
 
@@ -216,6 +218,11 @@ describe("badge click", () => {
       url: "videos/album/clip.mp4",
       filename: "clip.mp4",
       playable: true,
+      // The still, so the player can size its frame and keep something on
+      // screen while an unplayable container is converted.
+      poster: "video_frame/album/3",
+      // Where the player asks for a playable copy of an unplayable file.
+      transcodeUrl: "prepare_video/album/clip.mp4",
       globalIndex: 3,
     });
     window.removeEventListener("videoPlayRequested", handler);
diff --git a/tests/frontend/video-player-integration.test.js b/tests/frontend/video-player-integration.test.js
index f538bc84..3c8a01c2 100644
--- a/tests/frontend/video-player-integration.test.js
+++ b/tests/frontend/video-player-integration.test.js
@@ -85,6 +85,12 @@ describe("the modal template and the module agree", () => {
     "videoPlayerFallbackMessage",
     "videoPlayerDownloadLink",
     "videoPlayerCloseBtn",
+    "videoPlayerFrame",
+    "videoPlayerProgress",
+    "videoPlayerProgressMessage",
+    "videoPlayerProgressBar",
+    "videoPlayerProgressFill",
+    "videoPlayerProgressPercent",
   ])("the template provides #%s", (id) => {
     expect(document.getElementById(id)).not.toBeNull();
   });
diff --git a/tests/frontend/video-player.test.js b/tests/frontend/video-player.test.js
index 23e4a2b9..87c3be76 100644
--- a/tests/frontend/video-player.test.js
+++ b/tests/frontend/video-player.test.js
@@ -26,6 +26,41 @@ const { _resetVideoPlayerForTests, closeVideoPlayer, initializeVideoPlayer, isVi
   await import("../../photomap/frontend/static/javascript/video-player.js");
 
 const MP4 = { url: "videos/album/clip.mp4", filename: "clip.mp4", playable: true };
+// A container no browser decodes, with somewhere to send it for conversion.
+const AVI = {
+  url: "videos/album/clip.avi",
+  filename: "clip.avi",
+  playable: false,
+  transcodeUrl: "prepare_video/album/clip.avi",
+};
+// The same file from a server that predates conversion support.
+const AVI_NO_CONVERSION = { url: "videos/album/clip.avi", filename: "clip.avi", playable: false };
+
+/**
+ * Queue up what POST /prepare_video should answer.
+ *
+ * The last entry repeats, so a single argument is a steady state and several
+ * describe a conversion progressing.
+ */
+function mockConversion(...responses) {
+  const queue = [...responses];
+  global.fetch = jest.fn(() => {
+    const body = queue.length > 1 ? queue.shift() : queue[0];
+    return Promise.resolve({ ok: true, json: () => Promise.resolve(body) });
+  });
+}
+
+/** Let the fetch/json microtasks settle. Works under fake timers. */
+async function flush() {
+  for (let i = 0; i < 6; i += 1) {
+    await Promise.resolve();
+  }
+}
+
+const progress = () => document.getElementById("videoPlayerProgress");
+const progressMessage = () => document.getElementById("videoPlayerProgressMessage").textContent;
+const fallbackMessage = () => document.getElementById("videoPlayerFallbackMessage").textContent;
+const downloadLink = () => document.getElementById("videoPlayerDownloadLink");
 
 function modal() {
   return document.getElementById("videoPlayerModal");
@@ -42,19 +77,30 @@ beforeEach(() => {
   mockState.swiper.autoplay.running = false;
 
   document.body.innerHTML = `
-    <div id="videoPlayerModal" class="modal-overlay">
-      <div class="modal-content video-player-content">
-        <button class="modal-close" id="videoPlayerCloseBtn">&times;</button>
-        <div class="video-player-title" id="videoPlayerTitle"></div>
+    <div id="videoPlayerModal" class="modal-overlay video-player-overlay">
+      <button class="video-player-close" id="videoPlayerCloseBtn">&times;</button>
+      <div class="video-player-frame" id="videoPlayerFrame">
         <video id="videoPlayerElement" class="video-player-element" controls tabindex="0"></video>
-        <div class="video-player-fallback" id="videoPlayerFallback" hidden>
+        <div class="video-player-panel video-player-progress" id="videoPlayerProgress" hidden>
+          <p id="videoPlayerProgressMessage"></p>
+          <div class="video-player-bar" id="videoPlayerProgressBar" role="progressbar" aria-valuenow="0">
+            <div class="video-player-bar-fill" id="videoPlayerProgressFill"></div>
+          </div>
+          <p id="videoPlayerProgressPercent"></p>
+        </div>
+        <div class="video-player-panel video-player-fallback" id="videoPlayerFallback" hidden>
           <p id="videoPlayerFallbackMessage"></p>
           <a id="videoPlayerDownloadLink" href="#" download>Download the video</a>
         </div>
       </div>
+      <div class="video-player-title" id="videoPlayerTitle"></div>
     </div>
   `;
 
+  // Nothing in this file wants a real conversion; the tests that care about
+  // one install their own queue with mockConversion().
+  mockConversion({ state: "queued", progress: 0 });
+
   // jsdom implements neither play() nor load() on HTMLMediaElement.
   window.HTMLMediaElement.prototype.play = jest.fn(() => Promise.resolve());
   window.HTMLMediaElement.prototype.pause = jest.fn();
@@ -149,14 +195,27 @@ describe("opening", () => {
     expect(document.activeElement).toBe(video());
   });
 
-  it("focuses the close button when the fallback is showing", () => {
-    // There is no video to drive, and a hidden element cannot take focus —
-    // leaving it on <body>, where Escape still works but Tab starts from the
-    // top of the page.
-    openVideoPlayer({ url: "videos/a/clip.avi", filename: "clip.avi", playable: false });
+  it("focuses the close button when there is nothing to play yet", () => {
+    // The video element is never hidden any more — it holds the poster while
+    // a conversion runs — but with no src there is nothing for Space to
+    // drive, and the native controls are behind a panel. Leaving focus on
+    // <body> would mean Tab starts from the top of the page.
+    openVideoPlayer(AVI);
     expect(document.activeElement).toBe(document.getElementById("videoPlayerCloseBtn"));
   });
 
+  it("shows the poster, so the frame has an aspect ratio before metadata", () => {
+    openVideoPlayer({ ...MP4, poster: "video_frame/album/3" });
+    expect(video().getAttribute("poster")).toBe("video_frame/album/3");
+  });
+
+  it("drops the previous clip's poster when this one has none", () => {
+    openVideoPlayer({ ...MP4, poster: "video_frame/album/3" });
+    closeVideoPlayer();
+    openVideoPlayer(MP4);
+    expect(video().hasAttribute("poster")).toBe(false);
+  });
+
   it("opens from a videoPlayRequested event", () => {
     // The seam between the badge (PR 4) and the player.
     window.dispatchEvent(new CustomEvent("videoPlayRequested", { detail: MP4 }));
@@ -195,10 +254,10 @@ describe("closing", () => {
     expect(isVideoPlayerOpen()).toBe(false);
   });
 
-  it("does not close on a click inside the panel", () => {
+  it("does not close on a click on the frame", () => {
     openVideoPlayer(MP4);
     modal()
-      .querySelector(".modal-content")
+      .querySelector(".video-player-frame")
       .dispatchEvent(new MouseEvent("click", { bubbles: true }));
     expect(isVideoPlayerOpen()).toBe(true);
   });
@@ -258,34 +317,53 @@ describe("navigation closes the player", () => {
 });
 
 describe("formats the browser cannot play", () => {
-  it("explains instead of showing a dead player", () => {
-    openVideoPlayer({ url: "videos/album/clip.avi", filename: "clip.avi", playable: false });
+  it("converts instead of showing a dead player", async () => {
+    // The static hint says no browser decodes this container, so there is
+    // nothing to gain from a black-rectangle-then-error round trip.
+    openVideoPlayer(AVI);
 
-    expect(fallback().hidden).toBe(false);
-    expect(video().hidden).toBe(true);
+    expect(fallback().hidden).toBe(true);
+    expect(progress().hidden).toBe(false);
     expect(video().hasAttribute("src")).toBe(false);
-    expect(document.getElementById("videoPlayerFallbackMessage").textContent).toMatch(/cannot play/i);
+    expect(global.fetch).toHaveBeenCalledWith("prepare_video/album/clip.avi", { method: "POST" });
+    await flush();
   });
 
-  it("offers the file for download", () => {
-    openVideoPlayer({ url: "videos/album/clip.avi", filename: "clip.avi", playable: false });
-    const link = document.getElementById("videoPlayerDownloadLink");
-    expect(link.getAttribute("href")).toBe("videos/album/clip.avi");
-    expect(link.hidden).toBe(false);
+  it("explains and offers the file when the server cannot convert it", () => {
+    // A payload with no conversion route — an older server. This is exactly
+    // what the player did before conversion existed.
+    openVideoPlayer(AVI_NO_CONVERSION);
+
+    expect(fallback().hidden).toBe(false);
+    expect(fallbackMessage()).toMatch(/cannot play/i);
+    expect(downloadLink().getAttribute("href")).toBe("videos/album/clip.avi");
+    expect(downloadLink().hidden).toBe(false);
+    expect(global.fetch).not.toHaveBeenCalled();
   });
 
-  it("falls back when the video element itself errors", () => {
+  it("converts when the video element itself errors", async () => {
     // The load-bearing half: no static extension list predicts this
     // correctly in either direction (an HEVC .mp4 plays in Safari but not
     // Firefox), so the player always tries and reacts to what happened.
-    openVideoPlayer(MP4);
+    openVideoPlayer({ ...MP4, transcodeUrl: "prepare_video/album/clip.mp4" });
     expect(fallback().hidden).toBe(true);
 
     video().dispatchEvent(new Event("error"));
 
+    expect(progress().hidden).toBe(false);
+    // The original is released: it is streaming bytes nothing can decode.
+    expect(video().hasAttribute("src")).toBe(false);
+    expect(global.fetch).toHaveBeenCalledWith("prepare_video/album/clip.mp4", { method: "POST" });
+    await flush();
+  });
+
+  it("falls back when an errored video has nowhere to be converted", () => {
+    openVideoPlayer(MP4);
+    video().dispatchEvent(new Event("error"));
+
     expect(fallback().hidden).toBe(false);
-    expect(document.getElementById("videoPlayerFallbackMessage").textContent).toMatch(/could not be played/i);
-    expect(document.getElementById("videoPlayerDownloadLink").getAttribute("href")).toBe("videos/album/clip.mp4");
+    expect(fallbackMessage()).toMatch(/cannot play/i);
+    expect(downloadLink().getAttribute("href")).toBe("videos/album/clip.mp4");
   });
 
   it("ignores the error fired by teardown clearing the src", () => {
@@ -293,21 +371,182 @@ describe("formats the browser cannot play", () => {
     closeVideoPlayer();
     video().dispatchEvent(new Event("error"));
     expect(fallback().hidden).toBe(true);
+    expect(progress().hidden).toBe(true);
   });
 
   it("recovers the player on the next open", () => {
-    openVideoPlayer({ url: "videos/album/clip.avi", filename: "clip.avi", playable: false });
+    openVideoPlayer(AVI_NO_CONVERSION);
     closeVideoPlayer();
     openVideoPlayer(MP4);
     expect(fallback().hidden).toBe(true);
-    expect(video().hidden).toBe(false);
+    expect(progress().hidden).toBe(true);
     expect(video().getAttribute("src")).toBe("videos/album/clip.mp4");
   });
 
   it("explains when there is no URL at all", () => {
     openVideoPlayer({ url: "", filename: "clip.mp4", playable: true });
     expect(fallback().hidden).toBe(false);
-    expect(document.getElementById("videoPlayerDownloadLink").hidden).toBe(true);
+    expect(downloadLink().hidden).toBe(true);
+  });
+});
+
+describe("conversion", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it("plays the converted copy once it is ready", async () => {
+    mockConversion({ state: "ready", progress: 1, url: "transcoded_video/album/clip.avi" });
+    openVideoPlayer(AVI);
+    await flush();
+
+    expect(video().getAttribute("src")).toBe("transcoded_video/album/clip.avi");
+    expect(progress().hidden).toBe(true);
+    expect(video().play).toHaveBeenCalled();
+    expect(document.activeElement).toBe(video());
+  });
+
+  it("reports progress while the conversion runs", async () => {
+    mockConversion({ state: "running", progress: 0.42 });
+    openVideoPlayer(AVI);
+    await flush();
+
+    expect(progress().hidden).toBe(false);
+    expect(progressMessage()).toMatch(/converting/i);
+    expect(document.getElementById("videoPlayerProgressPercent").textContent).toBe("42%");
+    expect(document.getElementById("videoPlayerProgressFill").style.width).toBe("42%");
+    expect(document.getElementById("videoPlayerProgressBar").getAttribute("aria-valuenow")).toBe("42");
+  });
+
+  it("says it is waiting while the job sits in the queue", async () => {
+    mockConversion({ state: "queued", progress: 0 });
+    openVideoPlayer(AVI);
+    await flush();
+
+    expect(progressMessage()).toMatch(/waiting/i);
+  });
+
+  it("sweeps rather than sitting at 0% when the duration is unknown", async () => {
+    // ffmpeg could not determine the duration, so there is no percentage to
+    // report. A bar parked at 0% reads as stuck.
+    mockConversion({ state: "running", progress: 0 });
+    openVideoPlayer(AVI);
+    await flush();
+
+    const bar = document.getElementById("videoPlayerProgressBar");
+    expect(bar.classList.contains("video-player-bar--indeterminate")).toBe(true);
+    expect(document.getElementById("videoPlayerProgressFill").style.width).toBe("");
+  });
+
+  it("keeps polling until the conversion finishes", async () => {
+    mockConversion(
+      { state: "queued", progress: 0 },
+      { state: "running", progress: 0.5 },
+      { state: "ready", progress: 1, url: "transcoded_video/album/clip.avi" }
+    );
+    openVideoPlayer(AVI);
+    await flush();
+    expect(progressMessage()).toMatch(/waiting/i);
+
+    jest.advanceTimersByTime(1000);
+    await flush();
+    expect(progressMessage()).toMatch(/converting/i);
+
+    jest.advanceTimersByTime(1000);
+    await flush();
+    expect(video().getAttribute("src")).toBe("transcoded_video/album/clip.avi");
+    expect(global.fetch).toHaveBeenCalledTimes(3);
+  });
+
+  it("stops polling when the player closes", async () => {
+    // The backend drops a job nobody is asking about, so this is not merely
+    // tidy: it is how closing the player cancels the ffmpeg run.
+    mockConversion({ state: "running", progress: 0.1 });
+    openVideoPlayer(AVI);
+    await flush();
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+
+    closeVideoPlayer();
+    jest.advanceTimersByTime(10000);
+    await flush();
+
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not let a late response play into a dismissed player", async () => {
+    mockConversion({ state: "ready", progress: 1, url: "transcoded_video/album/clip.avi" });
+    openVideoPlayer(AVI);
+    closeVideoPlayer();
+    await flush();
+
+    expect(isVideoPlayerOpen()).toBe(false);
+    expect(video().hasAttribute("src")).toBe(false);
+  });
+
+  it("does not let a late response play over a different clip", async () => {
+    mockConversion({ state: "ready", progress: 1, url: "transcoded_video/album/clip.avi" });
+    openVideoPlayer(AVI);
+    openVideoPlayer(MP4);
+    await flush();
+
+    expect(video().getAttribute("src")).toBe("videos/album/clip.mp4");
+  });
+
+  it("shows the backend's reason when the conversion fails", async () => {
+    mockConversion({ state: "failed", progress: 0, detail: "This video could not be converted." });
+    openVideoPlayer(AVI);
+    await flush();
+
+    expect(fallback().hidden).toBe(false);
+    expect(fallbackMessage()).toBe("This video could not be converted.");
+    expect(downloadLink().getAttribute("href")).toBe("videos/album/clip.avi");
+  });
+
+  it("explains when the server has no ffmpeg", async () => {
+    mockConversion({ state: "unavailable", progress: 0, detail: "ffmpeg is not available." });
+    openVideoPlayer(AVI);
+    await flush();
+
+    expect(fallback().hidden).toBe(false);
+    expect(fallbackMessage()).toBe("ffmpeg is not available.");
+  });
+
+  it("survives the request itself failing", async () => {
+    global.fetch = jest.fn(() => Promise.reject(new Error("offline")));
+    openVideoPlayer(AVI);
+    await flush();
+
+    expect(fallback().hidden).toBe(false);
+    expect(fallbackMessage()).toMatch(/could not be prepared/i);
+  });
+
+  it("treats a non-OK response as a failure rather than parsing it", async () => {
+    global.fetch = jest.fn(() => Promise.resolve({ ok: false, status: 500, json: () => Promise.resolve({}) }));
+    openVideoPlayer(AVI);
+    await flush();
+
+    expect(fallback().hidden).toBe(false);
+    expect(fallbackMessage()).toMatch(/could not be prepared/i);
+  });
+
+  it("does not convert a second time when the converted copy also errors", async () => {
+    // The conversion is H.264/AAC in an MP4. If that will not play, nothing
+    // the backend can produce will, and re-converting would loop forever.
+    mockConversion({ state: "ready", progress: 1, url: "transcoded_video/album/clip.avi" });
+    openVideoPlayer(AVI);
+    await flush();
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+
+    video().dispatchEvent(new Event("error"));
+    await flush();
+
+    expect(fallback().hidden).toBe(false);
+    expect(fallbackMessage()).toMatch(/even after conversion/i);
+    expect(global.fetch).toHaveBeenCalledTimes(1);
   });
 });
 

From 836bdc17da68a4fe16763dc8958c6111233cb9f4 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Thu, 3 Sep 2026 15:18:15 -0400
Subject: [PATCH 2/4] fix: adversarial-review findings in video conversion and
 the player
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three fresh-context reviewers attacked the previous commit. Confirmed
findings, fixed here; each has a regression test.

**Copy safety could be defeated by the file itself.** The rule is that an
unknown stream re-encodes, never copies — but two pieces of file-controlled
text are printed on ffmpeg's *own* report lines, outside the `Metadata:`
blocks that were being stripped. A stream's language tag is printed inline
before the `: Video:`/`: Audio:` delimiter, so a tag of `x): Video: h264
(High), yuv420p` makes an audio line match the video pattern; and the input
path is echoed in the `Input #0 … from '…':` header, so a filename
containing a newline forges whole report lines. Both degraded *toward*
copy, which is the dangerous direction: a copied HEVC 10-bit stream is
exactly the black rectangle this feature removes, cached and reported
ready. `StreamProbe` now carries `trusted`, cleared when a stream line
holds more than one kind delimiter or when the path contains a newline, and
`plan_for` re-encodes everything from an untrusted probe.

**Every 16:9 NTSC DVD rip failed.** `scale=iw*sar:ih` truncates, and
720*32/27 is 853.33 — libx264 refuses an odd width in yuv420p outright, so
the single most common shape the filter exists for died with "width not
divisible by 2" on every retry. Now rounds both axes to even and sets
`setsar=1`.

**Wrong-movie collision.** The transcode cache no longer reuses
`VideoFrameCache.key_for`, which casefolds the path: on a case-sensitive
filesystem `clip.mp4` and `Clip.mp4` with matching mtimes (routine for
anything unpacked from one archive) collided. For a still that is the wrong
thumbnail; here it played the wrong film and reported it ready without
converting it.

**Conversions outlived what they belonged to.** Deleting an album while one
was in flight let it finish and `mkdir` the just-removed directory back,
orphaning a whole movie under a key nothing would ever clear again;
deleting a *video* left a full decodable copy of it in `~/.cache`, which is
the retention the still-cache was written to avoid. Added `forget_album`
(cancel, then clear), `TranscodeCache.discard`/`prune` wired into the
per-image delete and the index-save sweep, and a pre-publish cancellation
check so a conversion that succeeds after cancellation is still discarded.

**Lifecycle and accounting:**

* Everything between `Popen` and the read loop's `try/finally` was
  unprotected — thread exhaustion at `watcher.start()` left ffmpeg running
  unwatched and unreaped with a multi-gigabyte `.tmp` the sweeper could not
  even see (it counts `.mp4`). Now unwound, and the sweeper reclaims aged
  temps.
* The pool's threads are non-daemon and `concurrent.futures` joins them at
  exit, so stopping the server hung for up to ~47s. An `atexit` hook now
  cancels and kills first.
* `_forget_stale_jobs` could not reach queued or running entries and was
  skipped entirely on a cache hit, so a source whose mtime kept moving (a
  file still being copied in) queued a job per second forever.
* Unknown duration took the *tightest* deadline, killing every `.m2v`
  longer than ten minutes of encoding; it now takes the loosest, with the
  stall detector still covering wedged jobs.
* An audio-only `.mkv`/`.mov`/`.ogg` failed with ffmpeg's "Error opening
  output files: Invalid argument"; it now says it has no video track.
* `_stderr_tail` reported ffmpeg's last line, which is always the generic
  muxer post-mortem, hiding the actual cause on the line above.
* `TranscodeCache.get` stamps the entry, and the sweeper spares anything
  touched recently — the film being watched was otherwise the *first*
  thing evicted, 404ing its own next Range request.

**Player:** the video's `94vw` cap exceeded the frame's own max-width below
800px of viewport, so `overflow: hidden` sliced ~24px off the right of every
video on a phone; and the frame's unconditional `min-width` put up to 160px
of black on one side of a portrait clip on a landscape screen. Caps now
agree, the mins are gone (a `<video>` brings its own 300x150 floor) and the
frame centres. Also: a transient network error no longer tears the clip down
and starts a pointless re-encode (the `MediaError` code is consulted); one
dropped poll no longer abandons a conversion, since the poll is also the
liveness signal; focus no longer lands on `<body>` when no conversion is
available; reopening with no URL releases the previous clip instead of
leaving it playing unstoppably behind the panel; and an indeterminate
progress bar no longer publishes `aria-valuenow="0"`.

Dismissed after checking in a real browser: a report that a stale `error`
from a dismissed clip could destroy the next one. The HTML media element
load algorithm removes pending media element tasks, so replacing `src`
discards the queued event — verified in Chromium (no event fired, while the
control case fired code 4). The proof had manually dispatched the event in
jsdom, which bypasses that.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GwzC2csXxZkd9HsD8A2t7h
---
 photomap/backend/embeddings.py                |  22 ++
 photomap/backend/routers/album.py             |  16 +-
 photomap/backend/routers/index.py             |  26 +-
 photomap/backend/video.py                     |  42 ++
 photomap/backend/video_transcode.py           | 374 ++++++++++++++++--
 photomap/frontend/static/css/video-player.css |  26 +-
 .../static/javascript/video-player.js         |  52 ++-
 tests/backend/test_video_transcode.py         | 317 ++++++++++++++-
 tests/frontend/video-player.test.js           |  96 +++++
 9 files changed, 931 insertions(+), 40 deletions(-)

diff --git a/photomap/backend/embeddings.py b/photomap/backend/embeddings.py
index a6d8b49a..34a61ad6 100644
--- a/photomap/backend/embeddings.py
+++ b/photomap/backend/embeddings.py
@@ -50,6 +50,7 @@
 from .util import atomic_savez
 from .video import VIDEO_METADATA_KEY, extract_video_frame
 from .video_cache import VideoFrameCache
+from .video_transcode import TranscodeCache
 
 logger = logging.getLogger(__name__)
 
@@ -1337,6 +1338,27 @@ def _prune_video_frame_cache(self, filenames, modification_times) -> None:
         except Exception as e:
             logger.warning(f"Could not prune the video frame cache: {e}")
 
+        # The converted copies need the same sweep, and for a stronger reason:
+        # each one is a whole movie rather than a single JPEG, and the only
+        # other thing that reclaims them is a global byte budget that is not
+        # checked until some unrelated conversion finishes. Keyed differently
+        # from the frame cache (exact case), so the keep set is rebuilt rather
+        # than shared.
+        try:
+            transcodes = TranscodeCache(self.album_key)
+            if not transcodes.directory.is_dir():
+                return
+            keep_converted = {
+                transcodes.key_for(Path(str(name)), float(mtime))
+                for name, mtime in zip(filenames, modification_times, strict=False)
+                if is_video(Path(str(name)))
+            }
+            removed = transcodes.prune(keep_converted)
+            if removed:
+                logger.info(f"Removed {removed} stale converted video(s) from the cache")
+        except Exception as e:
+            logger.warning(f"Could not prune the video conversion cache: {e}")
+
     @staticmethod
     def _path_compare_key(p: Path) -> str:
         """Canonical key for the new-vs-missing diff in
diff --git a/photomap/backend/routers/album.py b/photomap/backend/routers/album.py
index 46a3ae83..24408d8a 100644
--- a/photomap/backend/routers/album.py
+++ b/photomap/backend/routers/album.py
@@ -22,7 +22,7 @@
 from ..encoders import default_encoder_spec, default_min_search_score
 from ..util import json_safe
 from ..video_cache import VideoFrameCache
-from ..video_transcode import TranscodeCache
+from ..video_transcode import TranscodeCache, forget_album
 
 
 class UmapEpsSetRequest(BaseModel):
@@ -260,6 +260,20 @@ def _cleanup_video_frames(album_key: str) -> None:
     Each cache is cleared independently so a failure on one still reclaims the
     other. Never raises: a failure here costs disk space, not correctness.
     """
+    # Cancel first, then clear. A conversion already in flight would otherwise
+    # finish afterwards and recreate the directory removed below — publishing a
+    # whole movie into a cache keyed by an album that no longer exists, which
+    # nothing will ever clear again. Cancelling makes the worker discard its
+    # output instead, even if ffmpeg has already succeeded by then.
+    try:
+        cancelled = forget_album(album_key)
+        if cancelled:
+            logger.info(
+                f"Cancelled {cancelled} in-flight conversion(s) for '{album_key}'"
+            )
+    except Exception as e:
+        logger.warning(f"Could not cancel conversions for '{album_key}': {e}")
+
     for cache_name, factory in (
         ("frame", VideoFrameCache),
         ("conversion", TranscodeCache),
diff --git a/photomap/backend/routers/index.py b/photomap/backend/routers/index.py
index 937685d1..1f88c78f 100644
--- a/photomap/backend/routers/index.py
+++ b/photomap/backend/routers/index.py
@@ -24,6 +24,7 @@
 from ..media_types import is_video
 from ..progress import IndexingCancelled, progress_tracker
 from ..video_cache import VideoFrameCache
+from ..video_transcode import TranscodeCache
 from .album import (
     AlbumDep,
     EmbeddingsDep,
@@ -376,13 +377,28 @@ def _remove_image_file(image_path: Path, move_to_trash: bool) -> None:
 
 
 def _discard_cached_frame(album_key: str, path: Path) -> None:
-    """Remove a deleted video's cached still. Never raises."""
+    """Remove a deleted video's derived files. Never raises.
+
+    Both the still and the converted copy, and the conversion is the one that
+    matters: it is a full, decodable copy of the video, so leaving it behind
+    means a user who deletes a private clip still has it sitting in
+    ``~/.cache``. (It is not reachable over HTTP once the source is gone —
+    every video route requires the source to exist — but "not served" is not
+    "not on disk".)
+
+    Each cache is discarded independently so a failure on one still reclaims
+    the other.
+    """
     if not is_video(path):
         return
-    try:
-        VideoFrameCache(album_key).discard(path)
-    except Exception as e:
-        logger.debug(f"Could not discard cached frame for {path}: {e}")
+    for name, cache in (
+        ("frame", VideoFrameCache(album_key)),
+        ("conversion", TranscodeCache(album_key)),
+    ):
+        try:
+            cache.discard(path)
+        except Exception as e:
+            logger.debug(f"Could not discard cached {name} for {path}: {e}")
 
 
 @index_router.delete(
diff --git a/photomap/backend/video.py b/photomap/backend/video.py
index 36b52bfc..ea21e479 100644
--- a/photomap/backend/video.py
+++ b/photomap/backend/video.py
@@ -476,6 +476,12 @@ class StreamProbe(BaseModel):
     video_pix_fmt: str | None = None
     has_audio: bool = False
     audio_codec: str | None = None
+    #: False when something in the banner could not be attributed to ffmpeg
+    #: itself, so no field here may be used to justify a stream copy.  See
+    #: :func:`probe_streams` for the two ways that happens.  Callers that only
+    #: want a rough description (duration for a caption, say) may ignore it;
+    #: anything deciding whether a stream is safe to copy may not.
+    trusted: bool = True
 
 
 def probe_streams(path: Path) -> StreamProbe | None:
@@ -491,6 +497,30 @@ def probe_streams(path: Path) -> StreamProbe | None:
     reason documented there: stream and duration lines are ffmpeg's own
     report, while the ``Metadata:`` blocks above them are attacker-controlled
     file tags that would otherwise be able to spoof a codec.
+
+    Stripping those blocks is necessary but **not sufficient**, because two
+    pieces of file-controlled text are printed outside them, on ffmpeg's own
+    report lines:
+
+    * A stream's *language tag* is printed inline as ``(%s)`` in its own
+      ``Stream #`` line, before the ``: Video:``/``: Audio:`` delimiter. A tag
+      of ``x): Video: h264 (High), yuv420p`` makes an **audio** stream's line
+      match the video pattern — and it degrades toward *copy*, which is the
+      dangerous direction: a copied HEVC stream is exactly the black rectangle
+      the converter exists to remove. Detected structurally: ffmpeg prints one
+      kind delimiter per stream line, so a line carrying more than one is not
+      a line ffmpeg composed alone.
+    * The input **path** is echoed in the ``Input #0, ..., from '...':``
+      header, and a filename may contain a newline on Linux and macOS — which
+      splits it into further lines that look exactly like report lines. There
+      is no way to tell those apart after the fact, so a path containing one
+      poisons the whole banner.
+
+    Neither is recoverable by parsing harder, so both set ``trusted=False``
+    rather than trying to pick the real line out. The fields are still
+    populated on a best-effort basis for descriptive use; what changes is that
+    :func:`~photomap.backend.video_transcode.plan_for` will not copy a stream
+    on their say-so.
     """
     result = _run_ffmpeg(
         ["-nostdin", "-hide_banner", "-i", str(path)], PROBE_TIMEOUT_SECONDS
@@ -501,6 +531,12 @@ def probe_streams(path: Path) -> StreamProbe | None:
     report = _strip_metadata_blocks(result.stderr.decode("utf-8", errors="replace"))
     probe = StreamProbe()
 
+    # The banner echoes the input path, so a newline in the filename can forge
+    # whole report lines. Checked on the path rather than on the banner: by the
+    # time it is text there is nothing left to distinguish the forgery.
+    if "\n" in str(path) or "\r" in str(path):
+        probe.trusted = False
+
     if m := _DURATION_RE.search(report):
         try:
             probe.duration = (
@@ -510,6 +546,12 @@ def probe_streams(path: Path) -> StreamProbe | None:
             pass
 
     for line in report.splitlines():
+        if not line.lstrip().startswith("Stream #"):
+            continue
+        # ffmpeg emits exactly one kind delimiter per stream line. More than
+        # one means part of the line came from the file, not from ffmpeg.
+        if line.count(": Video:") + line.count(": Audio:") > 1:
+            probe.trusted = False
         if not probe.has_video:
             m = _STREAM_VIDEO_RE.match(line)
             # Cover art embedded in an audio file presents as a video stream;
diff --git a/photomap/backend/video_transcode.py b/photomap/backend/video_transcode.py
index 336e0ca2..620e4f12 100644
--- a/photomap/backend/video_transcode.py
+++ b/photomap/backend/video_transcode.py
@@ -32,6 +32,8 @@
 
 from __future__ import annotations
 
+import atexit
+import hashlib
 import logging
 import os
 import shutil
@@ -48,7 +50,7 @@
 from pydantic import BaseModel
 
 from .video import StreamProbe, ffmpeg_exe, probe_streams
-from .video_cache import VideoFrameCache, album_dirname
+from .video_cache import album_dirname
 
 logger = logging.getLogger(__name__)
 
@@ -108,6 +110,13 @@
 # by a client that has genuinely gone away.
 ABANDON_AFTER_SECONDS = 45.0
 
+# A conversion whose mtime was refreshed this recently is never evicted.
+# ``TranscodeCache.get`` stamps an entry every time it is served, so this is
+# what stops the sweeper deleting the film somebody is in the middle of
+# watching — which, since the browser fetches it with Range requests over the
+# whole viewing session, would otherwise 404 mid-playback.
+EVICTION_GRACE_SECONDS = 900.0
+
 # How long a failure is remembered.  Without this a permanently unconvertible
 # file re-runs ffmpeg on every poll — several times a second.  It expires
 # because failure is also transient (a full disk, a mount that came back), and
@@ -154,13 +163,18 @@ def plan_for(probe: StreamProbe | None) -> TranscodePlan:
     """Decide what has to be re-encoded, from what the probe could determine.
 
     Every unknown resolves to "re-encode".  A probe that returned ``None``, a
+    probe whose banner could not be fully attributed to ffmpeg
+    (``trusted=False`` — see :func:`~photomap.backend.video.probe_streams`), a
     codec line the banner parser did not match, an unrecognized pixel format —
     all of them mean *we cannot prove a copy would play*, and the cost of
     guessing wrong is the exact black rectangle this module exists to remove.
     Re-encoding when a copy would have done merely wastes time once, and the
     result is cached.
     """
-    if probe is None:
+    if probe is None or not probe.trusted:
+        # Duration is dropped along with the rest: on the untrusted path it is
+        # the same forged text, and a bogus duration drives both the progress
+        # readout and the job deadline.
         return TranscodePlan(copy_video=False, has_audio=True, copy_audio=False)
 
     copy_video = (
@@ -220,8 +234,21 @@ def ffmpeg_args(source: Path, target: Path, plan: TranscodePlan) -> list[str]:
             # to 1.50 instead of 1.778 if the sample aspect is dropped.  Only
             # on the re-encode path — a stream copy carries the source's own
             # aspect metadata through untouched.
+            #
+            # Both axes are rounded to even numbers, which is not decoration:
+            # ``scale`` truncates to int, and libx264 refuses a yuv420p frame
+            # with an odd dimension outright ("width not divisible by 2").
+            # 720*32/27 is 853.33 -> 853, so the single most common shape this
+            # filter exists for — 16:9 NTSC DVD — failed every time without
+            # the rounding.  ``setsar=1`` then states that the output pixels
+            # really are square, so nothing downstream re-applies the source's
+            # aspect a second time.
+            #
+            # The comma here separates two filters, which is what a filtergraph
+            # wants; note that a comma *inside* one of these expressions would
+            # have to be escaped, which is why none of them contains one.
             "-vf",
-            "scale=iw*sar:ih",
+            "scale=trunc(iw*sar/2)*2:trunc(ih/2)*2,setsar=1",
         ]
 
     if not plan.has_audio:
@@ -282,15 +309,113 @@ def directory(self) -> Path:
 
     @staticmethod
     def key_for(video_path: Path, mtime: float | None = None) -> str:
-        return VideoFrameCache.key_for(video_path, mtime)
+        """``<exact-case path digest>-<mtime digest>``.
+
+        Shaped like :meth:`VideoFrameCache.key_for` but deliberately **not**
+        delegating to it: that one casefolds the path, so on a case-sensitive
+        filesystem two genuinely different files whose names differ only in
+        case (``clip.mp4`` and ``Clip.mp4``) collide whenever their mtimes also
+        match — which is routine for anything unpacked from one archive. For a
+        still that means the wrong thumbnail; here it would mean **playing the
+        wrong movie**, and reporting it ``ready`` without converting it.
+
+        The casefold exists there to stop a case-insensitive filesystem
+        presenting one file under two spellings and thrashing the extract/prune
+        loop. This cache has no such loop — it is swept by byte budget, not
+        against the index — so the worst an exact-case key costs it is
+        converting one file twice on macOS or Windows. That is the right way
+        round: duplicated work over wrong content.
+        """
+        if mtime is None:
+            try:
+                mtime = video_path.stat().st_mtime
+            except OSError:
+                mtime = 0.0
+        try:
+            resolved = Path(video_path).resolve().as_posix()
+        except (OSError, RuntimeError, ValueError):
+            resolved = Path(video_path).as_posix()
+        digest = hashlib.blake2b(
+            resolved.encode("utf-8", errors="surrogatepass"), digest_size=16
+        ).hexdigest()
+        stamp = hashlib.blake2b(f"{mtime:.6f}".encode(), digest_size=8).hexdigest()
+        return f"{digest}-{stamp}"
 
     def path_for(self, video_path: Path, mtime: float | None = None) -> Path:
         return self.directory / f"{self.key_for(video_path, mtime)}.mp4"
 
     def get(self, video_path: Path, mtime: float | None = None) -> Path | None:
-        """The converted file, if one has already been produced."""
+        """The converted file, if one has already been produced.
+
+        Stamps the entry as used. That is what keeps it out of the sweeper's
+        reach while it is being watched: the browser fetches a film with Range
+        requests spread over the whole viewing session, and without a stamp
+        here its mtime would be frozen at the moment the progress panel last
+        polled — making the film currently on screen the *first* thing evicted
+        when some other conversion finishes.
+        """
         path = self.path_for(video_path, mtime)
-        return path if path.is_file() else None
+        if not path.is_file():
+            return None
+        try:
+            os.utime(path, None)
+        except OSError:
+            pass
+        return path
+
+    def prune(self, keep_keys: set[str]) -> int:
+        """Delete every conversion whose key is not in ``keep_keys``.
+
+        The index-save sweep, mirroring :meth:`VideoFrameCache.prune`: one
+        pass covers mtime changes, moves, copies, deletes and files removed
+        outside the app, none of which have a hook of their own.
+
+        Unlike the frame cache's version this deliberately leaves ``.tmp``
+        files alone. There, a stray temp is a dead extraction worth seconds;
+        here it is very likely the conversion running *right now*, which may
+        have hours invested in it. Abandoned temps are reclaimed by
+        :func:`sweep_transcode_cache`, which can tell the difference by age.
+        """
+        directory = self.directory
+        if not directory.is_dir():
+            return 0
+        try:
+            entries = list(directory.iterdir())
+        except OSError as e:
+            logger.warning(f"Could not sweep the conversion cache {directory}: {e}")
+            return 0
+        removed = 0
+        for entry in entries:
+            if entry.suffix != ".mp4" or entry.stem in keep_keys:
+                continue
+            try:
+                entry.unlink()
+                removed += 1
+            except OSError as e:
+                logger.debug(f"Could not remove stale conversion {entry}: {e}")
+        return removed
+
+    def discard(self, video_path: Path, mtime: float | None = None) -> None:
+        """Drop every converted generation of ``video_path``.
+
+        Globs the path digest rather than computing one key, for the same
+        reason :meth:`VideoFrameCache.discard` does: the usual reason to
+        discard is that the source has just been deleted, so its mtime can no
+        longer be read and the exact key is unrecoverable.
+        """
+        prefix = self.key_for(video_path, mtime).split("-")[0]
+        directory = self.directory
+        if not directory.is_dir():
+            return
+        try:
+            stale = list(directory.glob(f"{prefix}-*.mp4"))
+        except OSError:
+            return
+        for entry in stale:
+            try:
+                entry.unlink()
+            except OSError as e:
+                logger.debug(f"Could not discard conversion {entry}: {e}")
 
     def clear(self) -> None:
         """Drop this album's conversions entirely (album deletion)."""
@@ -304,18 +429,41 @@ def sweep_transcode_cache(
 ) -> int:
     """Evict least-recently-used conversions until the cache fits ``budget``.
 
-    Recency is the file's mtime, which :func:`request_transcode` refreshes on
-    every cache hit — so a clip watched repeatedly outlives one converted
-    once and forgotten, regardless of when either was produced.
-
-    ``keep`` is never evicted: it is the file the caller has just produced and
-    is about to serve, and on a cache whose budget is smaller than a single
-    movie it would otherwise be deleted before it could be played.
+    Recency is the file's mtime, which :meth:`TranscodeCache.get` and
+    :func:`request_transcode` both refresh on every hit — so a clip watched
+    repeatedly outlives one converted once and forgotten, regardless of when
+    either was produced.
+
+    Two things are never evicted:
+
+    * ``keep`` — the file the caller has just produced and is about to serve.
+      On a cache whose budget is smaller than a single movie it would
+      otherwise be deleted before it could be played.
+    * anything stamped within :data:`EVICTION_GRACE_SECONDS`, which is what a
+      film being watched right now looks like. Honouring the budget is worth
+      less than not yanking a file out from under an open player, so the cache
+      is allowed to sit over budget until the viewing finishes.
+
+    Abandoned ``.tmp`` files are collected too, and *before* the budget test:
+    a conversion killed by a crash or a hard server stop leaves one behind,
+    and because they are not ``.mp4`` they would otherwise be invisible to the
+    accounting forever — the one class of garbage nothing else reclaims.
     """
     base = root if root is not None else transcode_cache_root()
     if not base.is_dir():
         return 0
 
+    now = time.time()
+    removed = 0
+    for stale in base.rglob("*.tmp"):
+        try:
+            if now - stale.stat().st_mtime <= EVICTION_GRACE_SECONDS:
+                continue  # very likely the conversion running right now
+            stale.unlink()
+            removed += 1
+        except OSError as e:
+            logger.debug(f"Could not remove abandoned conversion temp {stale}: {e}")
+
     entries: list[tuple[float, int, Path]] = []
     total = 0
     keep_resolved = keep.resolve() if keep else None
@@ -327,12 +475,13 @@ def sweep_transcode_cache(
         total += stat.st_size
         if keep_resolved is not None and path.resolve() == keep_resolved:
             continue
+        if now - stat.st_mtime <= EVICTION_GRACE_SECONDS:
+            continue
         entries.append((stat.st_mtime, stat.st_size, path))
 
     if total <= budget:
-        return 0
+        return removed
 
-    removed = 0
     entries.sort(key=lambda item: item[0])
     for _mtime, size, path in entries:
         if total <= budget:
@@ -356,6 +505,11 @@ class _Job:
     detail: str | None = None
     last_polled: float = field(default_factory=time.monotonic)
     finished_at: float | None = None
+    #: Set when the reason to stop is *known*, not merely inferred from
+    #: silence: the album was deleted, or the process is shutting down. Kept
+    #: apart from the polling clock because the two want opposite treatment of
+    #: a conversion that finishes anyway — see :func:`_drive_ffmpeg`.
+    cancelled: bool = False
 
 
 _jobs: dict[str, _Job] = {}
@@ -363,6 +517,40 @@ class _Job:
 _executor: ThreadPoolExecutor | None = None
 _executor_lock = threading.Lock()
 
+# Every ffmpeg this module currently has running, so shutdown can kill them.
+_live_processes: set[subprocess.Popen] = set()
+_live_lock = threading.Lock()
+_shutting_down = threading.Event()
+
+
+def _shutdown_conversions() -> None:
+    """Stop every conversion so the interpreter can actually exit.
+
+    ``ThreadPoolExecutor``'s worker threads are non-daemon and
+    ``concurrent.futures`` registers an ``atexit`` hook that *joins* them, so
+    without this a re-encode holds the whole process open at shutdown — the
+    watchdog would not notice for ``ABANDON_AFTER_SECONDS``, so stopping the
+    server took the better part of a minute, every time.
+
+    Registered after ``concurrent.futures``'s own hook (this module imports it
+    first) and ``atexit`` runs last-registered-first, so this gets to kill the
+    children before anything waits on the thread running them.
+    """
+    _shutting_down.set()
+    with _jobs_lock:
+        for job in _jobs.values():
+            job.cancelled = True
+    with _live_lock:
+        doomed = list(_live_processes)
+    for proc in doomed:
+        try:
+            proc.kill()
+        except OSError:
+            pass
+
+
+atexit.register(_shutdown_conversions)
+
 
 def _worker_pool() -> ThreadPoolExecutor:
     """The single worker every conversion runs on.
@@ -387,12 +575,46 @@ def _scoped_key(album_key: str, key: str) -> str:
 
 
 def _forget_stale_jobs(now: float) -> None:
-    """Drop finished entries nobody can still be waiting on. Caller holds the lock."""
+    """Drop entries nobody can still be waiting on. Caller holds the lock.
+
+    Two kinds, and the second is what bounds the registry:
+
+    * finished entries older than :data:`FAILURE_MEMORY_SECONDS`;
+    * **queued or running** entries whose client stopped polling. Reaping
+      these is not merely tidiness — a source whose mtime keeps moving (a
+      file still being copied in, a growing recording) produces a *new* cache
+      key on every poll, so every poll creates a job and queues a worker task,
+      once a second, none of which can ever be reclaimed by the first rule
+      because none of them ever finishes. Dropping the entry is also what
+      makes the watchdog treat the job as abandoned and kill its ffmpeg.
+    """
     for scoped, job in list(_jobs.items()):
-        if job.finished_at is not None and now - job.finished_at > FAILURE_MEMORY_SECONDS:
+        if job.finished_at is not None:
+            if now - job.finished_at > FAILURE_MEMORY_SECONDS:
+                del _jobs[scoped]
+        elif now - job.last_polled > ABANDON_AFTER_SECONDS:
             del _jobs[scoped]
 
 
+def forget_album(album_key: str) -> int:
+    """Cancel every conversion belonging to ``album_key``. Returns how many.
+
+    Called when the album is deleted. Without it, a conversion already in
+    flight finishes afterwards and ``mkdir(parents=True)`` **recreates the
+    directory that was just removed**, publishing a whole movie into a cache
+    nothing will ever clear again — the album key it is filed under no longer
+    exists, so the only remaining reclamation is the global byte budget.
+    """
+    prefix = f"{album_key}\x00"
+    cancelled = 0
+    with _jobs_lock:
+        for scoped, job in _jobs.items():
+            if scoped.startswith(prefix):
+                job.cancelled = True
+                cancelled += 1
+    return cancelled
+
+
 def request_transcode(
     album_key: str, video_path: Path, root: Path | None = None
 ) -> TranscodeStatus:
@@ -420,6 +642,14 @@ def request_transcode(
 
     key = cache.key_for(video_path, mtime)
     target = cache.path_for(video_path, mtime)
+    now = time.monotonic()
+
+    # Before the cache-hit shortcut, not after it: on a library whose videos
+    # are all already converted every call returns here, and the registry
+    # would never be swept at all.
+    with _jobs_lock:
+        _forget_stale_jobs(now)
+
     if target.is_file():
         # Refresh the LRU stamp so a clip that keeps being watched keeps its
         # place ahead of one converted once and never opened again.
@@ -430,9 +660,7 @@ def request_transcode(
         return TranscodeStatus(state="ready", progress=1.0)
 
     scoped = _scoped_key(album_key, key)
-    now = time.monotonic()
     with _jobs_lock:
-        _forget_stale_jobs(now)
         job = _jobs.get(scoped)
         if job is not None:
             job.last_polled = now
@@ -459,9 +687,23 @@ def _update(scoped: str, **fields: object) -> _Job | None:
 
 
 def _abandoned(scoped: str, now: float) -> bool:
+    """True when nothing is waiting for this job any more."""
+    if _shutting_down.is_set():
+        return True
     with _jobs_lock:
         job = _jobs.get(scoped)
-        return job is None or now - job.last_polled > ABANDON_AFTER_SECONDS
+        if job is None:
+            return True
+        return job.cancelled or now - job.last_polled > ABANDON_AFTER_SECONDS
+
+
+def _cancelled(scoped: str) -> bool:
+    """True only for a *known* reason to stop, never for mere silence."""
+    if _shutting_down.is_set():
+        return True
+    with _jobs_lock:
+        job = _jobs.get(scoped)
+        return job is None or job.cancelled
 
 
 def _drop(scoped: str) -> None:
@@ -470,8 +712,21 @@ def _drop(scoped: str) -> None:
 
 
 def _job_timeout(duration: float | None) -> float:
-    scaled = (duration or 0.0) * JOB_TIMEOUT_PER_SECOND
-    return min(max(scaled, MIN_JOB_TIMEOUT_SECONDS), MAX_JOB_TIMEOUT_SECONDS)
+    """Wall-clock ceiling for one conversion, scaled off the source duration.
+
+    An *unknown* duration takes the loosest ceiling, not the tightest. MPEG-2
+    elementary streams (``.m2v``) report ``Duration: N/A`` as a matter of
+    course, and giving those the ten-minute floor killed every one longer than
+    ten minutes of encoding — deterministically, so it recurred on every
+    retry. A genuinely wedged job is caught by the stall detector instead,
+    which does not depend on knowing the duration.
+    """
+    if duration is None or duration <= 0:
+        return MAX_JOB_TIMEOUT_SECONDS
+    return min(
+        max(duration * JOB_TIMEOUT_PER_SECOND, MIN_JOB_TIMEOUT_SECONDS),
+        MAX_JOB_TIMEOUT_SECONDS,
+    )
 
 
 def _run_job(scoped: str, source: Path, target: Path) -> None:
@@ -483,7 +738,22 @@ def _run_job(scoped: str, source: Path, target: Path) -> None:
             _drop(scoped)
             return
 
-        plan = plan_for(probe_streams(source))
+        probe = probe_streams(source)
+        # An extension in VIDEO_EXTENSIONS is no promise of a video stream:
+        # .mkv, .mov, .ogg and .asf all routinely hold audio only. ffmpeg
+        # would fail on the unconditional "-map 0:v:0" with "Error opening
+        # output files: Invalid argument", which is what the player would then
+        # show the user. Say what is actually wrong instead.
+        if probe is not None and probe.trusted and not probe.has_video:
+            _update(
+                scoped,
+                state="failed",
+                detail="This file has no video track to play.",
+                finished_at=time.monotonic(),
+            )
+            return
+
+        plan = plan_for(probe)
         _update(scoped, state="running", progress=0.0)
         logger.info(
             f"Converting {source.name} for playback "
@@ -577,6 +847,39 @@ def _drive_ffmpeg(
         tmp_path.unlink(missing_ok=True)
         return f"Could not start ffmpeg: {e}"
 
+    with _live_lock:
+        _live_processes.add(proc)
+    try:
+        return _follow_ffmpeg(scoped, proc, source, tmp_path, target, plan, stderr_file)
+    except BaseException:
+        # Everything from here to the read loop's own try/finally used to be
+        # unprotected, so anything raising in between — thread exhaustion at
+        # `watcher.start()` is the reachable one — left ffmpeg running with no
+        # watchdog, unreaped, and a multi-gigabyte ".tmp" behind that the
+        # sweeper could not even see (it counts ".mp4"). Killing here costs a
+        # conversion that was already lost.
+        try:
+            proc.kill()
+            proc.wait(timeout=WATCHDOG_INTERVAL_SECONDS)
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+        tmp_path.unlink(missing_ok=True)
+        raise
+    finally:
+        with _live_lock:
+            _live_processes.discard(proc)
+
+
+def _follow_ffmpeg(
+    scoped: str,
+    proc: subprocess.Popen,
+    source: Path,
+    tmp_path: Path,
+    target: Path,
+    plan: TranscodePlan,
+    stderr_file: IO[bytes],
+) -> str | None:
+    """Watch a running ffmpeg to completion and publish what it produced."""
     stop = threading.Event()
     last_beat = [time.monotonic()]
     deadline = time.monotonic() + _job_timeout(plan.duration)
@@ -590,6 +893,7 @@ def watchdog() -> None:
             elif now > deadline:
                 killed_for[0] = "timeout"
             elif _abandoned(scoped, now):
+                # Covers the polling clock, an explicit cancel, and shutdown.
                 killed_for[0] = "abandoned"
             else:
                 continue
@@ -638,6 +942,17 @@ def watchdog() -> None:
     except OSError:
         succeeded = False
 
+    # Cancellation is checked here rather than only up front, because the
+    # album can be deleted (or the server stopped) at any point during a
+    # conversion that then completes perfectly well. Publishing it would
+    # recreate the directory that was just removed. Note this is
+    # ``_cancelled``, not ``_abandoned``: mere silence from the client must
+    # NOT discard a finished conversion — see the comment above `succeeded`.
+    if succeeded and _cancelled(scoped):
+        tmp_path.unlink(missing_ok=True)
+        logger.info(f"Discarded the finished conversion of {source.name}; cancelled.")
+        return _ABANDONED
+
     if succeeded:
         try:
             os.replace(tmp_path, target)
@@ -667,7 +982,16 @@ def watchdog() -> None:
 
 
 def _stderr_tail(handle: IO[bytes]) -> str | None:
-    """ffmpeg's last complaint, short enough to show in the player."""
+    """ffmpeg's *first* complaint, short enough to show in the player.
+
+    The first, not the last. Under ``-loglevel error`` ffmpeg prints the
+    diagnosis first and a generic muxer post-mortem last — "Nothing was
+    written into output file, because at least one of its streams received no
+    packets", or "Error opening output files: Invalid argument" — so taking
+    the last line reliably showed the user the one line that says nothing
+    about what went wrong, while the actual cause (say "[libx264] width not
+    divisible by 2") sat above it.
+    """
     try:
         handle.seek(0)
         text = handle.read().decode("utf-8", errors="replace")
@@ -676,7 +1000,7 @@ def _stderr_tail(handle: IO[bytes]) -> str | None:
     lines = [line.strip() for line in text.splitlines() if line.strip()]
     if not lines:
         return None
-    return lines[-1][:_MAX_DETAIL_CHARS]
+    return lines[0][:_MAX_DETAIL_CHARS]
 
 
 def _reset_jobs_for_tests() -> None:
diff --git a/photomap/frontend/static/css/video-player.css b/photomap/frontend/static/css/video-player.css
index 9eeb584b..e6bd5d6d 100644
--- a/photomap/frontend/static/css/video-player.css
+++ b/photomap/frontend/static/css/video-player.css
@@ -54,14 +54,21 @@
 /* The media card. Shrink-wraps its <video>, so the border traces the picture
    at any aspect ratio instead of letterboxing it inside a fixed panel.
 
-   The min sizes matter only for the moments when there is nothing to size
-   against — no poster, no metadata yet, or an error before either arrived —
-   and stop the frame collapsing to a sliver behind the overlay panels. */
+   No min-width/min-height: they were unconditional, so whenever the video was
+   height-constrained to something narrower than the minimum — a portrait phone
+   clip on a landscape screen, the most common shape in a phone library — the
+   card was up to 160px wider than the picture, with all of the surplus on one
+   side. There is no need for a floor: a <video> with nothing to size against
+   has an intrinsic 300x150 of its own, which is what the overlay panels sit
+   in until a poster or metadata arrives.
+
+   Centring is what keeps any residual surplus symmetric rather than piling it
+   against the left border. */
 .video-player-frame {
   position: relative;
   display: flex;
-  min-width: min(320px, 78vw);
-  min-height: 180px;
+  align-items: center;
+  justify-content: center;
   max-width: 100%;
   background: #000;
   border: 1px solid rgba(255, 255, 255, 0.14);
@@ -79,7 +86,14 @@
   display: block;
   width: auto;
   height: auto;
-  max-width: min(94vw, 1600px);
+  /* Must not exceed what the frame can be: the frame's own max-width resolves
+     against the modal's content box, which is 100vw minus its 24px padding on
+     each side, plus the frame's 1px borders. A 94vw cap crossed that below
+     800px of viewport, and since a flex item's automatic minimum size is its
+     content size clamped by max-width, the video could not shrink to fit —
+     the frame's overflow:hidden silently sliced ~24px off the right of every
+     video on a phone. */
+  max-width: min(calc(100vw - 52px), 1600px);
   /* The overlay's own 24px padding top and bottom, plus the caption row and
      its gap. Resolved against the visible viewport for the reason given
      above. */
diff --git a/photomap/frontend/static/javascript/video-player.js b/photomap/frontend/static/javascript/video-player.js
index 673e796c..40657442 100644
--- a/photomap/frontend/static/javascript/video-player.js
+++ b/photomap/frontend/static/javascript/video-player.js
@@ -62,6 +62,13 @@ let usingConversion = false;
 // inside its abandonment window, which is measured in tens of seconds.
 const POLL_INTERVAL_MS = 1000;
 
+// Consecutive failed polls tolerated before giving up. The POST is also the
+// backend's liveness signal, so treating one dropped request as fatal both
+// told the user a five-minute conversion had failed and made the backend drop
+// it — for a wifi handoff, a sleep/wake, or a proxy hiccup.
+const MAX_POLL_FAILURES = 4;
+let pollFailures = 0;
+
 export function isVideoPlayerOpen() {
   return Boolean(modal?.classList.contains("visible"));
 }
@@ -111,7 +118,14 @@ function showProgress(message, progress) {
 
   progressMessageEl.textContent = message;
   progressBarEl?.classList.toggle("video-player-bar--indeterminate", !known);
-  progressBarEl?.setAttribute("aria-valuenow", String(percent));
+  if (known) {
+    progressBarEl?.setAttribute("aria-valuenow", String(percent));
+  } else {
+    // ARIA requires the attribute to be absent for an indeterminate
+    // progressbar; leaving it at 0 makes a screen reader announce a job that
+    // is running fine as stuck at 0%.
+    progressBarEl?.removeAttribute("aria-valuenow");
+  }
   if (progressFillEl) {
     // Cleared rather than set to 0% in the indeterminate case: the sweep
     // animation supplies the width, and an inline one would override it.
@@ -220,6 +234,13 @@ async function pollConversion(mySession, endpoint) {
       return;
     }
     console.debug("Video conversion request failed:", err);
+    pollFailures += 1;
+    if (pollFailures < MAX_POLL_FAILURES) {
+      // Keep asking. Backing off linearly stays well inside the backend's
+      // abandonment window even at the last attempt.
+      pollTimer = setTimeout(() => pollConversion(mySession, endpoint), POLL_INTERVAL_MS * pollFailures);
+      return;
+    }
     showFallback(`${subject()} could not be prepared for playback.`, current?.url || "");
     return;
   }
@@ -227,6 +248,7 @@ async function pollConversion(mySession, endpoint) {
   if (mySession !== session) {
     return;
   }
+  pollFailures = 0;
 
   if (status.state === "ready" && status.url) {
     usingConversion = true;
@@ -256,6 +278,7 @@ function beginConversion(mySession) {
     // An older server, or a payload with no conversion route. Behave the way
     // the player did before conversion existed.
     showFallback(`${subject()} is in a format your browser cannot play.`, current?.url || "");
+    focusPlayer();
     return;
   }
 
@@ -280,6 +303,7 @@ export function openVideoPlayer({ url, filename, playable = true, poster = "", t
   pollTimer = null;
   current = { url, filename, transcodeUrl };
   usingConversion = false;
+  pollFailures = 0;
 
   if (titleEl) {
     titleEl.textContent = filename || "";
@@ -305,6 +329,10 @@ export function openVideoPlayer({ url, filename, playable = true, poster = "", t
   modal.classList.add("visible");
 
   if (!url) {
+    // The only open path with nothing to play. Without the teardown the
+    // previous clip keeps streaming — audibly — behind the panel, and with
+    // the controls hidden there is no way to stop it.
+    teardownVideo();
     showFallback("This video is unavailable.", "");
     focusPlayer();
   } else if (playable === false) {
@@ -391,6 +419,21 @@ export function initializeVideoPlayer() {
       showFallback(`${subject()} could not be played even after conversion.`, current?.url || url);
       return;
     }
+
+    // Which failure it was decides whether converting could possibly help.
+    // Without this, a transient network drop on a perfectly decodable clip
+    // tore it down and started a full re-encode on the server.
+    const code = videoEl.error?.code;
+    if (code === 1 /* MEDIA_ERR_ABORTED */) {
+      return; // the load was cancelled, not rejected
+    }
+    if (code === 2 /* MEDIA_ERR_NETWORK */) {
+      showFallback(`${subject()} could not be loaded. Check that PhotoMapAI is still running.`, current?.url || url);
+      return;
+    }
+    // MEDIA_ERR_DECODE and MEDIA_ERR_SRC_NOT_SUPPORTED are exactly what a
+    // container or codec the browser cannot handle looks like. An absent code
+    // stays permissive, which is what the player did before.
     beginConversion(session);
   });
 
@@ -425,7 +468,12 @@ export function _resetVideoPlayerForTests() {
   slideshowWasRunning = false;
   clearTimeout(pollTimer);
   pollTimer = null;
-  session = 0;
+  // Advanced, never reset to a fixed value: session numbers are only a valid
+  // staleness guard while they are monotonic. Restarting at 0 lets a poll
+  // chain left pending by a previous test capture a number the next test
+  // reissues, so its check passes and it plays into the wrong player.
+  session += 1;
   current = null;
   usingConversion = false;
+  pollFailures = 0;
 }
diff --git a/tests/backend/test_video_transcode.py b/tests/backend/test_video_transcode.py
index 80a107c3..d166df88 100644
--- a/tests/backend/test_video_transcode.py
+++ b/tests/backend/test_video_transcode.py
@@ -149,6 +149,50 @@ def test_probe_returns_none_when_ffmpeg_is_unavailable(monkeypatch):
     assert probe_streams(Path("anything.mkv")) is None
 
 
+# An audio stream whose *language tag* closes its own paren early and then
+# spells out a video stream. ffmpeg prints the tag inline, before the
+# ": Audio:" delimiter, so the line matches the video pattern — and it
+# degrades toward *copy*, which is the dangerous direction.
+TAG_INJECTION_BANNER = """Input #0, matroska,webm, from 'attack.mkv':
+  Duration: 00:00:02.00, start: 0.000000, bitrate: 100 kb/s
+  Stream #0:0(x): Video: h264 (High), yuv420p, 1920x1080, 25 fps): Audio: opus, 48000 Hz, mono, fltp
+  Stream #0:1: Video: hevc (Main 10), yuv420p10le(tv), 320x240, 10 fps
+At least one output file must be specified
+"""
+
+
+def test_a_language_tag_cannot_forge_a_copyable_video_stream(banner):
+    """The file's own metadata must not be able to win a stream copy.
+
+    Without the ambiguity check this probes as h264/yuv420p — so a 10-bit
+    HEVC stream would be copied into an MP4 and cached as ``ready``, which is
+    exactly the black rectangle the converter exists to remove.
+    """
+    banner(TAG_INJECTION_BANNER)
+    probe = probe_streams(Path("attack.mkv"))
+    assert probe.trusted is False
+    assert plan_for(probe).copy_video is False
+
+
+def test_a_newline_in_the_filename_cannot_forge_report_lines(banner, tmp_path):
+    """ffmpeg echoes the input path, and a filename may contain a newline.
+
+    The forged lines are indistinguishable from real ones once they are text,
+    so the path itself is what condemns the banner.
+    """
+    banner(MODERN_BANNER)  # a banner that would otherwise justify a copy
+    evil = tmp_path / "a\nStream #0:0: Video: h264 (High), yuv420p\n.mkv"
+    probe = probe_streams(evil)
+    assert probe.trusted is False
+    assert plan_for(probe).copy_video is False
+
+
+def test_an_ordinary_banner_stays_trusted(banner):
+    """The guard must not condemn every normal file."""
+    banner(MODERN_BANNER)
+    assert probe_streams(Path("modern.mkv")).trusted is True
+
+
 def test_probe_of_garbage_reports_nothing_rather_than_raising(banner):
     banner("this is not an ffmpeg banner at all")
     probe = probe_streams(Path("junk.bin"))
@@ -237,6 +281,30 @@ def test_an_unparsed_pixel_format_is_re_encoded():
     assert plan.copy_video is False
 
 
+def test_an_untrusted_probe_re_encodes_everything():
+    """A banner that could not be fully attributed to ffmpeg justifies nothing.
+
+    The fields are still populated for descriptive use; what must not happen
+    is a stream *copy* on their say-so.
+    """
+    plan = plan_for(
+        StreamProbe(
+            has_video=True,
+            video_codec="h264",
+            video_pix_fmt="yuv420p",
+            has_audio=True,
+            audio_codec="aac",
+            duration=42.0,
+            trusted=False,
+        )
+    )
+    assert plan.copy_video is False
+    assert plan.copy_audio is False
+    # The duration comes from the same forged text and drives both the
+    # progress readout and the job deadline.
+    assert plan.duration is None
+
+
 def test_a_failed_probe_re_encodes_everything():
     plan = plan_for(None)
     assert plan.copy_video is False
@@ -273,7 +341,23 @@ def test_encode_path_pins_a_browser_decodable_format():
 def test_encode_path_corrects_non_square_pixels():
     """DVD rips, .vob, .mpg and AVCHD .m2ts are all anamorphic."""
     args = _args(copy_video=False, has_audio=False, copy_audio=False)
-    assert args[args.index("-vf") + 1] == "scale=iw*sar:ih"
+    assert args[args.index("-vf") + 1] == "scale=trunc(iw*sar/2)*2:trunc(ih/2)*2,setsar=1"
+
+
+def test_the_scale_filter_rounds_both_axes_to_even():
+    """libx264 refuses an odd dimension in yuv420p outright.
+
+    720x480 SAR 32:27 is 16:9 NTSC DVD — the single most common shape this
+    filter exists for. 720*32/27 = 853.33, and ``scale`` truncates, so an
+    unrounded expression yields 853 and every such rip fails permanently.
+    """
+    vf = _args(copy_video=False, has_audio=False, copy_audio=False)[
+        _args(copy_video=False, has_audio=False, copy_audio=False).index("-vf") + 1
+    ]
+    assert "trunc(" in vf and "*2" in vf
+    # And the output must declare square pixels, or a player re-applies the
+    # source aspect on top of the correction.
+    assert vf.endswith("setsar=1")
 
 
 def test_a_silent_source_drops_audio_explicitly():
@@ -532,6 +616,237 @@ def spy():
     assert calls == []
 
 
+def test_names_differing_only_in_case_get_different_conversions(tmp_path):
+    """On a case-sensitive filesystem these are two different movies.
+
+    The frame cache casefolds its key, so with matching mtimes — routine for
+    anything unpacked from one archive — both would map to one entry. For a
+    still that is the wrong thumbnail; here it would play the wrong film.
+    """
+    cache = TranscodeCache("album", root=tmp_path)
+    lower = tmp_path / "clip.mp4"
+    upper = tmp_path / "Clip.mp4"
+    lower.write_bytes(b"a")
+    upper.write_bytes(b"b")
+    import os
+
+    os.utime(lower, (1000, 1000))
+    os.utime(upper, (1000, 1000))
+
+    assert cache.path_for(lower) != cache.path_for(upper)
+
+
+def test_serving_a_conversion_refreshes_its_place_in_the_queue(tmp_path):
+    """A film is fetched with Range requests across the whole viewing session.
+
+    Without a stamp here its mtime is frozen at the moment the progress panel
+    last polled, making the film on screen the first thing the sweeper evicts.
+    """
+    import os
+
+    cache = TranscodeCache("album", root=tmp_path)
+    video = tmp_path / "clip.mkv"
+    video.write_bytes(b"x")
+    target = cache.path_for(video)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(b"converted")
+    os.utime(target, (1000, 1000))
+
+    assert cache.get(video) == target
+    assert target.stat().st_mtime > 1000
+
+
+def test_discard_removes_every_generation(tmp_path):
+    """The usual reason to discard is that the source is gone, so its mtime
+    can no longer be read and the exact key is unrecoverable."""
+    cache = TranscodeCache("album", root=tmp_path)
+    video = tmp_path / "clip.mkv"
+    video.write_bytes(b"x")
+    directory = cache.directory
+    directory.mkdir(parents=True, exist_ok=True)
+    prefix = cache.key_for(video).split("-")[0]
+    old = directory / f"{prefix}-deadbeefdeadbeef.mp4"
+    new = cache.path_for(video)
+    old.write_bytes(b"old")
+    new.write_bytes(b"new")
+    unrelated = directory / "ffffffffffffffffffffffffffffffff-0000000000000000.mp4"
+    unrelated.write_bytes(b"other")
+
+    video.unlink()  # the realistic case: source already deleted
+    cache.discard(video)
+
+    assert not old.exists() and not new.exists()
+    assert unrelated.exists()
+
+
+def test_prune_keeps_the_index_and_spares_work_in_progress(tmp_path):
+    cache = TranscodeCache("album", root=tmp_path)
+    directory = cache.directory
+    directory.mkdir(parents=True, exist_ok=True)
+    keep = directory / "aaaa-bbbb.mp4"
+    drop = directory / "cccc-dddd.mp4"
+    running = directory / "aaaa.xyz.tmp"
+    for f in (keep, drop, running):
+        f.write_bytes(b"x")
+
+    assert cache.prune({"aaaa-bbbb"}) == 1
+    assert keep.exists() and not drop.exists()
+    # A .tmp here is very likely the conversion running right now, which may
+    # have hours invested in it; only the age-aware sweeper may remove one.
+    assert running.exists()
+
+
+def test_sweep_spares_a_conversion_that_is_being_watched(tmp_path):
+    """Honouring the budget is worth less than not yanking a file out from
+    under an open player."""
+    fresh = _make_conversion(tmp_path, "a", "watching", 500, time.time())
+    old = _make_conversion(tmp_path, "a", "cold", 500, 1000)
+
+    sweep_transcode_cache(budget=100, root=tmp_path)
+
+    assert fresh.exists()
+    assert not old.exists()
+
+
+def test_sweep_reclaims_abandoned_temp_files(tmp_path):
+    """A conversion killed by a crash leaves a .tmp behind, and because it is
+    not a .mp4 nothing else can even see it."""
+    import os
+
+    stale = tmp_path / "a" / "abc.deadbeef.tmp"
+    stale.parent.mkdir(parents=True, exist_ok=True)
+    stale.write_bytes(b"\0" * 1000)
+    os.utime(stale, (1000, 1000))
+
+    assert sweep_transcode_cache(budget=10**9, root=tmp_path) == 1
+    assert not stale.exists()
+
+
+def test_an_unknown_duration_gets_the_loosest_deadline_not_the_tightest():
+    """MPEG-2 elementary streams (.m2v) always report Duration: N/A.
+
+    Giving those the ten-minute floor killed every one longer than ten minutes
+    of encoding, deterministically, on every retry.
+    """
+    assert video_transcode._job_timeout(None) == video_transcode.MAX_JOB_TIMEOUT_SECONDS
+    assert video_transcode._job_timeout(0) == video_transcode.MAX_JOB_TIMEOUT_SECONDS
+    assert video_transcode._job_timeout(5.0) == video_transcode.MIN_JOB_TIMEOUT_SECONDS
+
+
+def test_forget_album_cancels_only_that_album(monkeypatch, tmp_path):
+    monkeypatch.setattr(video_transcode, "ffmpeg_exe", lambda: "/bin/true")
+    mine = video_transcode._scoped_key("gone", "key")
+    theirs = video_transcode._scoped_key("staying", "key")
+    video_transcode._jobs[mine] = video_transcode._Job(state="running")
+    video_transcode._jobs[theirs] = video_transcode._Job(state="running")
+
+    assert video_transcode.forget_album("gone") == 1
+    assert video_transcode._cancelled(mine) is True
+    assert video_transcode._cancelled(theirs) is False
+    # An explicit cancel also reads as abandonment, so the watchdog kills it.
+    assert video_transcode._abandoned(mine, time.monotonic()) is True
+
+
+def test_a_stalled_job_nobody_polls_is_reaped_from_the_registry():
+    """A source whose mtime keeps moving (a file still being copied in) makes
+    every poll a new key, so without this the registry grows once a second and
+    nothing can ever reclaim it."""
+    scoped = video_transcode._scoped_key("album", "key")
+    video_transcode._jobs[scoped] = video_transcode._Job(
+        state="running",
+        last_polled=time.monotonic() - video_transcode.ABANDON_AFTER_SECONDS - 1,
+    )
+    with video_transcode._jobs_lock:
+        video_transcode._forget_stale_jobs(time.monotonic())
+    assert scoped not in video_transcode._jobs
+
+
+def test_stderr_reports_the_cause_not_the_muxer_post_mortem(tmp_path):
+    """ffmpeg prints the diagnosis first and a generic summary last."""
+    import io
+
+    handle = io.BytesIO(
+        b"[libx264] width not divisible by 2 (853x480)\n"
+        b"[vf#0:0] Error while filtering\n"
+        b"[out#0/mp4] Nothing was written into output file.\n"
+    )
+    assert "not divisible by 2" in video_transcode._stderr_tail(handle)
+
+
+@requires_ffmpeg
+def test_a_cancelled_job_discards_even_a_finished_conversion(tmp_path, monkeypatch):
+    """The album can be deleted while a conversion that then succeeds is still
+    running. Publishing it would recreate the directory just removed, into a
+    cache keyed by an album that no longer exists.
+
+    Drives the worker body directly rather than polling: a cancelled job never
+    reaches a terminal state, because polling for it is precisely what
+    cancellation revokes.
+    """
+    exe = ffmpeg_exe()
+    source = tmp_path / "clip.mkv"
+    subprocess.run(
+        [exe, "-y", "-loglevel", "error", "-f", "lavfi", "-i",
+         "testsrc=size=160x120:rate=10:duration=1", "-c:v", "libx264",
+         "-pix_fmt", "yuv420p", str(source)],
+        check=True,
+    )
+    cache = TranscodeCache("album", root=tmp_path / "cache")
+    target = cache.path_for(source)
+    scoped = video_transcode._scoped_key("album", cache.key_for(source))
+    video_transcode._jobs[scoped] = video_transcode._Job(state="running")
+
+    # Cancelled only once ffmpeg has already finished, which is the case that
+    # matters: the conversion succeeded and must still be thrown away.
+    monkeypatch.setattr(video_transcode, "_cancelled", lambda key: True)
+    video_transcode._run_job(scoped, source, target)
+
+    assert not target.exists()
+    assert not list(target.parent.glob("*.mp4"))
+    assert not list(target.parent.glob("*.tmp"))
+    # Dropped rather than recorded as a failure the client would be shown.
+    assert scoped not in video_transcode._jobs
+
+
+@requires_ffmpeg
+def test_an_audio_only_container_fails_legibly(tmp_path):
+    """.mkv/.mov/.ogg are all in VIDEO_EXTENSIONS but routinely hold audio only.
+
+    ffmpeg's own message is "Error opening output files: Invalid argument",
+    which is what the player would otherwise show the user.
+    """
+    exe = ffmpeg_exe()
+    source = tmp_path / "song.mkv"
+    subprocess.run(
+        [exe, "-y", "-loglevel", "error", "-f", "lavfi", "-i", "sine=duration=1",
+         "-c:a", "libopus", str(source)],
+        check=True,
+    )
+    status = _await_conversion("album", source, tmp_path / "cache", timeout=60)
+    assert status.state == "failed"
+    assert "no video track" in (status.detail or "")
+
+
+@requires_ffmpeg
+def test_an_anamorphic_dvd_rip_converts(tmp_path):
+    """720x480 SAR 32:27 is 16:9 NTSC DVD. 720*32/27 = 853.33, and libx264
+    refuses an odd width in yuv420p, so this failed on every retry."""
+    exe = ffmpeg_exe()
+    source = tmp_path / "dvd.mpg"
+    subprocess.run(
+        [exe, "-y", "-loglevel", "error", "-f", "lavfi", "-i",
+         "testsrc=size=720x480:rate=10:duration=1", "-c:v", "mpeg2video",
+         "-aspect", "16:9", str(source)],
+        check=True,
+    )
+    status = _await_conversion("album", source, tmp_path / "cache", timeout=120)
+    assert status.state == "ready", status.detail
+
+    converted = TranscodeCache("album", root=tmp_path / "cache").get(source)
+    probe = probe_streams(converted)
+    assert probe.video_codec == "h264"
+
+
 # --------------------------------------------------------------------------
 # Routes
 # --------------------------------------------------------------------------
diff --git a/tests/frontend/video-player.test.js b/tests/frontend/video-player.test.js
index 87c3be76..554094e2 100644
--- a/tests/frontend/video-player.test.js
+++ b/tests/frontend/video-player.test.js
@@ -357,6 +357,58 @@ describe("formats the browser cannot play", () => {
     await flush();
   });
 
+  it("does not convert when the failure was the network, not the format", () => {
+    // A transient drop on a perfectly decodable clip used to tear it down and
+    // start a full re-encode on the server.
+    openVideoPlayer({ ...MP4, transcodeUrl: "prepare_video/album/clip.mp4" });
+    Object.defineProperty(video(), "error", { value: { code: 2 }, configurable: true });
+
+    video().dispatchEvent(new Event("error"));
+
+    expect(global.fetch).not.toHaveBeenCalled();
+    expect(progress().hidden).toBe(true);
+    expect(fallback().hidden).toBe(false);
+    expect(fallbackMessage()).toMatch(/could not be loaded/i);
+  });
+
+  it("ignores an aborted load, which is not a failure at all", () => {
+    openVideoPlayer({ ...MP4, transcodeUrl: "prepare_video/album/clip.mp4" });
+    Object.defineProperty(video(), "error", { value: { code: 1 }, configurable: true });
+
+    video().dispatchEvent(new Event("error"));
+
+    expect(global.fetch).not.toHaveBeenCalled();
+    expect(fallback().hidden).toBe(true);
+  });
+
+  it("converts on an unsupported-source error", () => {
+    openVideoPlayer({ ...MP4, transcodeUrl: "prepare_video/album/clip.mp4" });
+    Object.defineProperty(video(), "error", { value: { code: 4 }, configurable: true });
+
+    video().dispatchEvent(new Event("error"));
+
+    expect(global.fetch).toHaveBeenCalledWith("prepare_video/album/clip.mp4", { method: "POST" });
+  });
+
+  it("focuses the close button when no conversion is available", () => {
+    // Otherwise focus stays on <body> (the badge blurs itself before
+    // dispatching), where Tab walks into the controls behind the backdrop.
+    openVideoPlayer(AVI_NO_CONVERSION);
+    expect(document.activeElement).toBe(document.getElementById("videoPlayerCloseBtn"));
+  });
+
+  it("releases the previous clip when reopened with nothing to play", () => {
+    // Otherwise it keeps streaming, audibly, behind the panel — with the
+    // controls hidden, so there is no way to stop it.
+    openVideoPlayer(MP4);
+    expect(video().getAttribute("src")).toBe("videos/album/clip.mp4");
+
+    openVideoPlayer({ url: "", filename: "gone.mp4", playable: true });
+
+    expect(video().hasAttribute("src")).toBe(false);
+    expect(video().pause).toHaveBeenCalled();
+  });
+
   it("falls back when an errored video has nowhere to be converted", () => {
     openVideoPlayer(MP4);
     video().dispatchEvent(new Event("error"));
@@ -430,6 +482,37 @@ describe("conversion", () => {
     expect(progressMessage()).toMatch(/waiting/i);
   });
 
+  it("survives a transient poll failure instead of abandoning the job", async () => {
+    // The poll is also the backend's liveness signal, so giving up on one
+    // dropped request also makes the backend drop the conversion.
+    let calls = 0;
+    global.fetch = jest.fn(() => {
+      calls += 1;
+      if (calls === 1) {
+        return Promise.reject(new Error("wifi handoff"));
+      }
+      return Promise.resolve({ ok: true, json: () => Promise.resolve({ state: "running", progress: 0.6 }) });
+    });
+
+    openVideoPlayer(AVI);
+    await flush();
+    expect(fallback().hidden).toBe(true); // not given up on
+
+    jest.advanceTimersByTime(1000);
+    await flush();
+    expect(progress().hidden).toBe(false);
+    expect(document.getElementById("videoPlayerProgressPercent").textContent).toBe("60%");
+  });
+
+  it("omits aria-valuenow while the bar is indeterminate", async () => {
+    // ARIA requires the attribute to be absent, or a screen reader announces
+    // a job that is running fine as stuck at 0%.
+    mockConversion({ state: "running", progress: 0 });
+    openVideoPlayer(AVI);
+    await flush();
+    expect(document.getElementById("videoPlayerProgressBar").hasAttribute("aria-valuenow")).toBe(false);
+  });
+
   it("sweeps rather than sitting at 0% when the duration is unknown", async () => {
     // ffmpeg could not determine the duration, so there is no percentage to
     // report. A bar parked at 0% reads as stuck.
@@ -515,10 +598,22 @@ describe("conversion", () => {
     expect(fallbackMessage()).toBe("ffmpeg is not available.");
   });
 
+  /** Drive the poll past its retry tolerance. */
+  async function exhaustPolls() {
+    for (let i = 0; i < 8; i += 1) {
+      jest.advanceTimersByTime(5000);
+      await flush();
+    }
+  }
+
   it("survives the request itself failing", async () => {
     global.fetch = jest.fn(() => Promise.reject(new Error("offline")));
     openVideoPlayer(AVI);
     await flush();
+    // One rejection is a hiccup, not a verdict — it must still be retrying.
+    expect(fallback().hidden).toBe(true);
+
+    await exhaustPolls();
 
     expect(fallback().hidden).toBe(false);
     expect(fallbackMessage()).toMatch(/could not be prepared/i);
@@ -528,6 +623,7 @@ describe("conversion", () => {
     global.fetch = jest.fn(() => Promise.resolve({ ok: false, status: 500, json: () => Promise.resolve({}) }));
     openVideoPlayer(AVI);
     await flush();
+    await exhaustPolls();
 
     expect(fallback().hidden).toBe(false);
     expect(fallbackMessage()).toMatch(/could not be prepared/i);

From b3195ab1fd2e82504476736178d23bb0d645e06b Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Thu, 3 Sep 2026 15:33:13 -0400
Subject: [PATCH 3/4] fix: one play badge for every video, now that any of them
 can be played
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The amber, dashed, slashed badge variant for containers no browser decodes
described a real limitation right up until the previous commit removed it:
clicking one used to reach a dead player offering a download. It now opens
the player, converts the file and plays it, exactly like any other video —
so the variant was advertising a restriction that no longer exists, and
doing it most loudly on the files that now work hardest.

`playable` stays in the badge's payload. The player still reads it to skip
a direct attempt it knows will fail and go straight to converting; it just
no longer changes how the badge looks or what it says.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GwzC2csXxZkd9HsD8A2t7h
---
 photomap/frontend/static/css/video-badge.css  | 38 +++----------------
 .../frontend/static/javascript/video-badge.js | 26 ++++++-------
 tests/frontend/video-badge.test.js            | 17 +++++----
 3 files changed, 27 insertions(+), 54 deletions(-)

diff --git a/photomap/frontend/static/css/video-badge.css b/photomap/frontend/static/css/video-badge.css
index 8af04454..2f69413d 100644
--- a/photomap/frontend/static/css/video-badge.css
+++ b/photomap/frontend/static/css/video-badge.css
@@ -100,39 +100,11 @@
   display: none;
 }
 
-/* Containers browsers generally cannot play. Muted rather than hidden: the
-   video is still indexed, searchable and mapped, and clicking still opens the
-   player, which explains and offers a download. */
-/* The difference has to survive being composited over an arbitrary frame.
-   Dimming alone did not: #fff -> #d8d8d8 with a slightly *lighter* disc
-   measured brighter than the playable state over a mid-grey frame, leaving a
-   dashed 1.4-unit stroke as the only real signal — about 3px of dash at the
-   grid's icon size. An amber tint plus a slash reads at a glance and does not
-   depend on the frame behind it. */
-.video-badge--unplayable {
-  color: #ffc65c;
-}
-
-.video-badge--unplayable .video-badge-icon {
-  background: rgba(0, 0, 0, 0.62);
-}
-
-.video-badge--unplayable .video-badge-icon circle {
-  stroke-dasharray: 3 2;
-}
-
-/* Drawn by the same SVG so it scales with the icon; hidden for playable
-   badges, which use the identical markup. */
-.video-badge-slash {
-  display: none;
-}
-
-.video-badge--unplayable .video-badge-slash {
-  display: block;
-  stroke: currentColor;
-  stroke-width: 1.8;
-  stroke-linecap: round;
-}
+/* There is deliberately no second "cannot play this" badge variant. It used
+   to exist — amber, with a dashed disc and a slash — for containers no
+   browser decodes, and it earned its keep while clicking one could only offer
+   a download. On-demand conversion removed the limitation it described, so
+   every video now gets the same play badge. */
 
 /* Grid tiles are much smaller than a full slide. */
 #gridViewSwiperWrapper .video-badge {
diff --git a/photomap/frontend/static/javascript/video-badge.js b/photomap/frontend/static/javascript/video-badge.js
index fde76452..d35a669d 100644
--- a/photomap/frontend/static/javascript/video-badge.js
+++ b/photomap/frontend/static/javascript/video-badge.js
@@ -52,7 +52,6 @@ const PLAY_ICON_SVG = `
   <svg class="video-badge-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
     <circle cx="12" cy="12" r="11" />
     <path d="M9.5 7.5v9l7-4.5z" />
-    <line class="video-badge-slash" x1="4.5" y1="19.5" x2="19.5" y2="4.5" />
   </svg>
 `;
 
@@ -82,24 +81,23 @@ export function makeVideoBadge(videoInfo, filename = "") {
   badge.innerHTML = `${PLAY_ICON_SVG}<span class="video-badge-label"></span>`;
   badge.querySelector(".video-badge-label").textContent = label;
 
-  // `playable` is a hint from the container extension, used for styling only.
-  // Whether a video actually plays depends on the codec inside it (an HEVC
-  // .mp4 plays in Safari but not Firefox), so the player always attempts
-  // playback and reacts to the element's own error event.
-  const unplayable = videoInfo?.playable === false;
+  // Every video gets the same badge, whatever container it is in.
+  //
+  // There used to be a second, amber-and-slashed variant for containers no
+  // browser decodes, warning that clicking would only offer a download. It is
+  // gone because it is no longer true: the player converts those on demand
+  // and plays them, so the only thing the variant still communicated was a
+  // limitation that had been removed. `playable` itself stays in the payload
+  // — the player reads it to skip a direct attempt that is going to fail and
+  // go straight to converting — it just no longer changes how this looks.
   const subject = filename || "video";
-  if (unplayable) {
-    badge.classList.add("video-badge--unplayable");
-    badge.title = `${subject} — this format may not play in your browser; click for options`;
-  } else {
-    badge.title = `Play ${subject}`;
-  }
+  badge.title = `Play ${subject}`;
 
   // The accessible name is built explicitly rather than left to aria-label,
   // which would *replace* the element's contents in the name computation —
   // the icon is aria-hidden, so the duration and frame rate (the entire
-  // reason the badge carries text) reached no screen reader at all. Every
-  // unplayable tile in a grid also announced identically, with no filename to
+  // reason the badge carries text) reached no screen reader at all. Without
+  // the filename, every tile in a grid announces identically, with nothing to
   // tell them apart.
   const spoken = [badge.title, label].filter(Boolean).join(", ");
   badge.setAttribute("aria-label", spoken);
diff --git a/tests/frontend/video-badge.test.js b/tests/frontend/video-badge.test.js
index 4949d75e..c0d0b704 100644
--- a/tests/frontend/video-badge.test.js
+++ b/tests/frontend/video-badge.test.js
@@ -109,10 +109,13 @@ describe("makeVideoBadge", () => {
     expect(badge.querySelector(".video-badge-label").innerHTML).not.toContain("<");
   });
 
-  it("marks containers browsers cannot play", () => {
+  it("offers to play a container the browser cannot decode, like any other", () => {
+    // The player converts these on demand now, so singling them out with a
+    // slashed badge would advertise a limitation that no longer exists.
     const badge = makeVideoBadge({ duration: 5, fps: 25, playable: false }, "clip.avi");
-    expect(badge.classList.contains("video-badge--unplayable")).toBe(true);
-    expect(badge.title).toMatch(/may not play/i);
+    expect(badge.classList.contains("video-badge--unplayable")).toBe(false);
+    expect(badge.title).toBe("Play clip.avi");
+    expect(badge.querySelector(".video-badge-slash")).toBeNull();
   });
 
   it("carries an accessible label", () => {
@@ -228,7 +231,7 @@ describe("badge click", () => {
     window.removeEventListener("videoPlayRequested", handler);
   });
 
-  it("reports an unplayable container so the player can explain", () => {
+  it("still reports the container hint, so the player can skip a doomed attempt", () => {
     const slide = makeSlide();
     applyVideoOverlay(slide, {
       ...VIDEO_DATA,
@@ -308,9 +311,9 @@ describe("accessible name", () => {
     expect(name).toContain("30 fps");
   });
 
-  it("keeps the filename in the unplayable announcement", () => {
-    // Otherwise every unplayable tile in a grid announces identically, with
-    // nothing to tell them apart.
+  it("keeps the filename in the announcement", () => {
+    // Otherwise every tile in a grid announces identically, with nothing to
+    // tell them apart.
     const badge = makeVideoBadge({ duration: 5, fps: 25, playable: false }, "clip.avi");
     expect(badge.getAttribute("aria-label")).toContain("clip.avi");
   });

From e8900fe29fd94c997c780ec37d97f3727f8c32a4 Mon Sep 17 00:00:00 2001
From: Lincoln Stein <lincoln.stein@gmail.com>
Date: Thu, 3 Sep 2026 16:20:23 -0400
Subject: [PATCH 4/4] feat: download the current image or video from the
 control panel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

There was no way to save the item you are looking at without bookmarking it
first, opening the bookmark menu, downloading, and unbookmarking again.

The download itself already existed and already handled video correctly —
`downloadSingleImage` picks `video_url` over the still frame, derives the
extension from the real path, and streams through an `<a download>` rather
than buffering a 200 MB clip into browser memory. Only a way to reach it was
missing, so this adds a trigger rather than an implementation: the logic moves
to a shared `download.js` that the bookmark menu and the new button both call.

The button sits next to Delete because it is the same shape of action, and it
resolves its target through `getCurrentSlideIndex()` — the same view-agnostic
primitive Delete uses — so one button serves both the swiper and the grid with
no per-view code. Nothing is drawn over the picture.

It is deliberately *outside* the `album_locked` guard that wraps Delete: a
lock protects an album's files from being changed, and saving a copy changes
nothing.

Videos always download as the **original** file, never a converted copy. The
conversion exists so the browser can decode a container it otherwise cannot;
it is a lossy re-encode in the general case, and it is not what is in the
user's library.

Adding the button did not widen the panel — it is a fixed 416px with seven
buttons or eight, measured against master. (That width already overflows a
390px viewport on master; unchanged here, and left alone.)

Also fixes two Windows-only failures in the previous commit's tests, both
test bugs rather than product ones: one compared an ffmpeg argument against a
hardcoded POSIX path, and the case-collision test asserted a premise that only
holds on a case-sensitive filesystem — on Windows the two names are one file,
so sharing a cache entry is the correct answer there.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GwzC2csXxZkd9HsD8A2t7h
---
 .../frontend/static/javascript/bookmarks.js   |  52 +----
 .../static/javascript/control-panel.js        |  31 +++
 .../frontend/static/javascript/download.js    |  57 +++++
 .../templates/modules/control-panel.html      |  23 +++
 tests/backend/test_video_transcode.py         |  20 +-
 tests/frontend/README.md                      |  24 ++-
 tests/frontend/download-current.test.js       | 195 ++++++++++++++++++
 tests/frontend/fullscreen-panels.test.js      |   2 +
 tests/frontend/panel-anchor.test.js           |   2 +
 .../frontend/video-player-integration.test.js |   2 +
 10 files changed, 353 insertions(+), 55 deletions(-)
 create mode 100644 photomap/frontend/static/javascript/download.js
 create mode 100644 tests/frontend/download-current.test.js

diff --git a/photomap/frontend/static/javascript/bookmarks.js b/photomap/frontend/static/javascript/bookmarks.js
index 490161e0..09aa9808 100644
--- a/photomap/frontend/static/javascript/bookmarks.js
+++ b/photomap/frontend/static/javascript/bookmarks.js
@@ -4,6 +4,7 @@
 
 import { showDeleteConfirmModal } from "./control-panel.js";
 import { createSimpleDirectoryPicker } from "./filetree.js";
+import { downloadItem, triggerSave } from "./download.js";
 import { deleteImages } from "./index.js";
 import { showConfirmModal } from "./modal-utils.js";
 import { visibleViewportBottom } from "./panel-anchor.js";
@@ -509,44 +510,8 @@ class BookmarkManager {
   }
 
   async downloadSingleImage(globalIndex) {
-    const data = await fetchJson(`retrieve_image/${encodeURIComponent(state.album)}/${globalIndex}`);
-    const isVideo = data.media_type === "video";
-    // For a video, download the playable file rather than its still frame.
-    const imageUrl = isVideo && data.video_url ? data.video_url : data.image_url;
-    // Derive the fallback extension from the real path — the old hardcoded
-    // .jpg would save a video under a name no player would open.
-    const fallbackExtension = data.filepath?.split(".").pop() || (isVideo ? "mp4" : "jpg");
-    const filename = data.filename || `image_${globalIndex}.${fallbackExtension}`;
-
-    if (isVideo) {
-      // Videos are far too large to buffer into a blob: a 200 MB clip would
-      // sit entirely in browser memory before the save dialog appeared. Point
-      // the download straight at the URL and let the browser stream it.
-      const a = document.createElement("a");
-      a.href = imageUrl;
-      a.download = filename;
-      document.body.appendChild(a);
-      a.click();
-      document.body.removeChild(a);
-      return;
-    }
-
-    // Fetch the actual image (binary, not JSON — fetch directly)
-    const imageResponse = await fetch(imageUrl);
-    if (!imageResponse.ok) {
-      throw new Error("Failed to fetch image");
-    }
-
-    const blob = await imageResponse.blob();
-    const url = URL.createObjectURL(blob);
-
-    const a = document.createElement("a");
-    a.href = url;
-    a.download = filename;
-    document.body.appendChild(a);
-    a.click();
-    document.body.removeChild(a);
-    URL.revokeObjectURL(url);
+    // Shared with the control panel's download button — see download.js.
+    return downloadItem(globalIndex);
   }
 
   async downloadAsZip(indices) {
@@ -561,15 +526,8 @@ class BookmarkManager {
       throw new Error(`Server error: ${response.status}`);
     }
 
-    const blob = await response.blob();
-    const url = URL.createObjectURL(blob);
-
-    const a = document.createElement("a");
-    a.href = url;
-    a.download = `${state.album}_bookmarked_images.zip`;
-    document.body.appendChild(a);
-    a.click();
-    document.body.removeChild(a);
+    const url = URL.createObjectURL(await response.blob());
+    triggerSave(url, `${state.album}_bookmarked_images.zip`);
     URL.revokeObjectURL(url);
   }
 
diff --git a/photomap/frontend/static/javascript/control-panel.js b/photomap/frontend/static/javascript/control-panel.js
index 3ed0a235..b3c6067e 100644
--- a/photomap/frontend/static/javascript/control-panel.js
+++ b/photomap/frontend/static/javascript/control-panel.js
@@ -1,5 +1,6 @@
 // control-panel.js
 // This file manages control panel button events (fullscreen, copy, delete)
+import { downloadItem } from "./download.js";
 import { deleteImage, getIndexMetadata } from "./index.js";
 import { initializePanelAnchor, syncPanelAnchor } from "./panel-anchor.js";
 import { getCurrentFilepath, getCurrentSlideIndex, slideState } from "./slide-state.js";
@@ -14,6 +15,7 @@ function cacheElements() {
     fullscreenBtn: document.getElementById("fullscreenBtn"),
     copyTextBtn: document.getElementById("copyTextBtn"),
     deleteCurrentFileBtn: document.getElementById("deleteCurrentFileBtn"),
+    downloadCurrentFileBtn: document.getElementById("downloadCurrentFileBtn"),
     controlPanel: document.getElementById("controlPanel"),
     searchPanel: document.getElementById("searchPanel"),
     scoreDisplay: document.getElementById("fixedScoreDisplay"),
@@ -163,6 +165,31 @@ function handleCopyText() {
 }
 
 // Delete the current file
+/**
+ * Save the current slide to disk.
+ *
+ * Resolved through getCurrentSlideIndex() rather than from any view's own
+ * DOM, which is what makes one button serve both the swiper and the grid —
+ * the same reason the delete button below works in both.
+ */
+async function handleDownloadCurrentFile() {
+  const [globalIndex] = getCurrentSlideIndex();
+  if (globalIndex === -1) {
+    alert("No image selected for download.");
+    return;
+  }
+
+  try {
+    showSpinner();
+    await downloadItem(globalIndex);
+  } catch (error) {
+    alert(`Download failed: ${errorDetail(error)}`);
+    console.error("Download failed:", error);
+  } finally {
+    hideSpinner();
+  }
+}
+
 async function handleDeleteCurrentFile() {
   const [globalIndex] = getCurrentSlideIndex();
   const currentFilepath = await getCurrentFilepath();
@@ -278,6 +305,10 @@ function setupControlPanelEventListeners() {
   }
 
   // Delete current file button
+  if (elements.downloadCurrentFileBtn) {
+    elements.downloadCurrentFileBtn.addEventListener("click", handleDownloadCurrentFile);
+  }
+
   if (elements.deleteCurrentFileBtn) {
     elements.deleteCurrentFileBtn.addEventListener("click", handleDeleteCurrentFile);
   }
diff --git a/photomap/frontend/static/javascript/download.js b/photomap/frontend/static/javascript/download.js
new file mode 100644
index 00000000..2ca8fd82
--- /dev/null
+++ b/photomap/frontend/static/javascript/download.js
@@ -0,0 +1,57 @@
+/**
+ * Saving a single album item to disk.
+ *
+ * Extracted from bookmarks.js so the control panel and the bookmark menu
+ * share one implementation rather than growing two that drift — the video
+ * handling below in particular is easy to get wrong in a way that only shows
+ * up on large files.
+ */
+
+import { state } from "./state.js";
+import { fetchJson } from "./utils.js";
+
+/**
+ * Download the album item at `globalIndex` under its own filename.
+ *
+ * Videos are saved as the **original** file, never a converted copy. The
+ * conversion exists so the browser can play a container it cannot decode; it
+ * is a lossy re-encode in the general case, and it is not what is in the
+ * user's library. `video_url` is the source bytes — see `create_slide_url`.
+ */
+export async function downloadItem(globalIndex) {
+  const data = await fetchJson(`retrieve_image/${encodeURIComponent(state.album)}/${globalIndex}`);
+  const isVideo = data.media_type === "video";
+  // For a video, download the playable file rather than its still frame.
+  const itemUrl = isVideo && data.video_url ? data.video_url : data.image_url;
+  // Derive the fallback extension from the real path — a hardcoded .jpg would
+  // save a video under a name no player would open.
+  const fallbackExtension = data.filepath?.split(".").pop() || (isVideo ? "mp4" : "jpg");
+  const filename = data.filename || `image_${globalIndex}.${fallbackExtension}`;
+
+  if (isVideo) {
+    // Videos are far too large to buffer into a blob: a 200 MB clip would sit
+    // entirely in browser memory before the save dialog appeared. Point the
+    // download straight at the URL and let the browser stream it.
+    triggerSave(itemUrl, filename);
+    return;
+  }
+
+  // Photos go through a blob so the object URL can carry the chosen filename.
+  const response = await fetch(itemUrl);
+  if (!response.ok) {
+    throw new Error("Failed to fetch image");
+  }
+  const url = URL.createObjectURL(await response.blob());
+  triggerSave(url, filename);
+  URL.revokeObjectURL(url);
+}
+
+/** Synthesise the anchor a save needs, click it, and clean up. */
+export function triggerSave(href, filename) {
+  const a = document.createElement("a");
+  a.href = href;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+}
diff --git a/photomap/frontend/templates/modules/control-panel.html b/photomap/frontend/templates/modules/control-panel.html
index 3170511f..a37ea691 100644
--- a/photomap/frontend/templates/modules/control-panel.html
+++ b/photomap/frontend/templates/modules/control-panel.html
@@ -74,6 +74,29 @@
       <div class="button-label">Delete</div>
     </div>
     {% endif %}
+    <!-- Deliberately outside the album_locked guard above: a lock protects the
+         album's files from being changed, and saving a copy changes nothing.
+         Sits next to Delete because it is the same shape of action — both act
+         on whatever slide is current, in either the swiper or the grid. -->
+    <div class="control-icon-container">
+      <button id="downloadCurrentFileBtn" title="Download image">
+        <svg
+          width="32"
+          height="32"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="#fff"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        >
+          <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+          <polyline points="7 10 12 15 17 10" />
+          <line x1="12" y1="15" x2="12" y2="3" />
+        </svg>
+      </button>
+      <div class="button-label">Download</div>
+    </div>
     <div class="control-icon-container">
       <button id="fullscreenBtn" title="Fullscreen">
         <svg width="32" height="32" viewBox="0 0 24 24" fill="#fff">
diff --git a/tests/backend/test_video_transcode.py b/tests/backend/test_video_transcode.py
index d166df88..df8abe1b 100644
--- a/tests/backend/test_video_transcode.py
+++ b/tests/backend/test_video_transcode.py
@@ -386,7 +386,9 @@ def test_every_plan_front_loads_the_index_and_states_the_container():
     assert args[args.index("-movflags") + 1] == "+faststart"
     # The output is a mkstemp ".tmp" name no muxer would recognize.
     assert args[args.index("-f") + 1] == "mp4"
-    assert args[-1] == "/out/clip.tmp"
+    # Compared through Path, not as a literal: ffmpeg_args stringifies the
+    # path, and str(Path("/out/clip.tmp")) is "\\out\\clip.tmp" on Windows.
+    assert args[-1] == str(Path("/out/clip.tmp"))
     assert "-progress" in args and args[args.index("-progress") + 1] == "pipe:1"
 
 
@@ -616,13 +618,29 @@ def spy():
     assert calls == []
 
 
+def _filesystem_is_case_sensitive(directory: Path) -> bool:
+    probe = directory / "CaseProbe.tmp"
+    probe.write_bytes(b"")
+    try:
+        return not (directory / "caseprobe.tmp").exists()
+    finally:
+        probe.unlink()
+
+
 def test_names_differing_only_in_case_get_different_conversions(tmp_path):
     """On a case-sensitive filesystem these are two different movies.
 
     The frame cache casefolds its key, so with matching mtimes — routine for
     anything unpacked from one archive — both would map to one entry. For a
     still that is the wrong thumbnail; here it would play the wrong film.
+
+    Skipped where the filesystem is case-insensitive (Windows, and macOS by
+    default): there the two names *are* one file, so sharing a cache entry is
+    the correct answer rather than the bug.
     """
+    if not _filesystem_is_case_sensitive(tmp_path):
+        pytest.skip("filesystem is case-insensitive; the two names are one file")
+
     cache = TranscodeCache("album", root=tmp_path)
     lower = tmp_path / "clip.mp4"
     upper = tmp_path / "Clip.mp4"
diff --git a/tests/frontend/README.md b/tests/frontend/README.md
index 1d3cc67f..eade04ea 100644
--- a/tests/frontend/README.md
+++ b/tests/frontend/README.md
@@ -26,6 +26,7 @@ npm test
 The following JavaScript modules are covered by unit tests:
 
 ### utils.js (33 tests)
+
 - `showSpinner()` - Shows the loading spinner
 - `hideSpinner()` - Hides the loading spinner
 - `joinPath()` - Joins directory paths correctly
@@ -35,15 +36,18 @@ The following JavaScript modules are covered by unit tests:
 - `setCheckmarkOnIcon()` - Adds/removes checkmark overlays on icons
 
 ### search.js
+
 - `setSearchResults()` - Sets search results and dispatches events
 
 ### slideshow.js (23 tests)
+
 - `slideShowRunning()` - Checks if slideshow autoplay is active
 - `updateSlideshowButtonIcon()` - Updates play/pause button icons
 - `showPlayPauseIndicator()` - Shows fullscreen play/pause indicator
 - `removeExistingIndicator()` - Removes existing indicators
 
 ### score-display.js (26 tests)
+
 - `ScoreDisplay` class
   - `show()` - Displays score with formatting
   - `showIndex()` - Displays slide index
@@ -52,6 +56,7 @@ The following JavaScript modules are covered by unit tests:
   - `update()` - Updates displayed score
 
 ### weight-slider.js (28 tests)
+
 - `WeightSlider` class
   - Constructor and initialization
   - `render()` - Renders slider UI
@@ -83,6 +88,7 @@ The following modules are not yet covered by tests and represent areas for futur
 ## CI Integration
 
 JavaScript tests run automatically on pull requests via GitHub Actions when changes are made to:
+
 - `photomap/frontend/static/javascript/**`
 - `tests/frontend/**`
 - `package.json`
@@ -97,18 +103,22 @@ When adding new tests:
 1. Create a test file in `tests/frontend/` with the naming convention `<module-name>.test.js`
 2. Import Jest globals and the module under test:
    ```javascript
-   import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals';
-   import { functionToTest } from '../../photomap/frontend/static/javascript/module.js';
+   import { jest, describe, it, expect, beforeEach, afterEach } from "@jest/globals";
+   import { functionToTest } from "../../photomap/frontend/static/javascript/module.js";
    ```
 3. If the module has dependencies with DOM side effects (like album-manager.js), use `jest.unstable_mockModule()` to mock them before importing:
    ```javascript
-   jest.unstable_mockModule('../../photomap/frontend/static/javascript/album-manager.js', () => ({
-     albumManager: { fetchAvailableAlbums: jest.fn(() => Promise.resolve([])) }
+   jest.unstable_mockModule("../../photomap/frontend/static/javascript/album-manager.js", () => ({
+     albumManager: { fetchAvailableAlbums: jest.fn(() => Promise.resolve([])) },
    }));
-   const { functionToTest } = await import('../../photomap/frontend/static/javascript/module.js');
+   const { functionToTest } = await import("../../photomap/frontend/static/javascript/module.js");
    ```
 4. Use fake timers for testing debounce, setTimeout, and animation-related code:
    ```javascript
-   beforeEach(() => { jest.useFakeTimers(); });
-   afterEach(() => { jest.useRealTimers(); });
+   beforeEach(() => {
+     jest.useFakeTimers();
+   });
+   afterEach(() => {
+     jest.useRealTimers();
+   });
    ```
diff --git a/tests/frontend/download-current.test.js b/tests/frontend/download-current.test.js
new file mode 100644
index 00000000..999ce996
--- /dev/null
+++ b/tests/frontend/download-current.test.js
@@ -0,0 +1,195 @@
+// The control panel's Download button, and the shared single-item download.
+//
+// The load-bearing case is video: a photo is fetched into a blob so the object
+// URL can carry a chosen filename, but a 200 MB clip buffered the same way
+// sits entirely in browser memory before the save dialog appears. And a video
+// must always be saved as the ORIGINAL file, never a converted copy.
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const mockFetchJson = jest.fn();
+const mockGetCurrentSlideIndex = jest.fn();
+
+jest.unstable_mockModule("../../photomap/frontend/static/javascript/utils.js", () => ({
+  errorDetail: (e) => e?.message ?? String(e),
+  fetchJson: mockFetchJson,
+  hideSpinner: jest.fn(),
+  setCheckmarkOnIcon: jest.fn(),
+  showSpinner: jest.fn(),
+}));
+jest.unstable_mockModule("../../photomap/frontend/static/javascript/state.js", () => ({
+  state: { album: "my album", swiper: null, single_swiper: null },
+  saveSettingsToLocalStorage: jest.fn(),
+}));
+jest.unstable_mockModule("../../photomap/frontend/static/javascript/index.js", () => ({
+  deleteImage: jest.fn(),
+  getIndexMetadata: jest.fn(),
+}));
+jest.unstable_mockModule("../../photomap/frontend/static/javascript/slide-state.js", () => ({
+  getCurrentFilepath: jest.fn(),
+  getCurrentSlideIndex: mockGetCurrentSlideIndex,
+  slideState: { getCurrentSlide: () => ({ globalIndex: 0 }) },
+}));
+
+const { downloadItem } = await import("../../photomap/frontend/static/javascript/download.js");
+const { initializeControlPanel } = await import("../../photomap/frontend/static/javascript/control-panel.js");
+
+/** Capture the <a> the download path synthesises, and swallow its click. */
+function captureAnchors() {
+  const anchors = [];
+  const realCreate = document.createElement.bind(document);
+  jest.spyOn(document, "createElement").mockImplementation((tag) => {
+    const el = realCreate(tag);
+    if (tag === "a") {
+      el.click = jest.fn();
+      anchors.push(el);
+    }
+    return el;
+  });
+  return anchors;
+}
+
+const VIDEO = {
+  media_type: "video",
+  filename: "holiday.avi",
+  filepath: "/photos/holiday.avi",
+  video_url: "videos/my%20album/holiday.avi",
+  image_url: "video_frame/my%20album/7",
+};
+
+beforeEach(() => {
+  jest.restoreAllMocks();
+  jest.clearAllMocks();
+  global.fetch = jest.fn(() => Promise.resolve({ ok: true, blob: () => Promise.resolve(new Blob(["x"])) }));
+  global.URL.createObjectURL = jest.fn(() => "blob:fake");
+  global.URL.revokeObjectURL = jest.fn();
+  global.alert = jest.fn();
+});
+
+describe("downloadItem", () => {
+  it("saves a video as the original file, never a converted copy", async () => {
+    // The conversion exists so the browser can decode the container; it is a
+    // lossy re-encode and it is not what is in the user's library.
+    mockFetchJson.mockResolvedValue(VIDEO);
+    const anchors = captureAnchors();
+
+    await downloadItem(7);
+
+    expect(anchors).toHaveLength(1);
+    expect(anchors[0].getAttribute("href")).toBe("videos/my%20album/holiday.avi");
+    expect(anchors[0].download).toBe("holiday.avi");
+    expect(anchors[0].getAttribute("href")).not.toContain("transcoded");
+  });
+
+  it("streams a video rather than buffering it into memory", async () => {
+    mockFetchJson.mockResolvedValue(VIDEO);
+    captureAnchors();
+
+    await downloadItem(7);
+
+    expect(global.fetch).not.toHaveBeenCalled();
+    expect(global.URL.createObjectURL).not.toHaveBeenCalled();
+  });
+
+  it("falls back to the real extension when the filename is missing", async () => {
+    mockFetchJson.mockResolvedValue({ ...VIDEO, filename: undefined });
+    const anchors = captureAnchors();
+
+    await downloadItem(7);
+
+    expect(anchors[0].download).toBe("image_7.avi");
+  });
+
+  it("still blob-downloads a photo, so the object URL can carry a name", async () => {
+    mockFetchJson.mockResolvedValue({
+      media_type: "image",
+      filename: "beach.jpg",
+      filepath: "/photos/beach.jpg",
+      image_url: "images/my%20album/beach.jpg",
+    });
+    const anchors = captureAnchors();
+
+    await downloadItem(3);
+
+    expect(global.fetch).toHaveBeenCalledWith("images/my%20album/beach.jpg");
+    expect(anchors[0].getAttribute("href")).toBe("blob:fake");
+    expect(anchors[0].download).toBe("beach.jpg");
+    expect(global.URL.revokeObjectURL).toHaveBeenCalledWith("blob:fake");
+  });
+
+  it("raises when the image cannot be fetched", async () => {
+    mockFetchJson.mockResolvedValue({ media_type: "image", image_url: "images/x", filename: "x.jpg" });
+    global.fetch = jest.fn(() => Promise.resolve({ ok: false, status: 404 }));
+
+    await expect(downloadItem(1)).rejects.toThrow(/Failed to fetch/);
+  });
+});
+
+describe("the shipped control panel markup", () => {
+  // The fixture below passing proves nothing about the real page if the id is
+  // renamed on one side only — the button would then silently do nothing.
+  const TEMPLATE = readFileSync(
+    fileURLToPath(new URL("../../photomap/frontend/templates/modules/control-panel.html", import.meta.url)),
+    "utf8"
+  );
+
+  it("provides #downloadCurrentFileBtn", () => {
+    expect(TEMPLATE).toContain('id="downloadCurrentFileBtn"');
+  });
+
+  it("keeps the button outside the album_locked guard", () => {
+    // A lock protects the album's files from being changed; saving a copy
+    // changes nothing, so a locked album must still be downloadable.
+    const guarded = TEMPLATE.slice(TEMPLATE.indexOf("{% if not album_locked %}"), TEMPLATE.indexOf("{% endif %}"));
+    expect(guarded).toContain('id="deleteCurrentFileBtn"');
+    expect(guarded).not.toContain('id="downloadCurrentFileBtn"');
+  });
+});
+
+describe("the control panel's Download button", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <div id="controlPanel">
+        <button id="downloadCurrentFileBtn"></button>
+        <button id="deleteCurrentFileBtn"></button>
+      </div>
+      <div id="searchPanel"></div>
+      <div id="fixedScoreDisplay"></div>`;
+    initializeControlPanel();
+  });
+
+  it("downloads whatever slide is current, in either view", async () => {
+    // getCurrentSlideIndex is view-agnostic, which is what lets one button
+    // serve both the swiper and the grid.
+    mockGetCurrentSlideIndex.mockReturnValue([7]);
+    mockFetchJson.mockResolvedValue(VIDEO);
+    const anchors = captureAnchors();
+
+    document.getElementById("downloadCurrentFileBtn").click();
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(mockFetchJson).toHaveBeenCalledWith("retrieve_image/my%20album/7");
+    expect(anchors[0].getAttribute("href")).toBe("videos/my%20album/holiday.avi");
+  });
+
+  it("says so rather than throwing when nothing is selected", async () => {
+    mockGetCurrentSlideIndex.mockReturnValue([-1]);
+
+    document.getElementById("downloadCurrentFileBtn").click();
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(global.alert).toHaveBeenCalledWith(expect.stringMatching(/no image selected/i));
+    expect(mockFetchJson).not.toHaveBeenCalled();
+  });
+
+  it("reports a failure instead of leaving the spinner up", async () => {
+    mockGetCurrentSlideIndex.mockReturnValue([7]);
+    mockFetchJson.mockRejectedValue(new Error("server exploded"));
+
+    document.getElementById("downloadCurrentFileBtn").click();
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(global.alert).toHaveBeenCalledWith(expect.stringMatching(/server exploded/));
+  });
+});
diff --git a/tests/frontend/fullscreen-panels.test.js b/tests/frontend/fullscreen-panels.test.js
index e7cb7d1c..46da0661 100644
--- a/tests/frontend/fullscreen-panels.test.js
+++ b/tests/frontend/fullscreen-panels.test.js
@@ -23,6 +23,8 @@ jest.unstable_mockModule("../../photomap/frontend/static/javascript/slide-state.
 }));
 jest.unstable_mockModule("../../photomap/frontend/static/javascript/utils.js", () => ({
   errorDetail: jest.fn(),
+  // control-panel.js reaches this through download.js.
+  fetchJson: jest.fn(),
   hideSpinner: jest.fn(),
   showSpinner: jest.fn(),
   setCheckmarkOnIcon: jest.fn(),
diff --git a/tests/frontend/panel-anchor.test.js b/tests/frontend/panel-anchor.test.js
index d31c84f2..dd93b49b 100644
--- a/tests/frontend/panel-anchor.test.js
+++ b/tests/frontend/panel-anchor.test.js
@@ -362,6 +362,8 @@ describe("the seam with fullscreen handling", () => {
     }));
     jest.unstable_mockModule("../../photomap/frontend/static/javascript/utils.js", () => ({
       errorDetail: jest.fn(),
+      // control-panel.js reaches this through download.js.
+      fetchJson: jest.fn(),
       hideSpinner: jest.fn(),
       showSpinner: jest.fn(),
       setCheckmarkOnIcon: jest.fn(),
diff --git a/tests/frontend/video-player-integration.test.js b/tests/frontend/video-player-integration.test.js
index 3c8a01c2..53e2cd66 100644
--- a/tests/frontend/video-player-integration.test.js
+++ b/tests/frontend/video-player-integration.test.js
@@ -28,6 +28,8 @@ jest.unstable_mockModule("../../photomap/frontend/static/javascript/slide-state.
 }));
 jest.unstable_mockModule("../../photomap/frontend/static/javascript/utils.js", () => ({
   errorDetail: jest.fn(),
+  // control-panel.js reaches this through download.js.
+  fetchJson: jest.fn(),
   hideSpinner: jest.fn(),
   showSpinner: jest.fn(),
   setCheckmarkOnIcon: jest.fn(),