Crate ez_ffmpeg 

ez-ffmpeg

ez-ffmpeg provides a safe and ergonomic Rust interface for FFmpeg integration. By abstracting away much of the raw C API complexity, It abstracts the complexity of the raw C API, allowing you to configure media pipelines, perform transcoding and filtering, and inspect streams with ease.

Crate Layout

• core: The foundational module that contains the main building blocks for configuring and running FFmpeg pipelines. This includes:

  • Input / Output: Descriptors for where media data comes from and goes to (files, URLs, custom I/O callbacks, etc.).
  • FilterComplex and FrameFilter: Mechanisms for applying FFmpeg filter graphs or custom transformations.
  • container_info: Utilities to extract information about the container, such as duration and format details.
  • stream_info: Utilities to query media metadata (duration, codecs, etc.).
  • hwaccel: Helpers for enumerating and configuring hardware-accelerated video codecs (CUDA, VAAPI, VideoToolbox, etc.).
  • codec: Tools to list and inspect available encoders/decoders.
  • device: Utilities to discover system cameras, microphones, and other input devices.
  • filter: Query FFmpeg’s built-in filters and infrastructure for building custom frame-processing filters.
  • context: Houses FfmpegContext for assembling an FFmpeg job.
  • scheduler: Provides FfmpegScheduler which manages the lifecycle of that job.

• wgpu_filter (feature "wgpu"): GPU-accelerated frame filters via wgpu (Vulkan/Metal/DX12/GL). Provide a WGSL fragment shader and apply effects with correct color handling, headless operation, and GPU/CPU overlap.

• opengl (feature "opengl", deprecated): The former OpenGL filter path, superseded by wgpu_filter. Kept for backward compatibility; it requires a display connection and will be removed in a future major release.

• rtmp (feature "rtmp"): Embedded RTMP server EmbedRtmpServer built for production streaming, using native epoll/kqueue/WSAPoll via libc FFI (edge-triggered on Linux/macOS, level-triggered on Windows), zero-copy GOP fanout with Arc<[FrameData]>, and tiered backpressure (1/2/4MB) on a 2-thread model; 10,000+ conns on Linux/macOS (8,000 on Windows) with in-process ingest (no TCP between FFmpeg and server).

• flv (feature "flv"): Provides data structures and helpers for handling FLV containers, useful if you’re working with RTMP or other FLV-based workflows.

• subtitle (feature "subtitle"): Burns ASS/SRT subtitles onto video frames inside the frame pipeline with a pure-Rust renderer — independent of whether the linked FFmpeg was built with --enable-libass. Accepts subtitle files or in-memory scripts and explicit font files.

Basic Usage

For a simple pipeline, you typically do the following:

1. Build a FfmpegContext by specifying at least one input and one output. Optionally, add filter descriptions (filter_desc) or attach FrameFilter pipelines at either the input (post-decode) or the output (pre-encode) stage.
2. Create an FfmpegScheduler from that context, then call start() and wait() (or .await if you enable the "async" feature) to run the job.

use ez_ffmpeg::FfmpegContext;
use ez_ffmpeg::FfmpegScheduler;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Build the FFmpeg context
    let context = FfmpegContext::builder()
        .input("input.mp4")
        .filter_desc("hue=s=0") // Example filter: desaturate
        .output("output.mov")
        .build()?;

    // 2. Run it via FfmpegScheduler (sync mode)
    let result = FfmpegScheduler::new(context)
        .start()?
        .wait();
    result?; // If any error occurred, propagate it
    Ok(())
}

Feature Flags

ez-ffmpeg uses Cargo features to provide optional functionality. By default, no optional features are enabled, allowing you to keep dependencies minimal. You can enable features as needed in your Cargo.toml:

[dependencies.ez-ffmpeg]
version = "*"
features = ["wgpu", "rtmp", "flv", "async"]

Core Features

