Crate oxideav_avif 

AVIF (AV1 Image File Format) — the AV1 profile of HEIF / MIAF, with the ISOBMFF / HEIF container served by oxideav_heif and AV1 pixel decode delegated to oxideav_av1.

The image-crate API

The root follows the workspace image-crate contract (see api): probe / info standalone; decode / decode_with / decode_rgb8 / decode_rgba8 / decode_all / decode_from and encode / encode_rgb8 / encode_rgba8 / encode_to with the default-on registry feature (the pixels come from the AV1 codec crate, which is framework-only). AvifImage is the decoded picture — planes + PixelFormat + ColorInfo + Metadata — with AvifImage::to_rgb8 / AvifImage::to_rgba8; AvifFile is the parsed container (parse).

The one-screen example needs the default registry feature (the decode* / encode* paths go through the AV1 codec crate):

let bytes = std::fs::read("in.avif").map_err(oxideav_avif::Error::from)?;
if oxideav_avif::probe(&bytes) {
    let info = oxideav_avif::info(&bytes)?;
    let img = oxideav_avif::decode(&bytes)?;
    let rgba: Vec<u8> = img.to_rgba8();
    let out = oxideav_avif::encode_rgba8(
        img.width(),
        img.height(),
        &rgba,
        &oxideav_avif::EncodeOptions::default().with_quality(90),
    )?;
    assert_eq!((info.width, info.height), (img.width(), img.height()));
    std::fs::write("out.avif", out).map_err(oxideav_avif::Error::from)?;
}

Layering

• Container (oxideav-heif): the box reader (box_parser is a thin surface over it), the meta item model — hdlr, pitm, iinf + infe, iloc (every construction method), iref, iprp / ipco / ipma, idat, grpl — item payload resolution, the typed ispe / pixi / colr / pasp / clap / irot / imir / iscl / auxC / clli / amve / rloc / lsel / a1op / a1lx / rref / crtt / mdft / udes / altt properties, the derived-image descriptors, pixel composition (grid / iovl / iden, alpha attachment, clap / irot / imir), the moov / trak / stbl sample tables and the still-image writer.
• AVIF profile (this crate): parse / parse_header build this crate’s Meta from the container’s, keep av1C raw for the AV1 layer, read mdcv / cclv and the HEIF-extension properties (aebr … cmin, the slideshow transition effects, prdi, sstr, txlo, elng, fnch, mskC) from the raw property bytes, and enforce the AVIF brand rule; the av1-avif §2–§8 audits (audit_avif_profile_compliance, audit_alpha_bit_depth, audit_sequence_header_obu, audit_tone_map, audit_avis_sequence …), the sato descriptor / evaluator (§4.2.3) and tmap detection (§4.2.2), the AV1 decode of every coded item with lsel / a1op layer selection, the AVIF-side composition rules (av1-avif §4.1 same-depth alpha, nearest-neighbour alpha resize, the ispe / grid trim with AV1’s ceiling chroma extents, monochrome overlays staying monochrome), the avis sample handling, the writer’s AVIF layout (brands, item order, property sets, auxC URNs) and the pixel encoder’s tile election.

Status

• AvifDecoder’s receive_frame composites the result:
  • Grid items (HEIF §6.6.2) — decode each tile via dimg iref and stitch into the declared output rectangle (see grid).
  • Alpha auxiliary — AV1-coded monochrome item referenced via auxl + auxC URN (see alpha). The av1-avif v1.2.0 §4.1 shall “AV1 Alpha Image Item shall be encoded with the same bit depth as the associated master AV1 Image Item” is audited at the container layer via audit_alpha_bit_depth / AlphaBitDepthAudit, surfaced through AvifInfo::alpha_bit_depth_compliance.
  • irot / imir / clap post-transforms (see transform).
