libopusfile

https://opus-codec.org/docs/opusfile_api-0.12/
Admin
libopusfile is a C API library for decoding and manipulating Ogg Opus audio streams with support for...
Tokens:51,668
Snippets:408
Trust Score:9.9
Update:4 months ago
Show doc for...
Tokens:
Raw
### op_bitrate_instant()

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__info.html

Computes the instantaneous bitrate based on decoded bits and playable samples since the last relevant event (call to this function, seek, or start of playback).

```APIDOC
## op_bitrate_instant()

### Description
Compute the instantaneous bitrate, measured as the ratio of bits to playable samples decoded since a) the last call to op_bitrate_instant(), b) the last seek, or c) the start of playback, whichever was most recent. This will spike somewhat after a seek or at the start/end of a chain boundary, as pre-skip, pre-roll, and end-trimming causes samples to be decoded but not played.

### Parameters
*   **_of** (OggOpusFile *) - The `OggOpusFile` from which to retrieve the bitrate.

### Returns
The bitrate, in bits per second, or a negative value on error.

### Return values
*   **OP_FALSE**: No data has been decoded since any of the events described above.
*   **OP_EINVAL**: The stream was only partially open.
```

--------------------------------

### Opus Get Server Info Macro

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Macro to retrieve server information for URL streams.

```APIDOC
## OP_GET_SERVER_INFO

### Description
Macro to retrieve server information for URL streams.

### Usage
`OP_GET_SERVER_INFO(_info)`

### Parameters
*   **_info** (OpusServerInfo *) - Required - Pointer to an OpusServerInfo structure to be populated with server details.
```

--------------------------------

### opus_tags_get_track_gain

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__header__info.html

Gets the track gain from an R128_TRACK_GAIN tag, if specified.

```APIDOC
## opus_tags_get_track_gain

### Description
Get the track gain from an R128_TRACK_GAIN tag, if one was specified.

### Method
(Not specified, likely a C function call)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Parameters
- **_tags** (const OpusTags *) - Pointer to the OpusTags structure.
- **_gain_q8** (int *) - Pointer to an integer where the track gain (in Q8 format) will be stored.

### Return Value
Returns an integer status code indicating success or failure. Success means the tag was found and parsed.
```

--------------------------------

### Opus Server Info Init

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Initializes an OpusServerInfo structure.

```APIDOC
## opus_server_info_init

### Description
Initializes an OpusServerInfo structure.

### Signature
`void opus_server_info_init(OpusServerInfo *_info)`

### Parameters
*   **_info** (OpusServerInfo *) - Required - Pointer to the OpusServerInfo structure to initialize.
```

--------------------------------

### OP_ENOTAUDIO Error Code

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__error__codes.html

Currently not used at all.

```c
#define OP_ENOTAUDIO (-135)
```

--------------------------------

### opus_tags_get_album_gain

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__header__info.html

Gets the album gain from an R128_ALBUM_GAIN tag, if specified.

```APIDOC
## opus_tags_get_album_gain

### Description
Get the album gain from an R128_ALBUM_GAIN tag, if one was specified.

### Method
(Not specified, likely a C function call)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Parameters
- **_tags** (const OpusTags *) - Pointer to the OpusTags structure.
- **_gain_q8** (int *) - Pointer to an integer where the album gain (in Q8 format) will be stored.

### Return Value
Returns an integer status code indicating success or failure. Success means the tag was found and parsed.
```

--------------------------------

### opus_server_info_init

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Initializes an OpusServerInfo structure, preparing it for use. This function sets up the structure with default values or allocates necessary memory.

```APIDOC
## opus_server_info_init

### Description
Initializes an OpusServerInfo structure.

### Signature
```c
void opus_server_info_init(OpusServerInfo *_info)
```

### Parameters
*   **_info** (OpusServerInfo *) - A pointer to the OpusServerInfo structure to be initialized.
```

--------------------------------

### op_head

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__info.html

Gets the ID header information for a specific link in an Ogg Opus stream.

```APIDOC
## op_head()

### Description
Get the ID header information for the given link in a (possibly chained) Ogg Opus stream.

### Method
(Implicitly a getter function, typically called after opening a stream)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
(Not applicable for this function)

### Response
#### Success Response
- **return value** (const OpusHead *) - A pointer to the ID header information.

#### Response Example
(Not applicable for this function)
```

--------------------------------

### opus_server_info_init()

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__url__options.html

Initializes an OpusServerInfo structure, setting all fields to indicate that the corresponding header was not available.

