Struct ThumbnailHandle 

pub struct ThumbnailHandle;

Thumbnail generation utilities.

All methods are stateless functions that accept a MediaFile reference.

Example

use std::time::Duration;

use unbundle::{MediaFile, ThumbnailHandle, ThumbnailOptions, UnbundleError};

let mut unbundler = MediaFile::open("input.mp4")?;

// Single thumbnail at 10 seconds, max 640px on longest edge
let thumb = ThumbnailHandle::at_timestamp(
    &mut unbundler,
    Duration::from_secs(10),
    640,
)?;
thumb.save("thumb.jpg")?;

// Contact-sheet grid
let config = ThumbnailOptions::new(4, 4);
let grid = ThumbnailHandle::grid(&mut unbundler, &config)?;
grid.save("grid.png")?;

Implementations

impl ThumbnailHandle

pub fn at_timestamp( unbundler: &mut MediaFile, timestamp: Duration, max_dimension: u32, ) -> Result<DynamicImage, UnbundleError>

Extract a single thumbnail at a timestamp, scaled to fit within max_dimension on its longest edge.

Preserves the video’s aspect ratio. For example, a 1920×1080 frame with max_dimension = 640 produces a 640×360 thumbnail.

Errors

Returns UnbundleError::NoVideoStream if the file has no video, UnbundleError::InvalidTimestamp if the timestamp exceeds the duration, or decoding errors.

pub fn at_frame( unbundler: &mut MediaFile, frame_number: u64, max_dimension: u32, ) -> Result<DynamicImage, UnbundleError>

Extract a single thumbnail at a frame number, scaled to fit within max_dimension on its longest edge.

Errors

Same as at_timestamp.

pub fn grid( unbundler: &mut MediaFile, config: &ThumbnailOptions, ) -> Result<DynamicImage, UnbundleError>

Generate a thumbnail contact-sheet grid.

Extracts columns × rows frames at evenly-spaced intervals across the video, scales them to the configured thumbnail width (preserving aspect ratio), and composites them into a single image.

Errors

Returns UnbundleError::NoVideoStream if the file has no video, or decoding / image errors.

Example

use unbundle::{MediaFile, ThumbnailHandle, ThumbnailOptions, UnbundleError};

let mut unbundler = MediaFile::open("input.mp4")?;
let config = ThumbnailOptions::new(4, 4).with_thumbnail_width(240);
let grid = ThumbnailHandle::grid(&mut unbundler, &config)?;
grid.save("contact_sheet.png")?;

pub fn grid_with_options( unbundler: &mut MediaFile, config: &ThumbnailOptions, extraction_config: &ExtractOptions, ) -> Result<DynamicImage, UnbundleError>

Generate a thumbnail grid with progress/cancellation support.

Like grid but accepts an ExtractOptions for progress callbacks and cancellation.

pub fn smart( unbundler: &mut MediaFile, sample_count: u32, max_dimension: u32, ) -> Result<DynamicImage, UnbundleError>

Extract a “smart” thumbnail that avoids black or near-uniform frames.

Samples sample_count frames evenly across the video and picks the one with the highest pixel variance (most visual detail). The chosen frame is then scaled to fit within max_dimension.

This is useful for generating representative thumbnails without relying on a fixed timestamp that might land on a fade-to-black or title card.

Errors

Returns UnbundleError::NoVideoStream if the file has no video, or decoding errors.

Example

use unbundle::{MediaFile, ThumbnailHandle, UnbundleError};

let mut unbundler = MediaFile::open("input.mp4")?;
let thumb = ThumbnailHandle::smart(&mut unbundler, 20, 640)?;
thumb.save("smart_thumb.jpg")?;

pub fn smart_with_options( unbundler: &mut MediaFile, sample_count: u32, max_dimension: u32, extraction_config: &ExtractOptions, ) -> Result<DynamicImage, UnbundleError>

Extract a smart thumbnail with progress/cancellation support.

Like smart but accepts an ExtractOptions for progress callbacks and cancellation.