• AVIS image sequences — avis::parse_avis walks the first track through the container’s sample-table parser and produces a flat frame-offset list with (timescale, display_dims, samples, av1_codec_config, handler, sample_description_types). avis::sample_bytes resolves a sample’s byte slice inside the source file. The registry-gated decoder (decoder::AvifDecoder::decode_avis_file) walks the table end to end, lifts the AV1CodecConfigurationRecord from stsd → av01 → av1C, and fans every sample through a shared oxideav_av1 registry decoder so inter-frame state is preserved. Decoder::send_packet dispatches to this path automatically when the file’s brand classification flags it as a sequence. The av1-avif v1.2.0 §3 shalls on an AV1 Image Sequence track (handler 'pict', single 'av01' sample description, identical Sequence Header OBUs across samples) are audited at the container layer via audit_avis_sequence / AvisSequenceCompliance.
• pixi (HEIF §6.5.6) and pasp (HEIF §6.5.4 / ISO/IEC 14496-12 §8.5.2.1.1) are surfaced through AvifInfo — see AvifInfo::num_channels, AvifInfo::max_bit_depth, AvifInfo::is_monochrome and AvifInfo::has_square_pixels.

Encoder

The container muxer is implemented in mux: AvifMuxer / AvifGridMuxer / AvifOverlayMuxer / encode_still_av1 emit a conformant AVIF file around an already-coded AV1 Image Item Data payload plus its av1C record — this crate decides the brands, item order and property sets, oxideav_heif::HeifWriter serialises the meta tree and mdat — with ispe / pixi / colr / pasp / clap / irot / imir item properties, an optional AV1-coded alpha auxiliary (auxC + auxl), and optional grid tiling (dimg). The output round-trips through this crate’s own parse path pixel-consistently (the coded AV1 stream is copied verbatim).

Turning raw pixels into that AV1 bitstream is the job of the still module (StillImage + encode_still / encode_still_grid): it drives oxideav_av1’s conformance-grade KEY-frame encoder across the full (bit depth × chroma format) matrix — including RGB(A) via the H.273 identity matrix, alpha auxiliaries, arbitrary extents (pad + clap), and grid tiling — then wraps the coded payload through the muxer. The registry Encoder surface (make_encoder / AvifEncoder) rides the same pipeline: every video frame sent through send_frame yields one complete AVIF file packet. Callers holding an already-coded payload keep muxing it directly with AvifMuxer.

Standalone vs registry-integrated

The crate’s default-on registry Cargo feature pulls in oxideav-core + oxideav-av1 and exposes the oxideav_core::Decoder trait surface plus the register entry point. Disable the feature (default-features = false) for an oxideav-core-free build that still exposes:

• The container parse (parser, parse, parse_header, meta; box_parser over oxideav_heif::boxes).
• The AVIS sample-table walker (avis::parse_avis).
• The grid / overlay / alpha / transform composition entry points (grid, overlay, alpha, transform) over the container’s compose layer, operating on crate-local image::AvifFrame / image::AvifPixelFormat.
• Container-side inspection: inspect::inspect, inspect::AvifInfo, inspect::transforms_for.
• The CICP signalling helpers (cicp).

Standalone callers that want pixel decode must pair this surface with their own AV1 decoder — the in-tree one (oxideav_av1) is pulled in only when registry is on.

Re-exports

pub use alpha::composite_alpha;

pub use alpha::find_alpha_item_id;

pub use alpha::ALPHA_URN_PREFIX;

pub use api::info;

pub use api::probe;

pub use api::AvifImage;

pub use api::ColorInfo;

pub use api::ColorRange;

pub use api::DecodeOptions;

pub use api::EncodeOptions;

pub use api::EncodeSpeed;

pub use api::Frame;

pub use api::ImageInfo;

pub use api::Metadata;

pub use api::PixelFormat;

pub use api::Plane;

pub use api::RgbImage;

pub use api::RgbaImage;

pub use api::StillChroma;

pub use avis::audit_avis_profile_compliance;

pub use avis::audit_avis_sequence;

pub use avis::audit_edit_list;

pub use avis::inspect_avis;

pub use avis::parse_avis;

pub use avis::parse_prft;

pub use avis::parse_producer_reference_times;

pub use avis::parse_ssix;

pub use avis::parse_subsegment_indexes;

