Struct FrameExtractor 

pub struct FrameExtractor { /* private fields */ }

Extracts packed RGB/gray frames from a video input, one pass, for AI/CV.

Build one with FrameExtractor::new, chain options, then call frames for a streaming iterator or collect_frames for a Vec.

Implementations

impl FrameExtractor

pub fn new(input: impl Into<Input>) -> Self

Creates an extractor over input (a path, URL, or anything convertible into an Input). Defaults: all frames, source size, Rgb24, ColorPolicy::Tagged, channel capacity 1.

pub fn sampling(self, sampling: Sampling) -> Self

Sets the sampling strategy (default Sampling::All).

pub fn video_stream_index(self, index: usize) -> Self

Selects an explicit video stream by absolute index (default: best video stream). Also pins the input-side per-frame HDR guard / color stamp to that stream — without it they bind to the first video stream, which coincides with the exported one except on exotic multi-video layouts.

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

Sets the output width in pixels; height (if unset) is derived keeping the aspect ratio (scale=W:-2).

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

Sets the output height in pixels; width (if unset) is derived keeping the aspect ratio (scale=-2:H).

pub fn pixel(self, layout: PixelLayout) -> Self

Sets the packed pixel layout (default PixelLayout::Rgb24).

pub fn color(self, policy: ColorPolicy) -> Self

Sets the color-interpretation policy (default ColorPolicy::Tagged).

pub fn conversion_precision(self, precision: ConversionPrecision) -> Self

Sets the swscale precision tier for the conversion stage — the single swscale pass that runs any resize plus the pixel-format conversion (default ConversionPrecision::Standard, which matches the FFmpeg CLI’s default scaler flags). ConversionPrecision::High opts into accurate rounding + full chroma interpolation at a several-fold conversion cost — see the enum docs for the tradeoff.

pub fn max_frames(self, max: u64) -> Self

Caps the number of exported frames. The sink owns this exact count.

pub fn start_time_us(self, us: i64) -> Self

Seeks to this start time (microseconds) before extracting.

pub fn duration_us(self, us: i64) -> Self

Limits extraction to this many microseconds of content past the start.

pub fn duration_hint_us(self, us: i64) -> Self

Supplies a duration (microseconds) for UniformN when the input is not probeable (live/piped). Ignored by other sampling modes. Takes precedence over the container/stream duration, but not over an explicit duration_us trim window.

pub fn channel_capacity(self, capacity: usize) -> Self

Sets the prefetch channel capacity (default 1, minimum 1). Each slot costs one packed frame of memory.

pub fn frames(self) -> Result<FrameIter>

Starts the run and returns a streaming iterator over the exported frames.

Option and stream/HDR resolution errors surface here, before any frame is produced; runtime failures surface as the iterator’s terminal Err.

pub fn collect_frames(self) -> Result<Vec<VideoFrame>>

Runs to completion and collects every exported frame into a Vec.

On a terminal error the partial frames are dropped and the error is returned; use frames to keep partial output.