How avifDecoderParse Works in libavif

This article explains the role and inner workings of the avifDecoderParse function within the libavif library’s decoding pipeline. It details how the function parses the ISOBMFF container to extract metadata, image properties, and item locations, preparing the decoder for the subsequent pixel decoding stage.

In the libavif decoding lifecycle, avifDecoderParse serves as the essential gateway between raw file input and actual image decompression. Before pixels can be decoded, the library must understand the structure of the AVIF container. AVIF files are based on the ISO Base Media File Format (ISOBMFF), which organizes data into nested structures called “boxes.” The primary job of avifDecoderParse is to read and validate these boxes to determine what the file contains.

When avifDecoderParse is called, it performs several sequential operations:

1. Box Parsing and Validation

The function scans the input data stream to locate and parse key ISOBMFF boxes. It verifies the file type by checking the ftyp (File Type) box for AVIF-compatible brand identifiers. It then processes the meta (Metadata) box, which contains the structural map of the image items, color profiles, and relationships between different image layers (such as the primary color image and its associated alpha auxiliary channel).

2. Extracting Image Properties and Metadata

As it parses the container, avifDecoderParse extracts crucial metadata without decoding the actual AV1 bitstream. It reads properties such as: * Image Dimensions: Width and height of the primary image. * Color Configuration: Bit depth, pixel format (e.g., YUV 4:2:0, 4:4:4), and color range. * Color Profiles: Embedded ICC profiles or NCLX (color primaries, transfer characteristics, and matrix coefficients) values. * Auxiliary Data: Exif and XMP metadata payloads.

3. Locating the Compressed Payloads

One of the most critical roles of avifDecoderParse is identifying where the compressed AV1 image data resides. It parses the iloc (Item Location) box to find the exact byte offsets and lengths of the compressed payloads (items) within the file. By mapping these locations, the function prepares the decoder to fetch the precise chunks of data needed for the next step, avoiding unnecessary memory overhead.

4. Setting Up the Decoder State

Once the parsing is complete, the function populates the internal structures of the avifDecoder object. It configures the image properties (accessible via decoder->image) so that the calling application can query the image’s dimensions and color properties before allocating buffers for the decoded pixels.

Integration in the Decoding Loop

In a typical libavif decoding loop, avifDecoderParse is called immediately after initializing the decoder and setting the source input, but before any frames are decoded:

// 1. Create and configure decoder
avifDecoder * decoder = avifDecoderCreate();
avifDecoderSetFile(decoder, "image.avif");

// 2. Parse the container (avifDecoderParse)
avifResult parseResult = avifDecoderParse(decoder);
if (parseResult == AVIF_RESULT_OK) {
    // At this point, metadata and dimensions are available
    // (e.g., decoder->image->width, decoder->image->height)

    // 3. Decode the actual pixels
    avifResult decodeResult = avifDecoderNextImage(decoder);
    if (decodeResult == AVIF_RESULT_OK) {
        // Image pixels are now fully decoded and ready for use
    }
}

// 4. Clean up
avifDecoderDestroy(decoder);

By decoupling the container parsing from the pixel decompression, avifDecoderParse allows applications to efficiently inspect AVIF file properties, read metadata, and prepare memory layouts before committing CPU resources to the computationally expensive task of AV1 video/image decoding.