cannam@86: All libvorbisfile decoding routines are declared in "vorbis/vorbisfile.h".
cannam@86:
cannam@86:
cannam@86: After initialization, decoding audio
cannam@86: is as simple as calling ov_read() (or the
cannam@86: similar functions ov_read_float() and
cannam@86: ov_read_filter). This function works
cannam@86: similarly to reading from a normal file using read().
cannam@86:
cannam@86: However, a few differences are worth noting:
cannam@86:
cannam@86:
multiple stream links
cannam@86:
cannam@86: A Vorbis stream may consist of multiple sections (called links) that
cannam@86: encode differing numbers of channels or sample rates. It is vitally
cannam@86: important to pay attention to the link numbers returned by ov_read and handle audio changes that may
cannam@86: occur at link boundaries. Such multi-section files do exist in the
cannam@86: wild and are not merely a specification curiosity.
cannam@86:
cannam@86:
returned data amount
cannam@86:
cannam@86: ov_read does not attempt to completely fill
cannam@86: a large, passed in data buffer; it merely guarantees that the passed
cannam@86: back data does not overflow the passed in buffer size. Large buffers
cannam@86: may be filled by iteratively looping over calls to ov_read (incrementing the buffer pointer)
cannam@86: until the original buffer is filled.
cannam@86:
cannam@86:
file cursor position
cannam@86:
cannam@86: Vorbis files do not necessarily start at a sample number or time offset
cannam@86: of zero. Do not be surprised if a file begins at a positive offset of
cannam@86: several minutes or hours, such as would happen if a large stream (such
cannam@86: as a concert recording) is chopped into multiple seperate files.
cannam@86:
cannam@86:
This function makes up the main chunk of a decode loop. It takes an
cannam@86: OggVorbis_File structure, which must have been initialized by a previous
cannam@86: call to ov_open(), ov_fopen(),
cannam@86: or ov_open_callbacks().