Minimal AVIF Box Structure for Parsers

This article outlines the minimal box hierarchy necessary for an AV1 Image File Format (AVIF) file to be recognized and decoded by a compliant parser. Because AVIF is built upon the ISO Base Media File Format (ISOBMFF) and constrained by the Multi-Image Application Format (MIAF) specification, a parser requires a specific arrangement of structural metadata and media data containers. Understanding these mandatory structural boxes allows developers to construct valid AVIF files, debug broken streams, or build lightweight demuxers.

The Minimum Box Hierarchy Tree

At the root level, an AVIF file requires three structural components: the File Type Box (ftyp), the Meta Box (meta), and the Media Data Box (mdat). Within the meta box, several mandatory child boxes define item properties, locations, and codecs.

├── ftyp (File Type Box)
├── meta (Meta Box)
│   ├── hdlr (Handler Box)
│   ├── pitm (Primary Item Box)
│   ├── iloc (Item Location Box)
│   ├── iinf (Item Information Box)
│   │   └── infe (Item Info Entry Box)
│   └── iprp (Item Properties Box)
│       ├── ipco (Item Property Container Box)
│       │   ├── ispe (Image Spatial Extents Property Box)
│       │   └── av1C (AV1 Codec Configuration Box)
│       └── ipma (Item Property Association Box)
└── mdat (Media Data Box)

Root-Level Boxes

1. ftyp (File Type Box)

The ftyp box must appear first. A compliant parser inspects this box to identify the file format before reading the rest of the stream.

• major_brand: Must be set to avif (for still images) or avis (for image sequences).
• minor_version: An informative integer representing the specification version (typically 0).
• compatible_brands: Must contain avif along with standard base brands like mif1 (MIAF) and iso8 or mp42.

2. meta (Meta Box)

The meta box contains all the structural metadata describing the primary image and its properties. Unlike standard ISOBMFF containers, the meta box is defined as a FullBox, meaning it contains an additional 4-byte header consisting of a 1-byte version and 3-byte flags (set to 00 00 00 00).

3. mdat (Media Data Box)

The mdat box carries the raw payload: the AV1 Open Bitstream Unit (OBU) data representing the compressed picture frames. The parser does not read this box sequentially; instead, it looks up data offsets defined in the meta box to locate byte ranges within mdat.

Mandatory Children of the meta Box

To successfully recognize and process the primary image item, a parser requires the following boxes inside meta:

hdlr (Handler Box)

Identifies the structure of the metadata. For AVIF still images, the handler_type field must be set to pict. Without this, the parser will not treat the meta box as an image container.

pitm (Primary Item Box)

Declares the item ID of the primary image. Even in single-image AVIF files, an explicit primary item identifier (e.g., item_ID = 1) is required to distinguish the main displayable image from auxiliary items like alpha planes or thumbnails.

iloc (Item Location Box)

Directs the parser to the exact byte offset and length of the image payload within the file (typically referencing offsets inside the mdat box). It defines construction methods, base offsets, and extent lengths.

iinf (Item Information Box)

Lists every item stored within the file. For a minimal AVIF file, it contains at least one child:

• infe (Item Info Entry Box): Maps the item_ID designated in pitm to an item type. The item_type for an AVIF primary image must be set to av01.

iprp (Item Properties Box)

The iprp box binds configuration data to items. It consists of two sub-boxes:

• ipco (Item Property Container Box): Holds indexed properties that can be shared across items. A minimal parser requires at least two properties inside ipco:
  • ispe (Image Spatial Extents): Defines the display width and display height in pixels.
  • av1C (AV1 Codec Configuration): Supplies the AV1-specific decoding metadata, including the profile, level, color bit depth, chroma subsampling (e.g., 4:2:0 or 4:4:4), and color primaries.
• ipma (Item Property Association Box): Connects the item_ID to the 1-based indices of the properties declared inside ipco. For a minimal file, this maps the primary image ID to the ispe and av1C property indices.

Parser Evaluation Flow

1. Reads the ftyp box to confirm avif is present in the compatible brands list.
2. Locates the meta box and confirms hdlr contains pict.
3. Reads pitm to identify the primary item_ID.
4. Cross-references the item_ID in iinf / infe to verify that the format is av01.
5. Retrieves dimensions and decoder configuration via ipma links to ispe and av1C inside ipco.
6. Resolves the byte offset and length using iloc, reads the compressed payload from mdat, and feeds the byte stream to the AV1 decoder.