```APIDOC
## opus_server_info_init()

### Description
Initializes an OpusServerInfo structure. All fields are set as if the corresponding header was not available.

### Parameters
- **_info** (OpusServerInfo *): The OpusServerInfo structure to initialize.

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

--------------------------------

### op_serialno

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__info.html

Gets the serial number of a specific link within an Ogg Opus stream.

```APIDOC
## op_serialno()

### Description
Get the serial number of the given link in a (possibly-chained) Ogg Opus stream.

### Method
(Implicitly a getter function, typically called after opening a stream)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
(Not applicable for this function)

### Response
#### Success Response
- **return value** (opus_uint32) - The serial number of the specified link.

#### Response Example
(Not applicable for this function)
```

--------------------------------

### op_fdopen

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__callbacks.html

Opens a stream using `fdopen()` and initializes OpusFileCallbacks for it. This function is useful when you already have a file descriptor.

```APIDOC
## op_fdopen

### Description
Opens a stream with `fdopen()` and fills in a set of callbacks that can be used to access it.

### Signature
```c
void *op_fdopen (OpusFileCallbacks *_cb, int _fd, const char *_mode)
```

### Parameters

*   **_cb** (OpusFileCallbacks*) - Pointer to the OpusFileCallbacks structure to be filled.
*   **_fd** (int) - The file descriptor of the stream to open.
*   **_mode** (const char*) - The mode in which to open the stream (e.g., "rb").

### Returns
A pointer to the opened OpusFile, or NULL on error.
```

--------------------------------

### op_fopen

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__callbacks.html

Opens a stream using `fopen()` and initializes OpusFileCallbacks for it. This is a convenience function for standard file opening.

```APIDOC
## op_fopen

### Description
Opens a stream with `fopen()` and fills in a set of callbacks that can be used to access it.

### Signature
```c
void *op_fopen (OpusFileCallbacks *_cb, const char *_path, const char *_mode)
```

### Parameters

*   **_cb** (OpusFileCallbacks*) - Pointer to the OpusFileCallbacks structure to be filled.
*   **_path** (const char*) - The path to the file to open.
*   **_mode** (const char*) - The mode in which to open the file (e.g., "rb").

### Returns
A pointer to the opened OpusFile, or NULL on error.
```

--------------------------------

### Opus Tags Get Track Gain

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Retrieves the track gain value from Opus metadata.

```APIDOC
## opus_tags_get_track_gain

### Description
Retrieves the track gain value from Opus metadata.

### Signature
`int opus_tags_get_track_gain(const OpusTags *_tags, int *_gain_q8)`

### Parameters
*   **_tags** (const OpusTags *) - Required - Pointer to the OpusTags structure.
*   **_gain_q8** (int *) - Required - Pointer to an integer where the track gain (in 8-bit quantized format) will be stored.
```

--------------------------------

### op_fopen

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__callbacks.html

Opens a stream using a file path and a set of callbacks. This is useful for avoiding custom seeking wrappers and resolving Windows cross-module linking issues.

```APIDOC
## op_fopen()

### Description
Opens a stream with `fopen()` and fills in a set of callbacks that can be used to access it. This is useful to avoid writing your own portable 64-bit seeking wrappers, and also avoids cross-module linking issues on Windows, where a `FILE *` must be accessed by routines defined in the same module that opened it.

### Parameters
- **_cb** (OpusFileCallbacks *) - Out - The callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
- **_path** (const char *) - The path to the file to open. On Windows, this string must be UTF-8. All other systems use the native character encoding.
- **_mode** (const char *) - The mode to open the file in.

### Returns
A stream handle to use with the callbacks, or `NULL` on error.
```

--------------------------------

### Opus Tags Get Album Gain

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Retrieves the album gain value from Opus metadata.

```APIDOC
## opus_tags_get_album_gain

### Description
Retrieves the album gain value from Opus metadata.

### Signature
`int opus_tags_get_album_gain(const OpusTags *_tags, int *_gain_q8)`

### Parameters
*   **_tags** (const OpusTags *) - Required - Pointer to the OpusTags structure.
*   **_gain_q8** (int *) - Required - Pointer to an integer where the album gain (in 8-bit quantized format) will be stored.
```

--------------------------------

### Opus Tags Get Binary Suffix

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Retrieves the binary data of a tag suffix from Opus metadata.

```APIDOC
## opus_tags_get_binary_suffix

### Description
Retrieves the binary data of a tag suffix from Opus metadata.

### Signature
`const unsigned char *opus_tags_get_binary_suffix(const OpusTags *_tags, int *_len)`

