@UnstableApi
public final class BoxParser

Utility methods for parsing MP4 format box payloads according to ISO/IEC 14496-12.

Summary

Public methods
static void

Possibly skips the version and flags fields (1+3 byte) of a full meta box.
static int
parseFullBoxFlags(int fullBoxInt)

Parses the box flags out of the additional integer component of a full box.
static int
parseFullBoxVersion(int fullBoxInt)

Parses the version number out of the additional integer component of a full box.
static @Nullable Metadata

Parses a metadata meta box if it contains metadata with handler 'mdta'.
static Mp4TimestampData

Parses an mvhd box (defined in ISO/IEC 14496-12).
static TrackSampleTable
parseStbl(
    Track track,
    Mp4Box.ContainerBox stblBox,
    GaplessInfoHolder gaplessInfoHolder
)

Parses an stbl box (defined in ISO/IEC 14496-12).
static @Nullable Track
parseTrak(
    Mp4Box.ContainerBox trak,
    Mp4Box.LeafBox mvhd,
    long duration,
    @Nullable DrmInitData drmInitData,
    boolean ignoreEditLists,
    boolean isQuickTime
)

Parses a trak box (defined in ISO/IEC 14496-12).
static List<TrackSampleTable>
parseTraks(
    Mp4Box.ContainerBox moov,
    GaplessInfoHolder gaplessInfoHolder,
    long duration,
    @Nullable DrmInitData drmInitData,
    boolean ignoreEditLists,
    boolean isQuickTime,
    Function<@NullableType Track, @NullableType Track> modifyTrackFunction
)

Parse the trak boxes in a moov box (defined in ISO/IEC 14496-12).
static Metadata

Parses a udta box.

Public methods

maybeSkipRemainingMetaBoxHeaderBytes

public static void maybeSkipRemainingMetaBoxHeaderBytes(ParsableByteArray meta)

Possibly skips the version and flags fields (1+3 byte) of a full meta box.

Boxes of type TYPE_meta are defined to be full boxes which have four additional bytes for a version and a flags field (see 4.2 'Object Structure' in ISO/IEC 14496-12:2005). QuickTime do not have such a full box structure. Since some of these files are encoded wrongly, we can't rely on the file type though. Instead we must check the 8 bytes after the common header bytes ourselves.

Parameters
ParsableByteArray meta

The 8 or more bytes following the meta box size and type.

parseFullBoxFlags

public static int parseFullBoxFlags(int fullBoxInt)

Parses the box flags out of the additional integer component of a full box.

parseFullBoxVersion

public static int parseFullBoxVersion(int fullBoxInt)

Parses the version number out of the additional integer component of a full box.

parseMdtaFromMeta

public static @Nullable Metadata parseMdtaFromMeta(Mp4Box.ContainerBox meta)

Parses a metadata meta box if it contains metadata with handler 'mdta'.

Parameters
Mp4Box.ContainerBox meta

The metadata box to decode.
Returns
@Nullable Metadata

Parsed metadata, or null.

parseMvhd

public static Mp4TimestampData parseMvhd(ParsableByteArray mvhd)

Parses an mvhd box (defined in ISO/IEC 14496-12).

Parameters
ParsableByteArray mvhd

Contents of the mvhd box to be parsed.
Returns
Mp4TimestampData

An object containing the parsed data.

parseStbl

public static TrackSampleTable parseStbl(
    Track track,
    Mp4Box.ContainerBox stblBox,
    GaplessInfoHolder gaplessInfoHolder
)

Parses an stbl box (defined in ISO/IEC 14496-12).

Parameters
Track track

Track to which this sample table corresponds.
Mp4Box.ContainerBox stblBox

stbl (sample table) box to decode.
GaplessInfoHolder gaplessInfoHolder

Holder to populate with gapless playback information.
Returns
TrackSampleTable

Sample table described by the stbl box.
Throws
androidx.media3.common.ParserException

Thrown if the stbl box can't be parsed.

parseTrak

public static @Nullable Track parseTrak(
    Mp4Box.ContainerBox trak,
    Mp4Box.LeafBox mvhd,
    long duration,
    @Nullable DrmInitData drmInitData,
    boolean ignoreEditLists,
    boolean isQuickTime
)

Parses a trak box (defined in ISO/IEC 14496-12).

Parameters
Mp4Box.ContainerBox trak

Box to decode.
Mp4Box.LeafBox mvhd

Movie header box, used to get the timescale.
long duration

The duration in units of the timescale declared in the mvhd box, or TIME_UNSET if the duration should be parsed from the tkhd box.
@Nullable DrmInitData drmInitData

DrmInitData to be included in the format, or null.
boolean ignoreEditLists

Whether to ignore any edit lists in the trak box.
boolean isQuickTime

True for QuickTime media. False otherwise.
Returns
@Nullable Track

A Track instance, or null if the track's type isn't supported.
Throws
androidx.media3.common.ParserException

Thrown if the trak box can't be parsed.

parseTraks

public static List<TrackSampleTable> parseTraks(
    Mp4Box.ContainerBox moov,
    GaplessInfoHolder gaplessInfoHolder,
    long duration,
    @Nullable DrmInitData drmInitData,
    boolean ignoreEditLists,
    boolean isQuickTime,
    Function<@NullableType Track, @NullableType Track> modifyTrackFunction
)

Parse the trak boxes in a moov box (defined in ISO/IEC 14496-12).

Parameters
Mp4Box.ContainerBox moov

Moov box to decode.
GaplessInfoHolder gaplessInfoHolder

Holder to populate with gapless playback information.
long duration

The duration in units of the timescale declared in the mvhd box, or TIME_UNSET if the duration should be parsed from the tkhd box.
@Nullable DrmInitData drmInitData

DrmInitData to be included in the format, or null.
boolean ignoreEditLists

Whether to ignore any edit lists in the trak boxes.
boolean isQuickTime

True for QuickTime media. False otherwise.
Function<@NullableType Track, @NullableType Track> modifyTrackFunction

A function to apply to the Tracks in the result.
Returns
List<TrackSampleTable>

A list of TrackSampleTable instances.
Throws
androidx.media3.common.ParserException

Thrown if the trak boxes can't be parsed.

parseUdta

public static Metadata parseUdta(Mp4Box.LeafBox udtaBox)

Parses a udta box.

Parameters
Mp4Box.LeafBox udtaBox

The udta (user data) box to decode.
Returns
Metadata

Parsed metadata.