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...

Detailed Description

Function Documentation

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]	_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.

Returns: 0 if the data appears to be Opus, or a negative value on error.

Return values

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.

Parameters

	_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.

Returns: A freshly opened 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.

Parameters

	_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.

Returns: A freshly opened 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.

Note: If you use this function, you must link against libopusurl.

Parameters

	_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`.

Returns: A freshly opened OggOpusFile, or NULL on error.

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

	_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`.

Returns: A freshly opened 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.

Parameters

	_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 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 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.

See also: op_test_callbacks

Parameters

	_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.

Returns: A partially opened 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.

See also: op_test_callbacks

Parameters

	_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.

Returns: A partially opened 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.

Note: If you use this function, you must link against libopusurl.

See also: op_test_url; op_test_callbacks

Parameters

	_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`.

Returns: A partially opened 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.

Note: If you use this function, you must link against libopusurl.

See also: op_test_callbacks

Parameters

	_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`.

Returns: A partially opened 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).

Parameters

	_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.

Returns: A partially opened 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().

Parameters

_of	The `OggOpusFile` to finish opening.

Returns: 0 on success, or a negative value on error.

Return values

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.

Parameters

_of	The `OggOpusFile` to free.

Functions for opening and closing streams

Detailed Description

Function Documentation