vorbisfile - function - ov_read

vorbisfile documentation | vorbisfile version 1.25 - 20000615

# ov_read

declared in "vorbis/vorbisfile.h";

This is the main function used to decode a Vorbis file within a loop.

This function deals with more complicated bitstream chaining issues. Up to this point, everything 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 we actually read audio back, we must be aware that multiple bitstream sections do not necessarily have to have the same number of channels or sampling rate.

ov_read returns the sequential logical bitstream number currently being decoded along with the PCM data in order that the toplevel application can take action on channel/sample rate changes. This number will be incremented even for streamed (non-seekable) streams For seekable streams, it represents the actual logical bitstream 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 vorbisfile 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 big 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.
> - 0 indicates EOF
> - n indicates actual number of bytes read. Within a logical bitstream, the number should equal `length`. At the end of a logical bitstream, the number of bytes read will equal the remaining number of bytes in the bitstream.

### Notes

Typical usage: `bytes_read = ov_read(&vf, buffer, 4096,0,2,1,&current_section)`
This reads up to 4096 bytes into a buffer, with signed 16-bit little-endian samples.

copyright © 2000 vorbis team | Ogg Vorbis team@vorbis.org
vorbisfile documentation | vorbisfile version 1.25 - 20000615