Vorbisfile documentation | vorbisfile version 1.2.0 - 20070723

# Setup/Teardown

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

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

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

All libvorbisfile initialization and deallocation routines are declared in "vorbis/vorbisfile.h".

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 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 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 is an Ogg Vorbis file or not. A successful return indicates that the file appears to be an Ogg Vorbis file, but the OggVorbis_File struct is not yet fully initialized for actual decoding. After a successful return, the file may be closed using ov_clear() or fully opened for decoding using ov_test_open().

This call is intended to be used as a less expensive file open test than a full ov_open().

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. Note that libvorbisfile owns the passed in file resource is it returns success; do not `fclose()` files owned by libvorbisfile.
ov_test_open | Finish opening a file after a successful call to ov_test() or ov_test_callbacks().
ov_clear | Closes the bitstream and cleans up loose ends. Must be called when finished with the bitstream. After return, the OggVorbis_File struct is invalid and may not be used before being initialized again before begin reinitialized.

copyright © 2007 Xiph.org | Ogg Vorbis
Vorbisfile documentation | vorbisfile version 1.2.0 - 20070723