Struct DecodeBuffer 

pub struct DecodeBuffer { /* private fields */ }

Pre-decodes frames from a video file into a ring buffer on a background thread.

DecodeBuffer decouples decoder latency from the presentation loop: the background thread keeps the buffer filled so pop_frame can return the next frame without waiting for the decoder.

The default ring buffer capacity is 8 frames. Use open → capacity → build to configure a different size.

Usage

let mut buf = DecodeBuffer::open(Path::new("clip.mp4"))
    .capacity(16)
    .build()?;

while let Some(frame) = buf.pop_frame() {
    // present frame…
}

Thread safety

DecodeBuffer is Send but not Sync; it must be owned by a single consumer. The internal std::sync::mpsc::Receiver enforces this.

Implementations

impl DecodeBuffer

pub fn open(path: &Path) -> DecodeBufferBuilder

Open the video at path and return a builder for configuring the buffer.

Chain with DecodeBufferBuilder::capacity and DecodeBufferBuilder::build to start decoding.

pub fn pop_frame(&mut self) -> FrameResult

Pop the next decoded frame.

• Returns FrameResult::Seeking immediately (non-blocking) while a seek_async is in progress.
• Returns FrameResult::Frame when a frame is available; blocks until the background thread produces one.
• Returns FrameResult::Eof when the background thread reaches end of file or the channel is disconnected.

pub fn buffered_frames(&self) -> usize

Returns an approximation of the number of decoded frames currently waiting in the buffer.

This value is advisory only; it may lag the actual buffer state by one scheduling quantum. Use it for diagnostics, not flow control.

pub fn seek_events(&self) -> &Receiver<SeekEvent>

Returns a reference to the seek event receiver.

After calling seek_async, poll this receiver to detect when the seek has completed:

• try_recv() — non-blocking; returns Err(TryRecvError::Empty) while the seek is still in progress.
• recv() — blocks until the seek finishes.

Events are delivered within ~200 ms for local files. Unconsumed events accumulate in the channel (one per completed seek).

pub fn error_events(&self) -> &Receiver<String>

Returns the receiver for non-fatal decode error messages.

Poll with try_recv() in the presentation loop. Each message corresponds to one failed decode_one() call in the background thread. The background thread exits after sending the error, so pop_frame will return Eof shortly after.

pub fn seek(&mut self, target_pts: Duration) -> Result<(), PreviewError>

Frame-accurate seek to target_pts.

Stops the background decode thread, seeks the underlying decoder to the nearest preceding I-frame (AVSEEK_FLAG_BACKWARD + codec buffer flush), then restarts the thread. The restarted thread discards frames until PTS ≥ target_pts before making them available via pop_frame.

Blocks until the thread has stopped and the seek has been accepted by the decoder. Frames are filled asynchronously after the method returns.

Errors

Returns PreviewError::SeekFailed if the decode thread panicked or if the underlying FFmpeg seek fails.

pub fn seek_coarse(&mut self, target_pts: Duration) -> Result<(), PreviewError>

Coarse seek to the nearest I-frame at or before target_pts.

Faster than seek because it skips the forward-decode discard step. The next pop_frame returns the frame at the I-frame position, which may be up to ±½ GOP before target_pts (typically ±1–2 s for H.264 at default settings).

Typical use: call repeatedly while a scrub-bar is being dragged; call seek on mouse-up for frame accuracy.

Errors

Returns PreviewError::SeekFailed if the decode thread panicked or if the underlying FFmpeg seek fails.

pub fn seek_async(&mut self, target_pts: Duration)

Initiate a frame-accurate seek on a background thread and return immediately.

While seeking is in progress, pop_frame returns FrameResult::Seeking with the last successfully decoded frame as a placeholder. Normal FrameResult::Frame values resume once the seek completes.

The seek uses the same frame-accurate strategy as seek: FFmpeg jumps to the nearest preceding I-frame, then frames before target_pts are discarded before the first frame is made available.

If called again before the previous seek completes, the new seek supersedes the old one; the old worker exits at the next cancel check.

Panics

Panics (inside the background worker thread) if the previous decode thread panicked — an internal bug that should never occur in practice.

Trait Implementations

impl Drop for DecodeBuffer

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.