Struct VideoDecoder 

pub struct VideoDecoder { /* private fields */ }

A video decoder for extracting frames from media files.

The decoder provides frame-by-frame access to video content with support for seeking, hardware acceleration, and format conversion.

Construction

Use VideoDecoder::open() to create a builder, then call VideoDecoderBuilder::build():

use ff_decode::VideoDecoder;
use ff_format::PixelFormat;

let decoder = VideoDecoder::open("video.mp4")?
    .output_format(PixelFormat::Rgba)
    .build()?;

Frame Decoding

Frames can be decoded one at a time or using an iterator:

// Decode one frame
if let Some(frame) = decoder.decode_one()? {
    println!("Frame at {:?}", frame.timestamp().as_duration());
}

// Use iterator
for frame in decoder.frames().take(100) {
    let frame = frame?;
    // Process frame...
}

Seeking

The decoder supports efficient seeking:

use ff_decode::SeekMode;
use std::time::Duration;

// Seek to 30 seconds (keyframe)
decoder.seek(Duration::from_secs(30), SeekMode::Keyframe)?;

// Seek to exact frame
decoder.seek(Duration::from_secs(30), SeekMode::Exact)?;

Implementations

impl VideoDecoder

pub fn open(path: impl AsRef<Path>) -> VideoDecoderBuilder

Opens a media file and returns a builder for configuring the decoder.

This is the entry point for creating a decoder. The returned builder allows setting options before the decoder is fully initialized.

Arguments

• path - Path to the media file to decode.

Examples

use ff_decode::VideoDecoder;

// Simple usage
let decoder = VideoDecoder::open("video.mp4")?
    .build()?;

// With options
let decoder = VideoDecoder::open("video.mp4")?
    .output_format(PixelFormat::Rgba)
    .hardware_accel(HardwareAccel::Auto)
    .build()?;

Note

This method does not validate that the file exists or is a valid media file. Validation occurs when VideoDecoderBuilder::build() is called.

pub fn stream_info(&self) -> &VideoStreamInfo

Returns the video stream information.

This contains metadata about the video stream including resolution, frame rate, codec, and color characteristics.

pub fn width(&self) -> u32

Returns the video width in pixels.

pub fn height(&self) -> u32

Returns the video height in pixels.

pub fn frame_rate(&self) -> f64

Returns the frame rate in frames per second.

pub fn duration(&self) -> Duration

Returns the total duration of the video.

Returns Duration::ZERO if duration is unknown.

pub fn position(&self) -> Duration

Returns the current playback position.

pub fn is_eof(&self) -> bool

Returns true if the end of stream has been reached.

pub fn path(&self) -> &Path

Returns the file path being decoded.

pub fn frame_pool(&self) -> Option<&Arc<dyn FramePool>>

Returns a reference to the frame pool, if configured.

pub fn hardware_accel(&self) -> HardwareAccel

Returns the currently active hardware acceleration mode.

This method returns the actual hardware acceleration being used, which may differ from what was requested:

• If HardwareAccel::Auto was requested, this returns the specific accelerator that was successfully initialized (e.g., HardwareAccel::Nvdec), or HardwareAccel::None if no hardware acceleration is available.
• If a specific accelerator was requested and initialization failed, the decoder creation would have returned an error.
• If HardwareAccel::None was requested, this always returns HardwareAccel::None.

Examples

use ff_decode::{VideoDecoder, HardwareAccel};

// Request automatic hardware acceleration
let decoder = VideoDecoder::open("video.mp4")?
    .hardware_accel(HardwareAccel::Auto)
    .build()?;

// Check which accelerator was selected
match decoder.hardware_accel() {
    HardwareAccel::None => println!("Using software decoding"),
    HardwareAccel::Nvdec => println!("Using NVIDIA NVDEC"),
    HardwareAccel::Qsv => println!("Using Intel Quick Sync"),
    HardwareAccel::VideoToolbox => println!("Using Apple VideoToolbox"),
    HardwareAccel::Vaapi => println!("Using VA-API"),
    HardwareAccel::Amf => println!("Using AMD AMF"),
    _ => unreachable!(),
}

pub fn decode_one(&mut self) -> Result<Option<VideoFrame>, DecodeError>

Decodes the next video frame.

This method reads and decodes a single frame from the video stream. Frames are returned in presentation order.

Returns

