ov_read()

declared in "vorbis/vorbisfile.h";

This is the main function used to decode a Vorbis file within a loop. It returns up to the specified number of bytes of decoded PCM audio in the requested endianness, signedness, and word size. If the audio is multichannel, the channels are interleaved in the output buffer. If the passed in buffer is large, ov_read() will not fill it; the passed in buffer size is treated as a limit and not a request.

The output channels are in stream order and not remapped. Vorbis I defines channel order as follows:

• one channel - the stream is monophonic
• two channels - the stream is stereo. channel order: left, right
• three channels - the stream is a 1d-surround encoding. channel order: left, center, right
• four channels - the stream is quadraphonic surround. channel order: front left, front right, rear left, rear right
• five channels - the stream is five-channel surround. channel order: front left, center, front right, rear left, rear right
• six channels - the stream is 5.1 surround. channel order: front left, center, front right, rear left, rear right, LFE
• seven channels - the stream is 6.1 surround. channel order: front left, center, front right, side left, side right, rear center, LFE
• eight channels - the stream is 7.1 surround. channel order: front left, center, front right, side left, side right, rear left, rear right, LFE
• greater than eight channels - channel use and order is undefined

Note that up to this point, the Vorbisfile API could more or less hide the multiple logical bitstream nature of chaining from the toplevel application if the toplevel application didn't particularly care. However, when reading audio back, the application must be aware that multiple bitstream sections do not necessarily use the same number of channels or sampling rate.

ov_read() passes back the index of the sequential logical bitstream currently being decoded (in *bitstream) along with the PCM data in order that the toplevel application can handle channel and/or sample rate changes. This number will be incremented at chaining boundaries even for non-seekable streams. For seekable streams, it represents the actual chaining index within the physical bitstream.

long ov_read(OggVorbis_File *vf, char *buffer, int length, int bigendianp, int word, int sgned, int *bitstream);

Parameters

vf

A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile functions.

buffer

A pointer to an output buffer. The decoded output is inserted into this buffer.

length

Number of bytes to be read into the buffer. Should be the same size as the buffer. A typical value is 4096.

bigendianp

Specifies big or little endian byte packing. 0 for little endian, 1 for b ig endian. Typical value is 0.

word

Specifies word size. Possible arguments are 1 for 8-bit samples, or 2 or 16-bit samples. Typical value is 2.

sgned

Signed or unsigned data. 0 for unsigned, 1 for signed. Typically 1.

bitstream

A pointer to the number of the current logical bitstream.

Return Values

OV_HOLE

indicates there was an interruption in the data.
(one of: garbage between pages, loss of sync followed by recapture, or a corrupt page)

OV_EBADLINK

indicates that an invalid stream section was supplied to libvorbisfile, or the requested link is corrupt.

OV_EINVAL

indicates the initial file headers couldn't be read or are corrupt, or that the initial open call for vf failed.

0

indicates EOF

n

indicates actual number of bytes read. ov_read() will decode at most one vorbis packet per invocation, so the value returned will generally be less than length.

Notes

Typical usage:

bytes_read = ov_read(&vf, buffer, 4096,0,2,1,&current_section)