fix(media): check the trailing keyframe gap before trusting go-media; robust mtime test

- gomediaKeyframes now also treats the stretch from the last go-media
  keyframe to the end of the media as a gap. The planner ends the final
  segment at the media end, so a partial index (for example Matroska Cues
  that stop early) could force a full video transcode without ffprobe
  being asked. When that trailing gap is past the copy cap in pre-flight,
  ffprobe now decides. The duration and start time come from the stream
  info the engine already has, normalized the same way as the planner.
- mediacache: the 1 ns mtime case is tested through FromFileInfo with a
  stub FileInfo; the on-disk Stat check uses a 1 s mtime step, so the
  test passes on filesystems with coarse timestamps.

CHANGELOG.md

@@ -12,6 +12,11 @@ All notable changes to this project will be documented in this file. For commit
     - Transcoding for media playback with quality presets -- requires ffmpeg.
     - Hardware Acceleration device selector (Software / detected GPU devices)
     - More operations use native api operations rather than ffmpeg, improving performance in many cases. Added temporary config option to force ffmpeg to be used
+      - HLS keyframe indexes for MP4/MOV/M4V/MKV/WebM are read from the container index with go-media instead of demuxing every packet with ffprobe; ffprobe still runs when go-media cannot read the file or reports a keyframe gap that would rule out stream copy.
+      - HEIC/AVIF rotation (irot) for the ffmpeg decode fallback is read with go-media instead of a full `ffmpeg -f null` decode.
+      - AVIF images get previews through the HEIC preview path (go-media decode, ffmpeg fallback) when HEIC previews are enabled.
+      - WMV/ASF video thumbnails use go-media for WMV3; WMV1/WMV2 still use ffmpeg.
+      - ffmpeg and go-media share one media metadata cache keyed by path, size and modification time, so a probe, duration or subtitle result from either backend is reused by the other.
   - Document enhancements
     - Official Collabora support using WOPI config.
     - Document previews use a pure-go in-process package (all versions get it now).

_docker/Dockerfile.media

@@ -1,20 +1,11 @@
 # syntax=docker/dockerfile:1.4
-# GPU-capable media image: Debian 13 Trixie GPU FFmpeg as runtime base
-# (x86_64 only). Track G in gtsteffaniak/ffmpeg (docker/dockerfile.gpu,
-# ARG DEBIAN_VERSION=trixie): mostly-static codecs + dynamic
-# VA/Vulkan/OpenCL/NVIDIA userspace. Pi 4 (V4L2) stays on the static
-# Alpine image (`Dockerfile`, not this file).
-# NOTE: the golang:bookworm stage below is build-time only — the Go
-# binary is built with CGO_ENABLED=0 (static), so it runs unchanged
-# on the Trixie runtime. No structural change needed for the Trixie
-# retarget of the FFmpeg GPU image (PR gtsteffaniak/ffmpeg#49).
+# GPU-capable media image: mostly-static glibc FFmpeg + dynamic VA/Vulkan/OpenCL drivers (amd64).
+# Codecs/TLS are linked into gtstef/ffmpeg:<ver> (full track, not *-static).
 #
-# Build after the ffmpeg GPU image is published and smoke-tested:
-#   docker build -f _docker/Dockerfile.media --build-arg VERSION=... --build-arg REVISION=... .
-# Runtime flags: Intel/AMD need /dev/dri (see _docker/docker-compose.media.yaml);
-# NVIDIA needs the host toolkit (`--gpus all` / `runtime: nvidia`).
-
-ARG FFMPEG_GPU_IMAGE=gtstef/ffmpeg:9.0.2-gpu
+# amd64: libva/Mesa/Vulkan/OpenCL userspace below; NVIDIA libs come from the host toolkit.
+# arm64 (e.g. Raspberry Pi): h264_v4l2m2m uses kernel V4L2 only — no extra GPU .debs; pass
+#   /dev/video10 or /dev/video11 (and group video). Pi 5 VAAPI via /dev/dri is optional (mesa on arm64).
+FROM gtstef/ffmpeg:9.0.2 AS ffmpeg
 
 FROM golang:bookworm AS base
 ARG VERSION
@@ -38,14 +29,36 @@ COPY ./frontend/ ./frontend/
 WORKDIR /build/frontend
 RUN npm run build:docker
 
-FROM ${FFMPEG_GPU_IMAGE} AS runtime
+FROM debian:bookworm-slim AS runtime
 ENV DEBIAN_FRONTEND=noninteractive