• wgpu: Enables wgpu-based GPU filters (WGSL shaders, headless-capable).
• opengl (deprecated): Enables the former OpenGL-based filters; superseded by wgpu.
• rtmp: Embedded RTMP server tuned for scale (10,000+ conns on Linux/macOS, 8,000 on Windows), native epoll/kqueue/WSAPoll IO (edge-triggered on Linux/macOS), zero-copy GOP, and in-process ingest that avoids TCP between FFmpeg and server.
• flv: Adds FLV container parsing and handling.
• subtitle: Native ASS/SRT subtitle burn-in rendered in pure Rust — no system libraries beyond FFmpeg itself (see the subtitle module docs).
• async: Makes the FfmpegScheduler wait method asynchronous (you can .await it).
• static: Uses static linking for FFmpeg libraries (via ffmpeg-next/static).

Relationship to the FFmpeg CLI

The transcoding pipeline (demux -> decode -> filter -> encode -> mux) is ported from the FFmpeg CLI sources, fftools/ffmpeg of FFmpeg 7.x: function names, timestamp handling and scheduling semantics follow that release, and code comments cite the corresponding fftools file and line (line numbers refer to the FFmpeg n7.1 tag). If you know ffmpeg_demux.c or ffmpeg_filter.c, grepping this crate for the same function names (ts_fixup, video_sync_process, enc_open, mux_fixup_ts, …) lands in the equivalent Rust.

Not every CLI feature is implemented. Notable gaps: progress/stats reporting (-progress), sub2video (rendering bitmap subtitles into video), -shortest cross-stream sync, bitstream filters (-bsf), keyframe forcing (-force_key_frames), -fix_sub_duration, two-pass encoding, and attachments. Unsupported paths fail with explicit errors rather than approximations.

Logging

FFmpeg’s own diagnostics (av_log) are redirected into the Rust log facade under the FFMPEG_LOG_TARGET target. Without a logger installed (env_logger, tracing-log, …) all FFmpeg messages are silently dropped — including decoder errors that explain a failing job. Use set_ffmpeg_log_level to bound the forwarded verbosity and Input::set_log_level_offset to shift it per input.

License Notice

ez-ffmpeg is licensed under your choice of MIT, Apache-2.0, or MPL-2.0 (matching the license field in Cargo.toml).

Note: FFmpeg itself is subject to its own licensing terms. When enabling features that incorporate FFmpeg components, please ensure that your usage complies with FFmpeg’s license.

Re-exports

pub use self::core::context::ffmpeg_context::FfmpegContext;

pub use self::core::context::input::Input;

pub use self::core::context::output::Output;

pub use self::core::scheduler::ffmpeg_scheduler::FfmpegScheduler;

pub use self::core::container_info;

pub use self::core::stream_info;

pub use self::core::set_ffmpeg_log_level;

pub use self::core::FfmpegLogLevel;

pub use self::core::FFMPEG_LOG_TARGET;

pub use self::core::packet_scanner;

pub use self::core::device;

pub use self::core::hwaccel;

pub use self::core::codec;

pub use self::core::filter;

pub use self::core::analysis;

pub use self::core::recipes;

Modules

core

The core module provides the foundational building blocks for configuring and running FFmpeg pipelines. It encompasses:

error

flv

The FLV module contains data structures and tools to parse or handle FLV containers. It helps convert raw media data into FLV tags, making it easier to integrate with FFmpeg-based pipelines or RTMP streaming flows where FLV is the underlying format.

openglDeprecated

Deprecated since 0.11.0 — superseded by the crate::wgpu_filter module (feature wgpu). This module remains functional but will be removed in a future major release; new code should not use it.

rtmp

The RTMP module includes an embedded RTMP server (EmbedRtmpServer) built for production-grade streaming with high concurrency support. It receives data directly from memory—bypassing TCP between FFmpeg and the server. Inspired by rml_rtmp’s threaded RTMP server.

subtitle

Native subtitle burn-in (ASS/SRT) rendered by a pure-Rust engine inside the frame pipeline.

util

wgpu_filter

GPU-accelerated frame filtering backed by wgpu (Vulkan/Metal/DX12/GL). Successor to the deprecated opengl module.

Structs

AVRational

Frame

Enums

AVMediaType