@UnstableApi
class VorbisUtil

Utility methods for parsing Vorbis streams.

Summary

Nested types

Vorbis comment header.

Vorbis setup header modes.

Vorbis identification header.

Public functions
java-static IntArray<Int>?

Returns the mapping from VORBIS channel layout to the channel layout expected by Android, or null if the mapping is unchanged.
java-static Int
iLog(x: Int)

Returns ilog(x), which is the index of the highest set bit in x.
java-static Metadata?
parseVorbisComments(vorbisComments: (Mutable)List<String!>!)

Builds a Metadata instance from a list of Vorbis Comments.
java-static ImmutableList<ByteArray<Byte>!>!

Returns codec-specific data for configuring a media codec for decoding Vorbis.
java-static VorbisUtil.CommentHeader!

Reads a Vorbis comment header.
java-static VorbisUtil.CommentHeader!
readVorbisCommentHeader(
    headerData: ParsableByteArray!,
    hasMetadataHeader: Boolean,
    hasFramingBit: Boolean
)

Reads a Vorbis comment header.
java-static VorbisUtil.VorbisIdHeader!

Reads a Vorbis identification header from headerData.
java-static Array<VorbisUtil.Mode!>!
readVorbisModes(headerData: ParsableByteArray!, channels: Int)

This method reads the modes which are located at the very end of the Vorbis setup header.
java-static Boolean
verifyVorbisHeaderCapturePattern(
    headerType: Int,
    header: ParsableByteArray!,
    quiet: Boolean
)

Verifies whether the next bytes in header are a Vorbis header of the given headerType.

Public functions

getVorbisToAndroidChannelLayoutMapping

java-static fun getVorbisToAndroidChannelLayoutMapping(channelCount: Int): IntArray<Int>?

Returns the mapping from VORBIS channel layout to the channel layout expected by Android, or null if the mapping is unchanged.

See https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-140001.2.3 and https://developer.android.com/reference/android/media/AudioFormat#channelMask.

iLog

java-static fun iLog(x: Int): Int

Returns ilog(x), which is the index of the highest set bit in x.

See the Vorbis spec

Parameters
x: Int

the value of which the ilog should be calculated.
Returns
Int

ilog(x)

parseVorbisComments

java-static fun parseVorbisComments(vorbisComments: (Mutable)List<String!>!): Metadata?

Builds a Metadata instance from a list of Vorbis Comments.

METADATA_BLOCK_PICTURE comments will be transformed into PictureFrame entries. All others will be transformed into VorbisComment entries.

Parameters
vorbisComments: (Mutable)List<String!>!

The raw input of comments, as a key-value pair KEY=VAL.
Returns
Metadata?

The fully parsed Metadata instance. Null if no vorbis comments could be parsed.

parseVorbisCsdFromEsdsInitializationData

java-static fun parseVorbisCsdFromEsdsInitializationData(initializationData: ByteArray!): ImmutableList<ByteArray<Byte>!>!

Returns codec-specific data for configuring a media codec for decoding Vorbis.

Parameters
initializationData: ByteArray!

The initialization data from the ESDS box.
Returns
ImmutableList<ByteArray<Byte>!>!

Codec-specific data for configuring a media codec for decoding Vorbis.

readVorbisCommentHeader

java-static fun readVorbisCommentHeader(headerData: ParsableByteArray!): VorbisUtil.CommentHeader!

Reads a Vorbis comment header.

See the Vorbis spec/Comment header

Parameters
headerData: ParsableByteArray!

A ParsableByteArray wrapping the header data.
Returns
VorbisUtil.CommentHeader!

A VorbisUtil.CommentHeader with all the comments.
Throws
androidx.media3.common.ParserException

If an error occurs parsing the comment header.

readVorbisCommentHeader

java-static fun readVorbisCommentHeader(
    headerData: ParsableByteArray!,
    hasMetadataHeader: Boolean,
    hasFramingBit: Boolean
): VorbisUtil.CommentHeader!

Reads a Vorbis comment header.

The data provided may not contain the Vorbis metadata common header and the framing bit.

See the Vorbis spec/Comment header

Parameters
headerData: ParsableByteArray!

A ParsableByteArray wrapping the header data.
hasMetadataHeader: Boolean

Whether the headerData contains a Vorbis metadata common header preceding the comment header.
hasFramingBit: Boolean

Whether the headerData contains a framing bit.
Returns
VorbisUtil.CommentHeader!

A VorbisUtil.CommentHeader with all the comments.
Throws
androidx.media3.common.ParserException

If an error occurs parsing the comment header.

readVorbisIdentificationHeader

java-static fun readVorbisIdentificationHeader(headerData: ParsableByteArray!): VorbisUtil.VorbisIdHeader!

Reads a Vorbis identification header from headerData.

See the Vorbis spec/Identification header

Parameters
headerData: ParsableByteArray!

a ParsableByteArray wrapping the header data.
Returns
VorbisUtil.VorbisIdHeader!

a VorbisUtil.VorbisIdHeader with meta data.
Throws
androidx.media3.common.ParserException

thrown if invalid capture pattern is detected.

readVorbisModes

java-static fun readVorbisModes(headerData: ParsableByteArray!, channels: Int): Array<VorbisUtil.Mode!>!

This method reads the modes which are located at the very end of the Vorbis setup header. That's why we need to partially decode or at least read the entire setup header to know where to start reading the modes.

See the Vorbis spec/Setup header

Parameters
headerData: ParsableByteArray!

a ParsableByteArray containing setup header data.
channels: Int

the number of channels.
Returns
Array<VorbisUtil.Mode!>!

an array of Modes.
Throws
androidx.media3.common.ParserException

thrown if bit stream is invalid.

verifyVorbisHeaderCapturePattern

java-static fun verifyVorbisHeaderCapturePattern(
    headerType: Int,
    header: ParsableByteArray!,
    quiet: Boolean
): Boolean

Verifies whether the next bytes in header are a Vorbis header of the given headerType.

Parameters
headerType: Int

the type of the header expected.
header: ParsableByteArray!

the alleged header bytes.
quiet: Boolean

if true no exceptions are thrown. Instead false is returned.
Returns
Boolean

Whether the header is a Vorbis header.
Throws
androidx.media3.common.ParserException

thrown if header type or capture pattern is not as expected.