Vorbisfile documentation | vorbisfile version 1.2.0 - 20070723

# 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