How libavif Parses the ISOBMFF ftyp Box

This article explains how the libavif library reads and validates the ftyp (File Type) box within an ISO Base Media File Format (ISOBMFF) container. We will detail the sequential parsing steps, the specific brand identifiers libavif looks for, and how the library determines if a file is a compatible AVIF image.

The Role of the ftyp Box in AVIF

The ISO Base Media File Format (ISOBMFF) serves as the container for AVIF images. The ftyp box is structurally required to be at the very beginning of the file (optionally preceded only by a free box). It defines the file’s primary purpose and compatibility profiles using four-character codes (4CCs).

For libavif to successfully decode an image, it must first parse this box to verify that the file actually conforms to the AVIF specification.

Step-by-Step Parsing in libavif

When a file is passed to libavif (typically starting inside the avifDecoderParse() function), the internal reader processes the ftyp box through the following sequence:

1. Box Header Reading

The parser reads the standard ISOBMFF box header, which consists of: * Box Size: A 32-bit (or 64-bit) unsigned integer indicating the total size of the box. * Box Type: A 4-byte character array. libavif verifies that this type is exactly 'ftyp'. If the first encountered box is not 'ftyp' (and not a negligible box like 'free'), the parser aborts immediately with an invalid file error.

2. Extracting the Major Brand

Directly following the box header, the parser reads the first 4 bytes of the box payload, which represent the major_brand. The major brand indicates the primary specification to which the file complies.

3. Extracting the Minor Version

The next 4 bytes represent the minor_version, a 32-bit integer indicating the specification’s version. While libavif reads this value, it is generally ignored for basic compatibility checks, as brand signatures dictate feature support.

4. Reading Compatible Brands

The remainder of the ftyp box payload is treated as an array of 4-byte compatible brands. libavif loops through this array, reading each 4CC until the end of the box payload is reached (calculated using the box size determined in step 1).

Brand Validation Logic

Once the brands are extracted, libavif evaluates them against a hardcoded list of supported AVIF-related signatures.

To be recognized as a valid AVIF file, either the major_brand or at least one of the compatible_brands must match one of the following recognized 4CCs:

Additionally, the parser checks for codec-specific compatibility helper brands, such as av01 (indicating the AV1 bitstream profile).

If neither avif nor avis is found within the major or compatible brands list, libavif will reject the file and return the error code AVIF_RESULT_INVALID_FTYP.

Error Handling and Security

During the parsing of the ftyp box, libavif implements strict bounds checking to prevent security vulnerabilities: * Truncation Checks: If the input buffer ends before the full size of the declared ftyp box is read, the library flags a truncation error. * Buffer Overrun Prevention: The reader ensures that the loop extracting compatible brands never reads past the declared box boundary or the end of the input stream. * Zero Size Prevention: An ftyp box reporting an invalid or impossible size will trigger an immediate parsing failure.