How to Multiplex and Inspect AVIF Files with MP4Box

This article explores how MP4Box, a core multimedia packager from the open-source GPAC framework, facilitates both the multiplexing of raw AV1 bitstreams into AVIF (AV1 Image File Format) files and the in-depth structural inspection of their internal boxes. By leveraging MP4Box, developers can package still images, alpha channels, and image sequences into standards-compliant containers while troubleshooting metadata, item references, and container architecture.

Why MP4Box for AVIF?

The AVIF format is derived from the High Efficiency Image File Format (HEIF), which in turn relies on the ISO Base Media File Format (ISOBMFF). Because MP4Box was engineered specifically to manipulate ISOBMFF structures, it provides native, low-level access to the containers that wrap AV1 payloads. This makes it an ideal tool for generating and debugging AVIF files compared to standard raster image editors.

Multiplexing AVIF Files

Multiplexing (or muxing) in the context of AVIF involves taking a raw AV1 image item (often an Open Bitstream Unit, or OBU) and structuring it within ISOBMFF item boxes alongside the appropriate metadata and properties.

Basic Single-Item Encapsulation

To create an AVIF still picture from an AV1 bitstream or video frame, MP4Box imports the track and defines it as an image item rather than a continuous media track:

mp4box -add image.obu:primary -new output.avif

In this command:

• image.obu is the raw AV1 still payload.
• :primary instructs MP4Box to assign this element as the primary item (pitm) in the container.
• The output filename extension .avif triggers the assignment of the correct major brand (avif) and compatible brands (mif1, miaf).

Handling Alpha Channels and Auxiliary Items

AVIF handles transparency by multiplexing a secondary monochrome AV1 image track designated as an auxiliary item. MP4Box associates these items using an auxl (auxiliary) reference type:

mp4box -add color.obu:primary -add alpha.obu:aux=alpha -new transparent.avif

This packages both planes into a single container, directing conforming decoders to render the alpha layer over the primary color frame.

Packaging Image Sequences (AVIFS)

MP4Box can package multiple AV1 frames into an animated AVIF (AVIFS). Instead of treating frames merely as independent metadata items, it structures them as a timed media track using typical ISOBMFF track (trak) and movie (moov) structures:

mp4box -add animation.obu:fps=24 -new animated.avifs

Inspecting AVIF Files

Beyond creation, MP4Box provides robust diagnostic capabilities to analyze compliance, inspect file topology, and debug rendering errors.

Structural Box Dumps

To verify that an AVIF file correctly adheres to the MIAF (Multi-Image Application Format) or AVIF specifications, you can generate a complete dump of the file's box tree:

mp4box -diso sample.avif

This produces an XML-formatted structural breakdown containing:

• ftyp (File Type Box): Confirms compatible brands (avif, avis, mif1).
• meta (Metadata Box): Hosts the static image items.
• iinf (Item Information Box): Lists all stored items, such as primary images, auxiliary alpha planes, and Exif/XMP metadata payloads.
• iloc (Item Location Box): Specifies byte offsets and lengths for each image segment inside the container.
• iprp (Item Properties Box): Contains essential visual parameters, such as pixel aspect ratios (pasp), clean aperture (clap), and color profile information (colr).

Summary and Track Information

For a fast overview of file tracks, brands, and container settings without dumping the entire XML hierarchy, use the -info command:

mp4box -info sample.avif

This returns high-level diagnostic data, identifying whether the file is configured as a collection of static items, a timed sequence, or an image collection with embedded previews.