Struct VideoDecoderBuilder 

pub struct VideoDecoderBuilder { /* private fields */ }

Builder for configuring and constructing a VideoDecoder.

This struct provides a fluent interface for setting up decoder options before opening a video file. It is created by calling VideoDecoder::open().

Examples

Basic Usage

use ff_decode::VideoDecoder;

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

With Custom Format

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

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

With Hardware Acceleration

use ff_decode::{VideoDecoder, HardwareAccel};

let decoder = VideoDecoder::open("video.mp4")?
    .hardware_accel(HardwareAccel::Nvdec)
    .build()?;

With Frame Pool

use ff_decode::{VideoDecoder, FramePool};
use std::sync::Arc;

let pool: Arc<dyn FramePool> = create_frame_pool();
let decoder = VideoDecoder::open("video.mp4")?
    .frame_pool(pool)
    .build()?;

Implementations

impl VideoDecoderBuilder

pub fn output_format(self, format: PixelFormat) -> Self

Sets the output pixel format for decoded frames.

If not set, frames are returned in the source format. Setting an output format enables automatic conversion during decoding.

Common Formats

• PixelFormat::Rgba - Best for UI rendering, includes alpha
• PixelFormat::Rgb24 - RGB without alpha, smaller memory footprint
• PixelFormat::Yuv420p - Source format for most H.264/H.265 videos

Examples

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

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

pub fn output_size(self, width: u32, height: u32) -> Self

Scales decoded frames to the given exact dimensions.

The frame is scaled in the same libswscale pass as pixel-format conversion, so there is no extra copy. If output_format is not set, the source pixel format is preserved while scaling.

Width and height must be greater than zero. They are rounded up to the nearest even number if necessary (required by most pixel formats).

Calling this method overwrites any previous output_width or output_height call. The last setter wins.

Errors

build() returns DecodeError::InvalidOutputDimensions if either dimension is zero after rounding.

Examples

use ff_decode::VideoDecoder;

// Decode every frame at 320×240
let decoder = VideoDecoder::open("video.mp4")?
    .output_size(320, 240)
    .build()?;

pub fn output_width(self, width: u32) -> Self

Scales decoded frames to the given width, preserving the aspect ratio.

The height is computed from the source aspect ratio and rounded to the nearest even number. Calling this method overwrites any previous output_size or output_height call. The last setter wins.

Errors

build() returns DecodeError::InvalidOutputDimensions if width is zero.

Examples

use ff_decode::VideoDecoder;

// Decode at 1280 px wide, preserving aspect ratio
let decoder = VideoDecoder::open("video.mp4")?
    .output_width(1280)
    .build()?;

pub fn output_height(self, height: u32) -> Self

Scales decoded frames to the given height, preserving the aspect ratio.

The width is computed from the source aspect ratio and rounded to the nearest even number. Calling this method overwrites any previous output_size or output_width call. The last setter wins.

Errors

build() returns DecodeError::InvalidOutputDimensions if height is zero.

Examples

use ff_decode::VideoDecoder;

// Decode at 720 px tall, preserving aspect ratio
let decoder = VideoDecoder::open("video.mp4")?
    .output_height(720)
    .build()?;

pub fn hardware_accel(self, accel: HardwareAccel) -> Self

Sets the hardware acceleration mode.

Hardware acceleration can significantly improve decoding performance, especially for high-resolution video (4K and above).

Available Modes

• HardwareAccel::Auto - Automatically detect and use available hardware (default)
• HardwareAccel::None - Disable hardware acceleration (CPU only)
• HardwareAccel::Nvdec - NVIDIA NVDEC (requires NVIDIA GPU)
• HardwareAccel::Qsv - Intel Quick Sync Video
• HardwareAccel::Amf - AMD Advanced Media Framework
• HardwareAccel::VideoToolbox - Apple VideoToolbox (macOS/iOS)
• HardwareAccel::Vaapi - VA-API (Linux)

