cannam@86: cannam@86: cannam@86: cannam@86: Vorbisfile - Setup/Teardown cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

cannam@86: cannam@86:

Setup/Teardown

In order to decode audio using cannam@86: libvorbisfile, a bitstream containing Vorbis audio must be properly cannam@86: initialized before decoding and cleared when decoding is finished. cannam@86: The simplest possible case is to use ov_fopen() to open the file for access, check cannam@86: it for Vorbis content, and prepare it for playback. A successful return code from ov_fopen() indicates the file is ready for use. cannam@86: Once the file is no longer needed, ov_clear() is used to close the file and cannam@86: deallocate decoding resources.

cannam@86: cannam@86: On systems other than Windows[a], an cannam@86: application may also open a file itself using fopen(), then pass the cannam@86: FILE * to libvorbisfile using ov_open(). Do not call cannam@86: fclose() on a file handle successfully submitted to ov_open(); libvorbisfile does this in the ov_clear() call.

cannam@86: cannam@86: An application that requires more setup flexibility may open a data cannam@86: stream using ov_open_callbacks() cannam@86: to change default libvorbis behavior or specify non-stdio data access cannam@86: mechanisms.

cannam@86: cannam@86:

cannam@86: All libvorbisfile initialization and deallocation routines are declared in "vorbis/vorbisfile.h". cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
function purpose
ov_fopen Opens a file and initializes the Ogg Vorbis bitstream with default values. This must be called before other functions in the library may be cannam@86: used.
ov_open Initializes the Ogg Vorbis bitstream with default values from a passed in file handle. This must be called before other functions in the library may be cannam@86: used. Do not use this call under Windows [a]; Use ov_fopen() or ov_open_callbacks() instead.
ov_open_callbacks Initializes the Ogg Vorbis bitstream from a file handle and custom file/bitstream manipulation routines. Used instead of ov_open() or ov_fopen() when altering or replacing libvorbis's default stdio I/O behavior, or when a bitstream must be initialized from a FILE * under Windows.
ov_test Partially opens a file just far enough to determine if the file cannam@86: is an Ogg Vorbis file or not. A successful return indicates that the cannam@86: file appears to be an Ogg Vorbis file, but the OggVorbis_File struct is not yet fully cannam@86: initialized for actual decoding. After a successful return, the file cannam@86: may be closed using ov_clear() or fully cannam@86: opened for decoding using ov_test_open().
This call is intended to cannam@86: be used as a less expensive file open test than a full ov_open().
cannam@86: Note that libvorbisfile owns the passed in file resource is it returns success; do not fclose() files owned by libvorbisfile.
ov_test_callbacks As above but allowing application-define I/O callbacks.
cannam@86: Note that libvorbisfile owns the passed in file resource is it returns success; do not fclose() files owned by libvorbisfile.
ov_test_open cannam@86: Finish opening a file after a successful call to ov_test() or ov_test_callbacks().
ov_clear Closes the cannam@86: bitstream and cleans up loose ends. Must be called when cannam@86: finished with the bitstream. After return, the OggVorbis_File struct is cannam@86: invalid and may not be used before being initialized again cannam@86: before begin reinitialized. cannam@86: cannam@86:
cannam@86: cannam@86:

cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:

copyright © 2000-2010 Xiph.Org	Ogg Vorbis
Vorbisfile documentation	vorbisfile version 1.3.2 - 20101101

cannam@86: cannam@86: cannam@86: cannam@86:

function	purpose
ov_fopen	Opens a file and initializes the Ogg Vorbis bitstream with default values. This must be called before other functions in the library may be cannam@86: used.
ov_open	Initializes the Ogg Vorbis bitstream with default values from a passed in file handle. This must be called before other functions in the library may be cannam@86: used. Do not use this call under Windows [a]; Use ov_fopen() or ov_open_callbacks() instead.
ov_open_callbacks	Initializes the Ogg Vorbis bitstream from a file handle and custom file/bitstream manipulation routines. Used instead of ov_open() or ov_fopen() when altering or replacing libvorbis's default stdio I/O behavior, or when a bitstream must be initialized from a `FILE *` under Windows.
ov_test	Partially opens a file just far enough to determine if the file cannam@86: is an Ogg Vorbis file or not. A successful return indicates that the cannam@86: file appears to be an Ogg Vorbis file, but the OggVorbis_File struct is not yet fully cannam@86: initialized for actual decoding. After a successful return, the file cannam@86: may be closed using ov_clear() or fully cannam@86: opened for decoding using ov_test_open(). This call is intended to cannam@86: be used as a less expensive file open test than a full ov_open(). cannam@86: Note that libvorbisfile owns the passed in file resource is it returns success; do not `fclose()` files owned by libvorbisfile.
ov_test_callbacks	As above but allowing application-define I/O callbacks. cannam@86: Note that libvorbisfile owns the passed in file resource is it returns success; do not `fclose()` files owned by libvorbisfile.
ov_test_open	cannam@86: Finish opening a file after a successful call to ov_test() or ov_test_callbacks().
ov_clear	Closes the cannam@86: bitstream and cleans up loose ends. Must be called when cannam@86: finished with the bitstream. After return, the OggVorbis_File struct is cannam@86: invalid and may not be used before being initialized again cannam@86: before begin reinitialized. cannam@86: cannam@86: