Crate avio

Expand description

Safe, high-level audio/video/image processing for Rust.

avio is the facade crate for the ff-* crate family — a backend-agnostic multimedia toolkit. It re-exports the public APIs of all member crates behind feature flags, so users can depend on a single crate and opt into only the functionality they need.

§Feature Flags

Feature	Crate	Default	Implies
`probe`	`ff-probe`	yes	—
`decode`	`ff-decode`	yes	—
`encode`	`ff-encode`	yes	—
`filter`	`ff-filter`	no	—
`pipeline`	`ff-pipeline`	no	`filter`
`preview`	`ff-preview`	no	—
`preview-proxy`	`ff-preview`	no	`preview`
`stream`	`ff-stream`	no	`pipeline`
`tokio`	ff-decode/encode	no	`decode` + `encode`

§Usage

# Default: probe + decode + encode
[dependencies]
avio = "0.15"

# Add filtering
avio = { version = "0.15", features = ["filter"] }

# Full stack (implies filter + pipeline)
avio = { version = "0.15", features = ["stream"] }

§Quick Start

§Probe

open is a free function (not a method) that reads metadata without decoding:

use avio::open;

let info = open("video.mp4")?;
println!("duration: {:?}", info.duration());

§Decode

All decoders follow the same builder pattern. Use .output_format() / .output_sample_rate() to request automatic format conversion inside the decoder:

use avio::{VideoDecoder, AudioDecoder, PixelFormat, SampleFormat};

// Video — request RGB24 output (FFmpeg converts internally)
let mut vdec = VideoDecoder::open("video.mp4")
    .output_format(PixelFormat::Rgb24)
    .build()?;
for result in &mut vdec { /* ... */ }

// Audio — resample to 16-bit 44.1 kHz
let mut adec = AudioDecoder::open("video.mp4")
    .output_format(SampleFormat::I16)
    .output_sample_rate(44_100)
    .build()?;

§Encode

There are three encode APIs, each suited to a different situation. Choosing the right one prevents unnecessary complexity.

§When to use `Pipeline` (feature: `pipeline`)

Use Pipeline when your source is an existing media file and you want to transcode, filter, or repackage it with minimal boilerplate.

You are transcoding a file to another codec or container.
You want to apply filters (scale, trim, fade, tone-map, …).
You want to concatenate multiple input files.
You need progress reporting without managing the decode loop yourself.
You are generating HLS or DASH output (stream feature).

use avio::{Pipeline, EncoderConfig, VideoCodec, AudioCodec, BitrateMode};

Pipeline::builder()
    .input("input.mp4")
    .output("output.mp4", EncoderConfig::builder()
        .video_codec(VideoCodec::H264)
        .audio_codec(AudioCodec::Aac)
        .bitrate_mode(BitrateMode::Crf(23))
        .build())
    .build()?
    .run()?;

Examples: transcode, trim_and_scale, concat_clips, extract_thumbnails, hls_output, abr_ladder.

§When to use `VideoEncoder` / `AudioEncoder` directly (feature: `encode`)

Use the encoder types directly when you need frame-level control or your frames come from a source other than a media file.

You are generating frames programmatically (e.g., a game renderer, a signal generator, test patterns).
You need to inspect or modify individual frames between decode and encode.
You want per-frame metadata, custom PTS/DTS, or non-standard GOP structure.
You need to react to EncodeError::Cancelled mid-stream.
You want cancellable progress via EncodeProgressCallback::should_cancel().

use avio::{VideoDecoder, VideoEncoder, VideoCodec};

let mut decoder = VideoDecoder::open("input.mp4").build()?;
let mut encoder = VideoEncoder::create("output.mp4")
    .video(decoder.width(), decoder.height(), decoder.frame_rate())
    .video_codec(VideoCodec::H264)
    .build()?;

while let Ok(Some(frame)) = decoder.decode_one() {
    // Inspect or modify `frame` here before encoding.
    encoder.push_video(&frame)?;
}
encoder.finish()?;

Examples: encode_video_direct, encode_audio_direct, encode_with_progress, two_pass_encode, filter_direct.

