ffmpeg-light

A Rust crate that wraps common FFmpeg tasks without the CLI memorization. Transcode, probe, filter, and process video/audio with a clean, type-safe API.

Features

Video & Audio Filters: Scale, crop, rotate, flip, denoise, deinterlace, volume control, equalization, normalization, and more
Fluent Builder API: Chain operations naturally with TranscodeBuilder
Robust Error Handling: Granular error types with contextual recovery suggestions
Media Probing: Extract duration, codecs, resolutions, and stream information
Thumbnail Generation: Extract frames at specific timestamps with size control
Filter Composition: Build complex filter chains with automatic optimization
Zero Breaking Changes: All v0.1.0 APIs remain fully supported

Why this exists

FFmpeg is powerful but the CLI has hundreds of flags. Using raw C bindings means managing C library builds. This crate sits in the middle: spawns the ffmpeg/ffprobe binaries you already have and gives you a type-safe Rust API.

Install

[dependencies]
ffmpeg-light = "0.2"

Requires ffmpeg and ffprobe on PATH. Get them via:

macOS: brew install ffmpeg
Linux: apt install ffmpeg (or equivalent)
Windows: ffmpeg.org

Quick Start

Probe a file

use ffmpeg_light::probe;

fn main() -> ffmpeg_light::Result<()> {
    let info = probe("input.mp4")?;
    println!("Duration: {:?}", info.duration());
    Ok(())
}

Transcode with filters

use ffmpeg_light::{AudioFilter, TranscodeBuilder, VideoFilter};

fn main() -> ffmpeg_light::Result<()> {
    TranscodeBuilder::new()
        .input("input.avi")
        .output("output.mp4")
        .video_codec("libx264")
        .audio_codec("aac")
        .video_bitrate(2500)
        .add_video_filter(VideoFilter::Scale {
            width: 1280,
            height: 720,
        })
        .add_audio_filter(AudioFilter::Normalization {
            target_level: -23.0,
        })
        .run()?;
    Ok(())
}

Apply multiple filters

use ffmpeg_light::{AudioFilter, TranscodeBuilder, VideoFilter};

fn main() -> ffmpeg_light::Result<()> {
    TranscodeBuilder::new()
        .input("raw.mov")
        .output("processed.mp4")
        .add_video_filter(VideoFilter::Crop {
            width: 1920,
            height: 1080,
            x: 0,
            y: 0,
        })
        .add_video_filter(VideoFilter::Denoise {
            strength: ffmpeg_light::filter::DenoiseStrength::Medium,
        })
        .add_audio_filter(AudioFilter::Normalization {
            target_level: -23.0,
        })
        .video_codec("libx264")
        .audio_codec("aac")
        .run()?;
    Ok(())
}

Grab a thumbnail

use ffmpeg_light::{thumbnail::ThumbnailOptions, types::Time};

fn main() -> ffmpeg_light::Result<()> {
    let options = ThumbnailOptions::new(Time::from_seconds_f64(12.5));
    ffmpeg_light::generate_thumbnail("input.mp4", "thumb.png", &options)?;
    Ok(())
}

API Overview

Transcoding & Filters

TranscodeBuilder: Fluent API for configuring transcoding jobs
- .video_codec(), .audio_codec(): Set output codecs
- .video_bitrate(), .audio_bitrate(): Control quality/file size
- .add_video_filter(), .add_audio_filter(): Chain filters
- .preset(): Encoding preset (e.g., "fast", "medium", "slow")
- .size(): Shortcut for Scale filter
- .run(): Execute the transcode job

Video Filters

Scale: Resize video
Crop: Extract a region
Trim: Cut a time range
Rotate: Rotate by degrees
Flip: Mirror horizontally or vertically
BrightnessContrast: Adjust brightness/contrast
Denoise: Reduce noise (Light/Medium/Heavy)
Deinterlace: Convert interlaced to progressive
Custom: Raw FFmpeg filter syntax

Audio Filters

Volume: Adjust audio level
Equalizer: 3-band EQ (bass, mid, treble)
Normalization: Normalize to target loudness
HighPass, LowPass: Frequency filtering
Custom: Raw FFmpeg audio filter syntax

Media Inspection

probe(path): Get file duration, codecs, resolution, frame rate, and bit rates
ProbeResult: Video/audio stream metadata

Thumbnails

generate_thumbnail(input, output, options): Extract frame at timestamp
ThumbnailOptions: Control timestamp, size, and format

Error Handling

The crate provides granular error types with recovery suggestions:

use ffmpeg_light::Error;

match some_operation() {
    Err(Error::FFmpegNotFound { suggestion }) => {
        eprintln!("FFmpeg not found. Help: {:?}", suggestion);
    }
    Err(Error::InvalidInput(msg)) => {
        eprintln!("Bad parameters: {}", msg);
    }
    Err(Error::FilterError(msg)) => {
        eprintln!("Filter problem: {}", msg);
    }
    Ok(_) => {}
    Err(e) => eprintln!("Error: {}", e),
}

Design notes

The crate shells out to ffmpeg/ffprobe. That keeps builds fast, works anywhere binaries exist, and avoids shipping unsafe C bindings.
Arguments are never handed to a shell; every value goes directly to std::process::Command.
If you need the full FFmpeg surface area, drop down to the CLI; this crate handles the frequent, repetitive tasks.

Supported Platforms

Tested on Linux, macOS, and Windows. Requires ffmpeg and ffprobe on PATH:

macOS: brew install ffmpeg
Linux: apt install ffmpeg (or distro equivalent)
Windows: Download from ffmpeg.org

Paths on Windows work best without spaces. The builder handles argument quoting automatically.

v0.2.0 Release Highlights

✅ 8 Video Filters: Scale, Crop, Trim, Rotate, Flip, BrightnessContrast, Denoise, Deinterlace
✅ 6 Audio Filters: Volume, Equalizer, Normalization, HighPass, LowPass, Custom
✅ Granular Error Types: FFmpegNotFound, ProcessingError, InvalidInput, FilterError, TimeoutError
✅ Builder Accessors: Inspect configured filters, codecs, and settings
✅ 41 Integration Tests: Comprehensive coverage of filters, error handling, and builder composition
✅ Zero Breaking Changes: All v0.1.0 APIs remain fully compatible

Roadmap

Async command helpers behind a tokio feature gate
Batch processing with parallel transcoding
Hardware acceleration (NVIDIA NVENC, Intel QuickSync, Apple VideoToolbox)
Streaming segment output (HLS/DASH)
Subtitle and chapter handling

License

Licensed under the Apache License, Version 2.0.

ffmpeg-light 0.2.0