Reading and Modifying AVIF Metadata with ExifTool

Modern command-line utilities like ExifTool read and modify metadata in AV1 Image File Format (AVIF) files by parsing the structural hierarchy of the underlying ISO Base Media File Format (ISOBMFF). Rather than decoding the compressed AV1 visual payload, these tools navigate nested structural data blocks known as "boxes" to extract, edit, and re-index embedded metadata payloads like Exif, XMP, and IPTC. This process involves locating data items via internal index tables, recalculating byte offsets when sizes change, and safely reconstructing the container without re-encoding the underlying image bitstream.

The ISOBMFF Structure Behind AVIF

AVIF does not store metadata as raw headers appended to the beginning of the file. Instead, it inherits the box-structured architecture defined by ISOBMFF and HEIF. Every block of data is preceded by a four-byte length header and a four-byte FourCC (Four-Character Code) label.

The root of an AVIF file contains high-level structural boxes:

• ftyp (File Type Box): Identifies the file brand and compatibility (e.g., avif, mif1).
• meta (Item Metadata Box): Houses descriptive metadata, references, and item catalogs.
• mdat (Media Data Box): Holds the raw binary data, including the AV1 image bitstream and sometimes raw metadata payloads.

Within the meta box, two structural components are critical for metadata management: the Item Information Box (iinf) and the Item Location Box (iloc).

How ExifTool Reads AVIF Metadata

To read metadata, ExifTool walks the box hierarchy to resolve item references:

1. Scanning Item Types: ExifTool navigates into the meta box and locates iinf. Inside iinf, it inspects individual Item Info Entries (infe). Each entry registers an item ID and a specific type, such as Exif or mime (with a content type like application/rdf+xml for XMP).
2. Resolving Byte Offsets: Once an item ID associated with metadata is found, ExifTool cross-references that ID in the iloc box. The iloc box acts as a partition map, declaring the exact byte offset and byte length of the item's payload.
3. Extracting the Payload: ExifTool seeks directly to the specified byte offset—which points to a location inside an idat (Item Data Box) or the root mdat box—and reads the raw payload.
4. Parsing Metadata Blocks: Once extracted, ExifTool feeds the raw byte stream into its format-specific parsers. For example, it strips any format-specific prefixes (such as the standard 4-byte Exif header offset) and reads standard TIFF/Exif tags or parses XML serialization for XMP.

How ExifTool Modifies AVIF Metadata

Writing metadata to an AVIF file is more complex than reading because altering a metadata field often changes the total byte size of that block. In an offset-based container like ISOBMFF, changing a single byte's position breaks existing references across the entire file.

To prevent data corruption, ExifTool uses an atomic rewrite process:

1. Payload Serialization: ExifTool takes the updated metadata tags, serializes them into the target format (such as an updated Exif binary block or XMP XML packet), and prepares the new byte stream.
2. Container Reconstruction: ExifTool generates a new temporary file rather than modifying the original in-place. It copies unchanged boxes, such as ftyp and the image bitstream inside mdat.
3. Offset Recalculation: Because the size of the metadata has changed, all data residing downstream from the insertion point shifts. ExifTool recalculates all absolute and relative offsets for every referenced item (including the primary AV1 image frame) and updates the entries within the iloc box.
4. Box Header Adjustments: The size field at the beginning of every ancestor box—including meta, mdat, and any parent grouping boxes—is updated to reflect the new dimensions.
5. Safe Replacement: Once the new file passes container integrity checks, ExifTool replaces the original file on disk.

Performance and Data Integrity

Because ExifTool treats the AV1 video frame within the mdat container as an opaque binary blob, metadata operations execute without decompressing or re-encoding visual data. This ensures zero generational quality loss, uses minimal CPU overhead, and keeps the operations fast enough for high-volume batch processing on the command line.