|
|
@@ -6,7 +6,7 @@
|
|
|
* IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. *
|
|
|
* *
|
|
|
* THE libopusfile SOURCE CODE IS (C) COPYRIGHT 1994-2012 *
|
|
|
- * by the Xiph.Org Foundation and contributors http://www.xiph.org/ *
|
|
|
+ * by the Xiph.Org Foundation and contributors https://xiph.org/ *
|
|
|
* *
|
|
|
********************************************************************
|
|
|
|
|
|
@@ -28,7 +28,7 @@
|
|
|
reference
|
|
|
<tt><a href="https://www.xiph.org/ogg/doc/libogg/reference.html">libogg</a></tt>
|
|
|
and
|
|
|
- <tt><a href="https://mf4.xiph.org/jenkins/view/opus/job/opus/ws/doc/html/index.html">libopus</a></tt>
|
|
|
+ <tt><a href="https://opus-codec.org/docs/opus_api-1.3.1/">libopus</a></tt>
|
|
|
libraries.
|
|
|
|
|
|
<tt>libopusfile</tt> provides several sets of built-in routines for
|
|
|
@@ -58,7 +58,7 @@
|
|
|
it is stored in the header to allow you to resample to it after decoding
|
|
|
(the <tt>libopusfile</tt> API does not currently provide a resampler,
|
|
|
but the
|
|
|
- <a href="http://www.speex.org/docs/manual/speex-manual/node7.html#SECTION00760000000000000000">the
|
|
|
+ <a href="https://www.speex.org/docs/manual/speex-manual/node7.html#SECTION00760000000000000000">the
|
|
|
Speex resampler</a> is a good choice if you need one).
|
|
|
In general, if you are playing back the audio, you should leave it at
|
|
|
48 kHz, provided your audio hardware supports it.
|
|
|
@@ -68,7 +68,7 @@
|
|
|
|
|
|
Opus files can contain anywhere from 1 to 255 channels of audio.
|
|
|
The channel mappings for up to 8 channels are the same as the
|
|
|
- <a href="http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-800004.3.9">Vorbis
|
|
|
+ <a href="https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-810004.3.9">Vorbis
|
|
|
mappings</a>.
|
|
|
A special stereo API can convert everything to 2 channels, making it simple
|
|
|
to support multichannel files in an application which only has stereo
|
|
|
@@ -147,18 +147,18 @@ typedef struct OggOpusFile OggOpusFile;
|
|
|
/**@endcond*/
|
|
|
|
|
|
/**\defgroup error_codes Error Codes*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
/**\name List of possible error codes
|
|
|
Many of the functions in this library return a negative error code when a
|
|
|
function fails.
|
|
|
This list provides a brief explanation of the common errors.
|
|
|
See each individual function for more details on what a specific error code
|
|
|
means in that context.*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
|
|
|
/**A request did not succeed.*/
|
|
|
#define OP_FALSE (-1)
|
|
|
-/*Currently not used externally.*/
|
|
|
+/**Currently not used externally.**/
|
|
|
#define OP_EOF (-2)
|
|
|
/**There was a hole in the page sequence numbers (e.g., a page was corrupt or
|
|
|
missing).*/
|
|
|
@@ -185,7 +185,7 @@ typedef struct OggOpusFile OggOpusFile;
|
|
|
#define OP_EBADHEADER (-133)
|
|
|
/**The ID header contained an unrecognized version number.*/
|
|
|
#define OP_EVERSION (-134)
|
|
|
-/*Currently not used at all.*/
|
|
|
+/**Currently not used at all.**/
|
|
|
#define OP_ENOTAUDIO (-135)
|
|
|
/**An audio packet failed to decode properly.
|
|
|
This is usually caused by a multistream Ogg packet where the durations of
|
|
|
@@ -200,11 +200,11 @@ typedef struct OggOpusFile OggOpusFile;
|
|
|
/**The first or last granule position of a link failed basic validity checks.*/
|
|
|
#define OP_EBADTIMESTAMP (-139)
|
|
|
|
|
|
-/*@}*/
|
|
|
-/*@}*/
|
|
|
+/**@}*/
|
|
|
+/**@}*/
|
|
|
|
|
|
/**\defgroup header_info Header Information*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
|
|
|
/**The maximum number of channels in an Ogg Opus stream.*/
|
|
|
#define OPUS_CHANNEL_COUNT_MAX (255)
|
|
|
@@ -284,7 +284,7 @@ struct OpusHead{
|
|
|
A particular tag may occur more than once, and order is significant.
|
|
|
The character set encoding for the strings is always UTF-8, but the tag
|
|
|
names are limited to ASCII, and treated as case-insensitive.
|
|
|
- See <a href="http://www.xiph.org/vorbis/doc/v-comment.html">the Vorbis
|
|
|
+ See <a href="https://www.xiph.org/vorbis/doc/v-comment.html">the Vorbis
|
|
|
comment header specification</a> for details.
|
|
|
|
|
|
In filling in this structure, <tt>libopusfile</tt> will null-terminate the
|
|
|
@@ -311,7 +311,7 @@ struct OpusTags{
|
|
|
};
|
|
|
|
|
|
/**\name Picture tag image formats*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
|
|
|
/**The MIME type was not recognized, or the image data did not match the
|
|
|
declared MIME type.*/
|
|
|
@@ -325,7 +325,7 @@ struct OpusTags{
|
|
|
/**The image is a GIF.*/
|
|
|
#define OP_PIC_FORMAT_GIF (3)
|
|
|
|
|
|
-/*@}*/
|
|
|
+/**@}*/
|
|
|
|
|
|
/**The contents of a METADATA_BLOCK_PICTURE tag.*/
|
|
|
struct OpusPictureTag{
|
|
|
@@ -398,7 +398,7 @@ struct OpusPictureTag{
|
|
|
These can be used to query the headers returned by <tt>libopusfile</tt>, or
|
|
|
to parse Opus headers from sources other than an Ogg Opus stream, provided
|
|
|
they use the same format.*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
|
|
|
/**Parses the contents of the ID header packet of an Ogg Opus stream.
|
|
|
\param[out] _head Returns the contents of the parsed packet.
|
|
|
@@ -671,12 +671,12 @@ void opus_picture_tag_init(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
|
|
|
\param _pic The #OpusPictureTag structure to clear.*/
|
|
|
void opus_picture_tag_clear(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
|
|
|
|
|
|
-/*@}*/
|
|
|
+/**@}*/
|
|
|
|
|
|
-/*@}*/
|
|
|
+/**@}*/
|
|
|
|
|
|
/**\defgroup url_options URL Reading Options*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
/**\name URL reading options
|
|
|
Options for op_url_stream_create() and associated functions.
|
|
|
These allow you to provide proxy configuration parameters, skip SSL
|
|
|
@@ -685,7 +685,7 @@ void opus_picture_tag_clear(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
|
|
|
times, only the value specified by the last occurrence has an effect
|
|
|
(unless otherwise specified).
|
|
|
They may be expanded in the future.*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
|
|
|
/**@cond PRIVATE*/
|
|
|
|
|
|
@@ -698,7 +698,7 @@ void opus_picture_tag_clear(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
|
|
|
#define OP_HTTP_PROXY_PASS_REQUEST (6720)
|
|
|
#define OP_GET_SERVER_INFO_REQUEST (6784)
|
|
|
|
|
|
-#define OP_URL_OPT(_request) ((_request)+(char *)0)
|
|
|
+#define OP_URL_OPT(_request) ((char *)(_request))
|
|
|
|
|
|
/*These macros trigger compilation errors or warnings if the wrong types are
|
|
|
provided to one of the URL options.*/
|
|
|
@@ -843,11 +843,11 @@ void opus_server_info_clear(OpusServerInfo *_info) OP_ARG_NONNULL(1);
|
|
|
#define OP_GET_SERVER_INFO(_info) \
|
|
|
OP_URL_OPT(OP_GET_SERVER_INFO_REQUEST),OP_CHECK_SERVER_INFO_PTR(_info)
|
|
|
|
|
|
-/*@}*/
|
|
|
-/*@}*/
|
|
|
+/**@}*/
|
|
|
+/**@}*/
|
|
|
|
|
|
/**\defgroup stream_callbacks Abstract Stream Reading Interface*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
/**\name Functions for reading from streams
|
|
|
These functions define the interface used to read from and seek in a stream
|
|
|
of data.
|
|
|
@@ -856,7 +856,7 @@ void opus_server_info_clear(OpusServerInfo *_info) OP_ARG_NONNULL(1);
|
|
|
These functions also include some convenience routines for working with
|
|
|
standard <code>FILE</code> pointers, complete streams stored in a single
|
|
|
block of memory, or URLs.*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
|
|
|
/**Reads up to \a _nbytes bytes of data from \a _stream.
|
|
|
\param _stream The stream to read from.
|
|
|
@@ -1034,18 +1034,18 @@ OP_WARN_UNUSED_RESULT void *op_url_stream_vcreate(OpusFileCallbacks *_cb,
|
|
|
OP_WARN_UNUSED_RESULT void *op_url_stream_create(OpusFileCallbacks *_cb,
|
|
|
const char *_url,...) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
|
|
|
|
|
|
-/*@}*/
|
|
|
-/*@}*/
|
|
|
+/**@}*/
|
|
|
+/**@}*/
|
|
|
|
|
|
/**\defgroup stream_open_close Opening and Closing*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
/**\name 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.*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
|
|
|
/**Test to see if this is an Opus stream.
|
|
|
For good results, you will need at least 57 bytes (for a pure Opus-only
|
|
|
@@ -1159,20 +1159,16 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
|
|
|
This value will be passed verbatim as the first
|
|
|
argument to all of the callbacks.
|
|
|
\param _cb The callbacks with which to access the stream.
|
|
|
- <code><a href="#op_read_func">read()</a></code> must
|
|
|
- be implemented.
|
|
|
- <code><a href="#op_seek_func">seek()</a></code> and
|
|
|
- <code><a href="#op_tell_func">tell()</a></code> may
|
|
|
- be <code>NULL</code>, or may always return -1 to
|
|
|
- indicate a stream is unseekable, but if
|
|
|
- <code><a href="#op_seek_func">seek()</a></code> is
|
|
|
- implemented and succeeds on a particular stream, then
|
|
|
- <code><a href="#op_tell_func">tell()</a></code> must
|
|
|
- also.
|
|
|
- <code><a href="#op_close_func">close()</a></code> may
|
|
|
- be <code>NULL</code>, but if it is not, it will be
|
|
|
- called when the \c OggOpusFile is destroyed by
|
|
|
- op_free().
|
|
|
+ \ref op_read_func "read()" must be implemented.
|
|
|
+ \ref op_seek_func "seek()" and \ref op_tell_func
|
|
|
+ "tell()" may be <code>NULL</code>, or may always
|
|
|
+ return -1 to indicate a stream is unseekable, but if
|
|
|
+ \ref op_seek_func "seek()" is implemented and
|
|
|
+ succeeds on a particular stream, then \ref
|
|
|
+ op_tell_func "tell()" must also.
|
|
|
+ \ref op_close_func "close()" may be <code>NULL</code>,
|
|
|
+ but if it is not, it will be called when the \c
|
|
|
+ OggOpusFile is destroyed by op_free().
|
|
|
It will not be called if op_open_callbacks() fails
|
|
|
with an error.
|
|
|
\param _initial_data An initial buffer of data from the start of the
|
|
|
@@ -1183,10 +1179,8 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
|
|
|
stream to be opened, even if it is unseekable.
|
|
|
\param _initial_bytes The number of bytes in \a _initial_data.
|
|
|
If the stream is seekable, its current position (as
|
|
|
- reported by
|
|
|
- <code><a href="#opus_tell_func">tell()</a></code>
|
|
|
- at the start of this function) must be equal to
|
|
|
- \a _initial_bytes.
|
|
|
+ reported by \ref op_tell_func "tell()" at the start
|
|
|
+ of this function) must be equal to \a _initial_bytes.
|
|
|
Otherwise, seeking to absolute positions will
|
|
|
generate inconsistent results.
|
|
|
\param[out] _error Returns 0 on success, or a failure code on error.
|
|
|
@@ -1206,11 +1200,10 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
|
|
|
implemented, such as an unsupported channel
|
|
|
family.</dd>
|
|
|
<dt>#OP_EINVAL</dt>
|
|
|
- <dd><code><a href="#op_seek_func">seek()</a></code>
|
|
|
- was implemented and succeeded on this source, but
|
|
|
- <code><a href="#op_tell_func">tell()</a></code>
|
|
|
- did not, or the starting position indicator was
|
|
|
- not equal to \a _initial_bytes.</dd>
|
|
|
+ <dd>\ref op_seek_func "seek()" was implemented and
|
|
|
+ succeeded on this source, but \ref op_tell_func
|
|
|
+ "tell()" did not, or the starting position
|
|
|
+ indicator was not equal to \a _initial_bytes.</dd>
|
|
|
<dt>#OP_ENOTFORMAT</dt>
|
|
|
<dd>The stream contained a link that did not have
|
|
|
any logical Opus streams in it.</dd>
|
|
|
@@ -1341,20 +1334,16 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,
|
|
|
This value will be passed verbatim as the first
|
|
|
argument to all of the callbacks.
|
|
|
\param _cb The callbacks with which to access the stream.
|
|
|
- <code><a href="#op_read_func">read()</a></code> must
|
|
|
- be implemented.
|
|
|
- <code><a href="#op_seek_func">seek()</a></code> and
|
|
|
- <code><a href="#op_tell_func">tell()</a></code> may
|
|
|
- be <code>NULL</code>, or may always return -1 to
|
|
|
- indicate a stream is unseekable, but if
|
|
|
- <code><a href="#op_seek_func">seek()</a></code> is
|
|
|
- implemented and succeeds on a particular stream, then
|
|
|
- <code><a href="#op_tell_func">tell()</a></code> must
|
|
|
- also.
|
|
|
- <code><a href="#op_close_func">close()</a></code> may
|
|
|
- be <code>NULL</code>, but if it is not, it will be
|
|
|
- called when the \c OggOpusFile is destroyed by
|
|
|
- op_free().
|
|
|
+ \ref op_read_func "read()" must be implemented.
|
|
|
+ \ref op_seek_func "seek()" and \ref op_tell_func
|
|
|
+ "tell()" may be <code>NULL</code>, or may always
|
|
|
+ return -1 to indicate a stream is unseekable, but if
|
|
|
+ \ref op_seek_func "seek()" is implemented and
|
|
|
+ succeeds on a particular stream, then \ref
|
|
|
+ op_tell_func "tell()" must also.
|
|
|
+ \ref op_close_func "close()" may be <code>NULL</code>,
|
|
|
+ but if it is not, it will be called when the \c
|
|
|
+ OggOpusFile is destroyed by op_free().
|
|
|
It will not be called if op_open_callbacks() fails
|
|
|
with an error.
|
|
|
\param _initial_data An initial buffer of data from the start of the
|
|
|
@@ -1367,9 +1356,8 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,
|
|
|
\param _initial_bytes The number of bytes in \a _initial_data.
|
|
|
If the stream is seekable, its current position (as
|
|
|
reported by
|
|
|
- <code><a href="#opus_tell_func">tell()</a></code>
|
|
|
- at the start of this function) must be equal to
|
|
|
- \a _initial_bytes.
|
|
|
+ \ref op_tell_func "tell()" at the start of this
|
|
|
+ function) must be equal to \a _initial_bytes.
|
|
|
Otherwise, seeking to absolute positions will
|
|
|
generate inconsistent results.
|
|
|
\param[out] _error Returns 0 on success, or a failure code on error.
|
|
|
@@ -1418,11 +1406,11 @@ int op_test_open(OggOpusFile *_of) OP_ARG_NONNULL(1);
|
|
|
\param _of The \c OggOpusFile to free.*/
|
|
|
void op_free(OggOpusFile *_of);
|
|
|
|
|
|
-/*@}*/
|
|
|
-/*@}*/
|
|
|
+/**@}*/
|
|
|
+/**@}*/
|
|
|
|
|
|
/**\defgroup stream_info Stream Information*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
/**\name Functions for obtaining information about streams
|
|
|
|
|
|
These functions allow you to get basic information about a stream, including
|
|
|
@@ -1437,18 +1425,17 @@ void op_free(OggOpusFile *_of);
|
|
|
streams returned by op_test_callbacks() or one of the associated
|
|
|
convenience functions.
|
|
|
Their documention will indicate so explicitly.*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
|
|
|
/**Returns whether or not the stream being read is seekable.
|
|
|
This is true if
|
|
|
<ol>
|
|
|
- <li>The <code><a href="#op_seek_func">seek()</a></code> and
|
|
|
- <code><a href="#op_tell_func">tell()</a></code> callbacks are both
|
|
|
- non-<code>NULL</code>,</li>
|
|
|
- <li>The <code><a href="#op_seek_func">seek()</a></code> callback was
|
|
|
- successfully executed at least once, and</li>
|
|
|
- <li>The <code><a href="#op_tell_func">tell()</a></code> callback was
|
|
|
- successfully able to report the position indicator afterwards.</li>
|
|
|
+ <li>The \ref op_seek_func "seek()" and \ref op_tell_func "tell()"
|
|
|
+ callbacks are both non-<code>NULL</code>,</li>
|
|
|
+ <li>The \ref op_seek_func "seek()" callback was successfully executed at
|
|
|
+ least once, and</li>
|
|
|
+ <li>The \ref op_tell_func "tell()" callback was successfully able to report
|
|
|
+ the position indicator afterwards.</li>
|
|
|
</ol>
|
|
|
This function may be called on partially-opened streams.
|
|
|
\param _of The \c OggOpusFile whose seekable status is to be returned.
|
|
|
@@ -1638,11 +1625,11 @@ opus_int64 op_raw_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
|
|
|
\retval #OP_EINVAL The stream was only partially open.*/
|
|
|
ogg_int64_t op_pcm_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
|
|
|
|
|
|
-/*@}*/
|
|
|
-/*@}*/
|
|
|
+/**@}*/
|
|
|
+/**@}*/
|
|
|
|
|
|
/**\defgroup stream_seeking Seeking*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
/**\name Functions for seeking in Opus streams
|
|
|
|
|
|
These functions let you seek in Opus streams, if the underlying stream
|
|
|
@@ -1667,7 +1654,7 @@ ogg_int64_t op_pcm_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
|
|
|
values as would be obtained by decoding the stream straight through.
|
|
|
However, such differences are expected to be smaller than the loss
|
|
|
introduced by Opus's lossy compression.*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
|
|
|
/**Seek to a byte offset relative to the <b>compressed</b> data.
|
|
|
This also scans packets to update the PCM cursor.
|
|
|
@@ -1702,11 +1689,11 @@ int op_raw_seek(OggOpusFile *_of,opus_int64 _byte_offset) OP_ARG_NONNULL(1);
|
|
|
seeking to the target destination was impossible.*/
|
|
|
int op_pcm_seek(OggOpusFile *_of,ogg_int64_t _pcm_offset) OP_ARG_NONNULL(1);
|
|
|
|
|
|
-/*@}*/
|
|
|
-/*@}*/
|
|
|
+/**@}*/
|
|
|
+/**@}*/
|
|
|
|
|
|
/**\defgroup stream_decoding Decoding*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
/**\name Functions for decoding audio data
|
|
|
|
|
|
These functions retrieve actual decoded audio data from the stream.
|
|
|
@@ -1744,7 +1731,7 @@ int op_pcm_seek(OggOpusFile *_of,ogg_int64_t _pcm_offset) OP_ARG_NONNULL(1);
|
|
|
If you are reading from an <https:> URL (particularly if seeking is not
|
|
|
supported), you should make sure to check for this error and warn the user
|
|
|
appropriately.*/
|
|
|
-/*@{*/
|
|
|
+/**@{*/
|
|
|
|
|
|
/**Indicates that the decoding callback should produce signed 16-bit
|
|
|
native-endian output samples.*/
|
|
|
@@ -1890,7 +1877,7 @@ void op_set_dither_enabled(OggOpusFile *_of,int _enabled) OP_ARG_NONNULL(1);
|
|
|
signed native-endian 16-bit values at 48 kHz
|
|
|
with a nominal range of <code>[-32768,32767)</code>.
|
|
|
Multiple channels are interleaved using the
|
|
|
- <a href="http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-800004.3.9">Vorbis
|
|
|
+ <a href="https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-810004.3.9">Vorbis
|
|
|
channel ordering</a>.
|
|
|
This must have room for at least \a _buf_size values.
|
|
|
\param _buf_size The number of values that can be stored in \a _pcm.
|
|
|
@@ -1972,7 +1959,7 @@ OP_WARN_UNUSED_RESULT int op_read(OggOpusFile *_of,
|
|
|
signed floats at 48 kHz with a nominal range of
|
|
|
<code>[-1.0,1.0]</code>.
|
|
|
Multiple channels are interleaved using the
|
|
|
- <a href="http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-800004.3.9">Vorbis
|
|
|
+ <a href="https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-810004.3.9">Vorbis
|
|
|
channel ordering</a>.
|
|
|
This must have room for at least \a _buf_size floats.
|
|
|
\param _buf_size The number of floats that can be stored in \a _pcm.
|
|
|
@@ -2150,8 +2137,8 @@ OP_WARN_UNUSED_RESULT int op_read_stereo(OggOpusFile *_of,
|
|
|
OP_WARN_UNUSED_RESULT int op_read_float_stereo(OggOpusFile *_of,
|
|
|
float *_pcm,int _buf_size) OP_ARG_NONNULL(1);
|
|
|
|
|
|
-/*@}*/
|
|
|
-/*@}*/
|
|
|
+/**@}*/
|
|
|
+/**@}*/
|
|
|
|
|
|
# if OP_GNUC_PREREQ(4,0)
|
|
|
# pragma GCC visibility pop
|
philippe44