• Ok(Some(frame)) - A frame was successfully decoded
• Ok(None) - End of stream reached, no more frames
• Err(_) - An error occurred during decoding

Errors

Returns DecodeError if:

• Reading from the file fails
• Decoding the frame fails
• Pixel format conversion fails

Examples

use ff_decode::VideoDecoder;

let mut decoder = VideoDecoder::open("video.mp4")?.build()?;

while let Some(frame) = decoder.decode_one()? {
    println!("Frame at {:?}", frame.timestamp().as_duration());
    // Process frame...
}

pub fn frames(&mut self) -> VideoFrameIterator<'_>

Returns an iterator over decoded frames.

This provides a convenient way to iterate over all frames in the video. The iterator will continue until end of stream or an error occurs.

Examples

use ff_decode::VideoDecoder;

let mut decoder = VideoDecoder::open("video.mp4")?.build()?;

// Process first 100 frames
for frame in decoder.frames().take(100) {
    let frame = frame?;
    // Process frame...
}

pub fn decode_range( &mut self, start: Duration, end: Duration, ) -> Result<Vec<VideoFrame>, DecodeError>

Decodes all frames within a specified time range.

This method seeks to the start position and decodes all frames until the end position is reached. Frames outside the range are skipped.

Performance

• The method performs a keyframe seek to the start position
• Frames before start (from nearest keyframe) are decoded but discarded
• All frames within [start, end) are collected and returned
• The decoder position after this call will be at or past end

For large time ranges or high frame rates, this may allocate significant memory. Consider using frames() with manual filtering for very large ranges.

Arguments

• start - Start of the time range (inclusive).
• end - End of the time range (exclusive).

Returns

A vector of frames with timestamps in the range [start, end). Frames are returned in presentation order.

Errors

Returns DecodeError if:

• Seeking to the start position fails
• Decoding frames fails
• The time range is invalid (start >= end)

Examples

use ff_decode::VideoDecoder;
use std::time::Duration;

let mut decoder = VideoDecoder::open("video.mp4")?.build()?;

// Decode frames from 5s to 10s
let frames = decoder.decode_range(
    Duration::from_secs(5),
    Duration::from_secs(10),
)?;

println!("Decoded {} frames", frames.len());
for frame in frames {
    println!("Frame at {:?}", frame.timestamp().as_duration());
}

Memory Usage

At 30fps, a 5-second range will allocate ~150 frames. For 1080p RGBA:

• Each frame: ~8.3 MB (1920 × 1080 × 4 bytes)
• 150 frames: ~1.25 GB

Consider using a frame pool to reduce allocation overhead.

pub fn seek( &mut self, position: Duration, mode: SeekMode, ) -> Result<(), DecodeError>

Seeks to a specified position in the video stream.

This method performs efficient seeking without reopening the file, providing significantly better performance than file-reopen-based seeking (5-10ms vs 50-100ms).

Performance

• Keyframe seeking: 5-10ms (typical GOP 1-2s)
• Exact seeking: 10-50ms depending on GOP size
• Backward seeking: Similar to keyframe seeking

For videos with large GOP sizes (>5 seconds), exact seeking may take longer as it requires decoding all frames from the nearest keyframe to the target.

Choosing a Seek Mode

• Use crate::SeekMode::Keyframe for:

  • Video player scrubbing (approximate positioning)
  • Thumbnail generation
  • Quick preview navigation

• Use crate::SeekMode::Exact for:

  • Frame-accurate editing
  • Precise timestamp extraction
  • Quality-critical operations

• Use crate::SeekMode::Backward for:

  • Guaranteed keyframe positioning
  • Preparing for forward playback

Arguments

• position - Target position to seek to.
• mode - Seek mode determining accuracy and performance.

Errors

Returns DecodeError::SeekFailed if:

• The target position is beyond the video duration
• The file format doesn’t support seeking
• The seek operation fails internally

Examples

use ff_decode::{VideoDecoder, SeekMode};
use std::time::Duration;

let mut decoder = VideoDecoder::open("video.mp4")?.build()?;

// Fast seek to 30 seconds (keyframe)
decoder.seek(Duration::from_secs(30), SeekMode::Keyframe)?;

// Exact seek to 1 minute
decoder.seek(Duration::from_secs(60), SeekMode::Exact)?;

// Seek and decode next frame
decoder.seek(Duration::from_secs(10), SeekMode::Keyframe)?;
if let Some(frame) = decoder.decode_one()? {
    println!("Frame at {:?}", frame.timestamp().as_duration());
}

