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`
`stream`	`ff-stream`	no	`pipeline`
`tokio`	ff-decode/encode	no	`decode` + `encode`

§Usage

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

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

# Full stack (implies filter + pipeline)
avio = { version = "0.5", 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.
AudioDecoder: An audio decoder for extracting audio frames from media files.
AudioEncoder: Encodes audio frames to a file using FFmpeg.
AudioFrame: A decoded audio frame.
AudioStreamInfo: Information about an audio stream within a media file.
Av1Options: AV1 per-codec options (libaom-av1).
ChapterInfo: Information about a chapter within a media file.
ChapterInfoBuilder: Builder for constructing ChapterInfo.
ContainerInfo: Container-level metadata extracted from AVFormatContext.
DnxhdOptions: Avid DNxHD / DNxHR per-codec options.
EncodeProgress: Encoding progress information.
FlacOptions: FLAC per-codec options.
H264Options: H.264 (AVC) per-codec options.
H265Options: H.265 (HEVC) per-codec options.
Hdr10Metadata: HDR10 static metadata (MaxCLL + MaxFALL + mastering display).
ImageDecoder: Decodes a single still image into a VideoFrame.
ImageEncoder: Encodes a single VideoFrame to a still image file.
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.
OpusOptions: Opus (libopus) per-codec options.
ProResOptions: Apple ProRes per-codec options.
Rational: A rational number represented as a fraction (numerator / denominator).
SubtitleStreamInfo: Information about a subtitle stream within a media file.
SvtAv1Options: SVT-AV1 (libsvtav1) per-codec options.
Timestamp: A timestamp representing a point in time within a media stream.
VecPool: A simple frame pool backed by a Vec of reusable buffers.
VideoDecoder: A video decoder for extracting frames from media files.
VideoEncoder: Encodes video (and optionally audio) frames to a file using FFmpeg.
VideoFrame: A decoded video frame.
VideoStreamInfo: Information about a video stream within a media file.
Vp9Options: VP9 (libvpx-vp9) per-codec options.

Enums§

AacProfile: AAC encoding profile.
AudioCodec: Audio codec identifier.
AudioCodecOptions: Per-codec encoding options for audio.
Av1Usage: AV1 encoding usage mode.
BitrateMode: Bitrate control mode for video encoding.
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).
Container: Container format for output file.
DecodeError: Errors that can occur during decoding operations.
DnxhdVariant: DNxHD / DNxHR encoding variant.
EncodeError: Encoding error type.
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.
Mp3Quality: MP3 quality mode: VBR quality scale or CBR fixed bitrate.
OpusApplication: Opus encoder application mode.
PixelFormat: Pixel format for video frames.
Preset: Encoding preset (speed vs quality tradeoff).
ProResProfile: Apple ProRes encoding profile.
ProbeError: Error type for media probing operations.
SampleFormat: Audio sample format for audio frames.
SeekMode: Seek mode for positioning the decoder.
SubtitleCodec: Subtitle codec identifier.
VideoCodec: Video codec identifier.
VideoCodecOptions: Per-codec encoding options.

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.
VideoCodecEncodeExt: Encode-specific methods for VideoCodec.

Functions§

open: Opens a media file and extracts its metadata.

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§

Crate avio

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

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

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