Viewer, Transport & Playback

Playback is split across threads so the UI never waits on a decoder: video is decoded ahead by RenderAhead, audio is decoded by the mix_buffers workers and played by the mixer, and the UI thread only composes what is already in memory.

Pipeline

The audio clock drives the playhead

While playing, drive_playback sets the playhead to the mixer's position every frame. Video follows audio, not the other way round, so A/V sync holds even when a frame is late: the viewer keeps the last composed frame instead of stalling the sound. Without an audio device the clock falls back to wall time and nothing is played.

RenderAhead: the video buffer

• Each buffer has one thread that walks forward from the playhead (default 3 s) and a little behind (2 s), crossing cuts, gaps and tracks without special cases.
• Decoded frames go into the buffer's SharedFrameCache under the configured RAM budget. At speeds above 1x the window grows, then shrinks back if the media playing together would not fit the budget: over-asking would leave holes, i.e. black flashes.
• Compound clips are not decoded: their nested timelines are walked only to keep the real media warm; they are composed on the GPU when the outer frame is drawn.
• The app runs separate buffers for the timeline, the media-pool preview and, during a slip, one for each end of the clip.
• The playhead target is updated every frame; the project copy inside the buffer is refreshed only when History::generation() changes.

Composing the viewer frame

1. timeline_video_layers asks vv_session::frame_provider for the layers of every active video clip at the playhead, bottom to top.
2. If a frame is still being decoded the call returns None and the previous image stays on screen, instead of flashing black where the clip should be. Once the buffer reports it is caught up, a frame that never arrives is dropped so the preview cannot freeze.
3. show_composited renders the layers with the Compositor into a wgpu texture and updates the egui texture in place. If layers and output size match the last frame, nothing is re-uploaded.
4. The frame is composed at the decoded resolution, widened to the timeline's aspect ratio, so letterbox bars appear without upscaling.

Viewer modes

Zoom and pan (viewer_zoom.rs) only change how the texture is drawn, never what is composed. The transport bar (transport.rs) serves both the preview (in/out = range to drop on the timeline) and the timeline (in/out = range to export).