opusfile  0.8-42-gcc89c68
Stand-alone decoder library for .opus files.
Opening and Closing

Functions for opening and closing streams

These functions allow you to test a stream to see if it is Opus, open it, and close it.

Several flavors are provided for each of the built-in stream types, plus a more general version which takes a set of application-provided callbacks.

int op_test (OpusHead *_head, const unsigned char *_initial_data, size_t _initial_bytes)
 Test to see if this is an Opus stream. More...
 
OP_WARN_UNUSED_RESULT OggOpusFile * op_open_file (const char *_path, int *_error) OP_ARG_NONNULL(1)
 Open a stream from the given file path. More...
 
OP_WARN_UNUSED_RESULT OggOpusFile * op_open_memory (const unsigned char *_data, size_t _size, int *_error)
 Open a stream from a memory buffer. More...
 
OP_WARN_UNUSED_RESULT OggOpusFile * op_vopen_url (const char *_url, int *_error, va_list _ap) OP_ARG_NONNULL(1)
 Open a stream from a URL. More...
 
OP_WARN_UNUSED_RESULT OggOpusFile * op_open_url (const char *_url, int *_error,...) OP_ARG_NONNULL(1)
 Open a stream from a URL. More...
 
OP_WARN_UNUSED_RESULT OggOpusFile * op_open_callbacks (void *_stream, const OpusFileCallbacks *_cb, const unsigned char *_initial_data, size_t _initial_bytes, int *_error) OP_ARG_NONNULL(2)
 Open a stream using the given set of callbacks to access it. More...
 
OP_WARN_UNUSED_RESULT OggOpusFile * op_test_file (const char *_path, int *_error) OP_ARG_NONNULL(1)
 Partially open a stream from the given file path. More...
 
OP_WARN_UNUSED_RESULT OggOpusFile * op_test_memory (const unsigned char *_data, size_t _size, int *_error)
 Partially open a stream from a memory buffer. More...
 
OP_WARN_UNUSED_RESULT OggOpusFile * op_vtest_url (const char *_url, int *_error, va_list _ap) OP_ARG_NONNULL(1)
 Partially open a stream from a URL. More...
 
OP_WARN_UNUSED_RESULT OggOpusFile * op_test_url (const char *_url, int *_error,...) OP_ARG_NONNULL(1)
 Partially open a stream from a URL. More...
 
OP_WARN_UNUSED_RESULT OggOpusFile * op_test_callbacks (void *_stream, const OpusFileCallbacks *_cb, const unsigned char *_initial_data, size_t _initial_bytes, int *_error) OP_ARG_NONNULL(2)
 Partially open a stream using the given set of callbacks to access it. More...
 
int op_test_open (OggOpusFile *_of) OP_ARG_NONNULL(1)
 Finish opening a stream partially opened with op_test_callbacks() or one of the associated convenience functions. More...
 
void op_free (OggOpusFile *_of)
 Release all memory used by an OggOpusFile. More...
 

Detailed Description

Function Documentation

◆ op_test()

int op_test ( OpusHead _head,
const unsigned char *  _initial_data,
size_t  _initial_bytes 
)

Test to see if this is an Opus stream.

For good results, you will need at least 57 bytes (for a pure Opus-only stream). Something like 512 bytes will give more reliable results for multiplexed streams. This function is meant to be a quick-rejection filter. Its purpose is not to guarantee that a stream is a valid Opus stream, but to ensure that it looks enough like Opus that it isn't going to be recognized as some other format (except possibly an Opus stream that is also multiplexed with other codecs, such as video).

Parameters
[out]_headThe parsed ID header contents. You may pass NULL if you do not need this information. If the function fails, the contents of this structure remain untouched.
_initial_dataAn initial buffer of data from the start of the stream.
_initial_bytesThe number of bytes in _initial_data.
Returns
0 if the data appears to be Opus, or a negative value on error.
Return values
OP_FALSEThere was not enough data to tell if this was an Opus stream or not.
OP_EFAULTAn internal memory allocation failed.
OP_EIMPLThe stream used a feature that is not implemented, such as an unsupported channel family.
OP_ENOTFORMATIf the data did not contain a recognizable ID header for an Opus stream.
OP_EVERSIONIf the version field signaled a version this library does not know how to parse.
OP_EBADHEADERThe ID header was not properly formatted or contained illegal values.