### Parameters
*   **_tags** (const OpusTags *) - Required - Pointer to the OpusTags structure.
*   **_len** (int *) - Required - Pointer to an integer where the length of the binary data will be stored.
```

--------------------------------

### op_raw_total

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__info.html

Gets the total compressed size of a stream or an individual link, including headers and muxing overhead.

```APIDOC
## op_raw_total()

### Description
Get the total (compressed) size of the stream, or of an individual link in a (possibly-chained) Ogg Opus stream, including all headers and Ogg muxing overhead.

### Method
(Implicitly a getter function, typically called after opening a stream)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
(Not applicable for this function)

### Response
#### Success Response
- **return value** (opus_int64) - The total compressed size in bytes.

#### Response Example
(Not applicable for this function)
```

--------------------------------

### op_fopen

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Opens a stream using fopen() and provides callbacks for accessing it.

```APIDOC
## op_fopen

### Description
Opens a stream using fopen() and provides callbacks for accessing it.

### Signature
`void * op_fopen(OpusFileCallbacks *_cb, const char *_path, const char *_mode)`

### Parameters
*   `_cb` (OpusFileCallbacks *) - A pointer to the OpusFileCallbacks structure to be filled. Must not be NULL.
*   `_path` (const char *) - The path to the file to open. Must not be NULL.
*   `_mode` (const char *) - The mode in which to open the file (e.g., "rb"). Must not be NULL.
```

--------------------------------

### op_fopen

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Opens an Opus file for reading using custom callbacks and a file path.

```APIDOC
## op_fopen

### Description
Opens an Opus file for reading using custom callbacks and a file path.

### Signature
`void *op_fopen(OpusFileCallbacks *_cb, const char *_path, const char *_mode)`

### Parameters
*   **_cb** (OpusFileCallbacks *) - Required - Pointer to the OpusFileCallbacks structure containing custom stream functions.
*   **_path** (const char *) - Required - The path to the Opus file.
*   **_mode** (const char *) - Required - The mode in which to open the file (e.g., "r").

### Returns
Returns a pointer to the opened Opus file stream, or NULL on error.
```

--------------------------------

### op_channel_count

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Gets the number of channels for a specific link in an Ogg Opus stream. This indicates whether the audio is mono, stereo, or multi-channel.

```APIDOC
## op_channel_count

### Description
Retrieves the number of audio channels for a specified link within an Ogg Opus stream. This value indicates the channel layout of the audio data (e.g., mono, stereo).

### Method
`op_channel_count(const OggOpusFile *_of, int _li)`

### Parameters
#### Path Parameters
- **_of** (const OggOpusFile *) - Required - A pointer to the `OggOpusFile` structure.
- **_li** (int) - Required - The index of the link for which to retrieve the channel count. Use -1 for the first link.

### Return Value
- **int** - The number of channels in the specified link.
```

--------------------------------

### op_raw_total

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Gets the total size in bytes of the compressed data for a specific link in an Ogg Opus stream. This represents the raw file size of the link.

```APIDOC
## op_raw_total

### Description
Retrieves the total size in bytes of the compressed data for a specified link within an Ogg Opus stream. This value corresponds to the raw size of the data for that particular link.

### Method
`op_raw_total(const OggOpusFile *_of, int _li)`

### Parameters
#### Path Parameters
- **_of** (const OggOpusFile *) - Required - A pointer to the `OggOpusFile` structure.
- **_li** (int) - Required - The index of the link for which to retrieve the total raw size. Use -1 for the first link.

### Return Value
- **opus_int64** - The total size in bytes of the compressed data for the specified link.
```

--------------------------------

### op_test_callbacks

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__open__close.html

Partially opens a stream using provided callbacks to test for Opus format and load initial headers. It allows querying basic information but not reading audio or seeking until fully opened.

```APIDOC
## op_test_callbacks()

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

### Method
(Implicitly a function call, not HTTP)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Parameters
- **_stream** (void *): The stream to read from. This value will be passed verbatim as the first argument to all of the callbacks.
- **_cb** (const OpusFileCallbacks *): 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 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_data** (const unsigned char *): An initial buffer of data from the start of the stream.
- **_initial_bytes** (size_t): 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.
- **_error** (int *): Returns 0 on success, or a failure code on error. You may pass in `NULL` if you don't want the failure code.

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

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__info.html

Gets the total compressed size of an Opus stream or an individual link, including headers and muxing overhead. Returns a negative value on error.