pub use avis::sample_bytes;

pub use avis::AvisInfo;

pub use avis::AvisMeta;

pub use avis::AvisProfileCompliance;

pub use avis::AvisSequenceCompliance;

pub use avis::EditListCompliance;

pub use avis::HANDLER_PICT;

pub use avis::NTP_UNIX_EPOCH_OFFSET_SECONDS;

pub use cicp::effective_cicp;

pub use cicp::is_matrix_reserved;

pub use cicp::is_primaries_reserved;

pub use cicp::is_transfer_reserved;

pub use cicp::matrix_name;

pub use cicp::primaries_name;

pub use cicp::transfer_name;

pub use cicp::CicpTriple;

pub use derived::audit_alpha_bit_depth;

pub use derived::audit_avif_profile_compliance;

pub use derived::audit_iden_derivations;

pub use derived::audit_pred_brand;

pub use derived::audit_sequence_header_obu;

pub use derived::audit_tone_map;

pub use derived::build_derivation_graph;

pub use derived::normalize_full_range_plane;

pub use derived::output_dims_from_reconstructed;

pub use derived::parse_grpl;

pub use derived::reconstructed_dims;

pub use derived::resolve_grids;

pub use derived::resolve_iden_derivations;

pub use derived::resolve_overlays;

pub use derived::resolve_tone_maps;

pub use derived::transform_chain;

pub use derived::AlphaBitDepthAudit;

pub use derived::AvifProfile;

pub use derived::AvifProfileCompliance;

pub use derived::BracketingKind;

pub use derived::DerivationGraph;

pub use derived::DerivationKind;

pub use derived::DerivationNode;

pub use derived::EntityGroup;

pub use derived::IdenCompliance;

pub use derived::Mif1Compliance;

pub use derived::PredBrandCompliance;

pub use derived::SampleTransform;

pub use derived::SequenceHeaderObuAudit;

pub use derived::Token;

pub use derived::ToneMapCompliance;

pub use derived::MAX_DERIVATION_DEPTH;

pub use error::AvifError;

pub use error::Result;

pub use grid::composite_grid;

pub use image::AvifFrame;

pub use image::AvifPixelFormat;

pub use image::AvifPlane;

pub use inspect::coded_item_dependencies;

pub use inspect::derivation_graph;

pub use inspect::entity_groups;

pub use inspect::gain_map_metadata;

pub use inspect::inspect;

pub use inspect::is_font_item;

pub use inspect::item_payload_bytes;

pub use inspect::region_items;

pub use inspect::region_items_for;

pub use inspect::text_items;

pub use inspect::text_items_for;

pub use inspect::transforms_for;

pub use inspect::AvifInfo;

pub use inspect::CodedItemDependencies;

pub use inspect::ResolvedRegionItem;

pub use inspect::ResolvedTextItem;

pub use meta::A1lx;

pub use meta::A1op;

pub use meta::AuxC;

pub use meta::AuxKind;

pub use meta::Cclv;

pub use meta::Clap;

pub use meta::Clli;

pub use meta::Colr;

pub use meta::Imir;

pub use meta::Irot;

pub use meta::Ispe;

pub use meta::ItemInfo;

pub use meta::Lsel;

pub use meta::Mdcv;

pub use meta::Meta;

pub use meta::Pasp;

pub use meta::Pixi;

pub use meta::Property;

pub use meta::AUX_URN_ALPHA_HEVC;

pub use meta::AUX_URN_ALPHA_MPEG;

pub use meta::AUX_URN_DEPTH_HEVC;

pub use meta::AUX_URN_DEPTH_MPEG;

pub use meta::AUX_URN_HDR_GAINMAP;

pub use meta::ITEM_TYPE_EXIF;

pub use meta::ITEM_TYPE_IDEN;

pub use meta::ITEM_TYPE_IOVL;

pub use meta::ITEM_TYPE_MIME;

pub use meta::ITEM_TYPE_SATO;

pub use meta::ITEM_TYPE_TMAP;

pub use meta::ITEM_TYPE_URI;

