Crate ffmpeg_light

Expand description

§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 is a small Rust crate that wraps a few common FFmpeg tasks.

It focuses on the “80% use cases” like probing media, transcoding, and generating thumbnails, without exposing the full complexity of FFmpeg.

§Quick Start

Add to your Cargo.toml:

[dependencies]
ffmpeg-light = "0.1"

Note: This crate requires ffmpeg and ffprobe binaries to be installed and available on PATH.

§Example: Probe a video file

use ffmpeg_light::probe;

let result = probe("input.mp4")?;
println!("Duration: {:?}", result.duration());

§Example: Transcode to H.264 MP4

use ffmpeg_light::transcode::TranscodeBuilder;

TranscodeBuilder::new()
    .input("input.avi")
    .output("output.mp4")
    .video_codec("libx264")
    .run()?;

Re-exports§

pub use error::Error;
pub use error::Result;
pub use filter::AudioFilter;
pub use filter::VideoFilter;
pub use probe::probe;
pub use thumbnail::generate as generate_thumbnail;
pub use transcode::TranscodeBuilder;
pub use types::*;

Modules§

command: Low-level process helpers for interacting with ffmpeg and ffprobe. Low-level helpers for invoking the ffmpeg and ffprobe binaries.
config: Configuration helpers for locating ffmpeg binaries. Configuration helpers for locating FFmpeg binaries.
error: Shared error type and Result alias used by the crate.
filter: Small collection of filter helpers used by transcoding. Video and audio filter definitions. Filters can be composed into chains for complex processing.
probe: Media probing API built on top of ffprobe JSON output. Media probing utilities built on top of ffprobe.
thumbnail: Thumbnail generation helpers. Thumbnail generation helpers.
transcode: Builder API around common transcoding flows. Transcoding helpers built on top of the CLI ffmpeg binary.
types: Shared domain types (timecodes, codecs, stream metadata). Common domain types shared across the crate.