◆ op_open_file()

OP_WARN_UNUSED_RESULT OggOpusFile* op_open_file ( const char *  _path,
int *  _error 
)

Open a stream from the given file path.

Parameters
_pathThe path to the file to open.
[out]_errorReturns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. The failure code will be OP_EFAULT if the file could not be opened, or one of the other failure codes from op_open_callbacks() otherwise.
Returns
A freshly opened OggOpusFile, or NULL on error.

◆ op_open_memory()

OP_WARN_UNUSED_RESULT OggOpusFile* op_open_memory ( const unsigned char *  _data,
size_t  _size,
int *  _error 
)

Open a stream from a memory buffer.

Parameters
_dataThe memory buffer to open.
_sizeThe number of bytes in the buffer.
[out]_errorReturns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. See op_open_callbacks() for a full list of failure codes.
Returns
A freshly opened OggOpusFile, or NULL on error.

◆ op_vopen_url()

OP_WARN_UNUSED_RESULT OggOpusFile* op_vopen_url ( const char *  _url,
int *  _error,
va_list  _ap 
)

Open a stream from a URL.

This function behaves identically to op_open_url(), except that it takes a va_list instead of a variable number of arguments. It does not call the va_end macro, and because it invokes the va_arg macro, the value of _ap is undefined after the call.

Note
If you use this function, you must link against libopusurl.
Parameters
_urlThe URL to open. Currently only the <file:>, <http:>, and <https:> schemes are supported. Both <http:> and <https:> may be disabled at compile time, in which case opening such URLs will always fail. Currently this only supports URIs. IRIs should be converted to UTF-8 and URL-escaped, with internationalized domain names encoded in punycode, before passing them to this function.
[out]_errorReturns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. See op_open_callbacks() for a full list of failure codes.
[in,out]_apA list of the optional flags to use. This is a variable-length list of options terminated with NULL.
Returns
A freshly opened OggOpusFile, or NULL on error.

◆ op_open_url()

OP_WARN_UNUSED_RESULT OggOpusFile* op_open_url ( const char *  _url,
int *  _error,
  ... 
)

Open a stream from a URL.

Note
If you use this function, you must link against libopusurl.
Parameters
_urlThe URL to open. Currently only the <file:>, <http:>, and <https:> schemes are supported. Both <http:> and <https:> may be disabled at compile time, in which case opening such URLs will always fail. Currently this only supports URIs. IRIs should be converted to UTF-8 and URL-escaped, with internationalized domain names encoded in punycode, before passing them to this function.
[out]_errorReturns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. See op_open_callbacks() for a full list of failure codes.
...The optional flags to use. This is a variable-length list of options terminated with NULL.
Returns
A freshly opened OggOpusFile, or NULL on error.

◆ op_open_callbacks()

OP_WARN_UNUSED_RESULT OggOpusFile* op_open_callbacks ( void *  _stream,
const OpusFileCallbacks _cb,
const unsigned char *  _initial_data,
size_t  _initial_bytes,
int *  _error 
)

Open a stream using the given set of callbacks to access it.

