How libavif Encodes and Decodes AVIF Images

The open-source libavif library is the official reference implementation for the AV1 Image File Format (AVIF), providing developers with a portable, C-based toolkit for reading and writing AVIF files. Rather than reinventing the wheel, libavif acts as an intermediary layer that pairs AV1 video compression engines with the ISO Base Media File Format (ISOBMFF) container structure. By abstracting the complexities of bitstream parsing, chroma subsampling, metadata management, and color transformations, the library allows software applications to seamlessly convert raw pixel data into compressed AVIF images and reconstruct them back into displayable formats.

Architecture and Codec Abstraction

At its core, libavif is a container parser and multiplexer rather than a standalone image compressor. AVIF relies on AV1 video compression frames encapsulated in a HEIF/ISOBMFF container. To handle the actual heavy lifting of raw pixel compression and decompression, libavif relies on external AV1 codecs through an abstraction layer.

Developers can compile libavif with one or more of these backend codecs enabled, and the library automatically selects the best available engine or allows the user to specify a preferred backend at runtime.

The Encoding Workflow

Encoding an image with libavif involves taking uncompressed image buffers and transforming them into a standard-compliant .avif file through several distinct stages:

  1. Pixel Ingestion and Color Conversion: The input data—typically RGB or RGBA—is converted into the YUV color space. The library supports various chroma subsampling modes, including 4:4:4 (full resolution), 4:2:2, and 4:2:0 (standard color compression), as well as monochrome.
  2. Channel Separation: If the input image contains an alpha channel (transparency), libavif separates the alpha plane from the color planes. The primary color payload and the alpha channel are encoded as two distinct AV1 bitstreams to maintain compliance with the AVIF specification.
  3. AV1 Frame Compression: The library configures the underlying AV1 encoder with parameters such as quality factor, speed preset, tile configurations, and bit depth (8, 10, or 12 bits). The encoder processes the YUV and alpha frames, outputting compressed AV1 temporal units.
  4. ISOBMFF Multiplexing: libavif packs the compressed bitstreams into the ISOBMFF container. It creates the required box hierarchy (such as ftyp, meta, hdlr, and iloc), links the alpha item as an auxiliary image to the primary color item, and embeds metadata like ICC profiles, Exif, and XMP payloads directly into container boxes.

The Decoding Workflow

Decoding operates in reverse, reading the container format and rendering raw pixel arrays for application use:

  1. Container Parsing: When an AVIF file is fed into libavif, the parser inspects the container headers, identifies the primary image item, discovers associated alpha or depth auxiliary items, and extracts image dimensions, bit depth, and color profile information (CICP or ICC).
  2. Bitstream Extraction: The library locates the raw AV1 chunks within the media data boxes (mdat) and passes the primary color bitstream to the configured decoder (such as dav1d). If an auxiliary alpha channel exists, it is sent to the decoder concurrently or sequentially.
  3. Reconstruction and Post-Processing: The decoder outputs raw YUV and alpha planes. libavif recombines these planes, performs YUV-to-RGB conversion according to the embedded color matrix, applies any required spatial transformations (such as rotation or mirroring specified in the container metadata), and outputs a final RGB/RGBA buffer.

Advanced Feature Handling

Beyond basic single-frame operations, libavif facilitates advanced media handling: