oxideav-avif

Pure-Rust AVIF (AV1 Image File Format): the AV1 profile of HEIF / MIAF. The ISOBMFF / HEIF container — box reader, meta item model, item payload resolution, derived-image graph, grid / overlay / identity composition, alpha attachment, clap / irot / imir, image-sequence tables and the still-image writer — is oxideav-heif; this crate owns everything AV1-specific on top of it: av1C and the AV1 item / sample handling, the av1-avif §2–§8 audits and profile brands, the AVIF item layout of the muxer, a1op / a1lx / lsel layered items, the HEIF-extension properties it types beyond the container's set, avis sequences, HDR metadata authoring and the pixel encoder's tile election. AV1 pixels come from oxideav-av1. Zero C dependencies.

Part of the oxideav framework but usable standalone.

Standalone use

oxideav-avif follows the workspace image-crate API: the same small root vocabulary as oxideav-png, oxideav-heif, … returning raw Vec<u8> pixels.

# fn main() -> Result<(), oxideav_avif::Error> {
let bytes = std::fs::read("in.avif").map_err(oxideav_avif::Error::from)?;
if oxideav_avif::probe(&bytes) {
    let info = oxideav_avif::info(&bytes)?;      // header only: width, height, format, frames, alpha, colour
    let img  = oxideav_avif::decode(&bytes)?;    // AvifImage, native planar layout
    let rgba: Vec<u8> = img.to_rgba8();          // tightly packed RGBA, 4 * width bytes per row
    let (w, h) = (img.width(), img.height());

    let opts = oxideav_avif::EncodeOptions::default().with_quality(90);
    let out: Vec<u8> = oxideav_avif::encode_rgba8(w, h, &rgba, &opts)?;
    std::fs::write("out.avif", out).map_err(oxideav_avif::Error::from)?;
    assert_eq!((info.width, info.height), (w, h));
}
# Ok(())
# }

Pixels need the registry feature. AVIF is a container whose pixels come from the AV1 codec crate, and codec crates in this workspace are framework-only. So:

A standalone caller that pairs the container model with its own AV1 decoder builds an AvifImage::new(width, height, format, planes)? (plane geometry validated) from the composed planes and gets to_rgba8() like everyone else.

[dependencies]
oxideav-avif = "0.0"                                   # with pixels (registry on)
# oxideav-avif = { version = "0.0", default-features = false }   # container + conversions only

Framework use

With registry the crate also plugs into oxideav-core:

# #[cfg(feature = "registry")] {
let mut ctx = oxideav_core::RuntimeContext::new();
oxideav_avif::register(&mut ctx);                 // codec "avif" + .avif / .avifs extension hints
// or: oxideav_avif::register_with_av1(&mut ctx.codecs) to install the AV1 codec too
let params = oxideav_core::CodecParameters::video(oxideav_core::CodecId::new("avif"));
let _dec = oxideav_avif::make_decoder(&params).unwrap();   // direct factory, same as the registry's
let _enc = oxideav_avif::make_encoder(&params).unwrap();
# }

The framework AvifDecoder / AvifEncoder are thin adapters over the functions above: send_packet (one complete AVIF file per packet) runs decode_with / decode_all_with with the decoder's DecodeOptions (gain_map=apply / reference_white codec options, set_options), and emits every frame with its ColorSignal; the encoder maps a VideoFrame onto the still encoder (quality / q / alpha_q / chroma / premultiplied options — the schemas are AvifEncoderOptions / AvifDecoderOptions, declared on the registry entry, parsed strictly). The decoder honours Decoder::set_execution_context (the AV1 worker budget; the threads option fixes it) and the encoder declares its 27 accepted input layouts (ENCODER_PIXEL_FORMATS) as the registry's accepted_pixel_formats. From<AvifImage> for VideoFrame and AvifImage::from_video_frame(&frame, &params) (also TryFrom<(&VideoFrame, &CodecParameters)>) move pictures between the two worlds. Codec id "avif", capability avif_heif_av1_decode; CodecParameters::extradata is the av1C record.

Supported layouts

PixelFormat (= AvifPixelFormat) mirrors oxideav_core::PixelFormat by name. Decode yields the storage layout; color.matrix == 0 (identity) means the 4:4:4 planes are G, B, R.

decode_all returns every sample of an avis image sequence (with its delay), the entities of the primary's brst burst group, else the primary alone. AvifImage::new / from_rgb8 / from_rgba8 are Results that refuse a zero dimension or a buffer that does not match the geometry with InvalidData.

Options

EncodeOptions (Default = lossless): base_q_idx (AV1 quantizer, 0 = lossless) or with_quality(0..=100) (base_q_idx = ((100 − q) × 255 + 50) / 100), alpha_q_idx, premultiplied_alpha (prem signalling), chroma for the RGB one-call paths, embed_exif / embed_xmp / embed_icc, speed (EncodeSpeed::Fast default / Balanced / Thorough — the AV1 search effort; Thorough is the exhaustive search, minutes per 12 MP), threads (AV1 tile-search workers; the layout follows the picture size — TILE_LAYOUT_THREADS — so the bytes are the same at any count). StillEncodeOptions is the deprecated alias.