pub use mux::encode_still_av1;

pub use mux::AvifGridMuxer;

pub use mux::AvifMuxer;

pub use mux::AvifOverlayMuxer;

pub use mux::BurstAlpha;

pub use mux::BurstMember;

pub use mux::EntityGroupSpec;

pub use mux::GridTile;

pub use mux::IdentityDerivation;

pub use mux::OverlayLayer;

pub use mux::ToneMapItem;

pub use overlay::composite_overlay;

pub use overlay::OverlayInput;

pub use overlay::MAX_OVERLAY_CANVAS_PIXELS;

pub use parser::audit_mif1;

pub use parser::classify_brands;

pub use parser::item_bytes;

pub use parser::item_bytes_owned;

pub use parser::item_bytes_owned_full;

pub use parser::item_bytes_owned_with_idat;

pub use parser::item_bytes_with_idat;

pub use parser::parse;

pub use parser::parse_header;

pub use parser::AvifFile;

pub use parser::AvifHeader;

pub use parser::BRAND_AVIF;

pub use parser::BRAND_AVIO;

pub use parser::BRAND_AVIS;

pub use parser::BRAND_MA1A;

pub use parser::BRAND_MA1B;

pub use parser::BRAND_MIAF;

pub use parser::BRAND_MIF1;

pub use parser::BRAND_MSF1;

pub use parser::ITEM_TYPE_AV01;

pub use parser::ITEM_TYPE_GRID;

pub use region::resolve_derived_region_items;

pub use region::DerivedRegionItem;

pub use region::RegionGeometry;

pub use region::RegionItem;

pub use region::ITEM_TYPE_MSKI;

pub use region::ITEM_TYPE_RGAN;

pub use region::REF_TYPE_DRGN;

pub use sample_group::parse_csgp;

pub use sample_group::parse_sample_group_descriptions;

pub use sample_group::parse_sample_to_groups;

pub use sample_group::parse_sbgp;

pub use sample_group::parse_sgpd;

pub use transform::apply_clap;

pub use transform::apply_imir;

pub use transform::apply_irot;

pub use transform::crop_top_left;

pub use api_codec::decode;

pub use api_codec::decode_all;

pub use api_codec::decode_all_with;

pub use api_codec::decode_from;

pub use api_codec::decode_rgb8;

pub use api_codec::decode_rgba8;

pub use api_codec::decode_with;

pub use api_codec::encode;

pub use api_codec::encode_all;

pub use api_codec::encode_rgb8;

pub use api_codec::encode_rgba8;

pub use api_codec::encode_to;

pub use decoder::make_decoder;

pub use decoder::AvifDecoder;

pub use decoder::AvifDecoderOptions;

pub use decoder::MAX_GRID_CANVAS_PIXELS;

pub use decoder::MAX_ITEM_DECODES;

pub use encoder::make_encoder;

pub use encoder::quality_to_base_q_idx;

pub use encoder::AvifEncoder;

pub use encoder::AvifEncoderOptions;

pub use encoder::ENCODER_PIXEL_FORMATS;

pub use sequence::encode_sequence;

pub use sequence::SequenceEncodeOptions;

pub use signal::color_signal_for;

pub use signal::labelled_pixel_format;

pub use signal::miaf_default_signal;

pub use still::StillEncodeOptions;Deprecated

pub use still::elect_grid_tiling;

pub use still::encode_still;

pub use still::encode_still_auto;

pub use still::encode_still_burst;

pub use still::encode_still_grid;

pub use still::encode_still_layered;

pub use still::encode_still_overlay;

pub use still::GainMapSpec;

pub use still::OverlayCanvas;

pub use still::OverlayLayerImage;

pub use still::StillImage;

pub use still::StillProperties;

pub use still::GRID_MIN_TILE_DIM;

pub use still::STILL_MAX_CODED_DIM;

pub use still::TILE_LAYOUT_THREADS;

Modules

alpha

AVIF alpha auxiliary-image handling.

api

