opusfile
0.1
Stand-alone decoder library for .opus files.
|
Functions for decoding audio data | |
These functions retrieve actual decoded audio data from the stream. The general functions, op_read() and op_read_float() return 16-bit or floating-point output, both using native endian ordering. The number of channels returned can change from link to link in a chained stream. There are special functions, op_read_stereo() and op_read_float_stereo(), which always output two channels, to simplify applications which do not wish to handle multichannel audio. These downmix multichannel files to two channels, so they can always return samples in the same format for every link in a chained file. If the rest of your audio processing chain can handle floating point, those routines should be preferred, as floating point output avoids introducing clipping and other issues which might be avoided entirely if, e.g., you scale down the volume at some other stage. However, if you intend to direct consume 16-bit samples, the conversion in
| |
OP_WARN_UNUSED_RESULT int | op_read (OggOpusFile *_of, opus_int16 *_pcm, int _buf_size, int *_li) OP_ARG_NONNULL(1) |
Reads more samples from the stream. | |
OP_WARN_UNUSED_RESULT int | op_read_float (OggOpusFile *_of, float *_pcm, int _buf_size, int *_li) OP_ARG_NONNULL(1) |
Reads more samples from the stream. | |
OP_WARN_UNUSED_RESULT int | op_read_stereo (OggOpusFile *_of, opus_int16 *_pcm, int _buf_size) OP_ARG_NONNULL(1) |
Reads more samples from the stream and downmixes to stereo, if necessary. | |
OP_WARN_UNUSED_RESULT int | op_read_float_stereo (OggOpusFile *_of, float *_pcm, int _buf_size) OP_ARG_NONNULL(1) |
Reads more samples from the stream and downmixes to stereo, if necessary. |
OP_WARN_UNUSED_RESULT int op_read | ( | OggOpusFile * | _of, |
opus_int16 * | _pcm, | ||
int | _buf_size, | ||
int * | _li | ||
) |
Reads more samples from the stream.
libopus
API as closely as we're able, _of | The OggOpusFile from which to read. | |
[out] | _pcm | A buffer in which to store the output PCM samples, as signed native-endian 16-bit values with a nominal range of [-32768,32767) . Multiple channels are interleaved using the Vorbis channel ordering. This must have room for at least _buf_size values. |
_buf_size | The number of values that can be stored in _pcm. It is reccommended that this be large enough for at least 120 ms of data at 48 kHz per channel (5760 values per channel). Smaller buffers will simply return less data, possibly consuming more memory to buffer the data internally. libopusfile may return less data than requested. If so, there is no guarantee that the remaining data in _pcm will be unmodified. | |
[out] | _li | The index of the link this data was decoded from. You may pass NULL if you do not need this information. If this function fails (returning a negative value), this parameter is left unset. |
op_head(_of,*_li)
. The number of samples returned may be 0 if the buffer was too small to store even a single sample for all channels, or if end-of-file was reached. The list of possible failure codes follows. Most of them can only be returned by unseekable, chained streams that encounter a new link. OP_HOLE | There was a hole in the data, and some samples may have been skipped. Call this function again to continue decoding past the hole. |
OP_EREAD | An underlying read operation failed. This may signal a truncation attack from an <https:> source. |
OP_EFAULT | An internal memory allocation failed. |
OP_EIMPL | An unseekable stream encountered a new link that used a feature that is not implemented, such as an unsupported channel family. |
OP_EINVAL | The stream was only partially open. |
OP_ENOTFORMAT | An unseekable stream encountered a new link that did not have any logical Opus streams in it. |
OP_EBADHEADER | An unseekable stream encountered a new link with a required header packet that was not properly formatted, contained illegal values, or was missing altogether. |
OP_EVERSION | An unseekable stream encountered a new link with an ID header that contained an unrecognized version number. |
OP_EBADPACKET | Failed to properly decode the next packet. |
OP_EBADLINK | We failed to find data we had seen before. |
OP_EBADTIMESTAMP | An unseekable stream encountered a new link with a starting timestamp that failed basic validity checks. |
OP_WARN_UNUSED_RESULT int op_read_float | ( | OggOpusFile * | _of, |
float * | _pcm, | ||
int | _buf_size, | ||
int * | _li | ||
) |
Reads more samples from the stream.
libopus
API as closely as we're able, _of | The OggOpusFile from which to read. | |
[out] | _pcm | A buffer in which to store the output PCM samples as signed floats with a nominal range of [-1.0,1.0] . Multiple channels are interleaved using the Vorbis channel ordering. This must have room for at least _buf_size floats. |
_buf_size | The number of floats that can be stored in _pcm. It is reccommended that this be large enough for at least 120 ms of data at 48 kHz per channel (5760 samples per channel). Smaller buffers will simply return less data, possibly consuming more memory to buffer the data internally. If less than _buf_size values are returned, libopusfile makes no guarantee that the remaining data in _pcm will be unmodified. | |
[out] | _li | The index of the link this data was decoded from. You may pass NULL if you do not need this information. If this function fails (returning a negative value), this parameter is left unset. |
op_head(_of,*_li)
. The number of samples returned may be 0 if the buffer was too small to store even a single sample for all channels, or if end-of-file was reached. The list of possible failure codes follows. Most of them can only be returned by unseekable, chained streams that encounter a new link. OP_HOLE | There was a hole in the data, and some samples may have been skipped. Call this function again to continue decoding past the hole. |
OP_EREAD | An underlying read operation failed. This may signal a truncation attack from an <https:> source. |
OP_EFAULT | An internal memory allocation failed. |
OP_EIMPL | An unseekable stream encountered a new link that used a feature that is not implemented, such as an unsupported channel family. |
OP_EINVAL | The stream was only partially open. |
OP_ENOTFORMAT | An unseekable stream encountered a new link that did not have any logical Opus streams in it. |
OP_EBADHEADER | An unseekable stream encountered a new link with a required header packet that was not properly formatted, contained illegal values, or was missing altogether. |
OP_EVERSION | An unseekable stream encountered a new link with an ID header that contained an unrecognized version number. |
OP_EBADPACKET | Failed to properly decode the next packet. |
OP_EBADLINK | We failed to find data we had seen before. |
OP_EBADTIMESTAMP | An unseekable stream encountered a new link with a starting timestamp that failed basic validity checks. |
OP_WARN_UNUSED_RESULT int op_read_stereo | ( | OggOpusFile * | _of, |
opus_int16 * | _pcm, | ||
int | _buf_size | ||
) |
Reads more samples from the stream and downmixes to stereo, if necessary.
This function is intended for simple players that want a uniform output format, even if the channel count changes between links in a chained stream.
_of | The OggOpusFile from which to read. | |
[out] | _pcm | A buffer in which to store the output PCM samples, as signed native-endian 16-bit values with a nominal range of [-32768,32767) . The left and right channels are interleaved in the buffer. This must have room for at least _buf_size values. |
_buf_size | The number of values that can be stored in _pcm. It is reccommended that this be large enough for at least 120 ms of data at 48 kHz per channel (11520 values total). Smaller buffers will simply return less data, possibly consuming more memory to buffer the data internally. If less than _buf_size values are returned, libopusfile makes no guarantee that the remaining data in _pcm will be unmodified. |
OP_HOLE | There was a hole in the data, and some samples may have been skipped. Call this function again to continue decoding past the hole. |
OP_EREAD | An underlying read operation failed. This may signal a truncation attack from an <https:> source. |
OP_EFAULT | An internal memory allocation failed. |
OP_EIMPL | An unseekable stream encountered a new link that used a feature that is not implemented, such as an unsupported channel family. |
OP_EINVAL | The stream was only partially open. |
OP_ENOTFORMAT | An unseekable stream encountered a new link that did not have any logical Opus streams in it. |
OP_EBADHEADER | An unseekable stream encountered a new link with a required header packet that was not properly formatted, contained illegal values, or was missing altogether. |
OP_EVERSION | An unseekable stream encountered a new link with an ID header that contained an unrecognized version number. |
OP_EBADPACKET | Failed to properly decode the next packet. |
OP_EBADLINK | We failed to find data we had seen before. |
OP_EBADTIMESTAMP | An unseekable stream encountered a new link with a starting timestamp that failed basic validity checks. |
OP_WARN_UNUSED_RESULT int op_read_float_stereo | ( | OggOpusFile * | _of, |
float * | _pcm, | ||
int | _buf_size | ||
) |
Reads more samples from the stream and downmixes to stereo, if necessary.
This function is intended for simple players that want a uniform output format, even if the channel count changes between links in a chained stream.
_of | The OggOpusFile from which to read. | |
[out] | _pcm | A buffer in which to store the output PCM samples, as signed floats with a nominal range of [-1.0,1.0] . The left and right channels are interleaved in the buffer. This must have room for at least _buf_size values. |
_buf_size | The number of values that can be stored in _pcm. It is reccommended that this be large enough for at least 120 ms of data at 48 kHz per channel (11520 values total). Smaller buffers will simply return less data, possibly consuming more memory to buffer the data internally. If less than _buf_size values are returned, libopusfile makes no guarantee that the remaining data in _pcm will be unmodified. |
OP_HOLE | There was a hole in the data, and some samples may have been skipped. Call this function again to continue decoding past the hole. |
OP_EREAD | An underlying read operation failed. This may signal a truncation attack from an <https:> source. |
OP_EFAULT | An internal memory allocation failed. |
OP_EIMPL | An unseekable stream encountered a new link that used a feature that is not implemented, such as an unsupported channel family. |
OP_EINVAL | The stream was only partially open. |
OP_ENOTFORMAT | An unseekable stream encountered a new link that that did not have any logical Opus streams in it. |
OP_EBADHEADER | An unseekable stream encountered a new link with a required header packet that was not properly formatted, contained illegal values, or was missing altogether. |
OP_EVERSION | An unseekable stream encountered a new link with an ID header that contained an unrecognized version number. |
OP_EBADPACKET | Failed to properly decode the next packet. |
OP_EBADLINK | We failed to find data we had seen before. |
OP_EBADTIMESTAMP | An unseekable stream encountered a new link with a starting timestamp that failed basic validity checks. |