```APIDOC
## op_raw_total()

### Description
Get the total (compressed) size of the stream, or of an individual link in a (possibly-chained) Ogg Opus stream, including all headers and Ogg muxing overhead.

Warning: If the Opus stream (or link) is concurrently multiplexed with other logical streams (e.g., video), this returns the size of the entire stream (or link), not just the number of bytes in the first logical Opus stream. Returning the latter would require scanning the entire file.

### Parameters
* **_of** (const OggOpusFile *) - The `OggOpusFile` from which to retrieve the compressed size.
* **_li** (int) - The index of the link whose compressed size should be computed. Use a negative number to get the compressed size of the entire stream.

### Returns
The compressed size of the entire stream if _li is negative, the compressed size of link _li if it is non-negative, or a negative value on error. The compressed size of the entire stream may be smaller than that of the underlying stream if trailing garbage was detected in the file.

### Return values
* **OP_EINVAL**: The stream is not seekable (so we can't know the length), _li wasn't less than the total number of links in the stream, or the stream was only partially open.
```

--------------------------------

### op_fdopen

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Opens an Opus file for reading using custom callbacks and a file descriptor.

```APIDOC
## op_fdopen

### Description
Opens an Opus file for reading using custom callbacks and a file descriptor.

### Signature
`void *op_fdopen(OpusFileCallbacks *_cb, int _fd, const char *_mode)`

### Parameters
*   **_cb** (OpusFileCallbacks *) - Required - Pointer to the OpusFileCallbacks structure containing custom stream functions.
*   **_fd** (int) - Required - The file descriptor of the Opus file.
*   **_mode** (const char *) - Required - The mode in which to open the file (e.g., "r").

### Returns
Returns a pointer to the opened Opus file stream, or NULL on error.
```

--------------------------------

### op_fdopen

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Opens a stream using fdopen() and provides callbacks for accessing it.

```APIDOC
## op_fdopen

### Description
Opens a stream using fdopen() and provides callbacks for accessing it.

### Signature
`void * op_fdopen(OpusFileCallbacks *_cb, int _fd, const char *_mode)`

### Parameters
*   `_cb` (OpusFileCallbacks *) - A pointer to the OpusFileCallbacks structure to be filled. Must not be NULL.
*   `_fd` (int) - The file descriptor of the stream to open.
*   `_mode` (const char *) - The mode in which to open the stream (e.g., "rb"). Must not be NULL.
```

--------------------------------

### op_serialno

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__info.html

Gets the serial number of a specific link in an Ogg Opus stream. For partially opened streams, it returns the serial number of the first link.

```APIDOC
## op_serialno()

### Description
Get the serial number of the given link in a (possibly-chained) Ogg Opus stream. This function may be called on partially-opened streams, but it will always return the serial number of the Opus stream in the first link.

### Parameters
* **_of** (const OggOpusFile *) - The `OggOpusFile` from which to retrieve the serial number.
* **_li** (int) - The index of the link whose serial number should be retrieved. Use a negative number to get the serial number of the current link.

### Returns
The serial number of the given link. If _li is greater than the total number of links, this returns the serial number of the last link. If the stream is not seekable, this always returns the serial number of the current link.
```

--------------------------------

### op_pcm_total

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Gets the total length in PCM samples (at 48 kHz) for a specific link in an Ogg Opus stream. This indicates the total duration of the audio content.

```APIDOC
## op_pcm_total

### Description
Retrieves the total length of the audio data in PCM samples (at a 48 kHz sample rate) for a specified link within an Ogg Opus stream. This value represents the total duration of the audio content in terms of samples.

### Method
`op_pcm_total(const OggOpusFile *_of, int _li)`

### Parameters
#### Path Parameters
- **_of** (const OggOpusFile *) - Required - A pointer to the `OggOpusFile` structure.
- **_li** (int) - Required - The index of the link for which to retrieve the total PCM length. Use -1 for the first link.

### Return Value
- **ogg_int64_t** - The total number of PCM samples in the specified link.
```

--------------------------------

### Decode Format: Use Default

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__decoding.html

Macro indicating that the decoding callback did not decode anything, and libopusfile should decode normally instead.

```c
#define OP_DEC_USE_DEFAULT (6720)
```

--------------------------------

### OP_GET_SERVER_INFO

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__url__options.html

Parses and returns information about the streaming server, if available.

```APIDOC
## OP_GET_SERVER_INFO

### Description
Parse information about the streaming server (if any) and return it.

### Parameters
#### Path Parameters
- **_info** (OpusServerInfo *) - Required - A pointer to an OpusServerInfo structure to store the server information.
```

--------------------------------

### Seek to PCM Offset in Opus Stream

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__seeking.html

Use op_pcm_seek for sample-accurate seeking in Opus streams. Decoding will commence at the exact specified PCM sample, relative to the start of the stream at 48 kHz. This function may require a small number of physical seeks.