Parameters
_streamThe stream to read from (e.g., a FILE *). This value will be passed verbatim as the first argument to all of the callbacks.
_cbThe callbacks with which to access the stream. read() must be implemented. seek() and tell() may be NULL, or may always return -1 to indicate a stream is unseekable, but if seek() is implemented and succeeds on a particular stream, then tell() must also. close() may be NULL, but if it is not, it will be called when the OggOpusFile is destroyed by op_free(). It will not be called if op_open_callbacks() fails with an error.
_initial_dataAn initial buffer of data from the start of the stream. Applications can read some number of bytes from the start of the stream to help identify this as an Opus stream, and then provide them here to allow the stream to be opened, even if it is unseekable.
_initial_bytesThe number of bytes in _initial_data. If the stream is seekable, its current position (as reported by tell() at the start of this function) must be equal to _initial_bytes. Otherwise, seeking to absolute positions will generate inconsistent results.
[out]_errorReturns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. The failure code will be one of
OP_EREAD
An underlying read, seek, or tell operation failed when it should have succeeded, or we failed to find data in the stream we had seen before.
OP_EFAULT
There was a memory allocation failure, or an internal library error.
OP_EIMPL
The stream used a feature that is not implemented, such as an unsupported channel family.
OP_EINVAL
seek() was implemented and succeeded on this source, but tell() did not, or the starting position indicator was not equal to _initial_bytes.
OP_ENOTFORMAT
The stream contained a link that did not have any logical Opus streams in it.
OP_EBADHEADER
A required header packet was not properly formatted, contained illegal values, or was missing altogether.
OP_EVERSION
An ID header contained an unrecognized version number.
OP_EBADLINK
We failed to find data we had seen before after seeking.
OP_EBADTIMESTAMP
The first or last timestamp in a link failed basic validity checks.
Returns
A freshly opened OggOpusFile, or NULL on error. libopusfile does not take ownership of the stream if the call fails. The calling application is responsible for closing the stream if this call returns an error.

◆ op_test_file()

OP_WARN_UNUSED_RESULT OggOpusFile* op_test_file ( const char *  _path,
int *  _error 
)

Partially open a stream from the given file path.

See also
op_test_callbacks
Parameters
_pathThe path to the file to open.
[out]_errorReturns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. The failure code will be OP_EFAULT if the file could not be opened, or one of the other failure codes from op_open_callbacks() otherwise.
Returns
A partially opened OggOpusFile, or NULL on error.

◆ op_test_memory()

OP_WARN_UNUSED_RESULT OggOpusFile* op_test_memory ( const unsigned char *  _data,
size_t  _size,
int *  _error 
)

Partially open a stream from a memory buffer.

See also
op_test_callbacks
Parameters
_dataThe memory buffer to open.
_sizeThe number of bytes in the buffer.
[out]_errorReturns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. See op_open_callbacks() for a full list of failure codes.
Returns
A partially opened OggOpusFile, or NULL on error.

◆ op_vtest_url()

OP_WARN_UNUSED_RESULT OggOpusFile* op_vtest_url ( const char *  _url,
int *  _error,
va_list  _ap 
)

Partially open a stream from a URL.

This function behaves identically to op_test_url(), except that it takes a va_list instead of a variable number of arguments. It does not call the va_end macro, and because it invokes the va_arg macro, the value of _ap is undefined after the call.

Note
If you use this function, you must link against libopusurl.
See also
op_test_url
op_test_callbacks
Parameters
_urlThe URL to open. Currently only the <file:>, <http:>, and <https:> schemes are supported. Both <http:> and <https:> may be disabled at compile time, in which case opening such URLs will always fail. Currently this only supports URIs. IRIs should be converted to UTF-8 and URL-escaped, with internationalized domain names encoded in punycode, before passing them to this function.
[out]_errorReturns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. See op_open_callbacks() for a full list of failure codes.
[in,out]_apA list of the optional flags to use. This is a variable-length list of options terminated with NULL.
Returns
A partially opened OggOpusFile, or NULL on error.

◆ op_test_url()

OP_WARN_UNUSED_RESULT OggOpusFile* op_test_url ( const char *  _url,
int *  _error,
  ... 
)

Partially open a stream from a URL.

