@UnstableApi
public final class VorbisUtil

Utility methods for parsing Vorbis streams.

Summary

Nested types
public final class VorbisUtil.CommentHeader

Vorbis comment header.
public final class VorbisUtil.Mode

Vorbis setup header modes.
public final class VorbisUtil.VorbisIdHeader

Vorbis identification header.

Public methods
static int
getPacketBlockSize(
    byte firstByteOfAudioPacket,
    VorbisUtil.VorbisIdHeader idHeader,
    VorbisUtil.Mode[] modes
)

Returns the block size of the given packet.
static int
getSampleCountInPacket(
    int packetBlockSize,
    int previousPacketBlockSize,
    boolean seenFirstAudioPacket
)

Returns the number of samples in the given packet.
static int
iLog(int x)

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

Reads a Vorbis comment header.
static VorbisUtil.CommentHeader
readVorbisCommentHeader(
    ParsableByteArray headerData,
    boolean hasMetadataHeader,
    boolean hasFramingBit
)

Reads a Vorbis comment header.
static VorbisUtil.VorbisIdHeader

Reads a Vorbis identification header from headerData.
static VorbisUtil.Mode[]
readVorbisModes(ParsableByteArray headerData, int channels)

This method reads the modes which are located at the very end of the Vorbis setup header.
static boolean
@CanIgnoreReturnValue
verifyVorbisHeaderCapturePattern(
    int headerType,
    ParsableByteArray header,
    boolean quiet
)

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

Public methods

getPacketBlockSize

public static int getPacketBlockSize(
    byte firstByteOfAudioPacket,
    VorbisUtil.VorbisIdHeader idHeader,
    VorbisUtil.Mode[] modes
)

Returns the block size of the given packet.

Parameters
byte firstByteOfAudioPacket

The first byte of the audio packet.
VorbisUtil.VorbisIdHeader idHeader

The Vorbis identification header.
VorbisUtil.Mode[] modes

The Vorbis modes.
Returns
int

The block size of the packet.

getSampleCountInPacket

public static int getSampleCountInPacket(
    int packetBlockSize,
    int previousPacketBlockSize,
    boolean seenFirstAudioPacket
)

Returns the number of samples in the given packet.

Parameters
int packetBlockSize

The block size of the packet.
int previousPacketBlockSize

The block size of the previous packet.
boolean seenFirstAudioPacket

Whether the first audio packet has been seen.
Returns
int

The number of samples in the packet.

iLog

public static int iLog(int x)

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

See the Vorbis spec

Parameters
int x

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

ilog(x)

readVorbisCommentHeader

public static VorbisUtil.CommentHeader readVorbisCommentHeader(ParsableByteArray headerData)

Reads a Vorbis comment header.

See the Vorbis spec/Comment header

Parameters
ParsableByteArray headerData

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

public static VorbisUtil.CommentHeader readVorbisCommentHeader(
    ParsableByteArray headerData,
    boolean hasMetadataHeader,
    boolean hasFramingBit
)

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
ParsableByteArray headerData

A ParsableByteArray wrapping the header data.
boolean hasMetadataHeader

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

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

public static VorbisUtil.VorbisIdHeader readVorbisIdentificationHeader(ParsableByteArray headerData)

Reads a Vorbis identification header from headerData.

See the Vorbis spec/Identification header

Parameters
ParsableByteArray headerData

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

public static VorbisUtil.Mode[] readVorbisModes(ParsableByteArray headerData, int channels)

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
ParsableByteArray headerData

a ParsableByteArray containing setup header data.
int channels

the number of channels.
Returns
VorbisUtil.Mode[]

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

thrown if bit stream is invalid.

verifyVorbisHeaderCapturePattern

@CanIgnoreReturnValue
public static boolean verifyVorbisHeaderCapturePattern(
    int headerType,
    ParsableByteArray header,
    boolean quiet
)

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

Parameters
int headerType

the type of the header expected.
ParsableByteArray header

the alleged header bytes.
boolean quiet

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.