```c
int op_pcm_seek(
   OggOpusFile * _of,
   ogg_int64_t _pcm_offset
);
```

--------------------------------

### op_fdopen

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__callbacks.html

Opens a stream using a file descriptor and a set of callbacks. Similar to op_fopen, it helps manage stream access and avoids cross-module issues on Windows.

```APIDOC
## op_fdopen()

### Description
Opens a stream with `fdopen()` and fills in a set of callbacks that can be used to access it. This is useful to avoid writing your own portable 64-bit seeking wrappers, and also avoids cross-module linking issues on Windows, where a `FILE *` must be accessed by routines defined in the same module that opened it.

### Parameters
- **_cb** (OpusFileCallbacks *) - Out - The callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
- **_fd** (int) - The file descriptor to open.
- **_mode** (const char *) - The mode to open the file in.

### Returns
A stream handle to use with the callbacks, or `NULL` on error.
```

--------------------------------

### op_freopen

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__callbacks.html

Opens a stream using `freopen()` and initializes OpusFileCallbacks for it. This function can be used to redirect an existing stream.

```APIDOC
## op_freopen

### Description
Opens a stream with `freopen()` and fills in a set of callbacks that can be used to access it.

### Signature
```c
void *op_freopen (OpusFileCallbacks *_cb, const char *_path, const char *_mode, void *_stream)
```

### Parameters

*   **_cb** (OpusFileCallbacks*) - Pointer to the OpusFileCallbacks structure to be filled.
*   **_path** (const char*) - The path to the file to open.
*   **_mode** (const char*) - The mode in which to open the file (e.g., "rb").
*   **_stream** (void*) - Pointer to the existing stream to be reopened.

### Returns
A pointer to the reopened OpusFile, or NULL on error.
```

--------------------------------

### opus_tags_init

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__header__info.html

Initializes an OpusTags structure.

```APIDOC
## opus_tags_init

### Description
Initializes an OpusTags structure.

### Method
(Not specified, likely a C function call)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Parameters
- **_tags** (OpusTags *) - Pointer to the OpusTags structure to initialize.

### Return Value
(None)
```

--------------------------------

### op_bitrate_instant

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__info.html

Computes the instantaneous bitrate of the Opus stream.

```APIDOC
## op_bitrate_instant()

### Description
Compute the instantaneous bitrate, measured as the ratio of bits to playable samples decoded since a) the last call to op_bitrate_instant(), b) the last seek, or c) the start of playback, whichever was most recent. This provides a real-time measure of the stream's bitrate.

### Method
(Implicitly a getter function, typically called during playback)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
(Not applicable for this function)

### Response
#### Success Response
- **return value** (opus_int32) - The instantaneous bitrate in bits per second.

#### Response Example
(Not applicable for this function)
```

--------------------------------

### op_freopen

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Opens a stream using freopen() and provides callbacks for accessing it.

```APIDOC
## op_freopen

### Description
Opens a stream using freopen() and provides callbacks for accessing it.

### Signature
`void * op_freopen(OpusFileCallbacks *_cb, const char *_path, const char *_mode, void *_stream)`

### Parameters
*   `_cb` (OpusFileCallbacks *) - A pointer to the OpusFileCallbacks structure to be filled. Must not be NULL.
*   `_path` (const char *) - The path to the file to open. Must not be NULL.
*   `_mode` (const char *) - The mode in which to open the file (e.g., "rb"). Must not be NULL.
*   `_stream` (void *) - A pointer to an existing stream to be reopened.
```

--------------------------------

### op_test_open

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Finishes opening a stream that was partially opened with `op_test_callbacks` or related convenience functions. This completes the initialization process.

```APIDOC
## op_test_open

### Description
Finishes the process of opening an Ogg Opus stream that was previously partially opened using functions like `op_test_callbacks` or `op_test_file`. This function completes the initialization and makes the stream ready for use.

### Method
`op_test_open(OggOpusFile *_of)`

### Parameters
#### Path Parameters
- **_of** (OggOpusFile *) - Required - A pointer to the partially initialized `OggOpusFile` structure.

### Return Value
- **int** - Returns 0 on success, or a negative error code on failure.
```

--------------------------------

### op_open_file()

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__open__close.html

Opens an Opus stream from a given file path. It returns a pointer to an OggOpusFile structure on success, or NULL on failure.

```APIDOC
## op_open_file()
OggOpusFile* op_open_file(const char *__path_, int *__error_)

### Description
Open a stream from the given file path.

### Parameters
*   **__path_** (*const char* *) - in* - The path to the file to open.
*   **__error_** (*int* *) - out* - 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_file

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Opens an Opus file from a given path for reading.

```APIDOC
## op_open_file