§When to use `AsyncVideoEncoder` / `AsyncAudioEncoder` (feature: `tokio`)

Use the async encoders when your application runs on a Tokio runtime and you need back-pressure or concurrent decode/encode.

You are writing an async application and cannot block the executor.
Frames arrive from an async source (network, channel, microphone).
You want the decoder and encoder to run concurrently on separate tasks.
You rely on the bounded internal channel (capacity 8) to prevent unbounded memory growth when the encoder is slower than the producer.

use avio::{AsyncVideoDecoder, AsyncVideoEncoder, VideoEncoder, VideoCodec};
use futures::StreamExt;

let mut encoder = AsyncVideoEncoder::from_builder(
    VideoEncoder::create("output.mp4")
        .video(1920, 1080, 30.0)
        .video_codec(VideoCodec::H264),
)?;

let stream = AsyncVideoDecoder::open("input.mp4").await?.into_stream();
tokio::pin!(stream);
while let Some(Ok(frame)) = stream.next().await {
    encoder.push(frame).await?;
}
encoder.finish().await?;

Examples: async_encode_video, async_encode_audio, async_transcode.

§Real-world Applications

§ascii-term — Terminal ASCII Art Video Player

ascii-term is a terminal media player that renders video as colored ASCII art with synchronized audio. It was fully migrated from ffmpeg-next / ffmpeg-sys-next to avio, with no direct unsafe FFmpeg code remaining in the application.

Key patterns used:

VideoDecoder with .output_format(PixelFormat::Rgb24) for per-pixel luminance
AudioDecoder with SampleFormat::F32 output, converted to interleaved PCM for rodio playback
Dual-thread A/V sync via crossbeam-channel

§Extension trait

VideoCodecEncodeExt adds encode-specific helpers (.default_extension(), .is_lgpl_compatible()) to VideoCodec. Import the trait to call them:

use avio::{VideoCodec, VideoCodecEncodeExt};

let ext = VideoCodec::H264.default_extension(); // "mp4"

Structs§

