opusfile
0.7
Stand-alone decoder library for .opus files.
|
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 *_source, 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 *_source, 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... | |
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).
[out] | _head | The 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_data | An initial buffer of data from the start of the stream. | |
_initial_bytes | The number of bytes in _initial_data. |
OP_FALSE | There was not enough data to tell if this was an Opus stream or not. |
OP_EFAULT | An internal memory allocation failed. |
OP_EIMPL | The stream used a feature that is not implemented, such as an unsupported channel family. |
OP_ENOTFORMAT | If the data did not contain a recognizable ID header for an Opus stream. |
OP_EVERSION | If the version field signaled a version this library does not know how to parse. |
OP_EBADHEADER | The ID header was not properly formatted or contained illegal values. |
OP_WARN_UNUSED_RESULT OggOpusFile* op_open_file | ( | const char * | _path, |
int * | _error | ||
) |
Open a stream from the given file path.
_path | The path to the file to open. | |
[out] | _error | Returns 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. |
OggOpusFile
, or NULL
on error. OP_WARN_UNUSED_RESULT OggOpusFile* op_open_memory | ( | const unsigned char * | _data, |
size_t | _size, | ||
int * | _error | ||
) |
Open a stream from a memory buffer.
_data | The memory buffer to open. | |
_size | The number of bytes in the buffer. | |
[out] | _error | Returns 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. |
OggOpusFile
, or NULL
on error. 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.
libopusurl
. _url | The 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] | _error | Returns 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] | _ap | A list of the optional flags to use. This is a variable-length list of options terminated with NULL . |
OggOpusFile
, or NULL
on error. OP_WARN_UNUSED_RESULT OggOpusFile* op_open_url | ( | const char * | _url, |
int * | _error, | ||
... | |||
) |
Open a stream from a URL.
libopusurl
. _url | The 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] | _error | Returns 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 . |
OggOpusFile
, or NULL
on error. OP_WARN_UNUSED_RESULT OggOpusFile* op_open_callbacks | ( | void * | _source, |
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.
_source | The stream to read from (e.g., a FILE * ). | |
_cb | The 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 source is unseekable, but if seek() is implemented and succeeds on a particular source, 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_data | An 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_bytes | The 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] | _error | Returns 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
|
OggOpusFile
, or NULL
on error. libopusfile
does not take ownership of the source if the call fails. The calling application is responsible for closing the source if this call returns an error. OP_WARN_UNUSED_RESULT OggOpusFile* op_test_file | ( | const char * | _path, |
int * | _error | ||
) |
Partially open a stream from the given file path.
_path | The path to the file to open. | |
[out] | _error | Returns 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. |
OggOpusFile
, or NULL
on error. 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.
_data | The memory buffer to open. | |
_size | The number of bytes in the buffer. | |
[out] | _error | Returns 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. |
OggOpusFile
, or NULL
on error. 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.
libopusurl
. _url | The 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] | _error | Returns 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] | _ap | A list of the optional flags to use. This is a variable-length list of options terminated with NULL . |
OggOpusFile
, or NULL
on error. OP_WARN_UNUSED_RESULT OggOpusFile* op_test_url | ( | const char * | _url, |
int * | _error, | ||
... | |||
) |
Partially open a stream from a URL.
libopusurl
. _url | The 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] | _error | Returns 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 . |
OggOpusFile
, or NULL
on error. OP_WARN_UNUSED_RESULT OggOpusFile* op_test_callbacks | ( | void * | _source, |
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 sources, where all such data must be buffered until you are sure of the stream type).
_source | The stream to read from (e.g., a FILE * ). | |
_cb | The 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 source is unseekable, but if seek() is implemented and succeeds on a particular source, 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_data | An 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_bytes | The 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] | _error | Returns 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. |
OggOpusFile
, or NULL
on error. libopusfile
does not take ownership of the source if the call fails. The calling application is responsible for closing the source if this call returns an error. 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().
_of | The OggOpusFile to finish opening. |
OP_EREAD | An underlying read, seek, or tell operation failed when it should have succeeded. |
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 | The stream was not partially opened with op_test_callbacks() or one of the associated convenience functions. |
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. |
void op_free | ( | OggOpusFile * | _of | ) |
Release all memory used by an OggOpusFile
.
_of | The OggOpusFile to free. |