BoxParser

Artifact: androidx.media3:media3-extractor

Kotlin |Java

@UnstableApi
class BoxParser

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

Summary

Public functions
`java-static Unit`	`maybeSkipRemainingMetaBoxHeaderBytes(meta: ParsableByteArray!)` 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?`	`parseMdtaFromMeta(meta: Mp4Box.ContainerBox!)` Parses a metadata meta box if it contains metadata with handler 'mdta'.
`java-static Mp4TimestampData!`	`parseMvhd(mvhd: ParsableByteArray!)` Parses an mvhd box (defined in ISO/IEC 14496-12).
`java-static TrackSampleTable!`	`parseStbl( track: Track!, stblBox: Mp4Box.ContainerBox!, gaplessInfoHolder: GaplessInfoHolder!, omitTrackSampleTable: Boolean )` 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!>!, omitTrackSampleTable: Boolean )` Parse the trak boxes in a moov box (defined in ISO/IEC 14496-12).
`java-static Metadata!`	`parseUdta(udtaBox: Mp4Box.LeafBox!)` 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!,
    omitTrackSampleTable: Boolean
): 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.
`omitTrackSampleTable: Boolean`	Whether to optimize for metadata retrieval by skipping allocation and population of per-sample arrays in the `TrackSampleTable`.

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!>!,
    omitTrackSampleTable: Boolean
): (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.
`omitTrackSampleTable: Boolean`	Whether to optimize for metadata retrieval by skipping allocation and population of per-sample arrays in the `TrackSampleTable`.

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.