AacOptions: AAC per-codec options.
AbrLadder: Produces multi-rendition HLS or DASH output from a single input.
AbrRendition: One resolution/bitrate tier in an ABR ladder.
AnalyzeOptions: Options for the first stabilization pass (motion analysis).
AnimationEntry: A registered animation track for a specific filter parameter.
AnimationTrack: A sorted collection of keyframes with interpolated value_at(t) lookup.
AsyncAudioDecoder: Async wrapper around AudioDecoder.
AsyncAudioDecoderBuilder: Async builder for AsyncAudioDecoder that mirrors the options available on the synchronous AudioDecoderBuilder.
AsyncAudioEncoder: Async wrapper around AudioEncoder.
AsyncImageDecoder: Async wrapper around ImageDecoder.
AsyncPreviewPlayer: Async wrapper around PlayerHandle.
AsyncVideoDecoder: Async wrapper around VideoDecoder.
AsyncVideoDecoderBuilder: Async builder for AsyncVideoDecoder that mirrors the options available on the synchronous VideoDecoderBuilder.
AsyncVideoEncoder: Async wrapper around VideoEncoder.
AudioAdder: Mux an audio track into a silent (or existing) video file.
AudioConcatenator: Concatenates multiple audio clips into a single seamless output stream.
AudioDecoder: An audio decoder for extracting audio frames from media files.
AudioEncoder: Encodes audio frames to a file using FFmpeg.
AudioEncoderConfig: Configuration for the audio stream of an export preset.
AudioExtractor: Demux an audio track from a media file and write it to a standalone audio file.
AudioFrame: A decoded audio frame.
AudioMixer: Multi-track, constant-power-panned stereo mixer.
AudioPipeline: High-level audio-only transcode pipeline.
AudioReplacement: Replace a video file’s audio track with audio from a separate source file.
AudioStreamInfo: Information about an audio stream within a media file.
AudioTrack: A single audio track in a MultiTrackAudioMixer mix.
AudioTrackHandle: Cloneable handle for filling a track and adjusting its gain from any thread.
Av1Options: AV1 per-codec options (libaom-av1).
BlackFrameDetector: Detects black intervals in a video file and returns their start timestamps.
ChapterInfo: Information about a chapter within a media file.
ChapterInfoBuilder: Builder for constructing ChapterInfo.
Clip: A single media clip on a timeline.
ClipJoiner: Joins two video clips with a cross-dissolve transition.
ClipTransition: Parameters for a cross-dissolve transition applied at the start of a VideoLayer.
ContainerInfo: Container-level metadata extracted from AVFormatContext.
DashOutput: Builds and writes a DASH segmented output.
DecodeBuffer: Pre-decodes frames from a video file into a ring buffer on a background thread.
DecodeBufferBuilder: Builder for DecodeBuffer.
DnxhdOptions: Avid DNxHD / DNxHR per-codec options.
DrawTextOptions: Options for the drawtext filter.
EncodeProgress: Encoding progress information.
EncoderConfig: Codec and quality configuration for the pipeline output.
EncoderConfigBuilder: Consuming builder for EncoderConfig.
ExportPreset: A named export preset combining video and audio encoder configuration.
FanoutOutput: A StreamOutput wrapper that fans frames out to multiple targets.
FilterGraph: An FFmpeg libavfilter filter graph.
FilterGraphBuilder: Builder for constructing a FilterGraph.
FlacOptions: FLAC per-codec options.
FrameExtractor: Extracts one frame per time interval from a video file.
FrameHistogram: Per-channel color histogram for a single video frame.
GifPreview: Generates an animated GIF preview from a configurable time range.
H264Options: H.264 (AVC) per-codec options.
H265Options: H.265 (HEVC) per-codec options.
Hdr10Metadata: HDR10 static metadata (MaxCLL + MaxFALL + mastering display).
Histogram: 256-bin luminance and per-channel RGB histogram.
HistogramExtractor: Extracts per-channel color histograms at configurable frame intervals.
HlsOutput: Builds and writes an HLS segmented output.
ImageDecoder: Decodes a single still image into a VideoFrame.
ImageEncoder: Encodes a single VideoFrame to a still image file.
Keyframe: A single keyframe in an animation track.
KeyframeEnumerator: Enumerates the timestamps of all keyframes in a video stream.
LiveAbrLadder: Live ABR ladder: fans frames to multiple encoders at different resolutions.
LiveDashOutput: Live DASH output: receives frames and writes a manifest.mpd playlist.
LiveHlsOutput: Live HLS output: receives frames and writes a sliding-window .m3u8 playlist.
LoudnessMeter: Measures EBU R128 integrated loudness, loudness range, and true peak.
LoudnessResult: Result of an EBU R128 loudness measurement.
MasteringDisplay: Mastering display colour volume (SMPTE ST 2086).
MediaInfo: Information about a media file.
MediaInfoBuilder: Builder for constructing MediaInfo.
Mp3Options: MP3 (libmp3lame) per-codec options.
MultiTrackAudioMixer: Mixes multiple audio tracks into a single output stream.
MultiTrackComposer: Composes multiple video layers onto a solid-colour canvas.
NetworkOptions: Shared network configuration for network-backed decoders and live outputs.
OpusOptions: Opus (libopus) per-codec options.
Pipeline: A configured, ready-to-run transcode pipeline.
PipelineBuilder: Consuming builder for Pipeline.
PlaybackClock: A monotonic clock that tracks elapsed playback time.
PlayerHandle: Shared, cloneable handle to a running PlayerRunner.
PlayerRunner: Exclusive owner of the decode pipeline. Move to a background thread and call run.
PreviewPlayer: Thin builder for a (PlayerRunner, PlayerHandle) pair.
ProResOptions: Apple ProRes per-codec options.
Progress: Progress information delivered to the caller on each processed frame.
ProxyGenerator: Generates a lower-resolution proxy file from an original media file.
ProxyJob: A handle to a running background proxy generation job.
ProxySource: A low-resolution proxy substitute for a VideoLayer’s source.
QualityMetrics: Computes video quality metrics between a reference and a distorted video.
Rational: A rational number represented as a fraction (numerator / denominator).
Rendition: A single resolution/bitrate rendition in an ABR ladder.
Rgb: An RGB colour value used by the three-way colour corrector.
RgbParade: Per-channel waveform monitor data (RGB parade).
RgbaFrame: A decoded video frame as contiguous RGBA bytes.
RgbaSink: Reference FrameSink implementation that stores the latest frame in a shared Arc<Mutex<Option<RgbaFrame>>>.
RtmpOutput: Live RTMP output: encodes frames and pushes them to an RTMP ingest endpoint.
SceneDetector: Detects scene changes in a video file and returns their timestamps.
ScopeAnalyzer: Scope analysis utilities for decoded video frames.
SilenceDetector: Detects silent intervals in an audio file and returns their time ranges.
SilenceRange: A detected silent interval in an audio stream.
SpriteSheet: Generates a thumbnail sprite sheet from a video file.
SrtOutput: Live SRT output: encodes frames as MPEG-TS and pushes them to an SRT destination.
StabilizeOptions: Options for the second stabilization pass (transform application).
Stabilizer: Two-pass video stabilization using FFmpeg’s vidstabdetect / vidstabtransform filters.
StreamCopyTrim: Trim a media file to a time range using stream copy (no re-encode).
StreamCopyTrimmer: Trim a media file to a time range using stream copy (no re-encode).
SubtitleEvent: A single subtitle event (cue).
SubtitleStreamInfo: Information about a subtitle stream within a media file.
SubtitleTrack: A parsed subtitle track containing ordered events.
SvtAv1Options: SVT-AV1 (libsvtav1) per-codec options.
ThumbnailPipeline: Extracts still frames from a video file at requested timestamps.
ThumbnailSelector: Automatically selects the best thumbnail frame from a video file.
Timeline: An ordered layout of Clip instances across video and audio tracks.
TimelineBuilder: Builder for Timeline.
TimelinePlayer: Thin builder for a (TimelineRunner, PlayerHandle) pair backed by a Timeline.
TimelineRunner: Exclusive owner of the timeline decode pipeline.
Timestamp: A timestamp representing a point in time within a media stream.
VecPool: A simple frame pool backed by a Vec of reusable buffers.
VideoConcatenator: Concatenates multiple video clips into a single seamless output stream.
VideoDecoder: A video decoder for extracting frames from media files.
VideoEffectRenderer: Reusable single-frame renderer for a Clip’s video effect chain.
VideoEncoder: Encodes video (and optionally audio) frames to a file using FFmpeg.
VideoEncoderConfig: Configuration for the video stream of an export preset.
VideoFrame: A decoded video frame.
VideoLayer: A single video layer in a MultiTrackComposer composition.
VideoPipeline: High-level video-only transcode pipeline.
VideoStreamInfo: Information about a video stream within a media file.
Vp9Options: VP9 (libvpx-vp9) per-codec options.
WaveformAnalyzer: Computes peak and RMS amplitude per time interval for an audio file.
WaveformSample: A single waveform measurement over a configurable time interval.