### Description
Opens an Opus file from a given path for reading.

### Signature
`OggOpusFile *op_open_file(const char *_path, int *_error)`

### Parameters
*   **_path** (const char *) - Required - The path to the Opus file.
*   **_error** (int *) - Optional - Pointer to an integer to store error information. If NULL, no error information is returned.

### Returns
Returns a pointer to an OggOpusFile structure on success, or NULL on error. The error code is stored in *_error if provided.
```

--------------------------------

### Opus Picture Tag Init

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Initializes an OpusPictureTag structure.

```APIDOC
## opus_picture_tag_init

### Description
Initializes an OpusPictureTag structure.

### Signature
`void opus_picture_tag_init(OpusPictureTag *_pic)`

### Parameters
*   **_pic** (OpusPictureTag *) - Required - Pointer to the OpusPictureTag structure to initialize.
```

--------------------------------

### op_open_callbacks

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__open__close.html

Opens an Opus stream using application-provided callbacks.

```APIDOC
## op_open_callbacks

### Description
Opens an Opus stream using a given set of callbacks to access it.

### Signature
`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)`

### Parameters
*   `_stream` (void *) - Pointer to the application-defined stream.
*   `_cb` (const OpusFileCallbacks *) - Pointer to a structure containing callback functions.
*   `_initial_data` (const unsigned char *) - Pointer to the initial data buffer.
*   `_initial_bytes` (size_t) - The number of bytes available in the initial data buffer.
*   `_error` (int *) - Pointer to an integer to store error information.

### Returns
Returns a pointer to an `OggOpusFile` structure on success, or NULL on failure. The error code is set in `_error`.
```

--------------------------------

### op_open_file

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Opens an Ogg Opus stream from a given file path. It returns a pointer to an OggOpusFile structure or NULL on error.

```APIDOC
## op_open_file

### Description
Opens an Ogg Opus stream from the given file path. This function initializes the necessary structures to read from the specified file.

### Method
`op_open_file(const char *_path, int *_error)`

### Parameters
#### Path Parameters
- **_path** (const char *) - Required - The path to the Ogg Opus file to open.
- **_error** (int *) - Optional - A pointer to an integer where an error code will be stored upon failure. 0 indicates success.

### Return Value
- **OggOpusFile*** - A pointer to the opened `OggOpusFile` structure on success, or NULL on failure.
```

--------------------------------

### OP_GET_SERVER_INFO

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__url__options.html

Parses and returns information about the streaming server. It populates an OpusServerInfo structure with available server details.

```APIDOC
## OP_GET_SERVER_INFO

### Description
Parse information about the streaming server (if any) and return it. Very little validation is done. In particular, OpusServerInfo::url may not be a valid URL, OpusServerInfo::bitrate_kbps may not really be in kbps, and OpusServerInfo::content_type may not be a valid MIME type. The character set of the string fields is not specified anywhere, and should not be assumed to be valid UTF-8.

### Parameters
- **_info** (OpusServerInfo *): Returns information about the server. If there is any error opening the stream, the contents of this structure remain unmodified. On success, fills in the structure with the server information that was available, if any. After a successful return, the contents of this structure should be freed by calling opus_server_info_clear().
```

--------------------------------

### op_bitrate_instant

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Computes the instantaneous bitrate of the Opus stream. This provides a real-time measure of the data rate.

```APIDOC
## op_bitrate_instant

### Description
Computes the instantaneous bitrate of the Opus stream. This is measured as the ratio of bits to playable samples decoded since the last call to this function or since the stream was opened.

### Method
`op_bitrate_instant(OggOpusFile *_of)`

### Parameters
#### Path Parameters
- **_of** (OggOpusFile *) - Required - A pointer to the `OggOpusFile` structure.

### Return Value
- **opus_int32** - The instantaneous bitrate in bits per second.
```

--------------------------------

### opus_picture_tag_init

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__header__info.html

Initializes an OpusPictureTag structure.

```APIDOC
## opus_picture_tag_init

### Description
Initializes an OpusPictureTag structure.

### Method
(Not specified, likely a C function call)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Parameters
- **_pic** (OpusPictureTag *) - Pointer to the OpusPictureTag structure to initialize.

### Return Value
(None)
```

--------------------------------

### op_free

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__open__close.html

Releases all memory used by an OggOpusFile.

```APIDOC
## op_free

### Description
Releases all memory used by an `OggOpusFile`.

### Signature
`void op_free(OggOpusFile *_of)`