pub fn flush(&mut self)

Flushes the decoder’s internal buffers.

This method clears any cached frames and resets the decoder state. The decoder is ready to receive new packets after flushing.

When to Use

• After seeking to ensure clean state
• Before switching between different parts of the video
• To clear buffered frames after errors

Examples

use ff_decode::VideoDecoder;

let mut decoder = VideoDecoder::open("video.mp4")?.build()?;

// Decode some frames...
for _ in 0..10 {
    decoder.decode_one()?;
}

// Flush and start fresh
decoder.flush();

Note

Calling seek() automatically flushes the decoder, so you don’t need to call this method explicitly after seeking.

pub fn thumbnail_at( &mut self, position: Duration, width: u32, height: u32, ) -> Result<VideoFrame, DecodeError>

Generates a thumbnail at a specific timestamp.

This method seeks to the specified position, decodes a frame, and scales it to the target dimensions. It’s optimized for thumbnail generation by using keyframe seeking for speed.

Performance

• Seeking: 5-10ms (keyframe mode)
• Decoding: 5-10ms for 1080p H.264
• Scaling: 1-3ms for 1080p → 320x180
• Total: ~10-25ms per thumbnail

Aspect Ratio

The thumbnail preserves the video’s aspect ratio using a “fit-within” strategy. The output dimensions will be at most the target size, with at least one dimension matching the target. No letterboxing is applied.

Arguments

• position - Timestamp to extract the thumbnail from.
• width - Target thumbnail width in pixels.
• height - Target thumbnail height in pixels.

Returns

A scaled VideoFrame representing the thumbnail.

Errors

Returns DecodeError if:

• Seeking to the position fails
• No frame can be decoded at that position (DecodeError::EndOfStream)
• Scaling fails

Examples

use ff_decode::VideoDecoder;
use std::time::Duration;

let mut decoder = VideoDecoder::open("video.mp4")?.build()?;

// Generate a 320x180 thumbnail at 5 seconds
let thumbnail = decoder.thumbnail_at(
    Duration::from_secs(5),
    320,
    180,
)?;

assert_eq!(thumbnail.width(), 320);
assert_eq!(thumbnail.height(), 180);

Use Cases

• Video player scrubbing preview
• Timeline thumbnail strips
• Gallery view thumbnails
• Social media preview images

pub fn thumbnails( &mut self, count: usize, width: u32, height: u32, ) -> Result<Vec<VideoFrame>, DecodeError>

Generates multiple thumbnails evenly distributed across the video.

This method creates a series of thumbnails by dividing the video duration into equal intervals and extracting a frame at each position. This is commonly used for timeline preview strips or video galleries.

Performance

For a 2-minute video generating 10 thumbnails:

• Per thumbnail: ~10-25ms (see thumbnail_at())
• Total: ~100-250ms

Performance scales linearly with the number of thumbnails.

Thumbnail Positions

Thumbnails are extracted at evenly spaced intervals:

• Position 0: 0s
• Position 1: duration / count
• Position 2: 2 * (duration / count)
• …
• Position N-1: (N-1) * (duration / count)

Arguments

• count - Number of thumbnails to generate.
• width - Target thumbnail width in pixels.
• height - Target thumbnail height in pixels.

Returns

A vector of VideoFrame thumbnails in temporal order.

Errors

Returns DecodeError if:

• Any individual thumbnail generation fails (see thumbnail_at())
• The video duration is unknown (Duration::ZERO)
• Count is zero

Examples

use ff_decode::VideoDecoder;

let mut decoder = VideoDecoder::open("video.mp4")?.build()?;

// Generate 10 thumbnails at 160x90 resolution
let thumbnails = decoder.thumbnails(10, 160, 90)?;

assert_eq!(thumbnails.len(), 10);
for thumb in thumbnails {
    assert_eq!(thumb.width(), 160);
    assert_eq!(thumb.height(), 90);
}

Use Cases

• Timeline preview strips (like YouTube’s timeline hover)
• Video gallery grid views
• Storyboard generation for editing
• Video summary/preview pages

Memory Usage

For 10 thumbnails at 160x90 RGBA:

• Per thumbnail: ~56 KB (160 × 90 × 4 bytes)
• Total: ~560 KB

This is typically acceptable, but consider using a smaller resolution or generating thumbnails on-demand for very large thumbnail counts.