Enums§

AacProfile: AAC encoding profile.
AlphaMode: Alpha modes.
AnimatedValue: A value that is either constant or animated over time.
AudioCodec: Audio codec identifier.
AudioCodecOptions: Per-codec encoding options for audio.
Av1Usage: AV1 encoding usage mode.
BitrateMode: Bitrate control mode for video encoding.
BlendMode: Specifies how two video layers are combined during compositing.
ChannelLayout: Audio channel layout representing the speaker configuration.
ColorPrimaries: Color primaries defining the color gamut (the range of colors that can be represented).
ColorRange: Color range defining the valid range of color values.
ColorSpace: Color space (matrix coefficients) for YUV to RGB conversion.
ColorTransfer: Color transfer characteristic (opto-electronic transfer function).
CompositeOp: Porter-Duff alpha-compositing operator for combining two video layers.
DecodeError: Errors that can occur during decoding operations.
DnxhdVariant: DNxHD / DNxHR encoding variant.
Easing: Easing function applied to a keyframe interval.
EncodeError: Encoding error type.
EqBand: A single band for the parametric equalizer.
FilterError: Errors that can occur during filter graph construction and processing.
FilterStep: A single step in a filter chain.
FrameResult: The result of a DecodeBuffer::pop_frame call.
H264Preset: libx264 encoding speed/quality preset.
H264Profile: H.264 encoding profile.
H264Tune: libx264 perceptual tuning parameter.
H265Profile: H.265 encoding profile.
H265Tier: H.265 encoding tier.
HardwareAccel: Hardware acceleration configuration.
HardwareEncoder: Hardware encoder type.
HlsSegmentFormat: Container format for individual HLS segments.
HwAccel: Hardware acceleration backend for filter graph operations.
Interpolation: Interpolation algorithm used by Stabilizer::transform.
LensProfile: Predefined lens distortion correction profiles for common cameras.
LiveAbrFormat: Output container format for the ABR ladder.
Mp3Quality: MP3 quality mode: VBR quality scale or CBR fixed bitrate.
NoiseType: Noise type used as the initial spectral model for afftdn.
OpusApplication: Opus encoder application mode.
OutputContainer: Output container format for encoding.
PipelineError: Errors that can occur while building or running a pipeline.
PixelFormat: Pixel format for video frames.
PlayerCommand: Commands sent from PlayerHandle to PlayerRunner via a bounded sync channel (capacity 64).
PlayerEvent: Events emitted by PlayerRunner::run and delivered to callers via PlayerHandle::poll_event.
Preset: Encoding preset (speed vs quality tradeoff).
PreviewError: Errors that can occur during preview and proxy operations.
ProResProfile: Apple ProRes encoding profile.
ProbeError: Error type for media probing operations.
ProxyResolution: Output resolution for a proxy file, expressed as a fraction of the source.
SampleFormat: Audio sample format for audio frames.
ScaleAlgorithm: Resampling algorithm for the scale filter.
SeekEvent: An event emitted by DecodeBuffer after a seek_async completes.
SeekMode: Seek mode for positioning the decoder.
StreamError: Errors that can occur during streaming output operations.
SubtitleCodec: Subtitle codec identifier.
SubtitleError: Error type for subtitle parsing operations.
ToneMap: Tone-mapping algorithm for HDR-to-SDR conversion.
VideoCodec: Video codec identifier.
VideoCodecOptions: Per-codec encoding options.
XfadeTransition: Transition type for the xfade cross-dissolve filter.
YadifMode: Deinterlacing mode for the yadif filter.

