Skip to main content

Crate unbundle

Crate unbundle 

Source
Expand description

§unbundle

Unbundle media files — extract still frames, audio tracks, and subtitles from video files.

unbundle provides a clean, ergonomic API for extracting video frames as image::DynamicImage values, audio tracks as encoded byte vectors, and subtitle tracks as structured text, powered by FFmpeg via the ffmpeg-next crate.

§Quick Start

§Extract a Video Frame

use unbundle::MediaFile;

let mut unbundler = MediaFile::open("input.mp4").unwrap();
let frame = unbundler.video().frame(0).unwrap();
frame.save("first_frame.png").unwrap();

§Extract Audio

use unbundle::{AudioFormat, MediaFile};

let mut unbundler = MediaFile::open("input.mp4").unwrap();
unbundler.audio().save("output.wav", AudioFormat::Wav).unwrap();

§Extract Frames by Range

use std::time::Duration;

use unbundle::{FrameRange, MediaFile};

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

// Every 30th frame
let frames = unbundler.video().frames(FrameRange::Interval(30)).unwrap();

// Frames between two timestamps
let frames = unbundler.video().frames(
    FrameRange::TimeRange(Duration::from_secs(10), Duration::from_secs(20))
).unwrap();

§Extract Subtitles

use unbundle::{MediaFile, SubtitleFormat};

let mut unbundler = MediaFile::open("input.mkv").unwrap();
unbundler.subtitle().save("output.srt", SubtitleFormat::Srt).unwrap();

§Open URL / Source String

use unbundle::MediaFile;

let mut unbundler = MediaFile::open_url("https://example.com/video.mp4").unwrap();
println!("{}", unbundler.metadata().format);

§Features

  • Frame extraction — by frame number, timestamp, range, interval, or specific frame list
  • Audio extraction — to WAV, MP3, FLAC, or AAC (file or in-memory)
  • Subtitle extraction — decode text-based subtitles to SRT, WebVTT, or raw text
  • Container remuxing — lossless format conversion (e.g. MKV → MP4)
  • Raw stream copy — packet-level stream extraction to file/memory without re-encoding
  • Rich metadata — video dimensions, frame rate, frame count, audio sample rate, channels, codec info, multi-track audio/subtitle metadata
  • Configurable output — pixel format (RGB8, RGBA8, GRAY8) and target resolution with aspect ratio preservation
  • Custom FFmpeg filters — apply filter graphs during frame extraction
  • Progress & cancellation — cooperative callbacks and CancellationToken for long-running operations
  • Streaming iteration — lazy FrameIterator (pull-based) and for_each_frame (push-based) without buffering entire frame sets
  • Validation — inspect media files for structural issues before extraction
  • Chapter support — extract chapter metadata (titles, timestamps)
  • Frame metadata — per-frame decode info (PTS, keyframe, picture type)
  • Segmented extraction — extract from multiple disjoint time ranges
  • Stream probing — lightweight MediaProbe for quick inspection
  • Thumbnail helpers — single thumbnails, grids, and smart selection
  • Efficient seeking — seeks to nearest keyframe, then decodes forward
  • Zero-copy in-memory audio — uses FFmpeg’s dynamic buffer I/O
  • Flexible source opening — open from local paths, URL inputs, and FFmpeg source strings

§Optional Features

FeatureDescription
asyncFrameStream and AudioFuture for async extraction via Tokio
rayonframes_parallel() distributes decoding across rayon threads
hardwareHardware-accelerated decoding (CUDA, VAAPI, DXVA2, D3D11VA, VideoToolbox, QSV)
sceneScene change detection via FFmpeg’s scdet filter
gifAnimated GIF export from video frames
waveformAudio waveform visualization data (min/max/RMS per bin)
loudnessPeak/RMS loudness analysis with dBFS conversion
transcodeAudio re-encoding between formats
encodeEncode DynamicImage sequences into video files
fullEnables all of the above

§Requirements

FFmpeg development libraries must be installed on your system. See the README for platform-specific instructions.

Re-exports§

pub use audio::AudioFormat;
pub use audio::AudioHandle;
pub use audio_iterator::AudioChunk;
pub use audio_iterator::AudioIterator;
pub use configuration::ExtractOptions;
pub use configuration::FrameOutputOptions;
pub use configuration::PixelFormat;
pub use encode::VideoCodec;
pub use encode::VideoEncoder;
pub use encode::VideoEncoderOptions;
pub use error::UnbundleError;
pub use ffmpeg::FfmpegLogLevel;
pub use ffmpeg::get_ffmpeg_log_level;
pub use ffmpeg::set_ffmpeg_log_level;
pub use gif::GifOptions;
pub use hardware_acceleration::HardwareAccelerationMode;
pub use hardware_acceleration::HardwareDeviceType;
pub use keyframe::GroupOfPicturesInfo;
pub use keyframe::KeyFrameMetadata;
pub use loudness::LoudnessInfo;
pub use metadata::AudioMetadata;
pub use metadata::ChapterMetadata;
pub use metadata::MediaMetadata;
pub use metadata::SubtitleMetadata;
pub use metadata::VideoMetadata;
pub use packet_iterator::PacketInfo;
pub use packet_iterator::PacketIterator;
pub use probe::MediaProbe;
pub use progress::CancellationToken;
pub use progress::OperationType;
pub use progress::ProgressCallback;
pub use progress::ProgressInfo;
pub use remux::Remuxer;
pub use scene::SceneChange;
pub use scene::SceneDetectionMode;
pub use scene::SceneDetectionOptions;
pub use stream::AudioFuture;
pub use stream::FrameStream;
pub use subtitle::BitmapSubtitleEvent;
pub use subtitle::SubtitleEvent;
pub use subtitle::SubtitleFormat;
pub use subtitle::SubtitleHandle;
pub use thumbnail::ThumbnailHandle;
pub use thumbnail::ThumbnailOptions;
pub use transcode::Transcoder;
pub use unbundle::MediaFile;
pub use validation::ValidationReport;
pub use variable_framerate::VariableFrameRateAnalysis;
pub use video::FilterChainHandle;
pub use video::FrameMetadata;
pub use video::FrameRange;
pub use video::FrameType;
pub use video::RawFrameView;
pub use video::VideoHandle;
pub use video_iterator::FrameIterator;
pub use waveform::WaveformBin;
pub use waveform::WaveformData;
pub use waveform::WaveformOptions;

Modules§

audio
Audio extraction.
audio_iterator
Lazy pull-based audio sample iteration.
configuration
Extraction configuration.
encode
Video encoder — encode a sequence of frames into a video file.
error
Error types for the unbundle crate.
ffmpeg
FFmpeg log level configuration.
gif
GIF export from video frames.
hardware_acceleration
Hardware-accelerated video decoding.
keyframe
Keyframe and Group of Pictures analysis.
loudness
Audio loudness analysis.
metadata
Media metadata types.
packet_iterator
Raw packet-level iteration.
probe
Lightweight media file probing.
progress
Progress reporting and cancellation support.
remux
Container format conversion (remuxing).
scene
Scene change detection.
stream
Async streaming for video and audio extraction.
subtitle
Subtitle extraction.
thumbnail
Thumbnail generation utilities.
transcode
Audio transcoding (re-encoding between formats).
unbundle
Core MediaFile implementation.
validation
Media file validation.
variable_framerate
Variable frame rate (VFR) detection and analysis.
video
Video frame extraction.
video_iterator
Lazy, pull-based video frame iterator.
waveform
Audio waveform generation.