### Parameters
*   `_of` (OggOpusFile *) - Pointer to the `OggOpusFile` structure to be freed.
```

--------------------------------

### op_test_file

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__open__close.html

Partially opens an Opus stream from a file path for testing.

```APIDOC
## op_test_file

### Description
Partially opens an Opus stream from the given file path for testing purposes.

### Signature
`OP_WARN_UNUSED_RESULT OggOpusFile * op_test_file(const char *_path, int *_error) OP_ARG_NONNULL(1)`

### Parameters
*   `_path` (const char *) - The path to the Opus file.
*   `_error` (int *) - Pointer to an integer to store error information.

### Returns
Returns a pointer to an `OggOpusFile` structure on success, or NULL on failure. The error code is set in `_error`.
```

--------------------------------

### op_url_stream_vcreate

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Creates a stream that reads from a given URL using a va_list for arguments.

```APIDOC
## op_url_stream_vcreate

### Description
Creates a stream that reads from a given URL using a va_list for arguments.

### Signature
`void * op_url_stream_vcreate(OpusFileCallbacks *_cb, const char *_url, va_list _ap)`

### Parameters
*   `_cb` (OpusFileCallbacks *) - A pointer to the OpusFileCallbacks structure. Must not be NULL.
*   `_url` (const char *) - The URL of the stream to create. Must not be NULL.
*   `_ap` (va_list) - A va_list containing additional arguments for URL handling.
```

--------------------------------

### opus_tags_init

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__header__info.html

Initializes an OpusTags structure, preparing it for use. This should be called on a freshly allocated structure before any other operations.

```APIDOC
## opus_tags_init()

### Description
Initializes an OpusTags structure.

### Parameters
- **__tags_** (OpusTags *) - The OpusTags structure to initialize.
```

--------------------------------

### op_bitrate_instant

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Returns the instantaneous bitrate in bits per second for the current position in the Opus stream. This value can fluctuate based on the Opus encoding.

```APIDOC
## op_bitrate_instant

### Description
Returns the instantaneous bitrate in bits per second for the current position in the Opus stream. This value can fluctuate based on the Opus encoding.

### Signature
```c
opus_int32 op_bitrate_instant(OggOpusFile *_of)
```

### Parameters
*   **_of** (OggOpusFile *) - Required - A pointer to the `OggOpusFile` structure.

### Returns
The instantaneous bitrate in bps. Returns -1 if the bitrate is unknown.
```

--------------------------------

### op_test_open

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__open__close.html

Finishes opening a stream that was partially opened with op_test_callbacks(). This function must be called to complete the stream opening process before audio can be read or further stream information can be obtained.

```APIDOC
## op_test_open()

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

### Method
(Implicitly a function call, not HTTP)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Parameters
- **__of_** (OggOpusFile *): The `OggOpusFile` to finish opening.

### Returns
0 on success, or a negative value on error. If this function fails, you are still responsible for freeing the `OggOpusFile` with `op_free()`.

### Error Handling
- **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_test_open

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__open__close.html

Finishes opening a stream that was partially opened.

```APIDOC
## op_test_open

### Description
Finishes opening a stream that was partially opened with `op_test_callbacks()` or one of its associated convenience functions.

### Signature
`int op_test_open(OggOpusFile *_of) OP_ARG_NONNULL(1)`

### Parameters
*   `_of` (OggOpusFile *) - Pointer to the `OggOpusFile` structure that was partially opened.

### Returns
Returns 0 on success, or a negative error code on failure.
```

--------------------------------

### op_open_memory()

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__open__close.html

Opens an Opus stream from a memory buffer. It returns a pointer to an OggOpusFile structure on success, or NULL on failure.

```APIDOC
## op_open_memory()
OggOpusFile* op_open_memory(const unsigned char *__data_, size_t __size_, int *__error_)

### Description
Open a stream from a memory buffer.

### Parameters
*   **__data_** (*const unsigned char* *) - in* - The memory buffer to open.
*   **__size_** (*size_t*) - in* - The number of bytes in the buffer.
*   **__error_** (*int* *) - out* - 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_open_callbacks

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Opens an Ogg Opus stream using a provided set of callbacks. This allows for custom stream handling and data access.

```APIDOC
## op_open_callbacks

### Description
Opens an Ogg Opus stream using a custom set of callbacks. This function provides flexibility by allowing the user to define how the stream data is accessed.

### Method
`op_open_callbacks(void *_stream, const OpusFileCallbacks *_cb, const unsigned char *_initial_data, size_t _initial_bytes, int *_error)`