Constants§

CRF_MAX: Maximum CRF value accepted by H.264/H.265 encoders.

Traits§

EncodeProgressCallback: EncodeProgress callback trait for monitoring encoding progress.
FramePool: A trait for frame buffer pooling.
FrameSink: A sink that receives decoded video frames as contiguous RGBA bytes.
Lerp: A value that supports linear component-wise interpolation.
StreamOutput: Common interface for all live stream outputs.
VideoCodecEncodeExt: Encode-specific methods for VideoCodec.

Functions§

open: Opens a media file and extracts its metadata.

Type Aliases§

ProgressCallback: Callback invoked on every processed frame to report progress.

Crate avio

Crate avio Copy item path

§Feature Flags

§Usage

§Quick Start

§Probe

§Decode

§Encode

§When to use Pipeline (feature: pipeline)

§When to use VideoEncoder / AudioEncoder directly (feature: encode)

§When to use AsyncVideoEncoder / AsyncAudioEncoder (feature: tokio)

§Real-world Applications

§ascii-term — Terminal ASCII Art Video Player

§Extension trait

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate avio

§When to use `Pipeline` (feature: `pipeline`)

§When to use `VideoEncoder` / `AudioEncoder` directly (feature: `encode`)

§When to use `AsyncVideoEncoder` / `AsyncAudioEncoder` (feature: `tokio`)