-ENV FILEBROWSER_FFMPEG_PATH="/usr/local/bin"
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  ca-certificates \
+  curl \
+  mailcap \
+  tzdata \
+  && rm -rf /var/lib/apt/lists/* \
+  && (dpkg --print-architecture | grep -q amd64 \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends \
+      libva2 \
+      libva-drm2 \
+      libdrm2 \
+      libvulkan1 \
+      mesa-va-drivers \
+      mesa-vulkan-drivers \
+      ocl-icd-libopencl1 \
+      intel-media-va-driver \
+      libmfx1 \
+    && rm -rf /var/lib/apt/lists/* \
+    || true)
+COPY --from=ffmpeg [ "/ffmpeg", "/ffprobe", "/usr/local/bin/" ]
+ENV FILEBROWSER_FFMPEG_PATH="/usr/local/bin/"
 ENV FILEBROWSER_DATABASE_PATH="/home/filebrowser/data/database.sqlite"
 ENV FILEBROWSER_CONFIG="/home/filebrowser/data/config.yaml"
 ENV PATH="$PATH:/home/filebrowser"
 ENV NVIDIA_VISIBLE_DEVICES=all
-ENV NVIDIA_DRIVER_CAPABILITIES=compute,utility,video,graphics
+ENV NVIDIA_DRIVER_CAPABILITIES=compute,video,utility,graphics
 
 RUN useradd -m -u 1000 -s /usr/sbin/nologin filebrowser
 USER filebrowser

_docker/Dockerfile.media.README.md

@@ -1,38 +0,0 @@
-# Filebrowser media image (GPU)
-
-`Dockerfile.media` builds a media image on top of the Debian 13 Trixie GPU
-FFmpeg image (`gtstef/ffmpeg:<version>-gpu`, Track G in
-`gtsteffaniak/ffmpeg`, `ARG DEBIAN_VERSION=trixie`). The
-production Pi 4 setup stays on the static Alpine `Dockerfile` (V4L2).
-
-## Prereq (sequencing)
-
-The media image is built only **after** the FFmpeg GPU image is published
-(`gtstef/ffmpeg:<version>-gpu`) and smoke-tested. The `FFMPEG_GPU_IMAGE`
-build-arg pins the exact published tag; if the tag is not smoke-tested, do
-not merge the media PR.
-
-## Build
-
-```bash
-docker build -f _docker/Dockerfile.media \
-  --build-arg FFMPEG_GPU_IMAGE=gtstef/ffmpeg:9.0.2-gpu \
-  --build-arg VERSION=latest --build-arg REVISION=$(git rev-parse HEAD) \
-  -t filebrowser-media:latest .
-```
-
-## Smoke
-
-```bash
-docker run --rm filebrowser-media:latest ffmpeg -hwaccels | grep -E "vaapi|cuda|vulkan|opencl"
-docker run --rm --device=/dev/dri/renderD128 filebrowser-media:latest \
-  -vaapi_device /dev/dri/renderD128 -f lavfi -i testsrc=size=640x480:rate=1 \
-  -c:v h264_vaapi -t 1 -f null -
-docker run --rm --gpus all filebrowser-media:latest \
-  -f lavfi -i testsrc=size=640x480:rate=1 -c:v h264_nvenc -t 1 -f null -
-```
-
-## Compose
-
-See `docker-compose.media.yaml` (intel/AMD and NVIDIA snippets; Pi stays
-static).

_docker/docker-compose.media.yaml

@@ -1,67 +0,0 @@
-# Compose snippets for the GPU media image (`_docker/Dockerfile.media`).
-#
-# filebrowser-media runs on the Debian GPU FFmpeg image
-# (gtstef/ffmpeg:<version>-gpu). Pi 4 production stays on the static
-# Alpine `Dockerfile` (V4L2). Copy the service you need into your
-# docker-compose.yaml.
-#
-#   docker compose -f _docker/docker-compose.media.yaml run --rm filebrowser-media \
-#     -f lavfi -i testsrc=size=640x480:rate=1 -c:v h264_vulkan -t 1 -f null -
-#   (replace service flags with your image name)
-
-services:
-  # Intel / AMD VAAPI (needs host /dev/dri)
-  # Find render group GID: getent group render
-  filebrowser-media-intel:
-    image: filebrowser-media:latest
-    build:
-      context: ../
-      dockerfile: ./_docker/Dockerfile.media
-      args:
-        VERSION: ${VERSION:-latest}
-        REVISION: ${REVISION:-local}
-        FFMPEG_GPU_IMAGE: ${FFMPEG_GPU_IMAGE:-gtstef/ffmpeg:9.0.2-gpu}
-    devices:
-      - /dev/dri:/dev/dri
-    group_add:
-      - "993" # render group GID placeholder — set to `getent group render`
-    environment:
-      # fallback when /dev/dri is not bind-mounted: LIBVA_DRIVER_NAME=radeonsi
-      LIBVA_DRIVER_NAME: ${LIBVA_DRIVER_NAME:-}
-    ports:
-      - "80:80"
-
-  # NVIDIA NVENC/NVDEC (needs NVIDIA driver + nvidia-container-toolkit on host)
-  # `runtime: nvidia` or `deploy.resources.reservations.devices` + NVIDIA_* env.
-  filebrowser-media-nvidia:
-    image: filebrowser-media:latest
-    build:
-      context: ../
-      dockerfile: ./_docker/Dockerfile.media
-      args:
-        VERSION: ${VERSION:-latest}
-        REVISION: ${REVISION:-local}
-        FFMPEG_GPU_IMAGE: ${FFMPEG_GPU_IMAGE:-gtstef/ffmpeg:9.0.2-gpu}
-    deploy:
-      resources:
-        reservations:
-          devices:
-            - driver: nvidia
-              count: 1
-              capabilities: [gpu]
-    environment:
-      NVIDIA_VISIBLE_DEVICES: all
-      NVIDIA_DRIVER_CAPABILITIES: compute,utility,video,graphics
-      # runtime: nvidia  (legacy alternative to deploy above)
-    ports:
-      - "80:80"
-
-  # Pi 4 V4L2 — NOT the GPU image. Production Pi stays on the static Alpine
-  # Dockerfile (h264_v4l2m2m via kernel V4L2, /dev/video10 or /dev/video11):
-  filebrowser-pi-static:
-    image: filebrowser-static:latest # placeholder for the existing Alpine build
-    devices:
-      - /dev/video10:/dev/video10
-      - /dev/video11:/dev/video11
-    ports:
-      - "80:80"

backend/internal/adapters/fs/files/files.go

@@ -17,6 +17,7 @@ import (
 	"github.com/gtsteffaniak/filebrowser/backend/internal/errors"
 	"github.com/gtsteffaniak/filebrowser/backend/internal/ffmpeg"
 	"github.com/gtsteffaniak/filebrowser/backend/internal/gomedia"
+	"github.com/gtsteffaniak/filebrowser/backend/internal/mediacache"
 	"github.com/gtsteffaniak/filebrowser/backend/internal/utils"
 	"github.com/gtsteffaniak/filebrowser/backend/pkg/indexing"
 	"github.com/gtsteffaniak/filebrowser/backend/pkg/indexing/iteminfo"
@@ -393,7 +394,8 @@ func processContent(info *iteminfo.ExtendedFileInfo, idx *indexing.Index, opts u
 			info.GetSubtitles(parentInfo)
 		}
 		subtitles, ok := gomedia.EmbeddedSubtitles(info.RealPath, info.ModTime, func() ([]utils.SubtitleTrack, bool) {
-			return ffmpeg.DetectEmbeddedSubtitles(info.RealPath, info.ModTime), true
+			// Shadow run: bypass the shared cache so ffprobe is compared fresh.
+			return ffmpeg.DetectEmbeddedSubtitlesContext(mediacache.WithoutCache(context.Background()), info.RealPath), true
 		})
 		if !ok {
 			subtitles = ffmpeg.DetectEmbeddedSubtitles(info.RealPath, info.ModTime)
@@ -541,8 +543,9 @@ func audioDuration(ctx context.Context, item *iteminfo.ExtendedItemInfo, realPat
 	if service == nil {
 		service = ffmpeg.Get()
 	}
-	// The shadow run can outlive the request, so it uses a context that is not cancelled with it.
-	shadowCtx := context.WithoutCancel(ctx)
+	// The shadow run can outlive the request, so it uses a context that is not
+	// cancelled with it. It bypasses the shared cache so ffmpeg is compared fresh.
+	shadowCtx := mediacache.WithoutCache(context.WithoutCancel(ctx))
 	legacy := func() (float64, bool) {
 		d, err := service.GetMediaDuration(shadowCtx, realPath)
 		return d, err == nil
@@ -713,8 +716,9 @@ func extractVideoMetadata(ctx context.Context, item *iteminfo.ExtendedItemInfo,
 	if probeService == nil {
 		probeService = ffmpeg.Get()
 	}
-	// The shadow run can outlive the request, so it uses a context that is not cancelled with it.
-	shadowCtx := context.WithoutCancel(ctx)
+	// The shadow run can outlive the request, so it uses a context that is not
+	// cancelled with it. It bypasses the shared cache so ffprobe is compared fresh.
+	shadowCtx := mediacache.WithoutCache(context.WithoutCancel(ctx))
 	legacyProbe := func() (gomedia.ProbeResult, bool) {
 		info, err := probeService.ProbeFile(shadowCtx, realPath)
 		if err != nil || info == nil {

backend/internal/ffmpeg/cache.go

@@ -1,14 +0,0 @@
-package ffmpeg
-
-import (
-	"time"
-
-	"github.com/gtsteffaniak/filebrowser/backend/internal/utils"
-	"github.com/gtsteffaniak/go-cache/cache"
-)
-
-var (
-	MediaCache           = cache.NewCache[[]utils.SubtitleTrack](24 * time.Hour) // subtitle track lists from ffprobe
-	SubtitleContentCache = cache.NewCache[string](24 * time.Hour)                // extracted embedded subtitle content
-	MetadataCache        = cache.NewCache[float64](24 * time.Hour)               // media duration from ffprobe
-)

backend/internal/ffmpeg/heic_orientation.go

@@ -9,13 +9,51 @@ import (
 	"os/exec"
 	"strconv"
 	"strings"
+	"sync/atomic"
 
 	"github.com/kovidgoyal/imaging"
 )
 
+// HEICDisplayRotationReader reads the display rotation that a HEIC/HEIF/AVIF
+// file's item properties (irot) ask for, without decoding it. The rotation is
+// in degrees counter-clockwise, normalized to (-180, 180], which is the value
+// ffmpeg prints as "Display Matrix: rotation of ..." for the same file. ok is
+// false when the reader could not tell; the ffmpeg probe is used instead.
+type HEICDisplayRotationReader func(path string) (rotation float64, ok bool)
+
+// heicDisplayRotationReader is the header reader set by
+// SetHEICDisplayRotationReader, or nil.
+var heicDisplayRotationReader atomic.Pointer[HEICDisplayRotationReader]
+
+// SetHEICDisplayRotationReader installs the reader HEICDisplayRotation tries
+// before running ffmpeg. The gomedia package installs go-media's reader when it
+// is loaded; it cannot be called from here directly because gomedia imports
+// this package. Passing nil removes the reader.
+func SetHEICDisplayRotationReader(fn HEICDisplayRotationReader) {
+	if fn == nil {
+		heicDisplayRotationReader.Store(nil)
+		return
+	}
+	heicDisplayRotationReader.Store(&fn)
+}
+
+// HEICDisplayRotation returns the display rotation of heicPath and whether it is
+// known. The installed header reader (go-media) answers first; the
+// "ffmpeg -f null" stderr probe runs only when no reader is installed or the
+// reader could not read the file.
+func (s *Service) HEICDisplayRotation(ctx context.Context, heicPath string) (float64, bool) {
+	if p := heicDisplayRotationReader.Load(); p != nil {
+		if rotation, ok := (*p)(heicPath); ok {
+			return rotation, true
+		}
+	}
+	return s.GetHEICDisplayMatrixRotation(ctx, heicPath)
+}
+
 // GetHEICDisplayMatrixRotation returns the largest rotation (degrees) ffmpeg reports for a
 // HEIC display matrix. The second return value is false when the probe could not run or
 // parse stderr — callers must not treat that as “no rotation was applied”.
+// HEICDisplayRotation is preferred; it only runs this probe as a fallback.
 func (s *Service) GetHEICDisplayMatrixRotation(ctx context.Context, heicPath string) (float64, bool) {
 	if s == nil {
 		return 0, false
@@ -36,6 +74,8 @@ func (s *Service) GetHEICDisplayMatrixRotation(ctx context.Context, heicPath str
 	return rotation, ok
 }
 
+// parseDisplayMatrixRotation returns the largest-magnitude "Display Matrix"
+// rotation in ffmpeg stderr, and whether any was found.
 func parseDisplayMatrixRotation(stderr string) (float64, bool) {
 	var best float64
 	var found bool
@@ -65,6 +105,7 @@ func parseDisplayMatrixRotation(stderr string) (float64, bool) {
 	return best, found
 }
 
+// isNormalOrientation reports whether an EXIF orientation needs no change.
 func isNormalOrientation(orientation string) bool {
 	switch orientation {
 	case "", "Horizontal (normal)", "Top-left", "1":
@@ -74,6 +115,8 @@ func isNormalOrientation(orientation string) bool {
 	}
 }
 
+// isPureRotationOrientation reports whether an EXIF orientation is a rotation
+// without a mirror.
 func isPureRotationOrientation(orientation string) bool {
 	switch orientation {
 	case "Rotate 90 CW", "Right-top", "6",
@@ -100,6 +143,8 @@ func orientationNeedsPostCorrection(orientation string, displayRotation float64,
 	return true
 }
 
+// applyOrientationToJPEG rotates or flips JPEG bytes for an EXIF orientation.
+// The input is returned unchanged when it cannot be decoded or re-encoded.
 func applyOrientationToJPEG(jpegBytes []byte, orientation string) []byte {
 	if len(jpegBytes) < 100 || isNormalOrientation(orientation) {
 		return jpegBytes

backend/internal/ffmpeg/heic_orientation_test.go

@@ -50,3 +50,35 @@ func TestOrientationNeedsPostCorrection(t *testing.T) {
 		}
 	}
 }
+
+func TestHEICDisplayRotationPrefersReader(t *testing.T) {
+	prev := heicDisplayRotationReader.Load()
+	t.Cleanup(func() { heicDisplayRotationReader.Store(prev) })
+
+	var calls int
+	SetHEICDisplayRotationReader(func(path string) (float64, bool) {
+		calls++
+		if path == "known.heic" {
+			return -90, true
+		}
+		return 0, false
+	})
+	var svc *Service // nil: the ffmpeg probe cannot run
+	got, ok := svc.HEICDisplayRotation(t.Context(), "known.heic")
+	if !ok || got != -90 {
+		t.Fatalf("HEICDisplayRotation(known) = %v, %v; want -90, true", got, ok)
+	}
+	// The reader cannot tell: the ffmpeg probe runs, and with no service it
+	// reports unknown rather than "no rotation".
+	if _, ok := svc.HEICDisplayRotation(t.Context(), "other.heic"); ok {
+		t.Fatal("HEICDisplayRotation(other) ok = true, want the ffmpeg probe's false")
+	}
+	if calls != 2 {
+		t.Fatalf("reader calls = %d, want 2", calls)
+	}
+
+	SetHEICDisplayRotationReader(nil)
+	if _, ok := svc.HEICDisplayRotation(t.Context(), "known.heic"); ok {
+		t.Fatal("with no reader, HEICDisplayRotation must use the ffmpeg probe")
+	}
+}

backend/internal/ffmpeg/image.go

@@ -81,14 +81,16 @@ func (s *Service) ConvertHEICToJPEG(ctx context.Context, heicPath string, target
 	return s.CorrectHEICJPEGOrientation(ctx, heicPath, jpegBytes), nil
 }
 
-// CorrectHEICJPEGOrientation applies irot / display-matrix correction after a full-resolution
-// HEIC decode when pixels are still in coded orientation (go-media and ffmpeg filter-free paths).
+// CorrectHEICJPEGOrientation applies EXIF orientation after a filter-free ffmpeg HEIC decode
+// when the pixels are still in coded orientation. The display rotation (irot) comes from
+// HEICDisplayRotation: go-media reads it from the item properties, and the ffmpeg stderr probe
+// is only a fallback.
 func (s *Service) CorrectHEICJPEGOrientation(ctx context.Context, heicPath string, jpegBytes []byte) []byte {
 	orientation, err := s.GetHEICOrientation(heicPath)
 	if err != nil {
 		orientation = "Horizontal (normal)"
 	}
-	displayRotation, displayKnown := s.GetHEICDisplayMatrixRotation(ctx, heicPath)
+	displayRotation, displayKnown := s.HEICDisplayRotation(ctx, heicPath)
 	if orientationNeedsPostCorrection(orientation, displayRotation, displayKnown) {
 		return applyOrientationToJPEG(jpegBytes, orientation)
 	}

backend/internal/ffmpeg/mediacache_integration_test.go

@@ -0,0 +1,115 @@
+package ffmpeg
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sync"
+	"testing"
+
+	"github.com/gtsteffaniak/filebrowser/backend/internal/mediacache"
+)
+
+const cacheFixtureMP4 = "../../../frontend/tests/playwright-files/myfolder/testdata/sample-640x480.mp4"
+
+var (
+	testServiceOnce sync.Once
+	testServiceErr  error
+)
+
+// initTestService starts the ffmpeg service once, without hardware probes, or
+// skips.
+func initTestService(t *testing.T) *Service {
+	t.Helper()
+	if testing.Short() {
+		t.Skip("starts ffmpeg")
+	}
+	if _, err := exec.LookPath("ffmpeg"); err != nil {
+		t.Skip("ffmpeg not installed")
+	}
+	if _, err := exec.LookPath("ffprobe"); err != nil {
+		t.Skip("ffprobe not installed")
+	}
+	testServiceOnce.Do(func() {
+		testServiceErr = Initialize(context.Background(), InitOptions{SkipHWTests: true, CacheDir: os.TempDir()})
+	})
+	if testServiceErr != nil {
+		t.Skipf("ffmpeg init failed: %v", testServiceErr)
+	}
+	svc := Get()
+	if svc == nil {
+		t.Skip("ffmpeg service unavailable")
+	}
+	return svc
+}
+
+// copyFixture copies the MP4 fixture so the test owns its cache key.
+func copyFixture(t *testing.T) (string, mediacache.Key) {
+	t.Helper()
+	data, err := os.ReadFile(cacheFixtureMP4)
+	if err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(t.TempDir(), "sample.mp4")
+	if err = os.WriteFile(path, data, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	key, err := mediacache.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		mediacache.Probes.Delete(key.String())
+		mediacache.Durations.Delete(key.String())
+	})
+	return path, key
+}
+
+// TestProbeFileUsesSharedCache checks that ffprobe results go into the shared
+// cache, cached values are reused, and WithoutCache bypasses both.
+func TestProbeFileUsesSharedCache(t *testing.T) {
+	svc := initTestService(t)
+	path, key := copyFixture(t)
+
+	got, err := svc.ProbeFile(context.Background(), path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	cached, ok := mediacache.Probes.Get(key.String())
+	if !ok || cached != *got {
+		t.Fatalf("ProbeFile must store its result in the shared cache: cached=%+v ok=%v got=%+v", cached, ok, *got)
+	}
+
+	sentinel := FileProbeInfo{Duration: 1, VideoCodec: "sentinel"}
+	mediacache.Probes.Set(key.String(), sentinel)
+	got, err = svc.ProbeFile(context.Background(), path)
+	if err != nil || *got != sentinel {
+		t.Fatalf("ProbeFile must reuse a cached value (e.g. from go-media): got=%+v err=%v", got, err)
+	}
+
+	fresh, err := svc.ProbeFile(mediacache.WithoutCache(context.Background()), path)
+	if err != nil || *fresh == sentinel {
+		t.Fatalf("WithoutCache must probe fresh: got=%+v err=%v", fresh, err)
+	}
+	if cached, _ := mediacache.Probes.Get(key.String()); cached != sentinel {
+		t.Fatal("WithoutCache must not overwrite the shared cache")
+	}
+}
+
+// TestGetMediaDurationUsesSharedCache checks that cached durations are reused
+// and WithoutCache probes fresh.
+func TestGetMediaDurationUsesSharedCache(t *testing.T) {
+	svc := initTestService(t)
+	path, key := copyFixture(t)
+
+	mediacache.Durations.Set(key.String(), 4242)
+	d, err := svc.GetMediaDuration(context.Background(), path)
+	if err != nil || d != 4242 {
+		t.Fatalf("GetMediaDuration must reuse a cached value: d=%v err=%v", d, err)
+	}
+	d, err = svc.GetMediaDuration(mediacache.WithoutCache(context.Background()), path)
+	if err != nil || d == 4242 || d <= 0 {
+		t.Fatalf("WithoutCache must probe fresh: d=%v err=%v", d, err)
+	}
+}

backend/internal/ffmpeg/metadata.go

@@ -8,6 +8,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/gtsteffaniak/filebrowser/backend/internal/mediacache"
 	goffmpeg "github.com/gtsteffaniak/go-ffmpeg"
 )
 
@@ -49,24 +50,29 @@ func resolveLocalMediaPath(mediaPath string) (string, os.FileInfo, error) {
 	return clean, info, nil
 }
 
-// FileProbeInfo holds ffprobe results for a local media file.
-type FileProbeInfo struct {
-	Duration   float64
-	VideoCodec string
-	AudioCodec string
-	FormatName string
-}
+// FileProbeInfo holds probe results for a local media file. It is the shared
+// cache type, so go-media and ffprobe results are interchangeable.
+type FileProbeInfo = mediacache.ProbeInfo
 
-// ProbeFile extracts duration and codec info from a media file.
+// ProbeFile extracts duration and codec info from a media file. Results are
+// stored in the shared media cache, which the go-media probe also reads, unless
+// ctx is mediacache.WithoutCache.
 func (s *Service) ProbeFile(ctx context.Context, mediaPath string) (*FileProbeInfo, error) {
 	if s == nil || s.inner == nil {
 		return nil, fmt.Errorf("ffmpeg service not available")
 	}
 
-	localPath, _, err := resolveLocalMediaPath(mediaPath)
+	localPath, fileInfo, err := resolveLocalMediaPath(mediaPath)
 	if err != nil {
 		return nil, err
 	}
+	useCache := !mediacache.Bypassed(ctx)
+	cacheKey := mediacache.FromFileInfo(localPath, fileInfo).String()
+	if useCache {
+		if cached, ok := mediacache.Probes.Get(cacheKey); ok {
+			return &cached, nil
+		}
+	}
 
 	info, err := s.inner.ProbeStream(ctx, goffmpeg.ProbeStreamOptions{
 		URL:        localPath,
@@ -77,15 +83,20 @@ func (s *Service) ProbeFile(ctx context.Context, mediaPath string) (*FileProbeIn
 		return nil, err
 	}
 
-	return &FileProbeInfo{
+	res := FileProbeInfo{
 		Duration:   info.Duration,
 		VideoCodec: info.VideoCodec,
 		AudioCodec: info.AudioCodec,
 		FormatName: info.FormatName,
-	}, nil
+	}
+	if useCache {
+		mediacache.Probes.Set(cacheKey, res)
+	}
+	return &res, nil
 }
 
-// GetMediaDuration extracts the duration of a media file in seconds.
+// GetMediaDuration extracts the duration of a media file in seconds. Results
+// are stored in the shared media cache unless ctx is mediacache.WithoutCache.
 func (s *Service) GetMediaDuration(ctx context.Context, mediaPath string) (float64, error) {
 	if s == nil || s.inner == nil {
 		return 0, fmt.Errorf("ffmpeg service not available")
@@ -95,9 +106,12 @@ func (s *Service) GetMediaDuration(ctx context.Context, mediaPath string) (float
 	if err != nil {
 		return 0, err
 	}
-	cacheKey := fmt.Sprintf("%s:%d", localPath, fileInfo.ModTime().Unix())
-	if duration, found := MetadataCache.Get(cacheKey); found {
-		return duration, nil
+	useCache := !mediacache.Bypassed(ctx)
+	cacheKey := mediacache.FromFileInfo(localPath, fileInfo).String()
+	if useCache {
+		if duration, found := mediacache.Durations.Get(cacheKey); found {
+			return duration, nil
+		}
 	}
 
 	duration, err := s.inner.GetMediaDuration(ctx, localPath)
@@ -105,6 +119,8 @@ func (s *Service) GetMediaDuration(ctx context.Context, mediaPath string) (float
 		return 0, err
 	}
 
-	MetadataCache.Set(cacheKey, duration)
+	if useCache {
+		mediacache.Durations.Set(cacheKey, duration)
+	}
 	return duration, nil
 }

backend/internal/ffmpeg/service.go

@@ -9,6 +9,7 @@ import (
 	"sync"
 	"sync/atomic"
 
+	"github.com/gtsteffaniak/filebrowser/backend/internal/mediacache"
 	goffmpeg "github.com/gtsteffaniak/go-ffmpeg"
 	"github.com/gtsteffaniak/go-ffmpeg/capabilities"
 	"github.com/gtsteffaniak/go-ffmpeg/ops"
@@ -460,7 +461,8 @@ func (s *Service) VideoPreview(ctx context.Context, w io.Writer, opts ops.Previe
 	return s.inner.CaptureFrame(ctx, w, frame)
 }
 
-// ExtractSubtitle returns embedded subtitle content as WebVTT.
+// ExtractSubtitle returns embedded subtitle content as WebVTT. Results are
+// stored in the shared media cache unless ctx is mediacache.WithoutCache.
 func (s *Service) ExtractSubtitle(ctx context.Context, videoPath string, streamIndex int) (string, error) {
 	if s == nil || s.inner == nil {
 		return "", fmt.Errorf("ffmpeg service not available")
@@ -470,9 +472,12 @@ func (s *Service) ExtractSubtitle(ctx context.Context, videoPath string, streamI
 	if err != nil {
 		return "", fmt.Errorf("failed to stat file: %w", err)
 	}
-	cacheKey := fmt.Sprintf("subtitle_content:%s:%d:%d", videoPath, streamIndex, fileInfo.ModTime().Unix())
-	if content, ok := SubtitleContentCache.Get(cacheKey); ok {
-		return content, nil
+	useCache := !mediacache.Bypassed(ctx)
+	cacheKey := mediacache.FromFileInfo(videoPath, fileInfo).Stream(streamIndex)
+	if useCache {
+		if content, ok := mediacache.SubtitleContent.Get(cacheKey); ok {
+			return content, nil
+		}
 	}
 
 	content, err := s.inner.ExtractSubtitle(ctx, videoPath, streamIndex)
@@ -480,7 +485,9 @@ func (s *Service) ExtractSubtitle(ctx context.Context, videoPath string, streamI
 		return "", err
 	}
 
-	SubtitleContentCache.Set(cacheKey, content)
+	if useCache {
+		mediacache.SubtitleContent.Set(cacheKey, content)
+	}
 	return content, nil
 }
 

backend/internal/ffmpeg/subtitles.go

@@ -7,16 +7,30 @@ import (
 	"strings"
 	"time"
 
+	"github.com/gtsteffaniak/filebrowser/backend/internal/mediacache"
 	"github.com/gtsteffaniak/filebrowser/backend/internal/utils"
 	goffmpeg "github.com/gtsteffaniak/go-ffmpeg"
 	"github.com/gtsteffaniak/go-logger/logger"
 )
 
-// DetectEmbeddedSubtitles detects embedded subtitle streams.
+// DetectEmbeddedSubtitles detects embedded subtitle streams. Results are stored
+// in the shared media cache, keyed by the file's current size and modification
+// time; modtime is kept for API compatibility and is not used for the key.
 func DetectEmbeddedSubtitles(videoPath string, modtime time.Time) []utils.SubtitleTrack {
-	key := "embedded_subtitles:" + videoPath + ":" + modtime.Format(time.RFC3339)
-	if cached, ok := MediaCache.Get(key); ok {
-		return cached
+	_ = modtime
+	return DetectEmbeddedSubtitlesContext(context.Background(), videoPath)
+}
+
+// DetectEmbeddedSubtitlesContext is DetectEmbeddedSubtitles with a context. The
+// shared media cache is skipped when ctx is mediacache.WithoutCache.
+func DetectEmbeddedSubtitlesContext(ctx context.Context, videoPath string) []utils.SubtitleTrack {
+	useCache := !mediacache.Bypassed(ctx)
+	key, statErr := mediacache.Stat(videoPath)
+	useCache = useCache && statErr == nil
+	if useCache {
+		if cached, ok := mediacache.SubtitleTracks.Get(key.String()); ok {
+			return cached
+		}
 	}
 
 	svc := Get()
@@ -24,14 +38,16 @@ func DetectEmbeddedSubtitles(videoPath string, modtime time.Time) []utils.Subtit
 		return nil
 	}
 
-	tracks, err := svc.inner.DetectSubtitles(context.Background(), videoPath)
+	tracks, err := svc.inner.DetectSubtitles(ctx, videoPath)
 	if err != nil {
 		logger.Debug("ffprobe failed for file: " + videoPath + ", error: " + err.Error())
 		return nil
 	}
 
 	subtitles := mapSubtitleTracks(tracks)
-	MediaCache.Set(key, subtitles)
+	if useCache {
+		mediacache.SubtitleTracks.Set(key.String(), subtitles)
+	}
 	return subtitles
 }
 

backend/internal/gomedia/containers_test.go

@@ -0,0 +1,73 @@
+package gomedia
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+const fixtureWMV2 = fixtureDir + "/file_example_WMV_480_1_2MB.wmv"
+
+// TestContainerGates pins which extensions go-media handles for probes and
+// for thumbnails.
+func TestContainerGates(t *testing.T) {
+	cases := []struct {
+		name             string
+		probe, thumbnail bool
+	}{
+		{"a.mp4", true, true},
+		{"a.M4V", true, true},
+		{"a.mov", true, true},
+		{"a.mkv", true, true},
+		{"a.webm", true, true},
+		{"a.wmv", false, true},
+		{"a.ASF", false, true},
+		{"a.avi", false, false},
+		{"a.ts", false, false},
+		{"a.m2ts", false, false},
+		{"a.mts", false, false},
+		{"a.mpg", false, false},
+		{"a.mpeg", false, false},
+		{"a.vob", false, false},
+		{"a.flv", false, false},
+	}
+	for _, c := range cases {
+		require.Equal(t, c.probe, supportsVideoContainer(c.name), "probe gate for %s", c.name)
+		require.Equal(t, c.thumbnail, supportsVideoThumbnail(c.name), "thumbnail gate for %s", c.name)
+	}
+	for _, name := range []string{"a.heic", "a.HEIF", "a.heics", "a.avif"} {
+		require.True(t, supportsHEIFImage(name), name)
+	}
+	require.False(t, supportsHEIFImage("a.jpg"))
+}
+
+// TestWMV2FallsBackToFFmpeg checks that a WMV2 file is not probed by go-media
+// and that its thumbnail falls back to ffmpeg (go-media has no WMV1/WMV2
+// decoder).
+func TestWMV2FallsBackToFFmpeg(t *testing.T) {
+	withGate(t, false)
+	_, ok := Probe(fixtureWMV2, nil)
+	require.False(t, ok, "WMV probes stay on ffprobe")
+	_, ok = VideoThumbnail(fixtureWMV2, 320, 240, 80, 10, nil)
+	require.False(t, ok, "WMV2 thumbnails must fall back to ffmpeg")
+}
+
+// TestWMV1FallsBackToFFmpeg is TestWMV2FallsBackToFFmpeg for a WMV1 stream
+// encoded on the fly.
+func TestWMV1FallsBackToFFmpeg(t *testing.T) {
+	withGate(t, false)
+	requireTool(t, "ffmpeg")
+	path := filepath.Join(t.TempDir(), "wmv1.wmv")
+	out, err := exec.Command("ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i", "testsrc2=size=160x120:rate=25:duration=2",
+		"-c:v", "wmv1", path).CombinedOutput()
+	if err != nil {
+		t.Skipf("ffmpeg cannot encode wmv1: %v: %s", err, out)
+	}
+	_, err = os.Stat(path)
+	require.NoError(t, err)
+	_, ok := VideoThumbnail(path, 160, 120, 80, 10, nil)
+	require.False(t, ok, "WMV1 thumbnails must fall back to ffmpeg")
+}

backend/internal/gomedia/gomedia.go

@@ -20,28 +20,30 @@ import (
 	"time"
 
 	"github.com/gtsteffaniak/filebrowser/backend/internal/ffmpeg"
+	"github.com/gtsteffaniak/filebrowser/backend/internal/mediacache"
 	"github.com/gtsteffaniak/filebrowser/backend/internal/utils"
 	"github.com/gtsteffaniak/filebrowser/backend/pkg/settings"
-	"github.com/gtsteffaniak/go-cache/cache"
 	"github.com/gtsteffaniak/go-logger/logger"
 	"github.com/gtsteffaniak/go-media/pkg/media"
 	"golang.org/x/sync/singleflight"
 )
 
-var (
-	subtitleListCache    = cache.NewCache[[]utils.SubtitleTrack](24 * time.Hour)
-	subtitleContentCache = cache.NewCache[string](24 * time.Hour)
+// Probe, duration, and subtitle results are cached in the mediacache package,
+// which the ffmpeg code path shares. A directory listing probes every video
+// child, and the preview flow probes the focused file again; the cache keeps
+// each request from re-reading the same containers. Keys include size and
+// modification time, so an edited file is read again.
 
-	// probeCache caches successful probe results by file identity (path, modtime,
-	// size). A directory listing probes every video child, and the preview flow
-	// probes the focused file again; without this each request re-read the same
-	// containers. Keying on modtime+size means an edited file is re-probed.
-	probeCache = cache.NewCache[ProbeResult](24 * time.Hour)
+// probeGroup coalesces concurrent probes of the same file so a burst of
+// requests for one container reads it once.
+var probeGroup singleflight.Group
 
-	// probeGroup coalesces concurrent probes of the same file so a burst of
-	// requests for one container reads it once.
-	probeGroup singleflight.Group
-)
+func init() {
+	// The ffmpeg HEIC decode path corrects orientation after decoding and needs
+	// the file's irot. internal/ffmpeg cannot import this package, so go-media's
+	// header reader is installed here.
+	ffmpeg.SetHEICDisplayRotationReader(HEICDisplayRotation)
+}
 
 // Enabled reports whether the go-media fast path may run. The admin
 // "Always use ffmpeg" setting turns it off.
@@ -60,9 +62,15 @@ func videoDimensions(info *media.ProbeInfo) (w, h int, ok bool) {
 }
 
 // videoContainerExts are the containers go-media parses for video probes,
-// thumbnails, and embedded subtitles. Other video containers (AVI, WMV, TS, ...)
-// are not go-media targets, so they go straight to ffmpeg with no file open and
-// no log line. go-media reads MOV as MP4.
+// thumbnails, embedded subtitles, and keyframe indexes. go-media reads MOV as
+// MP4.
+//
+// go-media also demuxes AVI, ASF/WMV, MPEG-TS/M2TS, and MPEG-PS (VOB), but their
+// probes are left to ffmpeg on purpose: go-media's results for those containers
+// do not yet match ffprobe (TS/M2TS and PS list no audio streams, PS durations
+// are missing or wrong, AVI misnames MPEG-4 Part 2 and AAC, ASF reports WMA Pro
+// as wmav2). Those files go straight to ffmpeg with no file open and no log
+// line. See videoThumbnailExts for the thumbnail exception.
 var videoContainerExts = map[string]bool{
 	".mp4":  true,
 	".m4v":  true,
@@ -71,11 +79,31 @@ var videoContainerExts = map[string]bool{
 	".webm": true,
 }
 
+// videoThumbnailExts are the containers go-media decodes video thumbnails from:
+// videoContainerExts plus ASF/WMV, whose WMV3 keyframes go-media decodes
+// bit-exact with ffmpeg. WMV1, WMV2, MS-MPEG4, and WVC1 Advanced Profile return
+// an unsupported error and fall back to ffmpeg. AVI, TS/M2TS, and PS stay on
+// ffmpeg: go-media's TS and PS thumbnails scan the whole file for the duration
+// (several times slower than ffmpeg on large files), and AVI seeks by a
+// duration that can be wrong.
+var videoThumbnailExts = map[string]bool{
+	".mp4":  true,
+	".m4v":  true,
+	".mov":  true,
+	".mkv":  true,
+	".webm": true,
+	".wmv":  true,
+	".asf":  true,
+}
+
 // heifImageExts are still-image containers go-media decodes for HEIC preview.
+// AVIF is a HEIF container with an AV1 image item; go-media decodes it in pure
+// Go and applies its irot/imir, like HEIC.
 var heifImageExts = map[string]bool{
 	".heic":  true,
 	".heif":  true,
 	".heics": true,
+	".avif":  true,
 }
 
 const heicDecodeMaxEdge = 16384
@@ -93,15 +121,27 @@ var cameraRawExts = map[string]bool{
 	".dc2": true, ".x3f": true, ".iiq": true, ".nkc": true, ".r3d": true,
 }
 
-// supportsVideoContainer reports whether go-media targets path's container.
+// supportsVideoContainer reports whether go-media targets path's container for
+// probes, embedded subtitles, and keyframe indexes.
 func supportsVideoContainer(path string) bool {
 	return videoContainerExts[strings.ToLower(filepath.Ext(path))]
 }
 
+// supportsVideoThumbnail reports whether go-media targets path's container for
+// video thumbnails.
+func supportsVideoThumbnail(path string) bool {
+	return videoThumbnailExts[strings.ToLower(filepath.Ext(path))]
+}
+
+// supportsHEIFImage reports whether path is a HEIF-family still image
+// (HEIC/HEIF/AVIF) go-media decodes.
+
 func supportsHEIFImage(path string) bool {
 	return heifImageExts[strings.ToLower(filepath.Ext(path))]
 }
 
+// supportsCameraRAW reports whether path is a camera RAW format go-media
+// extracts a preview from.
 func supportsCameraRAW(path string) bool {
 	return cameraRawExts[strings.ToLower(filepath.Ext(path))]
 }
@@ -133,16 +173,26 @@ func logUnsupported(op, path, reason string) {
 
 // openFile opens path for go-media, which reads through io.ReaderAt.
 func openFile(path string) (*os.File, int64, error) {
-	f, err := os.Open(path)
+	f, info, err := openFileInfo(path)
 	if err != nil {
 		return nil, 0, err
 	}
+	return f, info.Size(), nil
+}
+
+// openFileInfo opens path and returns its FileInfo, which also gives the
+// shared cache key.
+func openFileInfo(path string) (*os.File, os.FileInfo, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, nil, err
+	}
 	info, err := f.Stat()
 	if err != nil {
 		_ = f.Close()
-		return nil, 0, err
+		return nil, nil, err
 	}
-	return f, info.Size(), nil
+	return f, info, nil
 }
 
 // ffprobeFormatNames maps go-media containers to the format_name strings ffprobe
@@ -179,30 +229,25 @@ func probeFast(path string) (ProbeResult, bool) {
 		return ProbeResult{}, false
 	}
 
-	f, size, err := openFile(path)
+	f, info, err := openFileInfo(path)
 	if err != nil {
 		logFallback("probe", path, err)
 		return ProbeResult{}, false
 	}
 	defer f.Close()
 
-	info, err := f.Stat()
-	if err != nil {
-		logFallback("probe", path, err)
-		return ProbeResult{}, false
-	}
-	cacheKey := probeCacheKey(path, info.ModTime().UnixNano(), size)
-	if res, ok := probeCache.Get(cacheKey); ok {
+	cacheKey := mediacache.FromFileInfo(path, info).String()
+	if res, ok := mediacache.Probes.Get(cacheKey); ok {
 		return res, true
 	}
 
 	// Coalesce concurrent probes of the same file into one container read.
 	v, err, _ := probeGroup.Do(cacheKey, func() (any, error) {
-		res, ok := parseProbe(path, f, size)
+		res, ok := parseProbe(path, f, info.Size())
 		if !ok {
 			return nil, errProbeUnsupported
 		}
-		probeCache.Set(cacheKey, res)
+		mediacache.Probes.Set(cacheKey, res)
 		return res, nil
 	})
 	if err != nil {
@@ -219,12 +264,6 @@ func probeFast(path string) (ProbeResult, bool) {
 // no detail because parseProbe already logged the specific reason.
 var errProbeUnsupported = errors.New("probe unsupported")
 
-// probeCacheKey identifies a file version for caching: path plus modtime and size.
-// An edited file gets a new key, so stale metadata is never served.
-func probeCacheKey(path string, modTimeNanos, size int64) string {
-	return fmt.Sprintf("probe:%s:%d:%d", path, modTimeNanos, size)
-}
-
 // parseProbe reads a container and builds a ProbeResult. It reports false when
 // go-media should defer to ffmpeg, having logged why.
 func parseProbe(path string, f *os.File, size int64) (ProbeResult, bool) {
@@ -280,14 +319,18 @@ func durationFast(path string) (float64, bool) {
 	if !Enabled() {
 		return 0, false
 	}
-	f, size, err := openFile(path)
+	f, info, err := openFileInfo(path)
 	if err != nil {
 		logFallback("duration", path, err)
 		return 0, false
 	}
 	defer f.Close()
 
-	res, err := media.Duration(f, size)
+	cacheKey := mediacache.FromFileInfo(path, info).String()
+	if d, ok := mediacache.Durations.Get(cacheKey); ok {
+		return d, true
+	}
+	res, err := media.Duration(f, info.Size())
 	if err != nil {
 		logFallback("duration", path, err)
 		return 0, false
@@ -296,7 +339,9 @@ func durationFast(path string) (float64, bool) {
 		// Unknown duration is not an error; ffmpeg may still find one.
 		return 0, false
 	}
-	return res.Duration.Seconds(), true
+	d := res.Duration.Seconds()
+	mediacache.Durations.Set(cacheKey, d)
+	return d, true
 }
 
 // AudioInfo is the tag, lyrics availability, and cover art FileBrowser reads
@@ -384,7 +429,9 @@ func lyricsFast(path string) (text, format string, ok bool) {
 
 // EmbeddedSubtitles lists embedded subtitle tracks. go-media supports MKV, WebM,
 // and MP4 only. Other containers are reported as unsupported, not as "no
-// subtitles", because go-media returns an empty list for them.
+// subtitles", because go-media returns an empty list for them. modtime is kept
+// for API compatibility; the cache key comes from the file's current size and
+// modification time.
 // legacy is the ffmpeg subtitle detection, run only in shadow mode.
 func EmbeddedSubtitles(path string, modtime time.Time, legacy Legacy[[]utils.SubtitleTrack]) ([]utils.SubtitleTrack, bool) {
 	return timed("subtitle list", path, legacy, subtitleListDiff, func() ([]utils.SubtitleTrack, bool) {
@@ -399,19 +446,20 @@ func embeddedSubtitlesFast(path string, modtime time.Time) ([]utils.SubtitleTrac
 	if !supportsVideoContainer(path) {
 		return nil, false
 	}
-	key := fmt.Sprintf("embedded_subtitles:%s:%d", path, modtime.Unix())
-	if cached, ok := subtitleListCache.Get(key); ok {
-		return cached, true
-	}
-
-	f, size, err := openFile(path)
+	_ = modtime
+	f, st, err := openFileInfo(path)
 	if err != nil {
 		logFallback("subtitle list", path, err)
 		return nil, false
 	}
 	defer f.Close()
 
-	info, err := media.Probe(f, size)
+	key := mediacache.FromFileInfo(path, st).String()
+	if cached, ok := mediacache.SubtitleTracks.Get(key); ok {
+		return cached, true
+	}
+
+	info, err := media.Probe(f, st.Size())
 	if err != nil {
 		logFallback("subtitle list", path, err)
 		return nil, false
@@ -433,7 +481,7 @@ func embeddedSubtitlesFast(path string, modtime time.Time) ([]utils.SubtitleTrac
 		})
 	}
 	tracks := ffmpeg.BuildSubtitleTracks(streams)
-	subtitleListCache.Set(key, tracks)
+	mediacache.SubtitleTracks.Set(key, tracks)
 	return tracks, true
 }
 
@@ -453,24 +501,19 @@ func extractSubtitleFast(path string, streamIndex int) (string, bool) {
 	if !supportsVideoContainer(path) {
 		return "", false
 	}
-	st, err := os.Stat(path)
-	if err != nil {
-		logFallback("subtitle extract", path, err)
-		return "", false
-	}
-	key := fmt.Sprintf("subtitle_content:%s:%d:%d", path, streamIndex, st.ModTime().Unix())
-	if content, ok := subtitleContentCache.Get(key); ok {
-		return content, true
-	}
-
-	f, size, err := openFile(path)
+	f, st, err := openFileInfo(path)
 	if err != nil {
 		logFallback("subtitle extract", path, err)
 		return "", false
 	}
 	defer f.Close()
 
-	vtt, err := media.ExtractEmbeddedSubtitle(f, size, streamIndex)
+	key := mediacache.FromFileInfo(path, st).Stream(streamIndex)
+	if content, ok := mediacache.SubtitleContent.Get(key); ok {
+		return content, true
+	}
+
+	vtt, err := media.ExtractEmbeddedSubtitle(f, st.Size(), streamIndex)
 	if err != nil {
 		logFallback("subtitle extract", path, err)
 		return "", false
@@ -479,7 +522,7 @@ func extractSubtitleFast(path string, streamIndex int) (string, bool) {
 		logFallback("subtitle extract", path, errors.New("empty subtitle output"))
 		return "", false
 	}
-	subtitleContentCache.Set(key, vtt)
+	mediacache.SubtitleContent.Set(key, vtt)
 	return vtt, true
 }
 
@@ -501,7 +544,7 @@ func videoThumbnailFast(path string, width, height, quality int, seekPercent flo
 	if !Enabled() {
 		return nil, false
 	}
-	if !supportsVideoContainer(path) {
+	if !supportsVideoThumbnail(path) {
 		return nil, false
 	}
 	f, size, err := openFile(path)

backend/internal/gomedia/gomedia_test.go

@@ -11,6 +11,8 @@ import (
 	"testing"
 	"time"
 
+	"github.com/gtsteffaniak/filebrowser/backend/internal/mediacache"
+	"github.com/gtsteffaniak/filebrowser/backend/internal/utils"
 	"github.com/gtsteffaniak/filebrowser/backend/pkg/settings"
 	"github.com/stretchr/testify/require"
 )
@@ -131,27 +133,78 @@ func TestProbeUsesCache(t *testing.T) {
 	require.NoError(t, err)
 	require.NoError(t, os.WriteFile(path, data, 0o644))
 
-	st, err := os.Stat(path)
+	key, err := mediacache.Stat(path)
 	require.NoError(t, err)
-	key := probeCacheKey(path, st.ModTime().UnixNano(), st.Size())
 	sentinel := ProbeResult{Duration: 123, VideoCodec: "sentinel", AudioCodec: "sentinel", FormatName: "sentinel"}
-	probeCache.Set(key, sentinel)
-	t.Cleanup(func() { probeCache.Delete(key) })
+	// The ffmpeg probe stores into the same shared cache, so this also stands in
+	// for a value ffprobe produced earlier.
+	mediacache.Probes.Set(key.String(), sentinel)
+	t.Cleanup(func() { mediacache.Probes.Delete(key.String()) })
 
 	got, ok := Probe(path, nil)
 	require.True(t, ok)
 	require.Equal(t, sentinel, got, "probe must return the cached value for an unchanged file")
+
+	// An edit (new size and mtime) must miss the cached value.
+	require.NoError(t, os.WriteFile(path, append(data, 0), 0o644))
+	future := time.Now().Add(time.Hour)
+	require.NoError(t, os.Chtimes(path, future, future))
+	got, ok = Probe(path, nil)
+	require.True(t, ok)
+	require.NotEqual(t, sentinel, got, "an edited file must be probed again")
+	edited, err := mediacache.Stat(path)
+	require.NoError(t, err)
+	t.Cleanup(func() { mediacache.Probes.Delete(edited.String()) })
 }
 
-// TestProbeCacheKeyTracksFileIdentity checks that path, modtime, and size all
-// participate in the cache key, so an edited file is never served stale metadata.
-func TestProbeCacheKeyTracksFileIdentity(t *testing.T) {
-	base := probeCacheKey("f.mp4", 100, 200)
-	require.Equal(t, base, probeCacheKey("f.mp4", 100, 200), "identical identity must hash the same")
-	require.NotEqual(t, base, probeCacheKey("f.mp4", 101, 200), "modtime change must change the key")
-	require.NotEqual(t, base, probeCacheKey("f.mp4", 100, 201), "size change must change the key")
-	require.NotEqual(t, base, probeCacheKey("g.mp4", 100, 200), "path change must change the key")
-	require.NotEqual(t, base, probeCacheKey("f.mp4", 100, 201), "key must not collide across fields")
+// TestDurationUsesSharedCache checks that Duration reads and fills the shared
+// cache that ffmpeg's GetMediaDuration also uses.
+func TestDurationUsesSharedCache(t *testing.T) {
+	withGate(t, false)
+	path := filepath.Join(t.TempDir(), "sample.mp4")
+	data, err := os.ReadFile(fixtureMP4)
+	require.NoError(t, err)
+	require.NoError(t, os.WriteFile(path, data, 0o644))
+	key, err := mediacache.Stat(path)
+	require.NoError(t, err)
+	t.Cleanup(func() { mediacache.Durations.Delete(key.String()) })
+
+	d, ok := Duration(path, nil)
+	require.True(t, ok)
+	cached, found := mediacache.Durations.Get(key.String())
+	require.True(t, found, "go-media duration must be stored in the shared cache")
+	require.Equal(t, d, cached)
+
+	mediacache.Durations.Set(key.String(), 4242)
+	d, ok = Duration(path, nil)
+	require.True(t, ok)
+	require.Equal(t, 4242.0, d, "a cached duration (from either backend) must be reused")
+}
+
+// TestSubtitleCachesUseFileIdentity checks the subtitle list cache is keyed by
+// the file's real size and mtime, not by the caller's modtime argument.
+func TestSubtitleCachesUseFileIdentity(t *testing.T) {
+	withGate(t, false)
+	path := filepath.Join(t.TempDir(), "sample.mp4")
+	data, err := os.ReadFile(fixtureMP4)
+	require.NoError(t, err)
+	require.NoError(t, os.WriteFile(path, data, 0o644))
+	key, err := mediacache.Stat(path)
+	require.NoError(t, err)
+	sentinel := []utils.SubtitleTrack{{Name: "sentinel"}}
+	mediacache.SubtitleTracks.Set(key.String(), sentinel)
+	t.Cleanup(func() { mediacache.SubtitleTracks.Delete(key.String()) })
+
+	// The modtime argument is ignored for the key.
+	got, ok := EmbeddedSubtitles(path, time.Unix(1, 0), nil)
+	require.True(t, ok)
+	require.Equal(t, sentinel, got)
+
+	mediacache.SubtitleContent.Set(key.Stream(7), "WEBVTT\n\nsentinel")
+	t.Cleanup(func() { mediacache.SubtitleContent.Delete(key.Stream(7)) })
+	vtt, ok := ExtractSubtitle(path, 7, nil)
+	require.True(t, ok)
+	require.Equal(t, "WEBVTT\n\nsentinel", vtt)
 }
 
 func TestProbeWebMMatchesFFprobe(t *testing.T) {

backend/internal/gomedia/heif_rotation.go

@@ -0,0 +1,101 @@
+package gomedia
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"time"
+
+	"github.com/gtsteffaniak/filebrowser/backend/internal/ffmpeg"
+	"github.com/gtsteffaniak/go-media/pkg/media"
+)
+
+// heicRotationShadowTimeout bounds the dev-mode ffmpeg comparison probe.
+const heicRotationShadowTimeout = time.Minute
+
+// HEICDisplayRotation returns the display rotation that a HEIC/HEIF/AVIF
+// file's irot property asks for, read from the item properties without
+// decoding. The value is degrees counter-clockwise in (-180, 180], the same
+// number ffmpeg prints as "Display Matrix: rotation of ..." for the file. A
+// file with no irot returns 0 and ok=true. ok is false when go-media is
+// disabled or cannot read the item properties; the caller then runs the ffmpeg
+// probe.
+//
+// It is installed as ffmpeg's HEIC display rotation reader. In shadow mode the
+// ffmpeg stderr probe runs for comparison.
+func HEICDisplayRotation(path string) (float64, bool) {
+	return timed("heic rotation", path, heicRotationLegacy(path), heicRotationDiff, func() (float64, bool) {
+		return heicDisplayRotationFast(path)
+	})
+}
+
+// heicRotationLegacy returns the ffmpeg stderr probe for shadow mode, or nil
+// when ffmpeg is not available.
+func heicRotationLegacy(path string) Legacy[float64] {
+	if !ShadowEnabled() {
+		return nil
+	}
+	svc := ffmpeg.Get()
+	if svc == nil {
+		return nil
+	}
+	return func() (float64, bool) {
+		ctx, cancel := context.WithTimeout(context.Background(), heicRotationShadowTimeout)
+		defer cancel()
+		return svc.GetHEICDisplayMatrixRotation(ctx, path)
+	}
+}
+
+// heicDisplayRotationFast reads the primary item's irot with go-media and
+// converts it to ffmpeg's display rotation.
+func heicDisplayRotationFast(path string) (float64, bool) {
+	if !Enabled() {
+		return 0, false
+	}
+	// No extension check: the resolved path can have another name (symlink
+	// target). go-media sniffs the content and reports other files unsupported.
+	f, size, err := openFile(path)
+	if err != nil {
+		logFallback("heic rotation", path, err)
+		return 0, false
+	}
+	defer f.Close()
+
+	t, err := media.HEIFTransform(f, size)
+	if err != nil {
+		logFallback("heic rotation", path, err)
+		return 0, false
+	}
+	return displayRotation(t), true
+}
+
+// displayRotation converts go-media's counter-clockwise irot angle to ffmpeg's
+// display matrix convention: counter-clockwise degrees normalized to
+// (-180, 180]. ffmpeg builds the matrix with av_display_rotation_set(-irot)
+// and prints av_display_rotation_get, so irot 270 is reported as -90. A mirror
+// does not change the rotation value.
+func displayRotation(t media.ImageTransform) float64 {
+	r := ((t.Rotation % 360) + 360) % 360
+	if r > 180 {
+		r -= 360
+	}
+	return float64(r)
+}
+
+// heicRotationDiff compares go-media's display rotation with ffmpeg's. 180 and
+// -180 are the same rotation.
+func heicRotationDiff(fast, legacy float64) []string {
+	norm := func(v float64) float64 {
+		v = math.Mod(v, 360)
+		if v <= -180 {
+			v += 360
+		} else if v > 180 {
+			v -= 360
+		}
+		return v
+	}
+	if math.Abs(norm(fast)-norm(legacy)) > 0.5 {
+		return []string{fmt.Sprintf("display rotation go-media=%.2f ffmpeg=%.2f", fast, legacy)}
+	}
+	return nil
+}

backend/internal/gomedia/heif_rotation_test.go

@@ -0,0 +1,82 @@
+package gomedia
+
+import (
+	"math"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/gtsteffaniak/filebrowser/backend/internal/ffmpeg"
+	"github.com/gtsteffaniak/go-media/pkg/media"
+	"github.com/stretchr/testify/require"
+)
+
+// fixtureAVIFRotated has irot=1 (90° counter-clockwise) and imir axis 0.
+const fixtureAVIFRotated = "testdata/irot1_imir0.avif"
+
+// TestDisplayRotation checks the irot to ffmpeg display rotation mapping.
+func TestDisplayRotation(t *testing.T) {
+	cases := []struct {
+		rotation int
+		want     float64
+	}{
+		{0, 0}, {90, 90}, {180, 180}, {270, -90}, {-90, -90}, {360, 0}, {450, 90},
+	}
+	for _, c := range cases {
+		require.Equal(t, c.want, displayRotation(media.ImageTransform{Rotation: c.rotation}), "rotation %d", c.rotation)
+	}
+	require.Equal(t, 90.0, displayRotation(media.ImageTransform{Rotation: 90, Mirror: true}), "a mirror does not change the rotation")
+}
+
+// TestHEICDisplayRotationReadsIrot checks the rotation read from a fixture
+// with irot=1.
+func TestHEICDisplayRotationReadsIrot(t *testing.T) {
+	withGate(t, false)
+	got, ok := HEICDisplayRotation(fixtureAVIFRotated)
+	require.True(t, ok)
+	require.Equal(t, 90.0, got)
+}
+
+// TestHEICDisplayRotationFallsBack checks that non-HEIF input, broken input,
+// and the Always use ffmpeg setting leave the answer to ffmpeg.
+func TestHEICDisplayRotationFallsBack(t *testing.T) {
+	withGate(t, false)
+	_, ok := HEICDisplayRotation(fixtureMP4)
+	require.False(t, ok, "a non-HEIF file must fall back to the ffmpeg probe")
+
+	junk := filepath.Join(t.TempDir(), "junk.heic")
+	require.NoError(t, os.WriteFile(junk, []byte("not heif"), 0o644))
+	_, ok = HEICDisplayRotation(junk)
+	require.False(t, ok)
+
+	withGate(t, true)
+	_, ok = HEICDisplayRotation(fixtureAVIFRotated)
+	require.False(t, ok, "the Always use ffmpeg setting must skip go-media")
+}
+
+// TestHEICDisplayRotationInstalled checks that loading this package installs
+// go-media as the ffmpeg package's rotation reader.
+func TestHEICDisplayRotationInstalled(t *testing.T) {
+	withGate(t, false)
+	var svc *ffmpeg.Service // nil: the ffmpeg probe cannot run, so a result proves the reader answered
+	got, ok := svc.HEICDisplayRotation(t.Context(), fixtureAVIFRotated)
+	require.True(t, ok)
+	require.Equal(t, 90.0, got)
+}
+
+// TestHEICRotationDiff checks the shadow comparison of display rotations.
+func TestHEICRotationDiff(t *testing.T) {
+	require.Empty(t, heicRotationDiff(-90, -90))
+	require.Empty(t, heicRotationDiff(180, -180))
+	require.Empty(t, heicRotationDiff(0, math.Copysign(0, -1)))
+	require.Len(t, heicRotationDiff(90, -90), 1)
+}
+
+// TestAVIFDecodesThroughHEICPath checks that an AVIF file is accepted by the
+// HEIC decode path.
+func TestAVIFDecodesThroughHEICPath(t *testing.T) {
+	withGate(t, false)
+	data, ok := HEICJPEG(fixtureAVIFRotated, 80, nil)
+	require.True(t, ok)
+	require.NotEmpty(t, data)
+}

backend/internal/gomedia/keyframes.go

@@ -0,0 +1,145 @@
+package gomedia
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"math"
+	"sort"
+
+	"github.com/gtsteffaniak/go-media/pkg/media"
+)
+
+// keyframeTimeDedupeSec matches go-ffmpeg's ffprobe keyframe probe, which
+// drops keyframes within 1 ms of the previous one.
+const keyframeTimeDedupeSec = 0.001
+
+// keyframeShadowTolerance is how far apart two backends' keyframe times can be
+// before the shadow comparison reports them. ffprobe prints six decimals.
+const keyframeShadowTolerance = 0.002
+
+// KeyframeTimes returns the presentation times, in seconds, of the first video
+// stream's keyframes, for HLS segment planning. The result is sorted, has no
+// negative times, and drops keyframes within 1 ms of the previous one, the same
+// as go-ffmpeg's ffprobe probe. go-media reads only the container index (MP4
+// stss/stts/ctts, Matroska Cues or block headers), so it is much faster than
+// demuxing every packet with ffprobe.
+//
+// ok is false when go-media is disabled, the container is not one go-media
+// indexes, or the read fails; the caller then runs ffprobe. ctx cancels the
+// file reads. legacy is the ffprobe probe, run only in shadow mode.
+//
+// go-media can report fewer keyframes than ffprobe (ffprobe's parsers also flag
+// IDR frames the container index omits, and some Matroska muxers index only
+// part of the keyframes in Cues). It never reports a keyframe ffprobe would not.
+func KeyframeTimes(ctx context.Context, path string, legacy Legacy[[]float64]) ([]float64, bool) {
+	return timed("keyframe index", path, legacy, keyframeDiff, func() ([]float64, bool) {
+		return keyframeTimesFast(ctx, path, 0)
+	})
+}
+
+// KeyframeTimesWithin is KeyframeTimes limited to keyframes within windowSec
+// seconds of the first keyframe. It is the pre-flight check that can rule out
+// stream copy without reading the whole index (Matroska files without Cues).
+// It has no shadow comparison.
+func KeyframeTimesWithin(ctx context.Context, path string, windowSec float64) ([]float64, bool) {
+	return timed("keyframe preflight", path, nil, nil, func() ([]float64, bool) {
+		return keyframeTimesFast(ctx, path, windowSec)
+	})
+}
+
+// keyframeTimesFast reads the keyframe index with go-media. windowSec > 0
+// limits it to keyframes within that many seconds of the first one.
+func keyframeTimesFast(ctx context.Context, path string, windowSec float64) ([]float64, bool) {
+	if !Enabled() {
+		return nil, false
+	}
+	if !supportsVideoContainer(path) {
+		return nil, false
+	}
+	if err := ctx.Err(); err != nil {
+		return nil, false
+	}
+	f, size, err := openFile(path)
+	if err != nil {
+		logFallback("keyframe index", path, err)
+		return nil, false
+	}
+	defer f.Close()
+
+	r := ctxReaderAt{ctx: ctx, r: f}
+	var times []float64
+	if windowSec > 0 {
+		times, err = media.KeyframeTimesWithin(r, size, windowSec)
+	} else {
+		times, err = media.KeyframeTimes(r, size)
+	}
+	if err != nil {
+		if ctx.Err() == nil {
+			logFallback("keyframe index", path, err)
+		}
+		return nil, false
+	}
+	times = dedupeKeyframeTimes(times)
+	if len(times) == 0 {
+		logUnsupported("keyframe index", path, "no keyframes in container index")
+		return nil, false
+	}
+	return times, true
+}
+
+// dedupeKeyframeTimes sorts times, drops negative values, and drops times
+// within keyframeTimeDedupeSec of the previous kept time, as go-ffmpeg does for
+// ffprobe output.
+func dedupeKeyframeTimes(times []float64) []float64 {
+	sorted := append([]float64(nil), times...)
+	sort.Float64s(sorted)
+	out := make([]float64, 0, len(sorted))
+	for _, t := range sorted {
+		if t < 0 || math.IsNaN(t) || math.IsInf(t, 0) {
+			continue
+		}
+		if len(out) == 0 || t > out[len(out)-1]+keyframeTimeDedupeSec {
+			out = append(out, t)
+		}
+	}
+	return out
+}
+
+// ctxReaderAt fails reads once ctx is done, so a cancelled request or the plan
+// timeout stops a long index walk on a slow share.
+type ctxReaderAt struct {
+	ctx context.Context
+	r   io.ReaderAt
+}
+
+// ReadAt reads from the wrapped reader unless the context is done.
+func (c ctxReaderAt) ReadAt(p []byte, off int64) (int, error) {
+	if err := c.ctx.Err(); err != nil {
+		return 0, err
+	}
+	return c.r.ReadAt(p, off)
+}
+
+// keyframeDiff compares go-media's keyframe index with ffprobe's. go-media
+// reporting a subset of ffprobe's keyframes is expected (parser-flagged IDR
+// frames, partial Cues) and is logged at info level.
+func keyframeDiff(fast, legacy []float64) []string {
+	missing := 0
+	j := 0
+	for _, t := range fast {
+		for j < len(legacy) && legacy[j] < t-keyframeShadowTolerance {
+			j++
+			missing++
+		}
+		if j >= len(legacy) || math.Abs(legacy[j]-t) > keyframeShadowTolerance {
+			return []string{fmt.Sprintf("keyframe at %.6fs from go-media not in ffmpeg index (go-media=%d ffmpeg=%d keyframes)", t, len(fast), len(legacy))}
+		}
+		j++
+	}
+	missing += len(legacy) - j
+	if missing > 0 {
+		return []string{fmt.Sprintf("%sgo-media found %d of %d ffmpeg keyframes (keyframes outside the container index)", expectedDiffPrefix, len(fast), len(legacy))}
+	}
+	return nil
+}

backend/internal/gomedia/keyframes_test.go

@@ -0,0 +1,176 @@
+package gomedia
+
+import (
+	"context"
+	"math"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// ffprobeKeyframes runs the same packet probe as go-ffmpeg's
+// ProbeVideoKeyframeTimes: key packets of v:0, pts_time falling back to
+// dts_time, sorted and de-duplicated within 1 ms.
+func ffprobeKeyframes(t *testing.T, path string) []float64 {
+	t.Helper()
+	requireTool(t, "ffprobe")
+	out, err := exec.Command("ffprobe", "-v", "error", "-select_streams", "v:0",
+		"-show_entries", "packet=pts_time,dts_time,flags", "-of", "csv=p=0", path).Output()
+	require.NoError(t, err)
+	var times []float64
+	for _, line := range strings.Split(strings.TrimSpace(string(out)), "\n") {
+		f := strings.Split(strings.TrimSpace(line), ",")
+		if len(f) < 3 || !strings.Contains(f[2], "K") {
+			continue
+		}
+		v, perr := strconv.ParseFloat(f[0], 64)
+		if perr != nil {
+			v, perr = strconv.ParseFloat(f[1], 64)
+		}
+		if perr == nil {
+			times = append(times, v)
+		}
+	}
+	sort.Float64s(times)
+	return dedupeKeyframeTimes(times)
+}
+
+// encodeKeyframeClip makes a short clip with a fixed GOP. B-frames give MP4
+// files a ctts table and an edit list, the hard case for the timestamp model.
+func encodeKeyframeClip(t *testing.T, name string, args ...string) string {
+	t.Helper()
+	requireTool(t, "ffmpeg")
+	path := filepath.Join(t.TempDir(), name)
+	full := []string{"-v", "error", "-y", "-f", "lavfi", "-i", "testsrc2=size=160x120:rate=25:duration=6"}
+	full = append(full, args...)
+	full = append(full, path)
+	if out, err := exec.Command("ffmpeg", full...).CombinedOutput(); err != nil {
+		t.Skipf("ffmpeg cannot encode %s: %v: %s", name, err, out)
+	}
+	return path
+}
+
+// requireSameKeyframes fails unless got matches want within the shadow
+// tolerance.
+func requireSameKeyframes(t *testing.T, want, got []float64) {
+	t.Helper()
+	require.Equal(t, len(want), len(got), "keyframe count: ffprobe=%v go-media=%v", want, got)
+	for i := range want {
+		require.InDelta(t, want[i], got[i], keyframeShadowTolerance, "keyframe %d: ffprobe=%v go-media=%v", i, want, got)
+	}
+}
+
+// TestKeyframeTimesMatchFFprobe compares go-media keyframe indexes with
+// ffprobe for fixtures and encoded clips, including B-frame MP4/MOV.
+func TestKeyframeTimesMatchFFprobe(t *testing.T) {
+	if testing.Short() {
+		t.Skip("encodes clips with ffmpeg")
+	}
+	withGate(t, false)
+	x264 := []string{"-c:v", "libx264", "-g", "50", "-keyint_min", "50", "-sc_threshold", "0", "-bf", "2", "-pix_fmt", "yuv420p"}
+	cases := map[string]string{
+		"fixture.mp4":  fixtureMP4,
+		"fixture.webm": fixtureWebM,
+		"bframes.mp4":  encodeKeyframeClip(t, "bframes.mp4", x264...),
+		"bframes.mov":  encodeKeyframeClip(t, "bframes.mov", x264...),
+		"bframes.mkv":  encodeKeyframeClip(t, "bframes.mkv", x264...),
+		"mpeg4.m4v":    encodeKeyframeClip(t, "mpeg4.m4v", "-c:v", "mpeg4", "-g", "30", "-f", "mp4"),
+	}
+	for name, path := range cases {
+		t.Run(name, func(t *testing.T) {
+			want := ffprobeKeyframes(t, path)
+			got, ok := KeyframeTimes(context.Background(), path, nil)
+			require.True(t, ok)
+			requireSameKeyframes(t, want, got)
+
+			within, ok := KeyframeTimesWithin(context.Background(), path, 2.5)
+			require.True(t, ok)
+			require.NotEmpty(t, within)
+			require.LessOrEqual(t, len(within), len(got))
+			for i := range within {
+				require.Equal(t, got[i], within[i])
+				require.LessOrEqual(t, within[i]-got[0], 2.5+1e-9)
+			}
+		})
+	}
+}
+
+// TestKeyframeTimesFallsBack checks the cases that must leave the index to
+// ffprobe.
+func TestKeyframeTimesFallsBack(t *testing.T) {
+	withGate(t, false)
+	dir := t.TempDir()
+
+	// Not an indexed container: no file open, ffprobe answers.
+	ts := filepath.Join(dir, "clip.ts")
+	require.NoError(t, os.WriteFile(ts, []byte{0x47}, 0o644))
+	_, ok := KeyframeTimes(context.Background(), ts, nil)
+	require.False(t, ok)
+
+	// Indexed extension but not a real container.
+	junk := filepath.Join(dir, "junk.mp4")
+	require.NoError(t, os.WriteFile(junk, []byte("not a video"), 0o644))
+	_, ok = KeyframeTimes(context.Background(), junk, nil)
+	require.False(t, ok)
+
+	// Missing file.
+	_, ok = KeyframeTimes(context.Background(), filepath.Join(dir, "missing.mp4"), nil)
+	require.False(t, ok)
+
+	// Cancelled context.
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, ok = KeyframeTimes(ctx, fixtureMP4, nil)
+	require.False(t, ok)
+}
+
+// TestKeyframeTimesGate checks that the Always use ffmpeg setting disables
+// the go-media keyframe index.
+func TestKeyframeTimesGate(t *testing.T) {
+	withGate(t, true)
+	_, ok := KeyframeTimes(context.Background(), fixtureMP4, nil)
+	require.False(t, ok, "KeyframeTimes must skip go-media when the gate is on")
+	_, ok = KeyframeTimesWithin(context.Background(), fixtureMP4, 10)
+	require.False(t, ok)
+}
+
+// TestDedupeKeyframeTimes checks sorting, filtering, and the 1 ms dedupe.
+func TestDedupeKeyframeTimes(t *testing.T) {
+	got := dedupeKeyframeTimes([]float64{2, -1, 0, 0.0005, 1, 1.001, 1.0021, math.NaN(), math.Inf(1)})
+	require.Equal(t, []float64{0, 1, 1.0021, 2}, got)
+	require.Empty(t, dedupeKeyframeTimes(nil))
+}
+
+// TestCtxReaderAt checks that reads stop once the context is cancelled.
+func TestCtxReaderAt(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	r := ctxReaderAt{ctx: ctx, r: strings.NewReader("abcdef")}
+	buf := make([]byte, 3)
+	n, err := r.ReadAt(buf, 1)
+	require.NoError(t, err)
+	require.Equal(t, "bcd", string(buf[:n]))
+	cancel()
+	_, err = r.ReadAt(buf, 0)
+	require.ErrorIs(t, err, context.Canceled)
+}
+
+// TestKeyframeDiff checks the shadow comparison: a subset is expected, an
+// extra keyframe is a real difference.
+func TestKeyframeDiff(t *testing.T) {
+	require.Empty(t, keyframeDiff([]float64{0, 2, 4}, []float64{0, 2.001, 4}))
+
+	subset := keyframeDiff([]float64{0, 4}, []float64{0, 2, 4, 6})
+	require.Len(t, subset, 1)
+	require.True(t, strings.HasPrefix(subset[0], expectedDiffPrefix), subset[0])
+	require.Contains(t, subset[0], "2 of 4")
+
+	extra := keyframeDiff([]float64{0, 1, 2}, []float64{0, 2})
+	require.Len(t, extra, 1)
+	require.False(t, strings.HasPrefix(extra[0], expectedDiffPrefix), extra[0])
+}

backend/internal/mediacache/mediacache.go

@@ -0,0 +1,109 @@
+// Package mediacache holds the media metadata caches shared by the ffmpeg and
+// go-media code paths. Both backends read and write the same entries, so a
+// value found by one is reused by the other instead of being probed again.
+//
+// Every entry is keyed by file identity: path, size, and modification time in
+// nanoseconds. An edited file gets a new key, so a stale value is never served
+// for it; the old entry ages out after TTL.
+package mediacache
+
+import (
+	"context"
+	"fmt"
+	"io/fs"
+	"os"
+	"time"
+
+	"github.com/gtsteffaniak/filebrowser/backend/internal/utils"
+	"github.com/gtsteffaniak/go-cache/cache"
+)
+
+// TTL is how long a cached media value is kept after it is stored.
+const TTL = 24 * time.Hour
+
+// ProbeInfo is the container summary both backends produce: ffprobe through
+// go-ffmpeg, and go-media. FormatName uses ffprobe's format_name strings.
+type ProbeInfo struct {
+	Duration   float64
+	VideoCodec string
+	AudioCodec string
+	FormatName string
+}
+
+var (
+	// Probes caches container probes (duration, first video and audio codec,
+	// format name).
+	Probes = cache.NewCache[ProbeInfo](TTL)
+	// Durations caches media length in seconds.
+	Durations = cache.NewCache[float64](TTL)
+	// SubtitleTracks caches the embedded subtitle track list of a video.
+	SubtitleTracks = cache.NewCache[[]utils.SubtitleTrack](TTL)
+	// SubtitleContent caches one embedded subtitle stream converted to WebVTT.
+	// Use Key.Stream for its key.
+	SubtitleContent = cache.NewCache[string](TTL)
+)
+
+// Key identifies one version of a file. The zero Key is never produced for a
+// real file, because Path is always set.
+type Key struct {
+	Path    string
+	Size    int64
+	ModTime int64 // modification time in Unix nanoseconds
+}
+
+// FromFileInfo returns the Key for path using an already-read FileInfo, so
+// callers that stat or open the file anyway do not stat it twice.
+func FromFileInfo(path string, info fs.FileInfo) Key {
+	return Key{Path: path, Size: info.Size(), ModTime: info.ModTime().UnixNano()}
+}
+
+// Stat returns the Key for path. It follows symlinks, like os.Stat.
+func Stat(path string) (Key, error) {
+	info, err := os.Stat(path)
+	if err != nil {
+		return Key{}, err
+	}
+	return FromFileInfo(path, info), nil
+}
+
+// String returns the cache key for k. The path is quoted so a path containing
+// the separator cannot collide with another file's key.
+func (k Key) String() string {
+	return fmt.Sprintf("%q:%d:%d", k.Path, k.Size, k.ModTime)
+}
+
+// Stream returns the cache key for one stream of k, used by SubtitleContent.
+func (k Key) Stream(index int) string {
+	return fmt.Sprintf("%s:%d", k.String(), index)
+}
+
+// ClearAll drops every cached media value. It is used when the backend that
+// produced the values is switched (the admin "Always use ffmpeg" setting), so
+// the newly selected backend answers fresh.
+func ClearAll() {
+	Probes.ClearAll()
+	Durations.ClearAll()
+	SubtitleTracks.ClearAll()
+	SubtitleContent.ClearAll()
+}
+
+// bypassKey is the context key set by WithoutCache.
+type bypassKey struct{}
+
+// WithoutCache returns a context under which the ffmpeg code paths neither read
+// nor write the shared caches. Dev-mode shadow runs use it, so the ffmpeg result
+// they compare against go-media is computed fresh rather than read back from the
+// value go-media just stored.
+func WithoutCache(ctx context.Context) context.Context {
+	return context.WithValue(ctx, bypassKey{}, true)
+}
+
+// Bypassed reports whether ctx was returned by WithoutCache. A nil context is
+// not bypassed.
+func Bypassed(ctx context.Context) bool {
+	if ctx == nil {
+		return false
+	}
+	v, _ := ctx.Value(bypassKey{}).(bool)
+	return v
+}

backend/internal/mediacache/mediacache_test.go

@@ -0,0 +1,157 @@
+package mediacache
+
+import (
+	"context"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// TestStatKeyChangesWithSizeAndModTime checks on disk that a size change
+// or an mtime change gives a new key. The mtimes differ by whole seconds so
+// the check holds on filesystems with coarse timestamps; the 1 ns case is
+// covered by TestFromFileInfoNanosecondModTime.
+func TestStatKeyChangesWithSizeAndModTime(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "a.mp4")
+	if err := os.WriteFile(path, []byte("one"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	k1, err := Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if k1.Path != path || k1.Size != 3 || k1.ModTime == 0 {
+		t.Fatalf("unexpected key %+v", k1)
+	}
+
+	// Same size, different mtime.
+	mt := time.Unix(1_700_000_000, 0)
+	if err = os.Chtimes(path, mt, mt); err != nil {
+		t.Fatal(err)
+	}
+	k2, err := Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if k2.String() == k1.String() {
+		t.Fatalf("mtime change kept key %s", k2)
+	}
+	mt2 := mt.Add(time.Second)
+	if err = os.Chtimes(path, mt2, mt2); err != nil {
+		t.Fatal(err)
+	}
+	k3, _ := Stat(path)
+	if k3.String() == k2.String() {
+		t.Fatalf("1s mtime change kept key %s", k3)
+	}
+
+	// Same mtime, different size.
+	if err = os.WriteFile(path, []byte("three"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err = os.Chtimes(path, mt2, mt2); err != nil {
+		t.Fatal(err)
+	}
+	k4, _ := Stat(path)
+	if k4.String() == k3.String() {
+		t.Fatalf("size change kept key %s", k4)
+	}
+}
+
+// stubFileInfo is an fs.FileInfo with a fixed size and mtime.
+type stubFileInfo struct {
+	size    int64
+	modTime time.Time
+}
+
+// Name implements fs.FileInfo.
+func (s stubFileInfo) Name() string { return "a.mp4" }
+
+// Size implements fs.FileInfo.
+func (s stubFileInfo) Size() int64 { return s.size }
+
+// Mode implements fs.FileInfo.
+func (s stubFileInfo) Mode() fs.FileMode { return 0o600 }
+
+// ModTime implements fs.FileInfo.
+func (s stubFileInfo) ModTime() time.Time { return s.modTime }
+
+// IsDir implements fs.FileInfo.
+func (s stubFileInfo) IsDir() bool { return false }
+
+// Sys implements fs.FileInfo.
+func (s stubFileInfo) Sys() any { return nil }
+
+// TestFromFileInfoNanosecondModTime checks that mtimes 1 ns apart give
+// different keys, independent of what a filesystem can store.
+func TestFromFileInfoNanosecondModTime(t *testing.T) {
+	a := FromFileInfo("/m/a.mp4", stubFileInfo{size: 3, modTime: time.Unix(1_700_000_000, 123)})
+	b := FromFileInfo("/m/a.mp4", stubFileInfo{size: 3, modTime: time.Unix(1_700_000_000, 124)})
+	if a.String() == b.String() {
+		t.Fatalf("1ns mtime change kept key %s", a)
+	}
+	if a.ModTime != time.Unix(1_700_000_000, 123).UnixNano() {
+		t.Fatalf("ModTime = %d, want nanoseconds", a.ModTime)
+	}
+}
+
+// TestStatMissingFile checks that Stat reports a missing file.
+func TestStatMissingFile(t *testing.T) {
+	if _, err := Stat(filepath.Join(t.TempDir(), "missing")); err == nil {
+		t.Fatal("expected an error for a missing file")
+	}
+}
+
+// TestKeyStringDoesNotCollide checks that keys of different files, and of
+// different streams of one file, never collide.
+func TestKeyStringDoesNotCollide(t *testing.T) {
+	a := Key{Path: "a:1", Size: 2, ModTime: 3}
+	b := Key{Path: "a", Size: 1, ModTime: 2}
+	if a.String() == b.String() {
+		t.Fatalf("keys collide: %s", a)
+	}
+	if a.Stream(1) == a.Stream(2) || a.Stream(1) == a.String() {
+		t.Fatalf("stream keys collide: %s %s", a.Stream(1), a.Stream(2))
+	}
+}
+
+// TestClearAll checks that ClearAll empties every shared cache.
+func TestClearAll(t *testing.T) {
+	k := Key{Path: "/clear", Size: 1, ModTime: 1}
+	Probes.Set(k.String(), ProbeInfo{Duration: 1})
+	Durations.Set(k.String(), 1)
+	SubtitleContent.Set(k.Stream(0), "x")
+	ClearAll()
+	if _, ok := Probes.Get(k.String()); ok {
+		t.Fatal("probe survived ClearAll")
+	}
+	if _, ok := Durations.Get(k.String()); ok {
+		t.Fatal("duration survived ClearAll")
+	}
+	if _, ok := SubtitleContent.Get(k.Stream(0)); ok {
+		t.Fatal("subtitle content survived ClearAll")
+	}
+}
+
+// TestWithoutCache checks the cache bypass marker and that derived contexts
+// keep it.
+func TestWithoutCache(t *testing.T) {
+	if Bypassed(context.Background()) {
+		t.Fatal("background context must not bypass")
+	}
+	//nolint:staticcheck // nil is part of the documented contract.
+	if Bypassed(nil) {
+		t.Fatal("nil context must not bypass")
+	}
+	ctx := WithoutCache(context.Background())
+	if !Bypassed(ctx) {
+		t.Fatal("WithoutCache context must bypass")
+	}
+	child, cancel := context.WithCancel(ctx)
+	defer cancel()
+	if !Bypassed(child) {
+		t.Fatal("bypass must survive derived contexts")
+	}
+}

backend/internal/preview/preview.go

@@ -272,8 +272,9 @@ func determinePreviewType(file iteminfo.ExtendedFileInfo) filePreviewType {
 		return previewTypeOffice
 	}
 
-	// Check HEIC with conversion enabled
-	if strings.HasPrefix(file.Type, "image/heic") &&
+	// Check HEIC with conversion enabled. AVIF is a HEIF container too and uses
+	// the same path (go-media decode, ffmpeg fallback) under the HEIC setting.
+	if (strings.HasPrefix(file.Type, "image/heic") || file.Type == "image/avif") &&
 		settings.CanConvertImage(string(settings.HEICImagePreview)) {
 		return previewTypeHEIC
 	}

backend/internal/preview/preview_type_test.go

@@ -0,0 +1,49 @@
+package preview
+
+import (
+	"testing"
+
+	"github.com/gtsteffaniak/filebrowser/backend/pkg/indexing/iteminfo"
+	"github.com/gtsteffaniak/filebrowser/backend/pkg/settings"
+)
+
+// withHEICConversion sets ffmpeg availability and the HEIC preview setting for
+// one test.
+func withHEICConversion(t *testing.T, enabled bool) {
+	t.Helper()
+	prevAvail := settings.Env.FFmpegAvailable
+	prevPreview := settings.Config.Integrations.Media.Convert.ImagePreview
+	t.Cleanup(func() {
+		settings.Env.FFmpegAvailable = prevAvail
+		settings.Config.Integrations.Media.Convert.ImagePreview = prevPreview
+	})
+	settings.Env.FFmpegAvailable = true
+	settings.Config.Integrations.Media.Convert.ImagePreview = map[settings.ImagePreviewType]*bool{
+		settings.HEICImagePreview: &enabled,
+	}
+}
+
+// previewFile returns a file info with only a name and MIME type set.
+func previewFile(name, mimeType string) iteminfo.ExtendedFileInfo {
+	var f iteminfo.ExtendedFileInfo
+	f.Name = name
+	f.Type = mimeType
+	return f
+}
+
+// TestDeterminePreviewTypeAVIF checks that AVIF uses the HEIF decode path when
+// HEIC conversion is enabled, and the plain image path otherwise.
+func TestDeterminePreviewTypeAVIF(t *testing.T) {
+	withHEICConversion(t, true)
+	if got := determinePreviewType(previewFile("a.avif", "image/avif")); got != previewTypeHEIC {
+		t.Fatalf("avif with HEIC conversion = %v, want previewTypeHEIC", got)
+	}
+	if got := determinePreviewType(previewFile("a.heic", "image/heic")); got != previewTypeHEIC {
+		t.Fatalf("heic with HEIC conversion = %v, want previewTypeHEIC", got)
+	}
+
+	withHEICConversion(t, false)
+	if got := determinePreviewType(previewFile("a.avif", "image/avif")); got != previewTypeImage {
+		t.Fatalf("avif without HEIC conversion = %v, want previewTypeImage", got)
+	}
+}

backend/internal/preview/video.go

@@ -28,8 +28,11 @@ func (s *Service) GenerateVideoPreview(ctx context.Context, videoPath, previewSi
 		return nil, err
 	}
 
-	// go-media fast path: fit within the box, no crop. Falls back to ffmpeg when
-	// unsupported (e.g. HEVC, VP9, AV1) or failed.
+	// go-media fast path: fit within the box, no crop. go-media decodes H.264,
+	// HEVC, VP8, VP9, AV1, MPEG-4 Part 2, and WMV3 keyframes in pure Go. It falls
+	// back to ffmpeg when the container is not a go-media target (AVI, MPEG-TS,
+	// MPEG-PS, ...), the codec or profile is unsupported (WMV1/WMV2, VC-1
+	// Advanced, AV1 above 4K, ...), or the decode fails.
 	// In shadow mode (dev only) the ffmpeg preview also runs, for comparison.
 	// The shadow run can outlive the request, so it uses a context that is not cancelled with it.
 	shadowCtx := context.WithoutCancel(ctx)

backend/internal/transcoding/engine.go

@@ -133,7 +133,7 @@ func (e *MediaEngine) BuildPlan(ctx context.Context, realPath string, profile Pr
 	copyImpossible := false
 	plan.segmentSec = defaults.SegmentDurationSec
 	if plan.remux || plan.videoCopy {
-		rawKeyframes, kfErr := probeKeyframesCached(ctx, svc, realPath, stat.Size(), stat.ModTime().UnixNano(), plan.segmentSec, true)
+		rawKeyframes, kfErr := probeKeyframesCached(ctx, svc, realPath, stat.Size(), stat.ModTime().UnixNano(), plan.segmentSec, mediaSpan{durationSec: info.Duration, startTimeSec: info.StartTime}, true)
 		if kfErr != nil {
 			copyImpossible = true
 			logger.Warningf("transcode: keyframe probe failed on %s (%v) — forcing video transcode for HLS", realPath, kfErr)

backend/internal/transcoding/keyframe_cache.go

@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"github.com/gtsteffaniak/filebrowser/backend/internal/ffmpeg"
+	"github.com/gtsteffaniak/filebrowser/backend/internal/gomedia"
 	"github.com/gtsteffaniak/filebrowser/backend/pkg/settings"
 	"github.com/gtsteffaniak/go-logger/logger"
 )
@@ -55,6 +56,9 @@ type keyframeCache struct {
 
 var defaultKeyframeCache = &keyframeCache{entries: map[keyframeKey]*keyframeEntry{}}
 
+// get returns the keyframe timeline for key from memory, then disk, then
+// probe. Concurrent callers for one key wait on a single probe; failures are
+// not cached.
 func (c *keyframeCache) get(ctx context.Context, key keyframeKey, probe func(context.Context) ([]float64, error)) ([]float64, error) {
 	c.mu.Lock()
 	e := c.entries[key]
@@ -105,12 +109,15 @@ func keyframeDiskCacheEnabled() bool {
 	return settings.Config.Server.CacheDir != ""
 }
 
+// keyframeDiskPath returns the disk cache file for key's path.
 func keyframeDiskPath(key keyframeKey) string {
 	sum := sha256.Sum256([]byte(key.path))
 	name := hex.EncodeToString(sum[:])[:32] + ".json"
 	return filepath.Join(settings.TranscodeKeyframeCacheDir(), name)
 }
 
+// readKeyframeDiskCache returns the persisted timeline for key when it exists
+// and matches the file's size, mtime, and the cache version.
 func readKeyframeDiskCache(key keyframeKey) ([]float64, bool) {
 	if !keyframeDiskCacheEnabled() {
 		return nil, false
@@ -132,6 +139,8 @@ func readKeyframeDiskCache(key keyframeKey) ([]float64, bool) {
 	return stamp.Times, true
 }
 
+// writeKeyframeDiskCache persists a timeline for key atomically. Errors are
+// ignored; the cache is an optimization.
 func writeKeyframeDiskCache(key keyframeKey, times []float64) {
 	if len(times) == 0 || !keyframeDiskCacheEnabled() {
 		return
@@ -219,19 +228,88 @@ func probeKeyframesWithPreflight(ctx context.Context, svc *ffmpeg.Service, realP
 	)
 }
 
+// mediaSpan is the ffprobe format duration and start time of a file, the
+// values the HLS planner turns into its media timeline. The zero value means
+// unknown.
+type mediaSpan struct {
+	durationSec  float64
+	startTimeSec float64
+}
+
+// trailingGapExceedsCopyCap reports whether the stretch from the last
+// keyframe to the end of the media is longer than the copy cap, measured on
+// the same normalized timeline the planner builds: the final segment runs
+// from the last keyframe to the media end, so such a gap forces a transcode
+// just like a gap between two keyframes. An unknown span reports false.
+func trailingGapExceedsCopyCap(keyframes []float64, span mediaSpan, segmentSec float64) bool {
+	if len(keyframes) == 0 || span.durationSec <= 0 {
+		return false
+	}
+	kf, mediaDur := ffmpeg.PrepareHLSMediaTimeline(keyframes, span.durationSec, span.startTimeSec)
+	if len(kf) == 0 || mediaDur <= 0 {
+		return false
+	}
+	return mediaDur-kf[len(kf)-1] > maxCopySegmentDurationSec(segmentSec)
+}
+
 // keyframeProbeTimeout bounds a single full-file keyframe probe. The default
 // demux has no deadline of its own, so a slow network share would otherwise
 // stall plan building (and the client's session POST) indefinitely.
 const keyframeProbeTimeout = 2 * time.Minute
 
-func probeKeyframesCached(ctx context.Context, svc *ffmpeg.Service, realPath string, size, modTime int64, segmentSec float64, preflight bool) ([]float64, error) {
+// probeKeyframesCached returns the keyframe timeline of a file version from
+// the memory or disk cache, or probes it: go-media reads the container index
+// first, and ffprobe runs only when go-media cannot answer or reports a gap
+// that would rule out stream copy. span is the file's duration and start
+// time, used to check the gap after the last keyframe; the zero value skips
+// that check.
+func probeKeyframesCached(ctx context.Context, svc *ffmpeg.Service, realPath string, size, modTime int64, segmentSec float64, span mediaSpan, preflight bool) ([]float64, error) {
 	key := keyframeKey{path: realPath, size: size, modTime: modTime}
 	return defaultKeyframeCache.get(ctx, key, func(ctx context.Context) ([]float64, error) {
 		probeCtx, cancel := context.WithTimeout(ctx, keyframeProbeTimeout)
 		defer cancel()
+		if times, ok := gomediaKeyframes(probeCtx, svc, realPath, segmentSec, span, preflight); ok {
+			return times, nil
+		}
 		if preflight {
 			return probeKeyframesWithPreflight(probeCtx, svc, realPath, segmentSec)
 		}
 		return svc.ProbeVideoKeyframeTimes(probeCtx, realPath)
 	})
 }
+
+// gomediaKeyframes reads the keyframe timeline from the container index with
+// go-media. It reports ok=false when go-media cannot answer, and also when
+// preflight is set and the timeline has a gap past the copy cap, including
+// the gap from the last keyframe to the end of span: go-media can miss
+// keyframes that ffprobe's parsers flag (IDR frames not in the index,
+// partial Matroska Cues) but never adds one, so only ffprobe may decide that
+// stream copy is impossible. A bounded go-media read runs first, so a file
+// whose head already shows such a gap does not pay for a full index walk.
+func gomediaKeyframes(ctx context.Context, svc *ffmpeg.Service, realPath string, segmentSec float64, span mediaSpan, preflight bool) ([]float64, bool) {
+	if preflight {
+		if head, ok := gomedia.KeyframeTimesWithin(ctx, realPath, keyframeBoundedPreflightWindowSec); ok && keyframesExceedCopyCap(head, segmentSec) {
+			logger.Debugf("transcode: go-media keyframe pre-flight shows a gap past the copy cap on %s; confirming with ffprobe", realPath)
+			return nil, false
+		}
+	}
+	legacy := func() ([]float64, bool) {
+		shadowCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), keyframeProbeTimeout)
+		defer cancel()
+		times, err := svc.ProbeVideoKeyframeTimes(shadowCtx, realPath)
+		return times, err == nil
+	}
+	times, ok := gomedia.KeyframeTimes(ctx, realPath, legacy)
+	if !ok {
+		return nil, false
+	}
+	if preflight && keyframesExceedCopyCap(times, segmentSec) {
+		logger.Debugf("transcode: go-media keyframe index shows a gap past the copy cap on %s; confirming with ffprobe", realPath)
+		return nil, false
+	}
+	if preflight && trailingGapExceedsCopyCap(times, span, segmentSec) {
+		logger.Debugf("transcode: go-media keyframe index ends more than the copy cap before the end of %s; confirming with ffprobe", realPath)
+		return nil, false
+	}
+	return times, true
+}

backend/internal/transcoding/keyframe_cache_test.go

@@ -177,3 +177,33 @@ func TestKeyframeCacheDoesNotCacheFailures(t *testing.T) {
 		t.Fatalf("retry after failure: %v, %v", got, err)
 	}
 }
+
+// TestTrailingGapExceedsCopyCap checks the gap from the last keyframe to the
+// end of the media, on the planner's start-time-normalized timeline.
+func TestTrailingGapExceedsCopyCap(t *testing.T) {
+	every2 := func(from, to float64) []float64 {
+		var out []float64
+		for v := from; v < to; v += 2 {
+			out = append(out, v)
+		}
+		return out
+	}
+	cases := []struct {
+		name string
+		kf   []float64
+		span mediaSpan
+		want bool
+	}{
+		{"partial index", []float64{0, 2}, mediaSpan{durationSec: 60}, true},
+		{"full index", every2(0, 60), mediaSpan{durationSec: 60}, false},
+		{"unknown span", []float64{0, 2}, mediaSpan{}, false},
+		{"start time, partial", []float64{10, 12}, mediaSpan{durationSec: 70, startTimeSec: 10}, true},
+		{"start time, full", every2(10, 70), mediaSpan{durationSec: 70, startTimeSec: 10}, false},
+		{"no keyframes", nil, mediaSpan{durationSec: 60}, false},
+	}
+	for _, c := range cases {
+		if got := trailingGapExceedsCopyCap(c.kf, c.span, 4); got != c.want {
+			t.Errorf("%s: got %v, want %v", c.name, got, c.want)
+		}
+	}
+}

backend/internal/transcoding/keyframe_gomedia_test.go

@@ -0,0 +1,111 @@
+package transcoding
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+
+	"github.com/gtsteffaniak/filebrowser/backend/pkg/settings"
+)
+
+const keyframeFixtureMP4 = "../../../frontend/tests/playwright-files/myfolder/testdata/sample-640x480.mp4"
+
+// TestProbeKeyframesCachedUsesGoMedia checks that an MP4 keyframe timeline is
+// built without ffprobe: with no ffmpeg service, only go-media can answer.
+func TestProbeKeyframesCachedUsesGoMedia(t *testing.T) {
+	if settings.AlwaysUseFfmpegEnabled() {
+		t.Skip("go-media disabled by settings")
+	}
+	prevCacheDir := settings.Config.Server.CacheDir
+	settings.Config.Server.CacheDir = "" // keep the disk cache out of the test
+	t.Cleanup(func() { settings.Config.Server.CacheDir = prevCacheDir })
+
+	path := filepath.Join(t.TempDir(), "sample.mp4")
+	data, err := os.ReadFile(keyframeFixtureMP4)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err = os.WriteFile(path, data, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	st, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	times, err := probeKeyframesCached(context.Background(), nil, path, st.Size(), st.ModTime().UnixNano(), 4, mediaSpan{}, true)
+	if err != nil {
+		t.Fatalf("probeKeyframesCached: %v", err)
+	}
+	if len(times) == 0 || times[0] < 0 {
+		t.Fatalf("unexpected keyframes %v", times)
+	}
+	for i := 1; i < len(times); i++ {
+		if times[i] <= times[i-1] {
+			t.Fatalf("keyframes not strictly increasing: %v", times)
+		}
+	}
+}
+
+// TestGomediaKeyframesDefersCopyDecision checks that a go-media timeline with a
+// gap past the copy cap is not used for the pre-flight decision (ffprobe must
+// confirm it), while a plain probe still returns it.
+func TestGomediaKeyframesDefersCopyDecision(t *testing.T) {
+	if testing.Short() {
+		t.Skip("encodes a clip with ffmpeg")
+	}
+	if settings.AlwaysUseFfmpegEnabled() {
+		t.Skip("go-media disabled by settings")
+	}
+	if _, err := exec.LookPath("ffmpeg"); err != nil {
+		t.Skip("ffmpeg not installed")
+	}
+	path := filepath.Join(t.TempDir(), "longgop.mp4")
+	out, err := exec.Command("ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i", "testsrc2=size=128x96:rate=25:duration=40",
+		"-c:v", "libx264", "-g", "750", "-keyint_min", "750", "-sc_threshold", "0", "-pix_fmt", "yuv420p", path).CombinedOutput()
+	if err != nil {
+		t.Skipf("ffmpeg cannot encode libx264: %v: %s", err, out)
+	}
+
+	if times, ok := gomediaKeyframes(context.Background(), nil, path, 4, mediaSpan{}, true); ok {
+		t.Fatalf("pre-flight must defer a 30s GOP to ffprobe, got %v", times)
+	}
+	times, ok := gomediaKeyframes(context.Background(), nil, path, 4, mediaSpan{}, false)
+	if !ok {
+		t.Fatal("a plain probe must return the go-media timeline")
+	}
+	if len(times) != 2 || times[0] != 0 || times[1] < 29.9 || times[1] > 30.1 {
+		t.Fatalf("unexpected keyframes %v, want [0 30]", times)
+	}
+}
+
+// TestGomediaKeyframesDefersTrailingGap checks that a go-media index whose
+// last keyframe is more than the copy cap before the end of the media is not
+// used for the pre-flight decision, so ffprobe can confirm it, while the
+// same index is used when it reaches the end.
+func TestGomediaKeyframesDefersTrailingGap(t *testing.T) {
+	if testing.Short() {
+		t.Skip("encodes a clip with ffmpeg")
+	}
+	if settings.AlwaysUseFfmpegEnabled() {
+		t.Skip("go-media disabled by settings")
+	}
+	if _, err := exec.LookPath("ffmpeg"); err != nil {
+		t.Skip("ffmpeg not installed")
+	}
+	path := filepath.Join(t.TempDir(), "short.mp4")
+	out, err := exec.Command("ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i", "testsrc2=size=128x96:rate=25:duration=4",
+		"-c:v", "libx264", "-g", "50", "-keyint_min", "50", "-sc_threshold", "0", "-pix_fmt", "yuv420p", path).CombinedOutput()
+	if err != nil {
+		t.Skipf("ffmpeg cannot encode libx264: %v: %s", err, out)
+	}
+	// The index ends at 2 s; a 60 s span leaves a 58 s final segment.
+	if times, ok := gomediaKeyframes(context.Background(), nil, path, 4, mediaSpan{durationSec: 60}, true); ok {
+		t.Fatalf("pre-flight must defer a 58s trailing gap to ffprobe, got %v", times)
+	}
+	times, ok := gomediaKeyframes(context.Background(), nil, path, 4, mediaSpan{durationSec: 4}, true)
+	if !ok || len(times) != 2 {
+		t.Fatalf("index reaching the end must be used, got %v, %v", times, ok)
+	}
+}

backend/internal/web/media.go

@@ -12,6 +12,7 @@ import (
 	"github.com/gtsteffaniak/filebrowser/backend/internal/adapters/fs/files"
 	"github.com/gtsteffaniak/filebrowser/backend/internal/ffmpeg"
 	"github.com/gtsteffaniak/filebrowser/backend/internal/gomedia"
+	"github.com/gtsteffaniak/filebrowser/backend/internal/mediacache"
 	"github.com/gtsteffaniak/filebrowser/backend/internal/utils"
 	"github.com/gtsteffaniak/filebrowser/backend/pkg/settings"
 )
@@ -123,7 +124,8 @@ func subtitlesHandler(w http.ResponseWriter, r *http.Request, d *Context) (int,
 			}
 			// Shadow ffmpeg runs after the fast path; bound it so a detached request cannot
 			// leave extraction running indefinitely (sync fallback still uses r.Context()).
-			legacyCtx, cancel := context.WithTimeout(context.WithoutCancel(r.Context()), time.Minute)
+			// WithoutCache: compare against a fresh extraction, not the value go-media stored.
+			legacyCtx, cancel := context.WithTimeout(mediacache.WithoutCache(context.WithoutCancel(r.Context())), time.Minute)
 			defer cancel()
 			vtt, extractErr := svc.ExtractSubtitle(legacyCtx, fileInfo.RealPath, *track.Index)
 			return vtt, extractErr == nil

backend/pkg/settings/media_runtime.go

@@ -8,6 +8,7 @@ import (
 	"time"
 
 	"github.com/gtsteffaniak/filebrowser/backend/internal/ffmpeg"
+	"github.com/gtsteffaniak/filebrowser/backend/internal/mediacache"
 	goffmpeg "github.com/gtsteffaniak/go-ffmpeg"
 	"github.com/gtsteffaniak/go-ffmpeg/capabilities"
 	"github.com/gtsteffaniak/go-ffmpeg/encode"
@@ -288,6 +289,11 @@ func ApplyMediaSettings(s FullAdminMedia) {
 	Config.Integrations.Media.Debug = s.Debug
 	Config.Integrations.Media.HardwareAcceleration = s.HardwareAcceleration
 	Config.Integrations.Media.AccelDevice = s.AccelDevice
+	if Config.Integrations.Media.AlwaysUseFfmpeg != s.AlwaysUseFfmpeg {
+		// The shared media cache holds values from whichever backend answered
+		// first. Switching backends drops them so the selected one answers fresh.
+		mediacache.ClearAll()
+	}
 	Config.Integrations.Media.AlwaysUseFfmpeg = s.AlwaysUseFfmpeg
 	Config.Integrations.Media.AlwaysUseOnlyOffice = s.AlwaysUseOnlyOffice
 	Config.Integrations.Media.Transcode = s.Transcode

backend/pkg/settings/media_runtime_test.go

@@ -4,6 +4,8 @@ import (
 	"sync"
 	"testing"
 	"time"
+
+	"github.com/gtsteffaniak/filebrowser/backend/internal/mediacache"
 )
 
 func withMediaConfig(t *testing.T) {
@@ -308,3 +310,26 @@ func TestInitFFmpegIsIdempotent(t *testing.T) {
 		t.Fatal("InitFFmpeg must not run the probe during tests")
 	}
 }
+
+// TestApplyMediaSettingsClearsMediaCacheOnBackendSwitch checks that toggling
+// "Always use ffmpeg" drops values the other backend cached, and that an
+// unrelated settings change keeps them.
+func TestApplyMediaSettingsClearsMediaCacheOnBackendSwitch(t *testing.T) {
+	withMediaConfig(t)
+	key := mediacache.Key{Path: "/settings-test.mp4", Size: 1, ModTime: 1}.String()
+	t.Cleanup(func() { mediacache.Durations.Delete(key) })
+
+	media := CurrentMediaSettings()
+	mediacache.Durations.Set(key, 1)
+	media.Debug = !media.Debug
+	ApplyMediaSettings(media)
+	if _, ok := mediacache.Durations.Get(key); !ok {
+		t.Fatal("an unrelated media settings change must keep the shared media cache")
+	}
+
+	media.AlwaysUseFfmpeg = !media.AlwaysUseFfmpeg
+	ApplyMediaSettings(media)
+	if _, ok := mediacache.Durations.Get(key); ok {
+		t.Fatal("switching Always use ffmpeg must clear the shared media cache")
+	}
+}