Video export bug; output does not match what was recorded

[lilacpixel]

Description

Occasionally, when exporting video from Cap after recording in Studio Mode, the exported video will be rendered incorrectly, with flickering and/or stuck frames. This seems to occur most often in videos that have one or more zooms but has been observed in all types of recordings. When a stuck frame occurs, cursor and zoom effects will still play correctly, but the frame will not update properly for some time.

Forcing FFmpeg decoder reduces the occurrence of flickering frames but does not fix stuck frames on affected recordings. The same frame will always stick at the same point when exporting.

Reproduction

1. Record video of any duration.
2. Check playback in preview mode.
3. Export video to MP4 with any combination of settings.
4. Compare exported video to preview.

Additional Context

• Cap version: 0.4.84
• Operating system, version: macOS Sequoia 15.7.5
• Device: MacBook Air M2

Edit: Issue also occurs when exporting the same recording bundle on an M5 MacBook Pro with Tahoe 26.4.1.
Edit 2: Issue does NOT occur when exporting the same recording bundle on Windows 10 (LTSC).

Video as shown in Cap's preview (captured by macOS screen recording).

cap-video-preview.mp4

Same section of exported video. Note that the second click event does not correctly show the overlay closing.

cap-video-output.mp4

[linear]

CAP-704

[tembo]

Some context that might help with debugging this:

Decoder and Frame Pipeline Context

The export pipeline uses the AVAssetReader decoder on macOS (in crates/rendering/src/decoder/avassetreader.rs), which has sophisticated frame caching and fallback logic. When exact frames cannot be decoded, it uses a fallback distance mechanism to return nearby cached frames instead. The observation that "cursor and zoom effects still play correctly, but the frame will not update properly" aligns with how the current architecture separates cursor/zoom rendering from the underlying video frame decoding.

The fact that forcing FFmpeg decoder reduces flickering (as mentioned in the issue) is consistent with prior work in PR #1506 which added this experimental setting specifically to address hardware decoder reliability issues on macOS. The AVAssetReader can sometimes return frames out of order or miss frames under certain conditions, particularly during seeks or when the decoder health monitoring triggers recreation.

Relevant Code Paths

• Frame caching and fallback: crates/rendering/src/decoder/avassetreader.rs:867-909 handles situations where requested frames are not available, falling back to nearby cached frames based on max_fallback_distance
• The DecoderHealth struct (line 254-334) monitors decoder state and can trigger recreation when frames aren't being produced
• Preview playback uses a different code path than export - preview goes through the desktop app's socket.ts frame transport system while export uses crates/export/src/mp4.rs with the render-to-channel pipeline

Related Issues and PRs

• Export audio not sync to video #382 - Audio/video sync issues during export, also involving segments and timing
• [Bug] Video Rendering Issue #1552 and [Bug] Glitchy video output and incorrect cursor capture #1609 - Related video rendering issues on different platforms
• PR Playback performance and sync #1596 (open) - Playback performance and sync work that addresses frame ordering and transport
• PR perf: improve export speed with pipeline restructure, cursor precomputation, and encoder tuning #1675 (merged) - Recent export speed improvements that restructured the pipeline and added cursor timeline precomputation

Potential Investigation Areas

1. The stuck frames occurring at consistent points suggests the decoder may be hitting specific frames that fail to decode, causing the fallback logic to repeatedly return the same cached frame
2. The relationship to zooms could indicate an issue with how frame timing is calculated during zoom interpolation in crates/rendering/src/zoom_focus_interpolation.rs
3. Checking the debug logs (macOS: /Users/{username}/Library/Logs/so.cap.desktop) for decoder warnings like "No frames decoded from video" or "Frame requests could not be fulfilled" would help identify whether this is a decode failure vs a rendering timing issue

If the recording bundle can be shared with the maintainers (brendan@cap.so via WeTransfer), they can analyze the specific segments and timeline to identify where the frame sync breaks down.

[lilacpixel]

Recording bundle has been sent via WeTransfer. Nothing in the debug log looked particularly telling, but I'll include it here, just in case.

cap-desktop.log.2026-05-08.txt

Thank you!