DecodeOptions (Default = lenient, Some(16384) × Some(16384), Some(1 << 28) pixels, Some(1 << 30) input bytes; None = unlimited): max_width, max_height, max_pixels (also caps every grid / overlay canvas on the way), max_bytes, strict (an AVIF brand is required, a claimed mif1 must carry its mandatory boxes), tone_mapped (apply a tmap gain map — default off: the base image), reference_white_nits (203), layer (render this spatial layer of a layered primary instead of its lsel), threads (the AV1 worker budget for every coded item / sample — byte-identical at any budget; None = serial, or the execution context's budget on the registry decoder).

Registry encoder options (AvifEncoderOptions): quality 0..=100 (100 = lossless, the default; base_q_idx = ((100 − quality) × 255 + 50) / 100 when q is absent, the alpha auxiliary likewise when alpha_q is absent), q / alpha_q (explicit base_q_idx, win over quality), chroma (420 default / 422 / 444: the Y′CbCr layout a packed RGB(A) frame is coded in at a lossy quality; odd extents 4:4:4; lossless RGB keeps the byte-exact identity coding), premultiplied, speed (fast default / balanced / thorough: the AV1 search effort), threads (AV1 tile-search workers; 0 = the execution context's budget; the tile layout follows the picture size, so the bytes never depend on it). Measured on a 16 × 16 textured picture: Yuv420P 592 B exact → quality 50 324 B 37.4 dB → quality 10 294 B 25.0 dB; Rgb24 795 B exact (identity) → 50 329 B 31.0 dB (4:2:0) → 10 309 B 24.7 dB. A 12 MP 4:2:0 picture at quality 50 codes in 6.1 s serial / 1.3 s on 8 workers (examples/decode_threads).

Metadata and colour

AvifImage::color is the item's colr nclx as ColorInfo { range: ColorRange, primaries, transfer, matrix } (H.273 code points; ColorRange::{Unspecified, Limited, Full}); with no CICP the MIAF §7.3.6.4 default applies — BT.709 / sRGB / BT.601, full range. to_rgb8 / to_rgba8 invert the signalled matrix at the signalled range exactly (round-to-nearest, chroma replicated to its co-sited luma samples), bring 10 / 12-bit samples to 8 bits as round(v × 255 / (2^d − 1)), and read a matrix without a kernel (reserved / unspecified / constant-luminance / ICtCp / YCgCo) as BT.601 — try_to_rgb8 reports Unsupported instead.

AvifImage::metadata: icc (an ICC colr), exif (from the TIFF header on — the HEIF A.2.1 offset word is stripped on decode and re-written on encode), xmp; gamma is always None. encode writes them back as an ICC colr next to the nclx, an Exif item and an XMP mime item. HDR descriptive properties (mdcv / clli / cclv / amve) stay on inspect's AvifInfo and the still encoder's StillProperties.

Limits

Enforced before any pixel allocation, as Error::LimitExceeded: the DecodeOptions bounds above, plus the crate's own caps — a 32 MiB per-item AV1 payload, MAX_GRID_CANVAS_PIXELS / MAX_OVERLAY_CANVAS_PIXELS (1 << 28), MAX_ITEM_DECODES (4096 item decodes per file), MAX_DERIVATION_DEPTH. Hostile input returns Error, never panics (fuzzed: contract_api, derived_graph_decode, and the cross-decoder harnesses under fuzz/).

Layering

Status

Parsing, derived-image composition, image sequences and the writer ride the container crate; the AVIF-side surface below is complete and heavily tested.

Pixel decode is live at every AV1 bit depth. The primary item's AV1 OBU stream (and every AVIS sample) is handed to oxideav-av1's conformance-grade spec-driver decoder; the composition layer then stitches grid tiles, composites the alpha auxiliary (4:2:0 / 4:2:2 / 4:4:4 / monochrome masters), and applies clap / irot / imir — at 8, 10 and 12 bits end to end. 10/12-bit output rides little-endian 16-bit word planes (Yuv*P10Le / *P12Le, Gray10Le / Gray12Le, alpha-composited Yuva*P1xLe, and packed Ya16Le for HBD monochrome + alpha with the effective depth on the core significant-bits side channel). Every committed fixture decodes end to end — including the 3840×2160 alpha composite and the multi-sample AVIS sequence — and the encode→decode HBD matrix round-trips sample-exact where lossless.

Derived images decode to pixels. The decoder resolves the primary's output image per HEIF §6.3 for any item type — recursively over dimg inputs, cycle- and depth-guarded: grid tile stitch, iovl overlay composition (§6.6.2.2 canvas + offsets + layering with the §6.9.1 straight / pre-multiplied alpha rendering, 8/10/12-bit, translucent fills yielding a Yuva* canvas), iden identity derivations carrying their own clap / irot / imir, and every item's transformative properties in ipma order. A grid primary's alpha may be a coded item or a grid of monochrome tiles. Layered (progressive) items honour lsel / a1op (av1-avif §2.3).

Pixel encode is live (still module). StillImage + encode_still / encode_still_grid drive oxideav-av1's KEY-frame encoder across the full (bit depth × chroma format) matrix — 8/10/12 bit × 4:2:0 / 4:2:2 / 4:4:4 / monochrome — plus RGB(A) via the H.273 identity matrix in 4:4:4 (byte-exact lossless round-trips), alpha as a same-depth monochrome auxiliary (av1-avif §4.1, full-range signalled in-stream), arbitrary extents (edge-replicated pad to the coded 8-grid + top-left clap, ispe = coded extents per §2.2.2), grid tiling with right/bottom trim (64-pixel tile floor + tiling election, alpha as a hidden alpha grid, pass-through properties on the grid item), iovl overlays (encode_still_overlay), iden identity derivations (StillProperties::identity_derivation), layered / progressive items (encode_still_layered: AV1 spatial layers + a1lx + lsel), depth-map auxiliaries, and avis image sequences (sequence::encode_sequence: all-intra or KEY + P groups, full moov / trak / stbl). The ftyp profile brand follows the elected AV1 profile (§8: Main → MA1B, High → MA1A, Professional → general brands only). Lossless encodes decode back sample-exact through this crate's own decoder; lossy encodes are PSNR-gated in the test suite; black-box acceptance decodes the emitted files through an external AVIF decoder binary where one is installed. The registry Encoder (make_encoder / AvifEncoder) rides the same pipeline: one video frame in, one complete AVIF file packet out (quality / q / alpha_q / chroma / premultiplied codec options; 27 declared input layouts).

The container muxer (mux module) remains available standalone: given an already-coded AV1 Image Item Data payload plus its av1C record, AvifMuxer / AvifGridMuxer / AvifOverlayMuxer / encode_still_av1 emit a conformant AVIF file — ftyp (avif/mif1/miaf + MA1B/MA1A/no profile brand), the meta tree serialised by oxideav-heif's HeifWriter (derived-item bodies in idat, MIAF mdat order, de-duplicated ipco) — with ispe / pixi / colr / pasp / clap / irot / imir item properties, an optional AV1-coded alpha auxiliary (auxC + auxl, plus prem from the master when premultiplied, HEIF 3rd ed. §6.9.1), and optional grid tiling (dimg). The output round-trips through this crate's own parse path byte-for-byte (coded payload and every property) and passes audit_mif1. At this layer the AV1 bitstream is taken black-box.

Container coverage

Constructing the crate's types

The records a user builds or reads through the documented API — the picture (AvifImage) and the contract records around it, the container results (AvifFile, AvifInfo, AvisMeta, …), the typed metadata (Ispe, Clap, Colr, Mdcv, Clli, …), StillImage / StillProperties / EncodeOptions / DecodeOptions and the muxer specs — are #[non_exhaustive]: build them with Type::new(<every field, in declaration order>) (or Default where one exists) and read / assign their pub fields; the option records take with_<field> setters (StillProperties::default().with_irot(Some(1))). The enums that grow with the standard (Property, Colr, AvifError, AuxKind, DerivationKind, …) are #[non_exhaustive] too: match them with a _ arm. The parser's and composer's own records (table entries, descriptors, placements, the HEIF-extension property family) are #[doc(hidden)] — reachable, outside the semver contract. AvifFrame / AvifPlane / AvifPixelFormat and StillChroma stay plain (the sample model AV1 closes).

Low-overhead files

AVIF (av1-avif, 2025-10) defines no low-overhead profile: mif3 / mini (HEIF Amd 2:2026 Annex O) are not AVIF brands or boxes, so this crate's brand rule refuses them. oxideav-heif reads and writes mini files (an AV1-coded one expands to an avif-equivalent meta), which is where a .hmg / image/hif2 file opens.

Container-level use

use oxideav_avif::{inspect, parse};

let bytes = std::fs::read("image.avif")?;
let info = inspect(&bytes)?;                 // AvifInfo: everything the container says
println!("{}x{} bits_per_channel={:?} av1c_len={}",
    info.width, info.height, info.bits_per_channel, info.av1c.len());
let file = parse(&bytes)?;                   // AvifFile: brands, meta, the primary av01 item
for item in &file.meta.items {
    println!("item {} type={:?} name={:?}", item.id,
        std::str::from_utf8(&item.item_type), item.name);
}
// `file.primary_item_data` is the primary image's AV1 OBU stream and
// `file.av1c` its record — pair them with your own AV1 decoder, then
// `AvifImage::new(w, h, format, planes).to_rgba8()`.
# Ok::<(), Box<dyn std::error::Error>>(())

Test fixtures

tests/fixtures/monochrome.avif is Monochrome.avif from AOMediaCodec/av1-avif (1280×720, monochrome). tests/fixtures/{gray32,midgray,white16,red,black420}.avif are tiny reference-encoder-produced AVIFs covering each colour-plane layout. Integration tests walk the full HEIF hierarchy, extract the primary item, and decode every fixture to pixels end to end (the flat lossless fixtures assert exact constant planes).

License

MIT — see LICENSE.