Crate media_pp 

A small, GStreamer-flavored media pipeline library built on ffmpeg-next.

A pipeline has one or more SourceElements, each feeding a graph of Filters that ends in a Sink:

FileDemuxer -> SwDecoder -> Queue -> Pacer -> FrameCounter

Each source registered with a Pipeline runs on its own background thread. Within that source’s graph, Sink::consume is otherwise a plain synchronous call that returns Result, so a stage’s failure propagates straight back up the call stack with ?. A Queue adds another explicit thread boundary inside a branch: it owns a worker thread and a bounded channel, which is also where error handling changes shape — past that boundary a downstream failure can no longer be returned to the pusher, so it is reported on the Bus as BusEvent::Error and the worker keeps going.

use std::{sync::atomic::Ordering, time::Duration};

use media_pp::{
    elements::{FrameCounter, TestVideoOptions, TestVideoSource},
    pipeline::Pipeline,
};

media_pp::init()?;

let source = TestVideoSource::new("source", TestVideoOptions::default());
let (counter, frames) = FrameCounter::new("counter");

let pipeline = Pipeline::new("demo", source, |source, ctx| {
    let branch = ctx.branch().to(Box::new(counter))?;
    ctx.attach(source, 0, branch)?;
    Ok(())
})?;

pipeline.run()?;
std::thread::sleep(Duration::from_millis(200));
pipeline.stop();

println!("frames: {}", frames.load(Ordering::Relaxed));

Where to start

• elements is the inventory of built-in sources, filters, and sinks. Each type’s own documentation states what buffers it accepts, what it owns, and how it behaves under error and runtime control.
• pipeline builds and runs a graph; element and pad are the traits and the one output port everything is wired through.
• buffer is what travels between elements, control is what Pause/Resume/Stop/Seek travel through, and bus is how an element reports something the caller could not have been handed directly.

Buffer and timeline contract

MediaBuffer payloads are Arc-wrapped, so fan-out clones a reference rather than the media itself. PTS, duration, packet time bases, and video color information survive every stage that does not deliberately create a new timeline.

Eos is data, and it is forwarded like data: stateful stages (encoders holding delayed frames, muxers, resamplers) flush on it before passing it on. That is what separates the two ways a pipeline ends — Pipeline::finish sends ordered EOS from the source and drains everything behind it, while Pipeline::stop abandons buffered work.

Features and platforms

The crate has no default features. Hardware backends (d3d11, d3d12, dxgi-capture, cuda, wasapi-*, pipewire-*) and the optional ort and webrtc integrations are each behind their own Cargo feature, and backend-specific types carry the backend’s prefix. docs.rs builds this crate for Linux and therefore omits the Windows-only API; the complete reference is published separately (see the repository README).

Logging

Diagnostics never install a global log logger or tracing subscriber. The file logger in log is private and opt-in through log::init, and the caller owns the returned guard for as long as records must keep being written and flushed.

Re-exports

pub use error::Error;

pub use error::Result;

pub use ffmpeg_next as ffmpeg;

Modules

buffer

What travels between elements.

bus

Out-of-band reporting for what cannot be returned to the caller.

clock

The pipeline’s shared, pause-aware wall-clock reference.

color

A plain RGB color value, shared by anything in this crate that needs one — compositor backgrounds, layer/text colors, and so on. Kept in core rather than under a specific element’s module because nothing about it is pipeline- or backend-specific.

contract

What a port promises about the buffers passing through it.

control

Pause, Resume, Stop, Flush, Seek, and Finish — and the channel they travel through.

driver

Background tasks that have no pads of their own.

element

The traits every element implements, and the identity it carries.

elements

The built-in elements, grouped by the role they play in a graph.

error

The crate-wide error type.

graph

The pipeline’s topology, recorded separately from the elements themselves.

log

Opt-in file logging owned exclusively by media-pp.

pad

The one output port data leaves an element through.

pipeline

Building and running a graph.

playback_clock

Which stream currently defines the pipeline’s media position.

pool

Recycling the backing storage of video frames.

pp_log

Contextual logging identity and macros used by pipeline elements.

queue

The explicit thread boundary, and with it the error boundary.

rate

The rate a periodic source emits at, changeable while it runs.

Macros

pp_debug

Logs at Level::Debug — diagnostic state. Same forms and cost as pp_info!.

pp_error

Logs at Level::Error — a failed operation. Same forms and cost as pp_info!.

pp_info

Logs at Level::Info — sparse lifecycle and topology changes, not per-buffer activity.

pp_trace

Logs at Level::Trace — EOS and control-flow detail at element and thread boundaries. Same forms and cost as pp_info!.

pp_warn

Logs at Level::Warn — degraded or recovered conditions. Same forms and cost as pp_info!.

Functions

init

Must be called once before using any element that touches ffmpeg.