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/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..24408d8a 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, forget_album
 
 
 class UmapEpsSetRequest(BaseModel):
@@ -248,16 +249,41 @@ 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.
     """
+    # 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:
-        VideoFrameCache(album_key).clear()
+        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 clear video frame cache for '{album_key}': {e}")
+        logger.warning(f"Could not cancel conversions 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/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/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..ea21e479 100644
--- a/photomap/backend/video.py
+++ b/photomap/backend/video.py
@@ -437,3 +437,134 @@ 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
+    #: 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:
+    """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.
+
+    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
+    )
+    if result is None or isinstance(result, _FfmpegUnavailable):
+        return 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 = (
+                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 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;
+            # 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..620e4f12
--- /dev/null
+++ b/photomap/backend/video_transcode.py
@@ -0,0 +1,1009 @@
+"""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 atexit
+import hashlib
+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 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
+
+# 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
+# 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
+    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 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 = (
+        (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.
+            #
+            # 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=trunc(iw*sar/2)*2:trunc(ih/2)*2,setsar=1",
+        ]
+
+    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:
+        """``<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.
+
+        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)
+        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)."""
+        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 :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
+    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
+        if now - stat.st_mtime <= EVICTION_GRACE_SECONDS:
+            continue
+        entries.append((stat.st_mtime, stat.st_size, path))
+
+    if total <= budget:
+        return removed
+
+    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
+    #: 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] = {}
+_jobs_lock = threading.Lock()
+_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.
+
+    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 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:
+            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:
+    """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)
+    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.
+        try:
+            os.utime(target, None)
+        except OSError:
+            pass
+        return TranscodeStatus(state="ready", progress=1.0)
+
+    scoped = _scoped_key(album_key, key)
+    with _jobs_lock:
+        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:
+    """True when nothing is waiting for this job any more."""
+    if _shutting_down.is_set():
+        return True
+    with _jobs_lock:
+        job = _jobs.get(scoped)
+        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:
+    with _jobs_lock:
+        _jobs.pop(scoped, None)
+
+
+def _job_timeout(duration: float | None) -> float:
+    """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:
+    """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
+
+        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 "
+            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}"
+
+    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)
+    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):
+                # Covers the polling clock, an explicit cancel, and shutdown.
+                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
+
+    # 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)
+        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 *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")
+    except OSError:
+        return None
+    lines = [line.strip() for line in text.splitlines() if line.strip()]
+    if not lines:
+        return None
+    return lines[0][:_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-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/css/video-player.css b/photomap/frontend/static/css/video-player.css
index 40202d61..e6bd5d6d 100644
--- a/photomap/frontend/static/css/video-player.css
+++ b/photomap/frontend/static/css/video-player.css
@@ -1,60 +1,208 @@
 /* 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.
+
+   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;
+  align-items: center;
+  justify-content: center;
+  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;
+  /* 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. */
+  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 +222,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/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/static/javascript/video-badge.js b/photomap/frontend/static/javascript/video-badge.js
index 6362fe22..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);
@@ -190,6 +188,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..40657442 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,133 @@ 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;
+
+// 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"));
 }
 
+/** 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);
+  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.
+    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 +173,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 +193,134 @@ 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);
+    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;
+  }
+
+  if (mySession !== session) {
+    return;
+  }
+  pollFailures = 0;
+
+  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 || "");
+    focusPlayer();
+    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;
+  pollFailures = 0;
+
   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
@@ -104,15 +329,18 @@ export function openVideoPlayer({ url, filename, playable = true } = {}) {
   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) {
-    // 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 +349,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 +356,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 +386,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 +413,28 @@ 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;
+    }
+
+    // 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);
   });
 
   // A playing video must not be left behind by navigation: the modal would
@@ -206,8 +456,24 @@ 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;
+  // 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/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/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..df8abe1b
--- /dev/null
+++ b/tests/backend/test_video_transcode.py
@@ -0,0 +1,965 @@
+"""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
+
+
+# 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"))
+    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_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
+    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=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():
+    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"
+    # 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"
+
+
+# --------------------------------------------------------------------------
+# 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 == []
+
+
+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"
+    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
+# --------------------------------------------------------------------------
+
+
+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/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-badge.test.js b/tests/frontend/video-badge.test.js
index 39e731d8..c0d0b704 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 },
 };
 
@@ -107,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", () => {
@@ -216,12 +221,17 @@ 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);
   });
 
-  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,
@@ -301,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");
   });
diff --git a/tests/frontend/video-player-integration.test.js b/tests/frontend/video-player-integration.test.js
index f538bc84..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(),
@@ -85,6 +87,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..554094e2 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,105 @@ 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("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"));
 
     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 +423,226 @@ 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("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.
+    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.");
+  });
+
+  /** 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);
+  });
+
+  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();
+    await exhaustPolls();
+
+    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);
   });
 });