ov_fopen

declared in "vorbis/vorbisfile.h";

This is the simplest function used to open and initialize an OggVorbis_File structure. It sets up all the related decoding structure.

The first argument is a file path suitable for passing to fopen(). vf should be a pointer to an empty OggVorbis_File structure -- this is used for ALL the externally visible libvorbisfile functions. Once this has been called, the same OggVorbis_File struct should be passed to all the libvorbisfile functions.

The vf structure initialized using ov_fopen() must eventually be cleaned using ov_clear().

It is often useful to call ov_fopen() simply to determine whether a given file is a Vorbis bitstream. If the ov_fopen() call fails, then the file is either inaccessable (errno is set) or not recognizable as Vorbis (errno unchanged). If the call succeeds but the initialized vf structure will not be used, the application is responsible for calling ov_clear() to clear the decoder's buffers and close the file.

int ov_fopen(const char *path,OggVorbis_File *vf);

Parameters

path

Null terminated string containing a file path suitable for passing to fopen().

vf

A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile functions. Once this has been called, the same OggVorbis_File struct should be passed to all the libvorbisfile functions.

Return Values

0 indicates success

less than zero for failure:

• OV_EREAD - A read from media returned an error.
• OV_ENOTVORBIS - Bitstream does not contain any Vorbis data.
• OV_EVERSION - Vorbis version mismatch.
• OV_EBADHEADER - Invalid Vorbis bitstream header.
• OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.

Notes

[a] Threaded decode

If your decoder is threaded, it is recommended that you NOT call ov_open_callbacks() in the main control thread--instead, call ov_open_callbacks() in your decode/playback thread. This is important because ov_open_callbacks() may be a fairly time-consuming call, given that the full structure of the file is determined at this point, which may require reading large parts of the file under certain circumstances (determining all the logical bitstreams in one physical bitstream, for example). See Thread Safety for other information on using libvorbisfile with threads.

[b] Mixed media streams

As of Vorbisfile release 1.2.0, Vorbisfile is able to access the Vorbis content in mixed-media Ogg streams, not just Vorbis-only streams. For example, Vorbisfile may be used to open and access the audio from an Ogg stream consisting of Theora video and Vorbis audio. Vorbisfile 1.2.0 decodes the first logical audio stream of each physical stream section.

[c] Faster testing for Vorbis files

ov_test() and ov_test_callbacks() provide less computationally expensive ways to test a file for Vorbisness, but require more setup code.