### Parameters
#### Path Parameters
- **_stream** (void *) - Required - A pointer to the stream data source.
- **_cb** (const OpusFileCallbacks *) - Required - A pointer to a structure containing callback functions for stream operations.
- **_initial_data** (const unsigned char *) - Optional - A buffer containing initial data for the stream.
- **_initial_bytes** (size_t) - Optional - The number of bytes in `_initial_data`.
- **_error** (int *) - Optional - A pointer to an integer where an error code will be stored upon failure. 0 indicates success.

### Return Value
- **OggOpusFile*** - A pointer to the opened `OggOpusFile` structure on success, or NULL on failure.
```

--------------------------------

### op_url_stream_create

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__callbacks.html

Creates a stream that reads from a URL using standard variadic arguments. This is a convenient way to open streams from URLs.

```APIDOC
## op_url_stream_create

### Description
Creates a stream that reads from the given URL.

### Signature
```c
void *op_url_stream_create (OpusFileCallbacks *_cb, const char *_url, ...)
```

### Parameters

*   **_cb** (OpusFileCallbacks*) - Pointer to the OpusFileCallbacks structure to be filled.
*   **_url** (const char*) - The URL to stream from.
*   **...** - Additional arguments for URL formatting.

### Returns
A pointer to the created OpusFile stream, or NULL on error.
```

--------------------------------

### op_test_file

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Partially opens an Ogg Opus stream from a file path. This is useful for testing if a file is a valid Opus stream before fully opening it.

```APIDOC
## op_test_file

### Description
Partially opens an Ogg Opus stream from the given file path. This function can be used to check if a file is a valid Opus stream without fully allocating all resources.

### Method
`op_test_file(const char *_path, int *_error)`

### Parameters
#### Path Parameters
- **_path** (const char *) - Required - The path to the Ogg Opus file to test.
- **_error** (int *) - Optional - A pointer to an integer where an error code will be stored upon failure. 0 indicates success.

### Return Value
- **OggOpusFile*** - A pointer to a partially initialized `OggOpusFile` structure on success, or NULL on failure.
```

--------------------------------

### op_open_file

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__stream__open__close.html

Opens an Opus stream from a given file path.

```APIDOC
## op_open_file

### Description
Opens an Opus stream from the given file path.

### Signature
`OP_WARN_UNUSED_RESULT OggOpusFile * op_open_file(const char *_path, int *_error) OP_ARG_NONNULL(1)`

### Parameters
*   `_path` (const char *) - The path to the Opus file.
*   `_error` (int *) - Pointer to an integer to store error information.

### Returns
Returns a pointer to an `OggOpusFile` structure on success, or NULL on failure. The error code is set in `_error`.
```

--------------------------------

### OP_EOF Error Code

Source: https://opus-codec.org/docs/opusfile_api-0.12/group__error__codes.html

Currently not used externally.

```c
#define OP_EOF (-2)
```

--------------------------------

### op_url_stream_vcreate

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Creates an Opus stream from a URL using custom callbacks and a variable argument list.

```APIDOC
## op_url_stream_vcreate

### Description
Creates an Opus stream from a URL using custom callbacks and a variable argument list.

### Signature
`void *op_url_stream_vcreate(OpusFileCallbacks *_cb, const char *_url, va_list _ap)`

### Parameters
*   **_cb** (OpusFileCallbacks *) - Required - Pointer to the OpusFileCallbacks structure containing custom stream functions.
*   **_url** (const char *) - Required - The URL of the Opus stream.
*   **_ap** (va_list) - Required - A variable argument list for additional URL parameters.

### Returns
Returns a pointer to the created Opus URL stream, or NULL on error.
```

--------------------------------

### Opus HTTP Proxy Host Macro

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Macro to set the HTTP proxy host option for URL streams.

```APIDOC
## OP_HTTP_PROXY_HOST

### Description
Macro to set the HTTP proxy host option for URL streams.

### Usage
`OP_HTTP_PROXY_HOST(_host)`

### Parameters
*   **_host** (const char *) - Required - The hostname or IP address of the HTTP proxy.
```

--------------------------------

### opus_tags_init

Source: https://opus-codec.org/docs/opusfile_api-0.12/opusfile_8h_source.html

Initializes an `OpusTags` structure. This function prepares the structure for adding or parsing metadata tags.

```APIDOC
## opus_tags_init

### Description
Initializes an `OpusTags` structure. This function prepares the structure for adding or parsing metadata tags.

### Signature
```c
void opus_tags_init(OpusTags *_tags)
```

### Parameters
*   **_tags** (OpusTags *) - Required - A pointer to the `OpusTags` structure to initialize.
```
Tokens:
Raw