opusfile: Opening and Closing

| opusfile 0.8 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 *_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

## § 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] | _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_open_file()

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

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

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

  | _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_open_callbacks()

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

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

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

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

  | _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_test_callbacks()

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.

## § 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

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

## § op_free()

void op_free | ( | OggOpusFile * | _of | ) |

Release all memory used by an `OggOpusFile`.

Parameters

  _of | The `OggOpusFile` to free.