fix(rendering): FFmpeg decoder seeks instead of guessing on backward cache misses

[richiemcilroy]

Removes the last two mechanisms by which the FFmpeg decoder (Linux, and Windows without a D3D11 video device) shows a frame other than the one requested.

Causes

1. Backward lookback guess. A backward request whose frame was not cached was answered with a cached frame up to 2 frames older (MAX_FRAME_LOOKBACK_TOLERANCE), on the assumption that the requested frame was a VFR hold. When the frame existed but had left the cache, the answer was stale: 1 or 2 storm seeks in 3,000, and 161 seeds of the decoder reference model.
2. Seek past the request. FFmpegDecoder::reset seeks with the request time, which avformat rounds to the stream's tick. A request a fraction of a tick before a keyframe landed on that keyframe, one frame past the request (future in the reference model).

Fix

• Known holds in both directions (crates/rendering/src/decoder/ffmpeg.rs). A request inside a recorded pts hole is answered with the hole's start frame whether it moves forward or backward; holes are facts about the file and survive resets. Any other backward cache miss seeks, so the reader decodes the requested frame. The tolerance constant is gone.
• Seek margin (crates/video-decode/src/ffmpeg.rs). reset seeks 2 ms before the request. The reader decodes forward to the requested frame from wherever the seek lands, so the margin costs at most a little decoding and cannot change the answer.

Both decode loops (hardware and software fallback) change the same way.

Measured

	main	This PR
FFmpeg seek storms, full tier (3,000 seeks each)	1 to 2 stale seeks (flaky entries)	pass: entries removed
seek/seek-native/keyframes60/ffmpeg (Linux, Windows)	xfail	entry removed
Decoder reference model, FFmpeg: stale seeds	161 in 9 groups	0
Decoder reference model, FFmpeg: future seeds	162 in 13 groups	0
Decoder reference model, FFmpeg: grid-rounding seeds	380 in 15 groups	209 in 14 groups

• The full export, seek, playback and editing suites pass on macOS with both decoders.
• scripts/verify/perf-ab.py against main on Apple silicon, 3 interleaved pairs, median per-pair CPU ratio: export-basic +0.3%, export-jitter-camera-40s +0.4%, seek storms +0.1%, playback-basic -0.2%.
• The grid-rounding seeds that remain are a frame-numbering convention: the decoder floors request times while the model rounds them. Changing the request side alone broke sequential playback in the model, because pts_to_frame numbers decoded frames with the same floor, so it is left for a change to both.

Confidence Score: 5/5

The PR appears safe to merge; no actionable defects were found.

Summary

The PR makes FFmpeg seek on backward cache misses instead of returning a nearby older frame.

• FFmpeg seeks for backward misses instead of guessing from nearby frames.

No actionable issues were found. This review used code inspection; no builds or tests were run.

Acknowledged deferral: richiemcilroy leaves the existing grid-rounding mismatch for a separate change because request times and decoded-frame numbering must change together.

_{Reviews (1) · Last reviewed commit: "fix(rendering): FFmpeg decoder seeks ins..." · Reviewed by Greptile}

[capy-ai]

Capy found no issues.

View 1 other finding in Capy.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
cap-status	Ready	Preview	Oct 17, 2026 4:39am UTC

[capy-ai]

Capy found no issues.