The workspace image-crate API (IMAGE_CRATE_API.md): the small root vocabulary every oxideav-<format> picture crate shares — probe / info / decode* / encode*, the pixel type AvifImage, the raw RgbImage / RgbaImage records and the option records.

api_codec

The registry-gated half of the image-crate API: decode* / encode* over crate::api::AvifImage, the AV1 work done by oxideav-av1. The framework Decoder / Encoder (crate::AvifDecoder / crate::AvifEncoder) are thin adapters over the functions here.

avis

AVIS (AVIF image sequences) sample-table walk.

box_parser

ISO Base Media File Format box-header access (ISO/IEC 14496-12 §4.2, §4.2.2 FullBox), served by the container crate.

cicp

CICP (Coding-Independent Code Points) — ITU-T H.273 colour signalling.

decoder

AVIF Decoder implementation — registry-gated.

derived

Derived-image descriptors and entity grouping — HEIF §6.6.2 + §9.4, plus AV1-AVIF v1.2.0 §4.2.3 sample-transform derivations.

encoder

AVIF Encoder trait wiring — registry-gated.

error

Crate-local error type.

grid

AVIF grid-image composition (HEIF §6.6.2.3).

image

Crate-local frame / pixel-format types.

inspect

Standalone container-side inspection: parse the HEIF box hierarchy, resolve the primary item, surface dimensions / colour / pixi / pasp / alpha-presence in AvifInfo.

meta

meta box hierarchy parser — ISO/IEC 14496-12 §8.11 + ISO/IEC 23008-12 (HEIF) §6 / §9 (item properties). Restricted to the subset AVIF actually populates:

mux

AVIF container muxer — the AV1-profile item layout over the container crate’s writer (oxideav_heif::HeifWriter).

overlay

iovl image-overlay pixel composition — HEIF §6.6.2.2 (canvas + per-input offsets + layering order) rendered with the §6.9.1 alpha-plane semantics, at 8, 10 and 12 bits, framework-free.

parser

Top-level AVIF file walk: ftyp brand check → meta parse → resolve the primary item’s payload inside mdat → return the AV1 OBU byte slice + the properties the downstream decoder needs.

region

HEIF region items and region geometries (ISO/IEC 23008-12 §11.2 / §11.3).

sample_group

Sample-to-group parsing for AVIS image-sequence tracks.

sequence

AVIF image sequence (avis) encode — av1-avif §3 / §6.3 / §8.2, the AV1 ISOBMFF binding §2 (AV1 sample entry, sample format, sync samples) and ISO/IEC 14496-12 §8 (movie / track / sample tables).

signal

Colour signalling of a decoded AVIF on the framework surface (oxideav-core 0.1.37 ColorSignal) — registry-gated.

still

Pixel → AVIF still-image encoder — registry-gated.

transform

Post-decode geometric transforms for AVIF image items — HEIF §6.5.9 (clap), §6.5.10 (irot) and §6.5.12 (imir) — applied by the container crate’s composition layer (oxideav_heif::compose).

Constants

CODEC_ID_STR

Public codec id string. Matches the aggregator-crate Cargo feature avif.

Functions

register

Unified registration entry point: install both the AVIF codec factories and the .avif / .avifs extension hints into a RuntimeContext.

register_codecs

Register the AVIF decoder + encoder factories with a registry. The decoder is declared avif_heif_av1_decode — we parse the HEIF container end to end, hand the AV1 bitstream to oxideav-av1, and composite grid / alpha / transform properties on the resulting frames. The encoder factory (make_encoder) yields the pixel-in AVIF encoder (one complete AVIF file per frame; see crate::encoder for the format/option surface).

register_containers

Register the .avif / .avifs extensions against the codec id "avif" so consumers (cli-convert, pipeline output probing) can resolve a .avif output path through the central ContainerRegistry without a hard-coded extension list.

register_with_av1

Convenience: register AVIF and the underlying AV1 codec in one call — the historical contract of this entry point, restored now that oxideav-av1’s clean-room rebuild ships its own registry surface again. Callers that only want the AVIF factories keep using register_codecs.

Type Aliases

Error

The crate error under the contract’s name.