@UnstableApi
class BoxParser

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

Summary

Public functions
java-static Unit

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

Parses the box flags out of the additional integer component of a full box.
java-static Int
parseFullBoxVersion(fullBoxInt: Int)

Parses the version number out of the additional integer component of a full box.
java-static Metadata?

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

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

Parses an stbl box (defined in ISO/IEC 14496-12).
java-static Track?
parseTrak(
    trak: Mp4Box.ContainerBox!,
    mvhd: Mp4Box.LeafBox!,
    duration: Long,
    drmInitData: DrmInitData?,
    ignoreEditLists: Boolean,
    isQuickTime: Boolean
)

Parses a trak box (defined in ISO/IEC 14496-12).
java-static (Mutable)List<TrackSampleTable!>!
parseTraks(
    moov: Mp4Box.ContainerBox!,
    gaplessInfoHolder: GaplessInfoHolder!,
    duration: Long,
    drmInitData: DrmInitData?,
    ignoreEditLists: Boolean,
    isQuickTime: Boolean,
    modifyTrackFunction: Function<@NullableType Track!, @NullableType Track!>!
)

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

Parses a udta box.

Public functions

maybeSkipRemainingMetaBoxHeaderBytes

java-static fun maybeSkipRemainingMetaBoxHeaderBytes(meta: ParsableByteArray!): Unit

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
meta: ParsableByteArray!

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

parseFullBoxFlags

java-static fun parseFullBoxFlags(fullBoxInt: Int): Int

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

parseFullBoxVersion

java-static fun parseFullBoxVersion(fullBoxInt: Int): Int

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

parseMdtaFromMeta

java-static fun parseMdtaFromMeta(meta: Mp4Box.ContainerBox!): Metadata?

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

Parameters
meta: Mp4Box.ContainerBox!

The metadata box to decode.
Returns
Metadata?

Parsed metadata, or null.

parseMvhd

java-static fun parseMvhd(mvhd: ParsableByteArray!): Mp4TimestampData!

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

Parameters
mvhd: ParsableByteArray!

Contents of the mvhd box to be parsed.
Returns
Mp4TimestampData!

An object containing the parsed data.

parseStbl

java-static fun parseStbl(
    track: Track!,
    stblBox: Mp4Box.ContainerBox!,
    gaplessInfoHolder: GaplessInfoHolder!
): TrackSampleTable!

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

Parameters
track: Track!

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

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

java-static fun parseTrak(
    trak: Mp4Box.ContainerBox!,
    mvhd: Mp4Box.LeafBox!,
    duration: Long,
    drmInitData: DrmInitData?,
    ignoreEditLists: Boolean,
    isQuickTime: Boolean
): Track?

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

Parameters
trak: Mp4Box.ContainerBox!

Box to decode.
mvhd: Mp4Box.LeafBox!

Movie header box, used to get the timescale.
duration: Long

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.
drmInitData: DrmInitData?

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

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

True for QuickTime media. False otherwise.
Returns
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

java-static fun parseTraks(
    moov: Mp4Box.ContainerBox!,
    gaplessInfoHolder: GaplessInfoHolder!,
    duration: Long,
    drmInitData: DrmInitData?,
    ignoreEditLists: Boolean,
    isQuickTime: Boolean,
    modifyTrackFunction: Function<@NullableType Track!, @NullableType Track!>!
): (Mutable)List<TrackSampleTable!>!

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

Parameters
moov: Mp4Box.ContainerBox!

Moov box to decode.
gaplessInfoHolder: GaplessInfoHolder!

Holder to populate with gapless playback information.
duration: Long

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.
drmInitData: DrmInitData?

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

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

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

A function to apply to the Tracks in the result.
Returns
(Mutable)List<TrackSampleTable!>!

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

Thrown if the trak boxes can't be parsed.

parseUdta

java-static fun parseUdta(udtaBox: Mp4Box.LeafBox!): Metadata!

Parses a udta box.

Parameters
udtaBox: Mp4Box.LeafBox!

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

Parsed metadata.