ff-sys

Low-level FFmpeg FFI bindings for Rust.

Overview

ff-sys provides raw FFI bindings to FFmpeg libraries, generated by bindgen. This crate is intended as a building block for higher-level safe wrappers.

Features

• Complete FFmpeg bindings: Auto-generated bindings via bindgen
• Wrapper modules: Thin Rust wrappers for common operations
  • avcodec - Codec operations (encode/decode)
  • avformat - Container format I/O
  • swscale - Video scaling and color conversion
  • swresample - Audio resampling
• Error handling utilities: av_error_string() and check_av_error! macro
• Cross-platform: Windows (VCPKG), Linux, macOS

Supported Platforms

Prerequisites

FFmpeg development libraries must be installed on your system.

Windows

# Install via VCPKG (recommended)
vcpkg install ffmpeg:x64-windows

# Set environment variables
$env:VCPKG_ROOT = "C:\vcpkg"

Linux (Debian/Ubuntu)

sudo apt install libavcodec-dev libavformat-dev libswscale-dev libswresample-dev

macOS

brew install ffmpeg

Minimum Supported Rust Version

Rust 1.93.0 or later (edition 2024).

Usage

Note: This crate provides unsafe FFI bindings. Consider using higher-level wrappers from the ff-* crate family for safe abstractions.

Basic Example

use ff_sys::{ensure_initialized, av_error_string, check_av_error};

fn main() {
    // Initialize FFmpeg (idempotent)
    ensure_initialized();

    // Error handling example
    let error_msg = av_error_string(-12); // ENOMEM
    println!("Error: {}", error_msg);
}

Using Wrapper Modules

use ff_sys::swscale::{get_context, scale, free_context, scale_flags};
use ff_sys::{AVPixelFormat_AV_PIX_FMT_YUV420P, AVPixelFormat_AV_PIX_FMT_RGB24};

unsafe {
    // Create a scaling context
    let ctx = get_context(
        1920, 1080, AVPixelFormat_AV_PIX_FMT_YUV420P,
        1280, 720, AVPixelFormat_AV_PIX_FMT_RGB24,
        scale_flags::LANCZOS,
    )?;

    // Scale a frame (see swscale module for full API)
    // scale(ctx, src_ptrs, src_stride, 0, src_height, dst_ptrs, dst_stride)?;

    // Free the context when done
    free_context(ctx);
}

Module Structure

ff-sys/src/
├── lib.rs          # Crate root, bindgen include, utilities
├── avcodec.rs      # Codec context, packet handling
├── avformat.rs     # Format context, stream handling
├── swscale.rs      # Video scaling context
└── swresample.rs   # Audio resampling context

Related Crates

This crate is part of the ff-* crate family:

• ff-format - Type-safe pixel/sample formats, timestamps, stream info
• ff-probe - Media metadata extraction
• ff-decode - Video/audio decoding
• ff-encode - Video/audio encoding
• ff-filter - Filter graph operations (planned)

License

MIT OR Apache-2.0