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 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_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 frame in decoder.frames().take(100) {
    let frame = frame?;
    // Process frame...
}

Trait Implementations

impl Debug for VideoDecoderBuilder

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

Formats the value using the given formatter.