Decoding

All libvorbisfile decoding routines are declared in "vorbis/vorbisfile.h".

After initialization, decoding audio is as simple as calling ov_read() (or the similar functions ov_read_float() and ov_read_filter). This function works similarly to reading from a normal file using read().

However, a few differences are worth noting:

multiple stream links

A Vorbis stream may consist of multiple sections (called links) that encode differing numbers of channels or sample rates. It is vitally important to pay attention to the link numbers returned by ov_read and handle audio changes that may occur at link boundaries. Such multi-section files do exist in the wild and are not merely a specification curiosity.

returned data amount

ov_read does not attempt to completely fill a large, passed in data buffer; it merely guarantees that the passed back data does not overflow the passed in buffer size. Large buffers may be filled by iteratively looping over calls to ov_read (incrementing the buffer pointer) until the original buffer is filled.

file cursor position

Vorbis files do not necessarily start at a sample number or time offset of zero. Do not be surprised if a file begins at a positive offset of several minutes or hours, such as would happen if a large stream (such as a concert recording) is chopped into multiple seperate files.

function purpose

ov_read This function makes up the main chunk of a decode loop. It takes an OggVorbis_File structure, which must have been initialized by a previous call to ov_open(), ov_fopen(), or ov_open_callbacks().

ov_read_float This function decodes to floats instead of integer samples.

ov_read_filter This function works like ov_read, but passes the PCM data through the provided filter before converting to integer sample data.

copyright © 2007 Xiph.org	Ogg Vorbis
Vorbisfile documentation	vorbisfile version 1.2.0 - 20070723

function	purpose
ov_read	This function makes up the main chunk of a decode loop. It takes an OggVorbis_File structure, which must have been initialized by a previous call to `ov_open()`, `ov_fopen()`, or `ov_open_callbacks()`.
ov_read_float	This function decodes to floats instead of integer samples.
ov_read_filter	This function works like ov_read, but passes the PCM data through the provided filter before converting to integer sample data.