Fallback Behavior

If the requested hardware accelerator is unavailable, the decoder will fall back to software decoding unless DecodeError::HwAccelUnavailable is explicitly requested.

Examples

use ff_decode::{VideoDecoder, HardwareAccel};

// Use NVIDIA NVDEC if available
let decoder = VideoDecoder::open("video.mp4")?
    .hardware_accel(HardwareAccel::Nvdec)
    .build()?;

// Force CPU decoding
let cpu_decoder = Decoder::open("video.mp4")?
    .hardware_accel(HardwareAccel::None)
    .build()?;

pub fn thread_count(self, count: usize) -> Self

Sets the number of decoding threads.

More threads can improve decoding throughput, especially for high-resolution videos or codecs that support parallel decoding.

Thread Count Values

• 0 - Auto-detect based on CPU cores (default)
• 1 - Single-threaded decoding
• N - Use N threads for decoding

Performance Notes

• H.264/H.265: Benefit significantly from multi-threading
• VP9: Good parallel decoding support
• ProRes: Limited threading benefit

Setting too many threads may increase memory usage without proportional performance gains.

Examples

use ff_decode::VideoDecoder;

// Use 4 threads for decoding
let decoder = VideoDecoder::open("video.mp4")?
    .thread_count(4)
    .build()?;

// Single-threaded for minimal memory
let decoder = VideoDecoder::open("video.mp4")?
    .thread_count(1)
    .build()?;

pub fn frame_rate(self, fps: u32) -> Self

Sets the frame rate for image sequence decoding.

Only used when the path contains % (e.g. "frames/frame%04d.png"). Defaults to 25 fps when not set.

Examples

use ff_decode::VideoDecoder;

let decoder = VideoDecoder::open("frames/frame%04d.png")?
    .frame_rate(30)
    .build()?;

pub fn frame_pool(self, pool: Arc<dyn FramePool>) -> Self

Sets a frame pool for memory reuse.

Using a frame pool can significantly reduce allocation overhead during continuous video playback by reusing frame buffers.

Memory Management

When a frame pool is set:

• Decoded frames attempt to acquire buffers from the pool
• When frames are dropped, their buffers are returned to the pool
• If the pool is exhausted, new buffers are allocated normally

Examples

use ff_decode::{VideoDecoder, FramePool, PooledBuffer};
use std::sync::{Arc, Mutex};

// Create a simple frame pool
struct SimplePool {
    buffers: Mutex<Vec<Vec<u8>>>,
}

impl FramePool for SimplePool {
    fn acquire(&self, size: usize) -> Option<PooledBuffer> {
        // Implementation...
        None
    }
}

let pool = Arc::new(SimplePool {
    buffers: Mutex::new(vec![]),
});

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

pub fn path(&self) -> &Path

Returns the configured file path.

pub fn get_output_format(&self) -> Option<PixelFormat>

Returns the configured output format, if any.

pub fn get_hardware_accel(&self) -> HardwareAccel

Returns the configured hardware acceleration mode.

pub fn get_thread_count(&self) -> usize

Returns the configured thread count.

pub fn build(self) -> Result<VideoDecoder, DecodeError>

Builds the decoder with the configured options.

This method opens the media file, initializes the decoder context, and prepares for frame decoding.

Errors

Returns an error if:

• The file cannot be found (DecodeError::FileNotFound)
• The file contains no video stream (DecodeError::NoVideoStream)
• The codec is not supported (DecodeError::UnsupportedCodec)
• Hardware acceleration is unavailable (DecodeError::HwAccelUnavailable)
• Other FFmpeg errors occur (DecodeError::Ffmpeg)

Examples

use ff_decode::VideoDecoder;

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

// Start decoding
for result in &mut decoder {
    let frame = result?;
    // Process frame...
}

Trait Implementations

impl Debug for VideoDecoderBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.