zenavif

Pure Rust AVIF image codec. Decodes and encodes AVIF images using rav1d-safe (AV1 decoder) and zenavif-parse (AVIF container parser).

What it does

• Decodes 8/10/12-bit AVIF with all chroma subsampling modes (4:2:0, 4:2:2, 4:4:4, monochrome)
• Handles alpha channels (straight and premultiplied)
• Supports full and limited color range, HDR color spaces (BT.2020, P3, etc.)
• Preserves EXIF, XMP, rotation, mirror, clean aperture, pixel aspect ratio, HDR metadata
• Decodes animated AVIF sequences with per-frame timing
• Decodes gain maps (ISO 21496-1) and depth auxiliary images from AVIF containers
• Encodes AVIF with optional gain map embedding via GainMapConfig (requires encode feature)
• Encodes AVIF via zenravif (optional encode feature)
• 100% safe Rust by default. Zero unsafe in the decode path.
• Cooperative cancellation via the enough crate

Quick Start

use zenavif::decode;

let avif_data = std::fs::read("image.avif").unwrap();
let image = decode(&avif_data).unwrap();
println!("{}x{}", image.width(), image.height());

Custom configuration

use zenavif::{decode_with, DecoderConfig};
use enough::Unstoppable;

let config = DecoderConfig::new()
    .threads(4)
    .apply_grain(true)
    .frame_size_limit(8192 * 8192);

let avif_data = std::fs::read("image.avif").unwrap();
let image = decode_with(&avif_data, &config, &Unstoppable).unwrap();

Animation

let avif_data = std::fs::read("animation.avif").unwrap();
let animation = zenavif::decode_animation(&avif_data).unwrap();
for frame in &animation.frames {
    println!("{}x{} frame, {}ms",
        frame.pixels.width(), frame.pixels.height(), frame.duration_ms);
}

Encoding (requires encode feature)

use zenavif::{encode, decode};

let image = decode(&std::fs::read("input.avif").unwrap()).unwrap();
let encoded = zenavif::encode(&image).unwrap();
std::fs::write("output.avif", &encoded.avif_file).unwrap();

Encoding with custom config

use zenavif::{EncoderConfig, encode_rgb8};
use almost_enough::Unstoppable;

let config = EncoderConfig::new()
    .quality(80.0)   // 1.0 (worst) to 100.0 (best)
    .speed(4);       // 1 (slowest) to 10 (fastest)

let encoded = encode_rgb8(img.as_ref(), &config, Unstoppable.into_token()).unwrap();
std::fs::write("output.avif", &encoded.avif_file).unwrap();

Encoder configuration guide

Speed vs quality tradeoffs

Speed controls how much time the encoder spends optimizing. Higher speeds produce slightly larger files but encode much faster. Quality is comparable across speeds — the main tradeoff is encode time vs file size, not visual quality.

Measured on a 512×512 photographic image (CID22 corpus), q80, 8-bit (full sweep data):

Speed 4 is a good default. Speed 6 gives 4x faster encoding with identical quality. Speed 10 is best for real-time/interactive use — still good quality at ~80ms per frame. Speed 1-2 produce marginally smaller files but take 5-14x longer than speed 4.

Quality parameter

The quality parameter maps to an AV1 quantizer index:

Quantization matrices (QM)

With the encode-imazen feature, quantization matrices are enabled by default. QM applies frequency-dependent quantization weights that save 5-12% file size at q≤50 and roughly break even on size at high quality. Quality impact is small: within ±0.4 zensim of QM-off from q=70 onward, and ≤2 zensim points at low q (measured across 5 CID22 test images at speed 6).

QM is gracefully disabled for lossless encoding (with_lossless(true)); at quality=100 the underlying encoder also detects that all selected QM levels collapse to identity and clears the QM signaling, producing output equivalent to QM-off.

// QM is on by default. To disable:
let config = EncoderConfig::new()
    .quality(80.0)
    .with_qm(false);

Bit depth

The encoder matches output bit depth to input type by default:

• encode_rgb8 / encode_rgba8 → 8-bit AV1
• encode_rgb16 / encode_rgba16 → 10-bit AV1

Override with .bit_depth(EncodeBitDepth::Ten) if you want 10-bit output from 8-bit input (slightly better quality at the cost of larger files and wider decoder compatibility requirements).

Decoder output depth

The decoder outputs at the AV1 bitstream's native bit depth. Files encoded at 10-bit (common from other encoders that default to 10-bit) produce 16-bit PixelBuffer output. Use prefer_8bit(true) to downscale to 8-bit:

let config = DecoderConfig::new().prefer_8bit(true);
let image = decode_with(&avif_data, &config, &Unstoppable).unwrap();
// image is Rgb8 even if the AV1 bitstream was 10-bit

Features

Building

# Default safe decoder
cargo build --release

# With encoding
cargo build --release --features encode

# Fast assembly decoder (uses unsafe + C FFI)
cargo build --release --features unsafe-asm

# Run tests
cargo test

# Run with test vectors
just download-vectors
just test-integration

Credits

This project builds on excellent work by others:

• rav1d (BSD-2-Clause) — Pure Rust AV1 decoder (Rust port of dav1d). Provides the AV1 decoding backend via its managed safe API.

• zenavif-parse (MIT/Apache-2.0) — AVIF container parser for extracting image items and metadata from the ISOBMFF container.

• yuv (MIT) — YUV to RGB color conversion.

• libavif (BSD-2-Clause) — Reference AVIF implementation used for pixel-level verification and behavioral reference.

Image tech I maintain

* as of 2026

General Rust awesomeness

archmage · magetypes · enough · whereat · zenbench · cargo-copter

And other projects · GitHub @imazen · GitHub @lilith · lib.rs/~lilith · NuGet (over 30 million downloads / 87 packages)

License

Dual-licensed: AGPL-3.0 or commercial.

I've maintained and developed open-source image server software — and the 40+ library ecosystem it depends on — full-time since 2011. Fifteen years of continual maintenance, backwards compatibility, support, and the (very rare) security patch. That kind of stability requires sustainable funding, and dual-licensing is how we make it work without venture capital or rug-pulls. Support sustainable and secure software; swap patch tuesday for patch leap-year.

Our open-source products

Your options:

• Startup license — $1 if your company has under $1M revenue and fewer than 5 employees. Get a key →
• Commercial subscription — Governed by the Imazen Site-wide Subscription License v1.1 or later. Apache 2.0-like terms, no source-sharing requirement. Sliding scale by company size. Pricing & 60-day free trial →
• AGPL v3 — Free and open. Share your source if you distribute.

See LICENSE-COMMERCIAL for details.

AI-Generated Code Notice

Developed with AI assistance (Claude, Anthropic). Not all code manually reviewed — review critical paths before production use.