Note
If you use this function, you must link against libopusurl.
See also
op_test_callbacks
Parameters
_urlThe URL to open. Currently only the <file:>, <http:>, and <https:> schemes are supported. Both <http:> and <https:> may be disabled at compile time, in which case opening such URLs will always fail. Currently this only supports URIs. IRIs should be converted to UTF-8 and URL-escaped, with internationalized domain names encoded in punycode, before passing them to this function.
[out]_errorReturns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. See op_open_callbacks() for a full list of failure codes.
...The optional flags to use. This is a variable-length list of options terminated with NULL.
Returns
A partially opened OggOpusFile, or NULL on error.

◆ op_test_callbacks()

OP_WARN_UNUSED_RESULT OggOpusFile* op_test_callbacks ( void *  _stream,
const OpusFileCallbacks _cb,
const unsigned char *  _initial_data,
size_t  _initial_bytes,
int *  _error 
)

Partially open a stream using the given set of callbacks to access it.

This tests for Opusness and loads the headers for the first link. It does not seek (although it tests for seekability). You can query a partially open stream for the few pieces of basic information returned by op_serialno(), op_channel_count(), op_head(), and op_tags() (but only for the first link). You may also determine if it is seekable via a call to op_seekable(). You cannot read audio from the stream, seek, get the size or duration, get information from links other than the first one, or even get the total number of links until you finish opening the stream with op_test_open(). If you do not need to do any of these things, you can dispose of it with op_free() instead.

This function is provided mostly to simplify porting existing code that used libvorbisfile. For new code, you are likely better off using op_test() instead, which is less resource-intensive, requires less data to succeed, and imposes a hard limit on the amount of data it examines (important for unseekable streams, where all such data must be buffered until you are sure of the stream type).

Parameters
_streamThe stream to read from (e.g., a FILE *). This value will be passed verbatim as the first argument to all of the callbacks.
_cbThe callbacks with which to access the stream. read() must be implemented. seek() and tell() may be NULL, or may always return -1 to indicate a stream is unseekable, but if seek() is implemented and succeeds on a particular stream, then tell() must also. close() may be NULL, but if it is not, it will be called when the OggOpusFile is destroyed by op_free(). It will not be called if op_open_callbacks() fails with an error.
_initial_dataAn initial buffer of data from the start of the stream. Applications can read some number of bytes from the start of the stream to help identify this as an Opus stream, and then provide them here to allow the stream to be tested more thoroughly, even if it is unseekable.
_initial_bytesThe number of bytes in _initial_data. If the stream is seekable, its current position (as reported by tell() at the start of this function) must be equal to _initial_bytes. Otherwise, seeking to absolute positions will generate inconsistent results.
[out]_errorReturns 0 on success, or a failure code on error. You may pass in NULL if you don't want the failure code. See op_open_callbacks() for a full list of failure codes.
Returns
A partially opened OggOpusFile, or NULL on error. libopusfile does not take ownership of the stream if the call fails. The calling application is responsible for closing the stream if this call returns an error.

◆ op_test_open()

int op_test_open ( OggOpusFile *  _of)

Finish opening a stream partially opened with op_test_callbacks() or one of the associated convenience functions.

If this function fails, you are still responsible for freeing the OggOpusFile with op_free().

Parameters
_ofThe OggOpusFile to finish opening.
Returns
0 on success, or a negative value on error.
Return values
OP_EREADAn underlying read, seek, or tell operation failed when it should have succeeded.
OP_EFAULTThere was a memory allocation failure, or an internal library error.
OP_EIMPLThe stream used a feature that is not implemented, such as an unsupported channel family.
OP_EINVALThe stream was not partially opened with op_test_callbacks() or one of the associated convenience functions.
OP_ENOTFORMATThe stream contained a link that did not have any logical Opus streams in it.
OP_EBADHEADERA required header packet was not properly formatted, contained illegal values, or was missing altogether.
OP_EVERSIONAn ID header contained an unrecognized version number.
OP_EBADLINKWe failed to find data we had seen before after seeking.
OP_EBADTIMESTAMPThe first or last timestamp in a link failed basic validity checks.

◆ op_free()

void op_free ( OggOpusFile *  _of)

Release all memory used by an OggOpusFile.

Parameters
_ofThe OggOpusFile to free.