Fix a comment typo.
[opusfile.git] / include / opusfile.h
1 /********************************************************************
2  *                                                                  *
3  * THIS FILE IS PART OF THE libopusfile SOFTWARE CODEC SOURCE CODE. *
4  * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS     *
5  * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
6  * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING.       *
7  *                                                                  *
8  * THE libopusfile SOURCE CODE IS (C) COPYRIGHT 1994-2012           *
9  * by the Xiph.Org Foundation and contributors http://www.xiph.org/ *
10  *                                                                  *
11  ********************************************************************
12
13  function: stdio-based convenience library for opening/seeking/decoding
14  last mod: $Id: vorbisfile.h 17182 2010-04-29 03:48:32Z xiphmont $
15
16  ********************************************************************/
17 #if !defined(_opusfile_h)
18 # define _opusfile_h (1)
19 # include <stdarg.h>
20
21 /**\mainpage
22    \section Introduction
23
24    This is the documentation for the <tt>libopusfile</tt> C API.
25
26    The <tt>libopusfile</tt> package provides a convenient high-level API for
27     decoding and basic manipulation of all Ogg Opus audio streams.
28    <tt>libopusfile</tt> is implemented as a layer on top of Xiph.Org's
29     reference
30     <tt><a href="https://www.xiph.org/ogg/doc/libogg/reference.html">libogg</a></tt>
31     and
32     <tt><a href="https://mf4.xiph.org/jenkins/view/opus/job/opus/ws/doc/html/index.html">libopus</a></tt>
33     libraries.
34
35    <tt>libopusfile</tt> provides several sets of built-in routines for
36     file/stream access, and may also use custom stream I/O routines provided by
37     the embedded environment.
38    There are built-in I/O routines provided for ANSI-compliant
39     <code>stdio</code> (<code>FILE *</code>), memory buffers, and URLs
40     (including <file:> URLs, plus optionally <http:> and <https:> URLs).
41
42    \section Organization
43
44    The main API is divided into several sections:
45    - \ref stream_open_close
46    - \ref stream_info
47    - \ref stream_decoding
48    - \ref stream_seeking
49
50    Several additional sections are not tied to the main API.
51    - \ref stream_callbacks
52    - \ref header_info
53    - \ref error_codes*/
54
55
56 # if defined(__cplusplus)
57 extern "C" {
58 # endif
59
60 # include <stdio.h>
61 # include <ogg/ogg.h>
62 # include <opus_multistream.h>
63
64 /*Enable special features for gcc and gcc-compatible compilers.*/
65 # if !defined(OP_GNUC_PREREQ)
66 #  if defined(__GNUC__)&&defined(__GNUC_MINOR__)
67 #   define OP_GNUC_PREREQ(_maj,_min) \
68  ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min))
69 #  else
70 #   define OP_GNUC_PREREQ(_maj,_min) 0
71 #  endif
72 # endif
73
74 # if OP_GNUC_PREREQ(4,0)
75 #  pragma GCC visibility push(default)
76 # endif
77
78 typedef struct OpusHead    OpusHead;
79 typedef struct OpusTags    OpusTags;
80 typedef struct OggOpusFile OggOpusFile;
81
82 /*Warning attributes for libopusfile functions.*/
83 # if OP_GNUC_PREREQ(3,4)
84 #  define OP_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
85 # else
86 #  define OP_WARN_UNUSED_RESULT
87 # endif
88 # if OP_GNUC_PREREQ(3,4)
89 #  define OP_ARG_NONNULL(_x) __attribute__((__nonnull__(_x)))
90 # else
91 #  define OP_ARG_NONNULL(_x)
92 # endif
93
94 /**\defgroup error_codes Error Codes*/
95 /*@{*/
96 /**\name List of possible error codes
97    Many of the functions in this library return a negative error code when a
98     function fails.
99    This list provides a brief explanation of the common errors.
100    See each individual function for more details on what a specific error code
101     means in that context.*/
102 /*@{*/
103
104 /**A request did not succeed.*/
105 #define OP_FALSE         (-1)
106 /*Currently not used externally.*/
107 #define OP_EOF           (-2)
108 /**There was a hole in the page sequence numbers (e.g., a page was corrupt or
109     missing).*/
110 #define OP_HOLE          (-3)
111 /**An underlying read, seek, or tell operation failed when it should have
112     succeeded.*/
113 #define OP_EREAD         (-128)
114 /**A <code>NULL</code> pointer was passed where one was unexpected, or an
115     internal memory allocation failed, or an internal library error was
116     encountered.*/
117 #define OP_EFAULT        (-129)
118 /**The stream used a feature that is not implemented, such as an unsupported
119     channel family.*/
120 #define OP_EIMPL         (-130)
121 /**One or more parameters to a function were invalid.*/
122 #define OP_EINVAL        (-131)
123 /**A purported Ogg Opus stream did not begin with an Ogg page, a purported
124     header packet did not start with one of the required strings, "OpusHead" or
125     "OpusTags", or a link in a chained file was encountered that did not
126     contain any logical Opus streams.*/
127 #define OP_ENOTFORMAT    (-132)
128 /**A required header packet was not properly formatted, contained illegal
129     values, or was missing altogether.*/
130 #define OP_EBADHEADER    (-133)
131 /**The ID header contained an unrecognized version number.*/
132 #define OP_EVERSION      (-134)
133 /*Currently not used at all.*/
134 #define OP_ENOTAUDIO     (-135)
135 /**An audio packet failed to decode properly.
136    This is usually caused by a multistream Ogg packet where the durations of
137     the individual Opus packets contained in it are not all the same.*/
138 #define OP_EBADPACKET    (-136)
139 /**We failed to find data we had seen before, or the bitstream structure was
140     sufficiently malformed that seeking to the target destination was
141     impossible.*/
142 #define OP_EBADLINK      (-137)
143 /**An operation that requires seeking was requested on an unseekable stream.*/
144 #define OP_ENOSEEK       (-138)
145 /**The first or last granule position of a link failed basic validity checks.*/
146 #define OP_EBADTIMESTAMP (-139)
147
148 /*@}*/
149 /*@}*/
150
151 /**\defgroup header_info Header Information*/
152 /*@{*/
153
154 /**The maximum number of channels in an Ogg Opus stream.*/
155 #define OPUS_CHANNEL_COUNT_MAX (255)
156
157 /**Ogg Opus bitstream information.
158    This contains the basic playback parameters for a stream, and corresponds to
159     the initial ID header packet of an Ogg Opus stream.*/
160 struct OpusHead{
161   /**The Ogg Opus format version, in the range 0...255.
162      The top 4 bits represent a "major" version, and the bottom four bits
163       represent backwards-compatible "minor" revisions.
164      The current specification describes version 1.
165      This library will recognize versions up through 15 as backwards compatible
166       with the current specification.
167      An earlier draft of the specification described a version 0, but the only
168       difference between version 1 and version 0 is that version 0 did
169       not specify the semantics for handling the version field.*/
170   int           version;
171   /**The number of channels, in the range 1...255.*/
172   int           channel_count;
173   /**The number of samples that should be discarded from the beginning of the
174       stream.*/
175   unsigned      pre_skip;
176   /**The sampling rate of the original input.
177      All Opus audio is coded at 48 kHz, and should also be decoded at 48 kHz
178       for playback (unless the target hardware does not support this sampling
179       rate).
180      However, this field may be used to resample the audio back to the original
181       sampling rate, for example, when saving the output to a file.*/
182   opus_uint32   input_sample_rate;
183   /**The gain to apply to the decoded output, in dB, as a Q8 value in the range
184       -32768...32767.
185      The decoder will automatically scale the output by
186       pow(10,output_gain/(20.0*256)).*/
187   int           output_gain;
188   /**The channel mapping family, in the range 0...255.
189      Channel mapping family 0 covers mono or stereo in a single stream.
190      Channel mapping family 1 covers 1 to 8 channels in one or more streams,
191       using the Vorbis speaker assignments.
192      Channel mapping family 255 covers 1 to 255 channels in one or more
193       streams, but without any defined speaker assignment.*/
194   int           mapping_family;
195   /**The number of Opus streams in each Ogg packet, in the range 1...255.*/
196   int           stream_count;
197   /**The number of coupled Opus streams in each Ogg packet, in the range
198       0...127.
199      This must satisfy <code>0 <= coupled_count <= stream_count</code> and
200       <code>coupled_count + stream_count <= 255</code>.
201      The coupled streams appear first, before all uncoupled streams, in an Ogg
202       Opus packet.*/
203   int           coupled_count;
204   /**The mapping from coded stream channels to output channels.
205      Let <code>index=mapping[k]</code> be the value for channel <code>k</code>.
206      If <code>index<2*coupled_count</code>, then it refers to the left channel
207       from stream <code>(index/2)</code> if even, and the right channel from
208       stream <code>(index/2)</code> if odd.
209      Otherwise, it refers to the output of the uncoupled stream
210       <code>(index-coupled_count)</code>.*/
211   unsigned char mapping[OPUS_CHANNEL_COUNT_MAX];
212 };
213
214 /**The metadata from an Ogg Opus stream.
215
216    This structure holds the in-stream metadata corresponding to the 'comment'
217     header packet of an Ogg Opus stream.
218    The comment header is meant to be used much like someone jotting a quick
219     note on the label of a CD.
220    It should be a short, to the point text note that can be more than a couple
221     words, but not more than a short paragraph.
222
223    The metadata is stored as a series of (tag, value) pairs, in length-encoded
224     string vectors, using the same format as Vorbis (without the final "framing
225     bit"), Theora, and Speex, except for the packet header.
226    The first occurrence of the '=' character delimits the tag and value.
227    A particular tag may occur more than once, and order is significant.
228    The character set encoding for the strings is always UTF-8, but the tag
229     names are limited to ASCII, and treated as case-insensitive.
230    See <a href="http://www.xiph.org/vorbis/doc/v-comment.html">the Vorbis
231     comment header specification</a> for details.
232
233    In filling in this structure, <tt>libopusfile</tt> will null-terminate the
234     #user_comments strings for safety.
235    However, the bitstream format itself treats them as 8-bit clean vectors,
236     possibly containing NUL characters, so the #comment_lengths array should be
237     treated as their authoritative length.
238
239    This structure is binary and source-compatible with a
240     <code>vorbis_comment</code>, and pointers to it may be freely cast to
241     <code>vorbis_comment</code> pointers, and vice versa.
242    It is provided as a separate type to avoid introducing a compile-time
243     dependency on the libvorbis headers.*/
244 struct OpusTags{
245   /**The array of comment string vectors.*/
246   char **user_comments;
247   /**An array of the corresponding length of each vector, in bytes.*/
248   int   *comment_lengths;
249   /**The total number of comment streams.*/
250   int    comments;
251   /**The null-terminated vendor string.
252      This identifies the software used to encode the stream.*/
253   char  *vendor;
254 };
255
256 /**\name Functions for manipulating header data
257
258    These functions manipulate the #OpusHead and #OpusTags structures,
259     which describe the audio parameters and tag-value metadata, respectively.
260    These can be used to query the headers returned by <tt>libopusfile</tt>, or
261     to parse Opus headers from sources other than an Ogg Opus stream, provided
262     they use the same format.*/
263 /*@{*/
264
265 /**Parses the contents of the ID header packet of an Ogg Opus stream.
266    \param[out] _head Returns the contents of the parsed packet.
267                      The contents of this structure are untouched on error.
268                      This may be <code>NULL</code> to merely test the header
269                       for validity.
270    \param[in]  _data The contents of the ID header packet.
271    \param      _len  The number of bytes of data in the ID header packet.
272    \return 0 on success or a negative value on error.
273    \retval #OP_ENOTFORMAT If the data does not start with the "OpusHead"
274                            string.
275    \retval #OP_EVERSION   If the version field signaled a version this library
276                            does not know how to parse.
277    \retval #OP_EIMPL      If the channel mapping family was 255, which general
278                            purpose players should not attempt to play.
279    \retval #OP_EBADHEADER If the contents of the packet otherwise violate the
280                            Ogg Opus specification:
281                           <ul>
282                            <li>Insufficient data,</li>
283                            <li>Too much data for the known minor versions,</li>
284                            <li>An unrecognized channel mapping family,</li>
285                            <li>Zero channels or too many channels,</li>
286                            <li>Zero coded streams,</li>
287                            <li>Too many coupled streams, or</li>
288                            <li>An invalid channel mapping index.</li>
289                           </ul>*/
290 OP_WARN_UNUSED_RESULT int opus_head_parse(OpusHead *_head,
291  const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
292
293 /**Converts a granule position to a sample offset for a given Ogg Opus stream.
294    The sample offset is simply <code>_gp-_head->pre_skip</code>.
295    Granule position values smaller than OpusHead#pre_skip correspond to audio
296     that should never be played, and thus have no associated sample offset.
297    This function returns -1 for such values.
298    This function also correctly handles extremely large granule positions,
299     which may have wrapped around to a negative number when stored in a signed
300     ogg_int64_t value.
301    \param _head The #OpusHead information from the ID header of the stream.
302    \param _gp   The granule position to convert.
303    \return The sample offset associated with the given granule position
304             (counting at a 48 kHz sampling rate), or the special value -1 on
305             error (i.e., the granule position was smaller than the pre-skip
306             amount).*/
307 ogg_int64_t opus_granule_sample(const OpusHead *_head,ogg_int64_t _gp)
308  OP_ARG_NONNULL(1);
309
310 /**Parses the contents of the 'comment' header packet of an Ogg Opus stream.
311    \param[out] _tags An uninitialized #OpusTags structure.
312                      This returns the contents of the parsed packet.
313                      The contents of this structure are untouched on error.
314                      This may be <code>NULL</code> to merely test the header
315                       for validity.
316    \param[in]  _data The contents of the 'comment' header packet.
317    \param      _len  The number of bytes of data in the 'info' header packet.
318    \retval 0             Success.
319    \retval #OP_ENOTFORMAT If the data does not start with the "OpusTags"
320                            string.
321    \retval #OP_EBADHEADER If the contents of the packet otherwise violate the
322                            Ogg Opus specification.
323    \retval #OP_EFAULT     If there wasn't enough memory to store the tags.*/
324 OP_WARN_UNUSED_RESULT int opus_tags_parse(OpusTags *_tags,
325  const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
326
327 /**Initializes an #OpusTags structure.
328    This should be called on a freshly allocated #OpusTags structure before
329     attempting to use it.
330    \param _tags The #OpusTags structure to initialize.*/
331 void opus_tags_init(OpusTags *_tags) OP_ARG_NONNULL(1);
332
333 /**Add a (tag, value) pair to an initialized #OpusTags structure.
334    \note Neither opus_tags_add() nor opus_tags_add_comment() support values
335     containing embedded NULs, although the bitstream format does support them.
336    To add such tags, you will need to manipulate the #OpusTags structure
337     directly.
338    \param _tags  The #OpusTags structure to add the (tag, value) pair to.
339    \param _tag   A NUL-terminated, case-insensitive, ASCII string containing
340                   the tag to add (without an '=' character).
341    \param _value A NUL-terminated UTF-8 containing the corresponding value.
342    \return 0 on success, or a negative value on failure.
343    \retval #OP_EFAULT An internal memory allocation failed.*/
344 int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value)
345  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3);
346
347 /**Add a comment to an initialized #OpusTags structure.
348    \note Neither opus_tags_add_comment() nor opus_tags_add() support comments
349     containing embedded NULs, although the bitstream format does support them.
350    To add such tags, you will need to manipulate the #OpusTags structure
351     directly.
352    \param _tags    The #OpusTags structure to add the comment to.
353    \param _comment A NUL-terminated UTF-8 string containing the comment in
354                     "TAG=value" form.
355    \return 0 on success, or a negative value on failure.
356    \retval #OP_EFAULT An internal memory allocation failed.*/
357 int opus_tags_add_comment(OpusTags *_tags,const char *_comment)
358  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
359
360 /**Look up a comment value by its tag.
361    \param _tags  An initialized #OpusTags structure.
362    \param _tag   The tag to look up.
363    \param _count The instance of the tag.
364                  The same tag can appear multiple times, each with a distinct
365                   value, so an index is required to retrieve them all.
366                  The order in which these values appear is significant and
367                   should be preserved.
368                  Use opus_tags_query_count() to get the legal range for the
369                   \a _count parameter.
370    \return A pointer to the queried tag's value.
371            This points directly to data in the #OpusTags structure.
372            It should not be modified or freed by the application, and
373             modifications to the structure may invalidate the pointer.
374    \retval NULL If no matching tag is found.*/
375 const char *opus_tags_query(const OpusTags *_tags,const char *_tag,int _count)
376  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
377
378 /**Look up the number of instances of a tag.
379    Call this first when querying for a specific tag and then iterate over the
380     number of instances with separate calls to opus_tags_query() to retrieve
381     all the values for that tag in order.
382    \param _tags An initialized #OpusTags structure.
383    \param _tag  The tag to look up.
384    \return The number of instances of this particular tag.*/
385 int opus_tags_query_count(const OpusTags *_tags,const char *_tag)
386  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
387
388 /**Clears the #OpusTags structure.
389    This should be called on an #OpusTags structure after it is no longer
390     needed.
391    It will free all memory used by the structure members.
392    \param _tags The #OpusTags structure to clear.*/
393 void opus_tags_clear(OpusTags *_tags) OP_ARG_NONNULL(1);
394
395 /*@}*/
396
397 /*@}*/
398
399 /**\defgroup url_options URL Reading Options*/
400 /*@{*/
401 /**\name URL reading options
402    Options for op_url_stream_create() and associated functions.
403    These allow you to provide proxy configuration parameters, skip SSL
404     certificate checks, etc.
405    Options are processed in order, and if the same option is passed multiple
406     times, only the value specified by the last occurrence has an effect
407     (unless otherwise specified).
408    They may be expanded in the future.*/
409 /*@{*/
410
411 /*These are the raw numbers used to define the request codes.
412   They should not be used directly.*/
413 #define OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST (6464)
414 #define OP_HTTP_PROXY_HOST_REQUEST            (6528)
415 #define OP_HTTP_PROXY_PORT_REQUEST            (6592)
416 #define OP_HTTP_PROXY_USER_REQUEST            (6656)
417 #define OP_HTTP_PROXY_PASS_REQUEST            (6720)
418
419 #define OP_URL_OPT(_request) ((_request)+(char *)0)
420
421 /*These macros trigger compilation errors or warnings if the wrong types are
422    provided to one of the URL options.*/
423 #define OP_CHECK_INT(_x) ((void)((_x)==(opus_int32)0),(opus_int32)(_x))
424 #define OP_CHECK_CONST_CHAR_PTR(_x) ((_x)+((_x)-(const char *)(_x)))
425
426 /**Skip the certificate check when connecting via TLS/SSL (https).
427    \param _b <code>opus_int32</code>: Whether or not to skip the certificate
428               check.
429              The check will be skipped if \a _b is non-zero, and will not be
430               skipped if \a _b is zero.
431    \hideinitializer*/
432 #define OP_SSL_SKIP_CERTIFICATE_CHECK(_b) \
433  OP_URL_OPT(OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST),OP_CHECK_INT(_b)
434
435 /**Proxy connections through the given host.
436    If no port is specified via #OP_HTTP_PROXY_PORT, the port number defaults
437     to 8080 (http-alt).
438    All proxy parameters are ignored for non-http and non-https URLs.
439    \param _host <code>const char *</code>: The proxy server hostname.
440                 This may be <code>NULL</code> to disable the use of a proxy
441                  server.
442    \hideinitializer*/
443 #define OP_HTTP_PROXY_HOST(_host) \
444  OP_URL_OPT(OP_HTTP_PROXY_HOST_REQUEST),OP_CHECK_CONST_CHAR_PTR(_host)
445
446 /**Use the given port when proxying connections.
447    This option only has an effect if #OP_HTTP_PROXY_HOST is specified with a
448     non-<code>NULL</code> \a _host.
449    If this option is not provided, the proxy port number defaults to 8080
450     (http-alt).
451    All proxy parameters are ignored for non-http and non-https URLs.
452    \param _port <code>opus_int32</code>: The proxy server port.
453                 This must be in the range 0...65535 (inclusive), or the
454                  URL function this is passed to will fail.
455    \hideinitializer*/
456 #define OP_HTTP_PROXY_PORT(_port) \
457  OP_URL_OPT(OP_HTTP_PROXY_PORT_REQUEST),OP_CHECK_INT(_port)
458
459 /**Use the given user name for authentication when proxying connections.
460    All proxy parameters are ignored for non-http and non-https URLs.
461    \param _user const char *: The proxy server user name.
462                               This may be <code>NULL</code> to disable proxy
463                                authentication.
464                               A non-<code>NULL</code> value only has an effect
465                                if #OP_HTTP_PROXY_HOST and #OP_HTTP_PROXY_PASS
466                                are also specified with non-<code>NULL</code>
467                                arguments.
468    \hideinitializer*/
469 #define OP_HTTP_PROXY_USER(_user) \
470  OP_URL_OPT(OP_HTTP_PROXY_USER_REQUEST),OP_CHECK_CONST_CHAR_PTR(_host)
471
472 /**Use the given password for authentication when proxying connections.
473    All proxy parameters are ignored for non-http and non-https URLs.
474    \param _pass const char *: The proxy server password.
475                               This may be <code>NULL</code> to disable proxy
476                                authentication.
477                               A non-<code>NULL</code> value only has an effect
478                                if #OP_HTTP_PROXY_HOST and #OP_HTTP_PROXY_USER
479                                are also specified with non-<code>NULL</code>
480                                arguments.
481    \hideinitializer*/
482 #define OP_HTTP_PROXY_PASS(_pass) \
483  OP_URL_OPT(OP_HTTP_PROXY_PASS_REQUEST),OP_CHECK_CONST_CHAR_PTR(_host)
484
485 /*@}*/
486 /*@}*/
487
488 /**\defgroup stream_callbacks Abstract Stream Reading Interface*/
489 /*@{*/
490 /**\name Functions for reading from streams
491    These functions define the interface used to read from and seek in a stream
492     of data.
493    A stream does not need to implement seeking, but the decoder will not be
494     able to seek if it does not do so.
495    These functions also include some convenience routines for working with
496     standard <code>FILE</code> pointers, complete streams stored in a single
497     block of memory, or URLs.*/
498 /*@{*/
499
500 typedef struct OpusFileCallbacks OpusFileCallbacks;
501
502 /**Reads up to \a _nbytes bytes of data from \a _stream.
503    \param      _stream The stream to read from.
504    \param[out] _ptr    The buffer to store the data in.
505    \param      _nbytes The maximum number of bytes to read.
506                        This function may return fewer, though it will not
507                         return zero unless it reaches end-of-file.
508    \return The number of bytes successfully read, or a negative value on
509             error.*/
510 typedef int (*op_read_func)(void *_stream,unsigned char *_ptr,int _nbytes);
511
512 /**Sets the position indicator for \a _stream.
513    The new position, measured in bytes, is obtained by adding \a _offset
514     bytes to the position specified by \a _whence.
515    If \a _whence is set to <code>SEEK_SET</code>, <code>SEEK_CUR</code>, or
516     <code>SEEK_END</code>, the offset is relative to the start of the stream,
517     the current position indicator, or end-of-file, respectively.
518    \retval 0  Success.
519    \retval -1 Seeking is not supported or an error occurred.
520               <code>errno</code> need not be set.*/
521 typedef int (*op_seek_func)(void *_stream,opus_int64 _offset,int _whence);
522
523 /**Obtains the current value of the position indicator for \a _stream.
524    \return The current position indicator.*/
525 typedef opus_int64 (*op_tell_func)(void *_stream);
526
527 /**Closes the underlying stream.
528    \retval 0   Success.
529    \retval EOF An error occurred.
530                <code>errno</code> need not be set.*/
531 typedef int (*op_close_func)(void *_stream);
532
533 /**The callbacks used to access non-<code>FILE</code> stream resources.
534    The function prototypes are basically the same as for the stdio functions
535     <code>fread()</code>, <code>fseek()</code>, <code>ftell()</code>, and
536     <code>fclose()</code>.
537    The differences are that the <code>FILE *</code> arguments have been
538     replaced with a <code>void *</code>, which is to be used as a pointer to
539     whatever internal data these functions might need, that #seek and #tell
540     take and return 64-bit offsets, and that #seek <em>must</em> return -1 if
541     the stream is unseekable.*/
542 struct OpusFileCallbacks{
543   /**Used to read data from the stream.
544      This must not be <code>NULL</code>.*/
545   op_read_func  read;
546   /**Used to seek in the stream.
547      This may be <code>NULL</code> if seeking is not implemented.*/
548   op_seek_func  seek;
549   /**Used to return the current read position in the stream.
550      This may be <code>NULL</code> if seeking is not implemented.*/
551   op_tell_func  tell;
552   /**Used to close the stream when the decoder is freed.
553      This may be <code>NULL</code> to leave the stream open.*/
554   op_close_func close;
555 };
556
557 /**Opens a stream with <code>fopen()</code> and fills in a set of callbacks
558     that can be used to access it.
559    This is useful to avoid writing your own portable 64-bit seeking wrappers,
560     and also avoids cross-module linking issues on Windows, where a
561     <code>FILE *</code> must be accessed by routines defined in the same module
562     that opened it.
563    \param[out] _cb   The callbacks to use for this file.
564                      If there is an error opening the file, nothing will be
565                       filled in here.
566    \param      _path The path to the file to open.
567    \param      _mode The mode to open the file in.
568    \return A stream handle to use with the callbacks, or <code>NULL</code> on
569             error.*/
570 OP_WARN_UNUSED_RESULT void *op_fopen(OpusFileCallbacks *_cb,
571  const char *_path,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
572  OP_ARG_NONNULL(3);
573
574 /**Opens a stream with <code>fdopen()</code> and fills in a set of callbacks
575     that can be used to access it.
576    This is useful to avoid writing your own portable 64-bit seeking wrappers,
577     and also avoids cross-module linking issues on Windows, where a
578     <code>FILE *</code> must be accessed by routines defined in the same module
579     that opened it.
580    \param[out] _cb   The callbacks to use for this file.
581                      If there is an error opening the file, nothing will be
582                       filled in here.
583    \param      _fd   The file descriptor to open.
584    \param      _mode The mode to open the file in.
585    \return A stream handle to use with the callbacks, or <code>NULL</code> on
586             error.*/
587 OP_WARN_UNUSED_RESULT void *op_fdopen(OpusFileCallbacks *_cb,
588  int _fd,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(3);
589
590 /**Opens a stream with <code>freopen()</code> and fills in a set of callbacks
591     that can be used to access it.
592    This is useful to avoid writing your own portable 64-bit seeking wrappers,
593     and also avoids cross-module linking issues on Windows, where a
594     <code>FILE *</code> must be accessed by routines defined in the same module
595     that opened it.
596    \param[out] _cb     The callbacks to use for this file.
597                        If there is an error opening the file, nothing will be
598                         filled in here.
599    \param      _path   The path to the file to open.
600    \param      _mode   The mode to open the file in.
601    \param      _stream A stream previously returned by op_fopen(), op_fdopen(),
602                         or op_freopen().
603    \return A stream handle to use with the callbacks, or <code>NULL</code> on
604             error.*/
605 OP_WARN_UNUSED_RESULT void *op_freopen(OpusFileCallbacks *_cb,
606  const char *_path,const char *_mode,void *_stream) OP_ARG_NONNULL(1)
607  OP_ARG_NONNULL(2) OP_ARG_NONNULL(3) OP_ARG_NONNULL(4);
608
609 /**Creates a stream that reads from the given block of memory.
610    This block of memory must contain the complete stream to decode.
611    This is useful for caching small streams (e.g., sound effects) in RAM.
612    \param[out] _cb   The callbacks to use for this stream.
613                      If there is an error creating the stream, nothing will be
614                       filled in here.
615    \param      _data The block of memory to read from.
616    \param      _size The size of the block of memory.
617    \return A stream handle to use with the callbacks, or <code>NULL</code> on
618             error.*/
619 OP_WARN_UNUSED_RESULT void *op_mem_stream_create(OpusFileCallbacks *_cb,
620  const unsigned char *_data,size_t _size) OP_ARG_NONNULL(1);
621
622 /**Creates a stream that reads from the given URL.
623    This function behaves identically to op_url_stream_create(), except that it
624     takes a va_list instead of a variable number of arguments.
625    It does not call the <code>va_end</code> macro, and because it invokes the
626     <code>va_arg</code> macro, the value of \a _ap is undefined after the call.
627    \param[out]    _cb  The callbacks to use for this stream.
628                        If there is an error creating the stream, nothing will
629                         be filled in here.
630    \param         _url The URL to read from.
631                        Currently only the <file:>, <http:>, and <https:>
632                         schemes are supported.
633                        Both <http:> and <https:> may be disabled at compile
634                         time, in which case opening such URLs will always fail.
635    \param[in,out] _ap  A list of the \ref url_options "optional flags" to use.
636                        This is a variable-length list of options terminated
637                         with <code>NULL</code>.
638    \return A stream handle to use with the callbacks, or <code>NULL</code> on
639             error.*/
640 OP_WARN_UNUSED_RESULT void *op_url_stream_vcreate(OpusFileCallbacks *_cb,
641  const char *_url,va_list _ap) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
642
643 /**Creates a stream that reads from the given URL using the specified proxy.
644    \param[out] _cb  The callbacks to use for this stream.
645                     If there is an error creating the stream, nothing will be
646                      filled in here.
647    \param      _url The URL to read from.
648                     Currently only the <file:>, <http:>, and <https:> schemes
649                      are supported.
650                     Both <http:> and <https:> may be disabled at compile time,
651                      in which case opening such URLs will always fail.
652    \param      ...  The \ref url_options "optional flags" to use.
653                     This is a variable-length list of options terminated with
654                      <code>NULL</code>.
655    \return A stream handle to use with the callbacks, or <code>NULL</code> on
656             error.*/
657 OP_WARN_UNUSED_RESULT void *op_url_stream_create(OpusFileCallbacks *_cb,
658  const char *_url,...) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
659
660 /*@}*/
661 /*@}*/
662
663 /**\defgroup stream_open_close Opening and Closing*/
664 /*@{*/
665 /**\name Functions for opening and closing streams
666
667    These functions allow you to test a stream to see if it is Opus, open it,
668     and close it.
669    Several flavors are provided for each of the built-in stream types, plus a
670     more general version which takes a set of application-provided callbacks.*/
671 /*@{*/
672
673 /**Test to see if this is an Opus stream.
674    For good results, you will need at least 57 bytes (for a pure Opus-only
675     stream).
676    Something like 512 bytes will give more reliable results for multiplexed
677     streams.
678    This function is meant to be a quick-rejection filter.
679    Its purpose is not to guarantee that a stream is a valid Opus stream, but to
680     ensure that it looks enough like Opus that it isn't going to be recognized
681     as some other format (except possibly an Opus stream that is also
682     multiplexed with other codecs, such as video).
683    \param[out] _head     The parsed ID header contents.
684                          You may pass <code>NULL</code> if you do not need
685                           this information.
686                          If the function fails, the contents of this structure
687                           remain untouched.
688    \param _initial_data  An initial buffer of data from the start of the
689                           stream.
690    \param _initial_bytes The number of bytes in \a _initial_data.
691    \return 0 if the data appears to be Opus, or a negative value on error.
692    \retval #OP_FALSE      There was not enough data to tell if this was an Opus
693                            stream or not.
694    \retval #OP_EFAULT     An internal memory allocation failed.
695    \retval #OP_EIMPL      The stream used a feature that is not implemented,
696                            such as an unsupported channel family.
697    \retval #OP_ENOTFORMAT If the data did not contain a recognizable ID
698                            header for an Opus stream.
699    \retval #OP_EVERSION   If the version field signaled a version this library
700                            does not know how to parse.
701    \retval #OP_EBADHEADER The ID header was not properly formatted or contained
702                            illegal values.*/
703 int op_test(OpusHead *_head,
704  const unsigned char *_initial_data,size_t _initial_bytes);
705
706 /**Open a stream from the given file path.
707    \param      _path  The path to the file to open.
708    \param[out] _error Returns 0 on success, or a failure code on error.
709                       You may pass in <code>NULL</code> if you don't want the
710                        failure code.
711                       The failure code will be #OP_EFAULT if the file could not
712                        be opened, or one of the other failure codes from
713                        op_open_callbacks() otherwise.
714    \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
715 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_file(const char *_path,int *_error)
716  OP_ARG_NONNULL(1);
717
718 /**Open a stream from a memory buffer.
719    \param      _data  The memory buffer to open.
720    \param      _size  The number of bytes in the buffer.
721    \param[out] _error Returns 0 on success, or a failure code on error.
722                       You may pass in <code>NULL</code> if you don't want the
723                        failure code.
724                       See op_open_callbacks() for a full list of failure codes.
725    \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
726 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_memory(const unsigned char *_data,
727  size_t _size,int *_error);
728
729 /**Open a stream from a URL.
730    This function behaves identically to op_open_url(), except that it
731     takes a va_list instead of a variable number of arguments.
732    It does not call the <code>va_end</code> macro, and because it invokes the
733     <code>va_arg</code> macro, the value of \a _ap is undefined after the call.
734    \param         _url   The URL to open.
735                          Currently only the <file:>, <http:>, and <https:>
736                           schemes are supported.
737                          Both <http:> and <https:> may be disabled at compile
738                           time, in which case opening such URLs will always
739                           fail.
740    \param[out]    _error Returns 0 on success, or a failure code on error.
741                          You may pass in <code>NULL</code> if you don't want
742                           the failure code.
743                          See op_open_callbacks() for a full list of failure
744                           codes.
745    \param[in,out] _ap    A list of the \ref url_options "optional flags" to
746                           use.
747                          This is a variable-length list of options terminated
748                           with <code>NULL</code>.
749    \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
750 OP_WARN_UNUSED_RESULT OggOpusFile *op_vopen_url(const char *_url,
751  int *_error,va_list _ap) OP_ARG_NONNULL(1);
752
753 /**Open a stream from a URL.
754    However, this approach will not work for live streams or HTTP/1.0 servers
755     (which do not support Range requets).
756    \param      _url   The URL to open.
757                       Currently only the <file:>, <http:>, and <https:> schemes
758                        are supported.
759                       Both <http:> and <https:> may be disabled at compile
760                        time, in which case opening such URLs will always fail.
761    \param[out] _error Returns 0 on success, or a failure code on error.
762                       You may pass in <code>NULL</code> if you don't want the
763                        failure code.
764                       See op_open_callbacks() for a full list of failure codes.
765    \param      ...    The \ref url_options "optional flags" to use.
766                       This is a variable-length list of options terminated with
767                        <code>NULL</code>.
768    \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
769 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
770  int *_error,...) OP_ARG_NONNULL(1);
771
772 /**Open a stream using the given set of callbacks to access it.
773    \param _source        The stream to read from (e.g., a <code>FILE *</code>).
774    \param _cb            The callbacks with which to access the stream.
775                          <code><a href="#op_read_func">read()</a></code> must
776                           be implemented.
777                          <code><a href="#op_seek_func">seek()</a></code> and
778                           <code><a href="#op_tell_func">tell()</a></code> may
779                           be <code>NULL</code>, or may always return -1 to
780                           indicate a source is unseekable, but if
781                           <code><a href="#op_seek_func">seek()</a></code> is
782                           implemented and succeeds on a particular source, then
783                           <code><a href="#op_tell_func">tell()</a></code> must
784                           also.
785                          <code><a href="#op_close_func">close()</a></code> may
786                           be <code>NULL</code>, but if it is not, it will be
787                           called when the \c OggOpusFile is destroyed by
788                           op_free().
789                          It will not be called if op_open_callbacks() fails
790                           with an error.
791    \param _initial_data  An initial buffer of data from the start of the
792                           stream.
793                          Applications can read some number of bytes from the
794                           start of the stream to help identify this as an Opus
795                           stream, and then provide them here to allow the
796                           stream to be opened, even if it is unseekable.
797    \param _initial_bytes The number of bytes in \a _initial_data.
798                          If the stream is seekable, its current position (as
799                           reported by
800                           <code><a href="#opus_tell_func">tell()</a></code>
801                           at the start of this function) must be equal to
802                           \a _initial_bytes.
803                          Otherwise, seeking to absolute positions will
804                           generate inconsistent results.
805    \param[out] _error    Returns 0 on success, or a failure code on error.
806                          You may pass in <code>NULL</code> if you don't want
807                           the failure code.
808                          The failure code will be one of
809                          <dl>
810                            <dt>#OP_EREAD</dt>
811                            <dd>An underlying read, seek, or tell operation
812                             failed when it should have succeeded, or we failed
813                             to find data in the stream we had seen before.</dd>
814                            <dt>#OP_EFAULT</dt>
815                            <dd>There was a memory allocation failure, or an
816                             internal library error.</dd>
817                            <dt>#OP_EIMPL</dt>
818                            <dd>The stream used a feature that is not
819                             implemented, such as an unsupported channel
820                             family.</dd>
821                            <dt>#OP_EINVAL</dt>
822                            <dd><code><a href="#op_seek_func">seek()</a></code>
823                             was implemented and succeeded on this source, but
824                             <code><a href="#op_tell_func">tell()</a></code>
825                             did not, or the starting position indicator was
826                             not equal to \a _initial_bytes.</dd>
827                            <dt>#OP_ENOTFORMAT</dt>
828                            <dd>The stream contained a link that did not have
829                             any logical Opus streams in it.</dd>
830                            <dt>#OP_EBADHEADER</dt>
831                            <dd>A required header packet was not properly
832                             formatted, contained illegal values, or was missing
833                             altogether.</dd>
834                            <dt>#OP_EVERSION</dt>
835                            <dd>An ID header contained an unrecognized version
836                             number.</dd>
837                            <dt>#OP_EBADLINK</dt>
838                            <dd>We failed to find data we had seen before after
839                             seeking.</dd>
840                            <dt>#OP_EBADTIMESTAMP</dt>
841                            <dd>The first or last timestamp in a link failed
842                             basic validity checks.</dd>
843                          </dl>
844    \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
845 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_source,
846  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
847  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
848
849 /**Partially open a stream from the given file path.
850    \see op_test_callbacks
851    \param      _path  The path to the file to open.
852    \param[out] _error Returns 0 on success, or a failure code on error.
853                       You may pass in <code>NULL</code> if you don't want the
854                        failure code.
855                       The failure code will be #OP_EFAULT if the file could not
856                        be opened, or one of the other failure codes from
857                        op_open_callbacks() otherwise.
858    \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
859 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_file(const char *_path,int *_error)
860  OP_ARG_NONNULL(1);
861
862 /**Partially open a stream from a memory buffer.
863    \see op_test_callbacks
864    \param      _data  The memory buffer to open.
865    \param      _size  The number of bytes in the buffer.
866    \param[out] _error Returns 0 on success, or a failure code on error.
867                       You may pass in <code>NULL</code> if you don't want the
868                        failure code.
869                       See op_open_callbacks() for a full list of failure codes.
870    \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
871 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_memory(const unsigned char *_data,
872  size_t _size,int *_error);
873
874 /**Partially open a stream from a URL.
875    This function behaves identically to op_test_url(), except that it
876     takes a va_list instead of a variable number of arguments.
877    It does not call the <code>va_end</code> macro, and because it invokes the
878     <code>va_arg</code> macro, the value of \a _ap is undefined after the call.
879    \see op_test_url
880    \see op_test_callbacks
881    \param         _url    The URL to open.
882                           Currently only the <file:>, <http:>, and <https:>
883                            schemes are supported.
884                           Both <http:> and <https:> may be disabled at compile
885                            time, in which case opening such URLs will always
886                            fail.
887    \param[out]    _error  Returns 0 on success, or a failure code on error.
888                           You may pass in <code>NULL</code> if you don't want
889                            the failure code.
890                           See op_open_callbacks() for a full list of failure
891                            codes.
892    \param[in,out] _ap     A list of the \ref url_options "optional flags" to
893                            use.
894                           This is a variable-length list of options terminated
895                            with <code>NULL</code>.
896    \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
897 OP_WARN_UNUSED_RESULT OggOpusFile *op_vtest_url(const char *_url,
898  int *_error,va_list _ap) OP_ARG_NONNULL(1);
899
900 /**Partially open a stream from a URL.
901    \see op_test_callbacks
902    \param      _url    The URL to open.
903                        Currently only the <file:>, <http:>, and <https:>
904                         schemes are supported.
905                        Both <http:> and <https:> may be disabled at compile
906                         time, in which case opening such URLs will always fail.
907    \param[out] _error  Returns 0 on success, or a failure code on error.
908                        You may pass in <code>NULL</code> if you don't want the
909                         failure code.
910                        See op_open_callbacks() for a full list of failure
911                         codes.
912    \param      ...     The \ref url_options "optional flags" to use.
913                        This is a variable-length list of options terminated
914                         with <code>NULL</code>.
915    \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
916 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,
917  int *_error,...) OP_ARG_NONNULL(1);
918
919 /**Partially open a stream using the given set of callbacks to access it.
920    This tests for Opusness and loads the headers for the first link.
921    It does not seek (although it tests for seekability).
922    You can query a partially open stream for the few pieces of basic
923     information returned by op_serialno(), op_channel_count(), op_head(), and
924     op_tags() (but only for the first link).
925    You may also determine if it is seekable via a call to op_seekable().
926    You cannot read audio from the stream, seek, get the size or duration,
927     get information from links other than the first one, or even get the total
928     number of links until you finish opening the stream with op_test_open().
929    If you do not need to do any of these things, you can dispose of it with
930     op_free() instead.
931
932    This function is provided mostly to simplify porting existing code that used
933     <tt>libvorbisfile</tt>.
934    For new code, you are likely better off using op_test() instead, which
935     is less resource-intensive, requires less data to succeed, and imposes a
936     hard limit on the amount of data it examines (important for unseekable
937     sources, where all such data must be buffered until you are sure of the
938     stream type).
939    \param _source        The stream to read from (e.g., a <code>FILE *</code>).
940    \param _cb            The callbacks with which to access the stream.
941                          <code><a href="#op_read_func">read()</a></code> must
942                           be implemented.
943                          <code><a href="#op_seek_func">seek()</a></code> and
944                           <code><a href="#op_tell_func">tell()</a></code> may
945                           be <code>NULL</code>, or may always return -1 to
946                           indicate a source is unseekable, but if
947                           <code><a href="#op_seek_func">seek()</a></code> is
948                           implemented and succeeds on a particular source, then
949                           <code><a href="#op_tell_func">tell()</a></code> must
950                           also.
951                          <code><a href="#op_close_func">close()</a></code> may
952                           be <code>NULL</code>, but if it is not, it will be
953                           called when the \c OggOpusFile is destroyed by
954                           op_free().
955                          It will not be called if op_open_callbacks() fails
956                           with an error.
957    \param _initial_data  An initial buffer of data from the start of the
958                           stream.
959                          Applications can read some number of bytes from the
960                           start of the stream to help identify this as an Opus
961                           stream, and then provide them here to allow the
962                           stream to be tested more thoroughly, even if it is
963                           unseekable.
964    \param _initial_bytes The number of bytes in \a _initial_data.
965                          If the stream is seekable, its current position (as
966                           reported by
967                           <code><a href="#opus_tell_func">tell()</a></code>
968                           at the start of this function) must be equal to
969                           \a _initial_bytes.
970                          Otherwise, seeking to absolute positions will
971                           generate inconsistent results.
972    \param[out] _error    Returns 0 on success, or a failure code on error.
973                          You may pass in <code>NULL</code> if you don't want
974                           the failure code.
975                          See op_open_callbacks() for a full list of failure
976                           codes.
977    \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
978 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_source,
979  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
980  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
981
982 /**Finish opening a stream partially opened with op_test_callbacks() or one of
983     the associated convenience functions.
984    If this function fails, you are still responsible for freeing the
985     \c OggOpusFile with op_free().
986    \param _of The \c OggOpusFile to finish opening.
987    \return 0 on success, or a negative value on error.
988    \retval #OP_EREAD         An underlying read, seek, or tell operation failed
989                               when it should have succeeded.
990    \retval #OP_EFAULT        There was a memory allocation failure, or an
991                               internal library error.
992    \retval #OP_EIMPL         The stream used a feature that is not implemented,
993                               such as an unsupported channel family.
994    \retval #OP_EINVAL        The stream was not partially opened with
995                               op_test_callbacks() or one of the associated
996                               convenience functions.
997    \retval #OP_ENOTFORMAT    The stream contained a link that did not have any
998                               logical Opus streams in it.
999    \retval #OP_EBADHEADER    A required header packet was not properly
1000                               formatted, contained illegal values, or was
1001                               missing altogether.
1002    \retval #OP_EVERSION      An ID header contained an unrecognized version
1003                               number.
1004    \retval #OP_EBADLINK      We failed to find data we had seen before after
1005                               seeking.
1006    \retval #OP_EBADTIMESTAMP The first or last timestamp in a link failed basic
1007                               validity checks.*/
1008 int op_test_open(OggOpusFile *_of) OP_ARG_NONNULL(1);
1009
1010 /**Release all memory used by an \c OggOpusFile.
1011    \param _of The \c OggOpusFile to free.*/
1012 void op_free(OggOpusFile *_of);
1013
1014 /*@}*/
1015 /*@}*/
1016
1017 /**\defgroup stream_info Stream Information*/
1018 /*@{*/
1019 /**\name Functions for obtaining information about streams
1020
1021    These functions allow you to get basic information about a stream, including
1022     seekability, the number of links (for chained streams), plus the size,
1023     duration, bitrate, header parameters, and meta information for each link
1024     (or, where available, the stream as a whole).
1025    Some of these (size, duration) are only available for seekable streams.
1026    You can also query the current stream position, link, and playback time,
1027     and instantaneous bitrate during playback.
1028
1029    Some of these functions may be used successfully on the partially open
1030     streams returned by op_test_callbacks() or one of the associated
1031     convenience functions.
1032    Their documention will indicate so explicitly.*/
1033 /*@{*/
1034
1035 /**Returns whether or not the data source being read is seekable.
1036    This is true if
1037    <ol>
1038    <li>The <code><a href="#op_seek_func">seek()</a></code> and
1039     <code><a href="#op_tell_func">tell()</a></code> callbacks are both
1040     non-<code>NULL</code>,</li>
1041    <li>The <code><a href="#op_seek_func">seek()</a></code> callback was
1042     successfully executed at least once, and</li>
1043    <li>The <code><a href="#op_tell_func">tell()</a></code> callback was
1044     successfully able to report the position indicator afterwards.</li>
1045    </ol>
1046    This function may be called on partially-opened streams.
1047    \param _of The \c OggOpusFile whose seekable status is to be returned.
1048    \return A non-zero value if seekable, and 0 if unseekable.*/
1049 int op_seekable(OggOpusFile *_of) OP_ARG_NONNULL(1);
1050
1051 /**Returns the number of links in this chained stream.
1052    This function may be called on partially-opened streams, but it will always
1053     return 1.
1054    The actual number of links is not known until the stream is fully opened.
1055    \param _of The \c OggOpusFile from which to retrieve the link count.
1056    \return For fully-open seekable sources, this returns the total number of
1057             links in the whole stream.
1058            For partially-open or unseekable sources, this always returns 1.*/
1059 int op_link_count(OggOpusFile *_of) OP_ARG_NONNULL(1);
1060
1061 /**Get the serial number of the given link in a (possibly-chained) Ogg Opus
1062     stream.
1063    This function may be called on partially-opened streams, but it will always
1064     return the serial number of the Opus stream in the first link.
1065    \param _of The \c OggOpusFile from which to retrieve the serial number.
1066    \param _li The index of the link whose serial number should be retrieved.
1067               Use a negative number to get the serial number of the current
1068                link.
1069    \return The serial number of the given link.
1070            If \a _li is greater than the total number of links, this returns
1071             the serial number of the last link.
1072            If the source is not seekable, this always returns the serial number
1073             of the current link.*/
1074 opus_uint32 op_serialno(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1075
1076 /**Get the channel count of the given link in a (possibly-chained) Ogg Opus
1077     stream.
1078    This is equivalent to <code>op_head(_of,_li)->channel_count</code>, but
1079     is provided for convenience.
1080    This function may be called on partially-opened streams, but it will always
1081     return the channel count of the Opus stream in the first link.
1082    \param _of The \c OggOpusFile from which to retrieve the channel count.
1083    \param _li The index of the link whose channel count should be retrieved.
1084               Use a negative number to get the channel count of the current
1085                link.
1086    \return The channel count of the given link.
1087            If \a _li is greater than the total number of links, this returns
1088             the channel count of the last link.
1089            If the source is not seekable, this always returns the channel count
1090             of the current link.*/
1091 int op_channel_count(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1092
1093 /**Get the total (compressed) size of the stream, or of an individual link in
1094     a (possibly-chained) Ogg Opus stream, including all headers and Ogg muxing
1095     overhead.
1096    \param _of The \c OggOpusFile from which to retrieve the compressed size.
1097    \param _li The index of the link whose compressed size should be computed.
1098               Use a negative number to get the compressed size of the entire
1099                stream.
1100    \return The compressed size of the entire stream if \a _li is negative, the
1101             compressed size of link \a _li if it is non-negative, or a negative
1102             value on error.
1103            The compressed size of the entire stream may be smaller than that
1104             of the underlying source if trailing garbage was detected in the
1105             file.
1106    \retval #OP_EINVAL The source is not seekable (so we can't know the length),
1107                        \a _li wasn't less than the total number of links in
1108                        the stream, or the stream was only partially open.*/
1109 opus_int64 op_raw_total(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1110
1111 /**Get the total PCM length (number of samples at 48 kHz) of the stream, or of
1112     an individual link in a (possibly-chained) Ogg Opus stream.
1113    Users looking for <code>op_time_total()</code> should use op_pcm_total()
1114     instead.
1115    Because timestamps in Opus are fixed at 48 kHz, there is no need for a
1116     separate function to convert this to seconds (and leaving it out avoids
1117     introducing floating point to the API, for those that wish to avoid it).
1118    \param _of The \c OggOpusFile from which to retrieve the PCM offset.
1119    \param _li The index of the link whose PCM length should be computed.
1120               Use a negative number to get the PCM length of the entire stream.
1121    \return The PCM length of the entire stream if \a _li is negative, the PCM
1122             length of link \a _li if it is non-negative, or a negative value on
1123             error.
1124    \retval #OP_EINVAL The source is not seekable (so we can't know the length),
1125                        \a _li wasn't less than the total number of links in
1126                        the stream, or the stream was only partially open.*/
1127 ogg_int64_t op_pcm_total(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1128
1129 /**Get the ID header information for the given link in a (possibly chained) Ogg
1130     Opus stream.
1131    This function may be called on partially-opened streams, but it will always
1132     return the ID header information of the Opus stream in the first link.
1133    \param _of The \c OggOpusFile from which to retrieve the ID header
1134                information.
1135    \param _li The index of the link whose ID header information should be
1136                retrieved.
1137               Use a negative number to get the ID header information of the
1138                current link.
1139               For an unseekable stream, \a _li is ignored, and the ID header
1140                information for the current link is always returned, if
1141                available.
1142    \return The contents of the ID header for the given link.*/
1143 const OpusHead *op_head(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1144
1145 /**Get the comment header information for the given link in a (possibly
1146     chained) Ogg Opus stream.
1147    This function may be called on partially-opened streams, but it will always
1148     return the tags from the Opus stream in the first link.
1149    \param _of The \c OggOpusFile from which to retrieve the comment header
1150                information.
1151    \param _li The index of the link whose comment header information should be
1152                retrieved.
1153               Use a negative number to get the comment header information of
1154                the current link.
1155               For an unseekable stream, \a _li is ignored, and the comment
1156                header information for the current link is always returned, if
1157                available.
1158    \return The contents of the comment header for the given link, or
1159             <code>NULL</code> if this is an unseekable stream that encountered
1160             an invalid link.*/
1161 const OpusTags *op_tags(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1162
1163 /**Retrieve the index of the current link.
1164    This is the link that produced the data most recently read by
1165     op_read_float() or its associated functions, or, after a seek, the link
1166     that the seek target landed in.
1167    Reading more data may advance the link index (even on the first read after a
1168     seek).
1169    \param _of The \c OggOpusFile from which to retrieve the current link index.
1170    \return The index of the current link on success, or a negative value on
1171             failure.
1172            For seekable streams, this is a number between 0 and the value
1173             returned by op_link_count().
1174            For unseekable streams, this value starts at 0 and increments by one
1175             each time a new link is encountered (even though op_link_count()
1176             always returns 1).
1177    \retval #OP_EINVAL The stream was only partially open.*/
1178 int op_current_link(OggOpusFile *_of) OP_ARG_NONNULL(1);
1179
1180 /**Computes the bitrate for a given link in a (possibly chained) Ogg Opus
1181     stream.
1182    The stream must be seekable to compute the bitrate.
1183    For unseekable streams, use op_bitrate_instant() to get periodic estimates.
1184    \param _of The \c OggOpusFile from which to retrieve the bitrate.
1185    \param _li The index of the link whose bitrate should be computed.
1186               USe a negative number to get the bitrate of the whole stream.
1187    \return The bitrate on success, or a negative value on error.
1188    \retval #OP_EINVAL The stream was only partially open, the stream was not
1189                        seekable, or \a _li was larger than the number of
1190                        links.*/
1191 opus_int32 op_bitrate(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1192
1193 /**Compute the instantaneous bitrate, measured as the ratio of bits to playable
1194     samples decoded since a) the last call to op_bitrate_instant(), b) the last
1195     seek, or c) the start of playback, whichever was most recent.
1196    This will spike somewhat after a seek or at the start/end of a chain
1197     boundary, as pre-skip, pre-roll, and end-trimming causes samples to be
1198     decoded but not played.
1199    \param _of The \c OggOpusFile from which to retrieve the bitrate.
1200    \return The bitrate, in bits per second, or a negative value on error.
1201    \retval #OP_FALSE  No data has been decoded since any of the events
1202                        described above.
1203    \retval #OP_EINVAL The stream was only partially open.*/
1204 opus_int32 op_bitrate_instant(OggOpusFile *_of) OP_ARG_NONNULL(1);
1205
1206 /**Obtain the current value of the position indicator for \a _of.
1207    \param _of The \c OggOpusFile from which to retrieve the position indicator.
1208    \return The byte position that is currently being read from.
1209    \retval #OP_EINVAL The stream was only partially open.*/
1210 opus_int64 op_raw_tell(OggOpusFile *_of) OP_ARG_NONNULL(1);
1211
1212 /**Obtain the PCM offset of the next sample to be read.
1213    If the stream is not properly timestamped, this might not increment by the
1214     proper amount between reads, or even return monotonically increasing
1215     values.
1216    \param _of The \c OggOpusFile from which to retrieve the PCM offset.
1217    \return The PCM offset of the next sample to be read.
1218    \retval #OP_EINVAL The stream was only partially open.*/
1219 ogg_int64_t op_pcm_tell(OggOpusFile *_of) OP_ARG_NONNULL(1);
1220
1221 /*@}*/
1222 /*@}*/
1223
1224 /**\defgroup stream_seeking Seeking*/
1225 /*@{*/
1226 /**\name Functions for seeking in Opus streams
1227
1228    These functions let you seek in Opus streams, if the underlying source
1229     support it.
1230    Seeking is implemented for all built-in stream I/O routines, though some
1231     individual sources may not be seekable (pipes, live HTTP streams, or HTTP
1232     streams from a server that does not support <code>Range</code> requests).
1233
1234    op_raw_seek() is the fastest: it is guaranteed to perform at most one
1235     physical seek, but, since the target is a byte position, makes no guarantee
1236     how close to a given time it will come.
1237    op_pcm_seek() provides sample-accurate seeking.
1238    The number of physical seeks it requires is still quite small (often 1 or
1239     2, even in highly variable bitrate streams).
1240
1241    Seeking in Opus requires decoding some pre-roll amount before playback to
1242     allow the internal state to converge (as if recovering from packet loss).
1243    This is handled internally by <tt>libopusfile</tt>, but means there is
1244     little extra overhead for decoding up to the exact position requested
1245     (since it must decode some amount of audio anyway).
1246    It also means that decoding after seeking may not return exactly the same
1247     values as would be obtained by decoding the stream straight through.
1248    However, such differences are expected to be smaller than the loss
1249     introduced by Opus's lossy compression.*/
1250 /*@{*/
1251
1252 /**Seek to a byte offset relative to the <b>compressed</b> data.
1253    This also scans packets to update the PCM cursor.
1254    It will cross a logical bitstream boundary, but only if it can't get any
1255     packets out of the tail of the link to which it seeks.
1256    \param _of          The \c OggOpusFile in which to seek.
1257    \param _byte_offset The byte position to seek to.
1258    \return 0 on success, or a negative error code on failure.
1259    \retval #OP_EREAD    The underlying seek operation failed.
1260    \retval #OP_EINVAL   The stream was only partially open, or the target was
1261                          outside the valid range for the stream.
1262    \retval #OP_ENOSEEK  This stream is not seekable.
1263    \retval #OP_EBADLINK Failed to initialize a decoder for a stream for an
1264                          unknown reason.*/
1265 int op_raw_seek(OggOpusFile *_of,opus_int64 _byte_offset) OP_ARG_NONNULL(1);
1266
1267 /**Seek to the specified PCM offset, such that decoding will begin at exactly
1268     the requested position.
1269    \param _of         The \c OggOpusFile in which to seek.
1270    \param _pcm_offset The PCM offset to seek to.
1271                       This is in samples at 48 kHz relative to the start of the
1272                        stream.
1273    \return 0 on success, or a negative value on error.
1274    \retval #OP_EREAD    An underlying read or seek operation failed.
1275    \retval #OP_EINVAL   The stream was only partially open, or the target was
1276                          outside the valid range for the stream.
1277    \retval #OP_ENOSEEK  This stream is not seekable.
1278    \retval #OP_EBADLINK We failed to find data we had seen before, or the
1279                          bitstream structure was sufficiently malformed that
1280                          seeking to the target destination was impossible.*/
1281 int op_pcm_seek(OggOpusFile *_of,ogg_int64_t _pcm_offset) OP_ARG_NONNULL(1);
1282
1283 /*@}*/
1284 /*@}*/
1285
1286 /**\defgroup stream_decoding Decoding*/
1287 /*@{*/
1288 /**\name Functions for decoding audio data
1289
1290    These functions retrieve actual decoded audio data from the stream.
1291    The general functions, op_read() and op_read_float() return 16-bit or
1292     floating-point output, both using native endian ordering.
1293    The number of channels returned can change from link to link in a chained
1294     stream.
1295    There are special functions, op_read_stereo() and op_read_float_stereo(),
1296     which always output two channels, to simplify applications which do not
1297     wish to handle multichannel audio.
1298    These downmix multichannel files to two channels, so they can always return
1299     samples in the same format for every link in a chained file.
1300
1301    If the rest of your audio processing chain can handle floating point, those
1302     routines should be preferred, as floating point output avoids introducing
1303     clipping and other issues which might be avoided entirely if, e.g., you
1304     scale down the volume at some other stage.
1305    However, if you intend to direct consume 16-bit samples, the conversion in
1306     <tt>libopusfile</tt> provides noise-shaping dithering API.
1307
1308    <tt>libopusfile</tt> can also be configured at compile time to use the
1309     fixed-point <tt>libopus</tt> API.
1310    If so, the floating-point API may also be disabled.
1311    In that configuration, nothing in <tt>libopusfile</tt> will use any
1312     floating-point operations, to simplify support on devices without an
1313     adequate FPU.
1314
1315    \warning HTTPS streams may be be vulnerable to truncation attacks if you do
1316     not check the error return code from op_read_float() or its associated
1317     functions.
1318    If the remote peer does not close the connection gracefully (with a TLS
1319     "close notify" message), these functions will return OP_EREAD instead of 0
1320     when they reach the end of the file.
1321    If you are reading from an <https:> URL (particularly if seeking is not
1322     supported), you should make sure to check for this error and warn the user
1323     appropriately.*/
1324 /*@{*/
1325
1326 /**Reads more samples from the stream.
1327    \note Although \a _buf_size must indicate the total number of values that
1328     can be stored in \a _pcm, the return value is the number of samples
1329     <em>per channel</em>.
1330    This is done because
1331    <ol>
1332    <li>The channel count cannot be known a prior (reading more samples might
1333         advance us into the next link, with a different channel count), so
1334         \a _buf_size cannot also be in units of samples per channel,</li>
1335    <li>Returning the samples per channel matches the <code>libopus</code> API
1336         as closely as we're able,</li>
1337    <li>Returning the total number of values instead of samples per channel
1338         would mean the caller would need a division to compute the samples per
1339         channel, and might worry about the possibility of getting back samples
1340         for some channels and not others, and</li>
1341    <li>This approach is relatively fool-proof: if an application passes too
1342         small a value to \a _buf_size, they will simply get fewer samples back,
1343         and if they assume the return value is the total number of values, then
1344         they will simply read too few (rather than reading too many and going
1345         off the end of the buffer).</li>
1346    </ol>
1347    \param      _of       The \c OggOpusFile from which to read.
1348    \param[out] _pcm      A buffer in which to store the output PCM samples, as
1349                           signed native-endian 16-bit values with a nominal
1350                           range of <code>[-32768,32767)</code>.
1351                          Multiple channels are interleaved using the
1352                           <a href="http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-800004.3.9">Vorbis
1353                           channel ordering</a>.
1354                          This must have room for at least \a _buf_size values.
1355    \param      _buf_size The number of values that can be stored in \a _pcm.
1356                          It is recommended that this be large enough for at
1357                           least 120 ms of data at 48 kHz per channel (5760
1358                           values per channel).
1359                          Smaller buffers will simply return less data, possibly
1360                           consuming more memory to buffer the data internally.
1361                          <tt>libopusfile</tt> may return less data than
1362                           requested.
1363                          If so, there is no guarantee that the remaining data
1364                           in \a _pcm will be unmodified.
1365    \param[out] _li       The index of the link this data was decoded from.
1366                          You may pass <code>NULL</code> if you do not need this
1367                           information.
1368                          If this function fails (returning a negative value),
1369                           this parameter is left unset.
1370    \return The number of samples read per channel on success, or a negative
1371             value on failure.
1372            The channel count can be retrieved on success by calling
1373             <code>op_head(_of,*_li)</code>.
1374            The number of samples returned may be 0 if the buffer was too small
1375             to store even a single sample for all channels, or if end-of-file
1376             was reached.
1377            The list of possible failure codes follows.
1378            Most of them can only be returned by unseekable, chained streams
1379             that encounter a new link.
1380    \retval #OP_HOLE          There was a hole in the data, and some samples
1381                               may have been skipped.
1382                              Call this function again to continue decoding
1383                               past the hole.
1384    \retval #OP_EREAD         An underlying read operation failed.
1385                              This may signal a truncation attack from an
1386                               <https:> source.
1387    \retval #OP_EFAULT        An internal memory allocation failed.
1388    \retval #OP_EIMPL         An unseekable stream encountered a new link that
1389                               used a feature that is not implemented, such as
1390                               an unsupported channel family.
1391    \retval #OP_EINVAL        The stream was only partially open.
1392    \retval #OP_ENOTFORMAT    An unseekable stream encountered a new link that
1393                               did not have any logical Opus streams in it.
1394    \retval #OP_EBADHEADER    An unseekable stream encountered a new link with a
1395                               required header packet that was not properly
1396                               formatted, contained illegal values, or was
1397                               missing altogether.
1398    \retval #OP_EVERSION      An unseekable stream encountered a new link with
1399                               an ID header that contained an unrecognized
1400                               version number.
1401    \retval #OP_EBADPACKET    Failed to properly decode the next packet.
1402    \retval #OP_EBADLINK      We failed to find data we had seen before.
1403    \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
1404                               a starting timestamp that failed basic validity
1405                               checks.*/
1406 OP_WARN_UNUSED_RESULT int op_read(OggOpusFile *_of,
1407  opus_int16 *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
1408
1409 /**Reads more samples from the stream.
1410    \note Although \a _buf_size must indicate the total number of values that
1411     can be stored in \a _pcm, the return value is the number of samples
1412     <em>per channel</em>.
1413    <ol>
1414    <li>The channel count cannot be known a prior (reading more samples might
1415         advance us into the next link, with a different channel count), so
1416         \a _buf_size cannot also be in units of samples per channel,</li>
1417    <li>Returning the samples per channel matches the <code>libopus</code> API
1418         as closely as we're able,</li>
1419    <li>Returning the total number of values instead of samples per channel
1420         would mean the caller would need a division to compute the samples per
1421         channel, and might worry about the possibility of getting back samples
1422         for some channels and not others, and</li>
1423    <li>This approach is relatively fool-proof: if an application passes too
1424         small a value to \a _buf_size, they will simply get fewer samples back,
1425         and if they assume the return value is the total number of values, then
1426         they will simply read too few (rather than reading too many and going
1427         off the end of the buffer).</li>
1428    </ol>
1429    \param      _of       The \c OggOpusFile from which to read.
1430    \param[out] _pcm      A buffer in which to store the output PCM samples as
1431                           signed floats with a nominal range of
1432                           <code>[-1.0,1.0]</code>.
1433                          Multiple channels are interleaved using the
1434                           <a href="http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-800004.3.9">Vorbis
1435                           channel ordering</a>.
1436                          This must have room for at least \a _buf_size floats.
1437    \param      _buf_size The number of floats that can be stored in \a _pcm.
1438                          It is recommended that this be large enough for at
1439                           least 120 ms of data at 48 kHz per channel (5760
1440                           samples per channel).
1441                          Smaller buffers will simply return less data, possibly
1442                           consuming more memory to buffer the data internally.
1443                          If less than \a _buf_size values are returned,
1444                           <tt>libopusfile</tt> makes no guarantee that the
1445                           remaining data in \a _pcm will be unmodified.
1446    \param[out] _li       The index of the link this data was decoded from.
1447                          You may pass <code>NULL</code> if you do not need this
1448                           information.
1449                          If this function fails (returning a negative value),
1450                           this parameter is left unset.
1451    \return The number of samples read per channel on success, or a negative
1452             value on failure.
1453            The channel count can be retrieved on success by calling
1454             <code>op_head(_of,*_li)</code>.
1455            The number of samples returned may be 0 if the buffer was too small
1456             to store even a single sample for all channels, or if end-of-file
1457             was reached.
1458            The list of possible failure codes follows.
1459            Most of them can only be returned by unseekable, chained streams
1460             that encounter a new link.
1461    \retval #OP_HOLE          There was a hole in the data, and some samples
1462                               may have been skipped.
1463                              Call this function again to continue decoding
1464                               past the hole.
1465    \retval #OP_EREAD         An underlying read operation failed.
1466                              This may signal a truncation attack from an
1467                               <https:> source.
1468    \retval #OP_EFAULT        An internal memory allocation failed.
1469    \retval #OP_EIMPL         An unseekable stream encountered a new link that
1470                               used a feature that is not implemented, such as
1471                               an unsupported channel family.
1472    \retval #OP_EINVAL        The stream was only partially open.
1473    \retval #OP_ENOTFORMAT    An unseekable stream encountered a new link that
1474                               did not have any logical Opus streams in it.
1475    \retval #OP_EBADHEADER    An unseekable stream encountered a new link with a
1476                               required header packet that was not properly
1477                               formatted, contained illegal values, or was
1478                               missing altogether.
1479    \retval #OP_EVERSION      An unseekable stream encountered a new link with
1480                               an ID header that contained an unrecognized
1481                               version number.
1482    \retval #OP_EBADPACKET    Failed to properly decode the next packet.
1483    \retval #OP_EBADLINK      We failed to find data we had seen before.
1484    \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
1485                               a starting timestamp that failed basic validity
1486                               checks.*/
1487 OP_WARN_UNUSED_RESULT int op_read_float(OggOpusFile *_of,
1488  float *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
1489
1490 /**Reads more samples from the stream and downmixes to stereo, if necessary.
1491    This function is intended for simple players that want a uniform output
1492     format, even if the channel count changes between links in a chained
1493     stream.
1494    \note \a _buf_size indicates the total number of values that can be stored
1495     in \a _pcm, while the return value is the number of samples <em>per
1496     channel</em>, even though the channel count is known, for consistency with
1497     op_read().
1498    \param      _of       The \c OggOpusFile from which to read.
1499    \param[out] _pcm      A buffer in which to store the output PCM samples, as
1500                           signed native-endian 16-bit values with a nominal
1501                           range of <code>[-32768,32767)</code>.
1502                          The left and right channels are interleaved in the
1503                           buffer.
1504                          This must have room for at least \a _buf_size values.
1505    \param      _buf_size The number of values that can be stored in \a _pcm.
1506                          It is recommended that this be large enough for at
1507                           least 120 ms of data at 48 kHz per channel (11520
1508                           values total).
1509                          Smaller buffers will simply return less data, possibly
1510                           consuming more memory to buffer the data internally.
1511                          If less than \a _buf_size values are returned,
1512                           <tt>libopusfile</tt> makes no guarantee that the
1513                           remaining data in \a _pcm will be unmodified.
1514    \return The number of samples read per channel on success, or a negative
1515             value on failure.
1516            The number of samples returned may be 0 if the buffer was too small
1517             to store even a single sample for both channels, or if end-of-file
1518             was reached.
1519            The list of possible failure codes follows.
1520            Most of them can only be returned by unseekable, chained streams
1521             that encounter a new link.
1522    \retval #OP_HOLE          There was a hole in the data, and some samples
1523                               may have been skipped.
1524                              Call this function again to continue decoding
1525                               past the hole.
1526    \retval #OP_EREAD         An underlying read operation failed.
1527                              This may signal a truncation attack from an
1528                               <https:> source.
1529    \retval #OP_EFAULT        An internal memory allocation failed.
1530    \retval #OP_EIMPL         An unseekable stream encountered a new link that
1531                               used a feature that is not implemented, such as
1532                               an unsupported channel family.
1533    \retval #OP_EINVAL        The stream was only partially open.
1534    \retval #OP_ENOTFORMAT    An unseekable stream encountered a new link that
1535                               did not have any logical Opus streams in it.
1536    \retval #OP_EBADHEADER    An unseekable stream encountered a new link with a
1537                               required header packet that was not properly
1538                               formatted, contained illegal values, or was
1539                               missing altogether.
1540    \retval #OP_EVERSION      An unseekable stream encountered a new link with
1541                               an ID header that contained an unrecognized
1542                               version number.
1543    \retval #OP_EBADPACKET    Failed to properly decode the next packet.
1544    \retval #OP_EBADLINK      We failed to find data we had seen before.
1545    \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
1546                               a starting timestamp that failed basic validity
1547                               checks.*/
1548 OP_WARN_UNUSED_RESULT int op_read_stereo(OggOpusFile *_of,
1549  opus_int16 *_pcm,int _buf_size) OP_ARG_NONNULL(1);
1550
1551 /**Reads more samples from the stream and downmixes to stereo, if necessary.
1552    This function is intended for simple players that want a uniform output
1553     format, even if the channel count changes between links in a chained
1554     stream.
1555    \note \a _buf_size indicates the total number of values that can be stored
1556     in \a _pcm, while the return value is the number of samples <em>per
1557     channel</em>, even though the channel count is known, for consistency with
1558     op_read_float().
1559    \param      _of       The \c OggOpusFile from which to read.
1560    \param[out] _pcm      A buffer in which to store the output PCM samples, as
1561                           signed floats with a nominal range of
1562                           <code>[-1.0,1.0]</code>.
1563                          The left and right channels are interleaved in the
1564                           buffer.
1565                          This must have room for at least \a _buf_size values.
1566    \param      _buf_size The number of values that can be stored in \a _pcm.
1567                          It is recommended that this be large enough for at
1568                           least 120 ms of data at 48 kHz per channel (11520
1569                           values total).
1570                          Smaller buffers will simply return less data, possibly
1571                           consuming more memory to buffer the data internally.
1572                          If less than \a _buf_size values are returned,
1573                           <tt>libopusfile</tt> makes no guarantee that the
1574                           remaining data in \a _pcm will be unmodified.
1575    \return The number of samples read per channel on success, or a negative
1576             value on failure.
1577            The number of samples returned may be 0 if the buffer was too small
1578             to store even a single sample for both channels, or if end-of-file
1579             was reached.
1580            The list of possible failure codes follows.
1581            Most of them can only be returned by unseekable, chained streams
1582             that encounter a new link.
1583    \retval #OP_HOLE          There was a hole in the data, and some samples
1584                               may have been skipped.
1585                              Call this function again to continue decoding
1586                               past the hole.
1587    \retval #OP_EREAD         An underlying read operation failed.
1588                              This may signal a truncation attack from an
1589                               <https:> source.
1590    \retval #OP_EFAULT        An internal memory allocation failed.
1591    \retval #OP_EIMPL         An unseekable stream encountered a new link that
1592                               used a feature that is not implemented, such as
1593                               an unsupported channel family.
1594    \retval #OP_EINVAL        The stream was only partially open.
1595    \retval #OP_ENOTFORMAT    An unseekable stream encountered a new link that
1596                               that did not have any logical Opus streams in it.
1597    \retval #OP_EBADHEADER    An unseekable stream encountered a new link with a
1598                               required header packet that was not properly
1599                               formatted, contained illegal values, or was
1600                               missing altogether.
1601    \retval #OP_EVERSION      An unseekable stream encountered a new link with
1602                               an ID header that contained an unrecognized
1603                               version number.
1604    \retval #OP_EBADPACKET    Failed to properly decode the next packet.
1605    \retval #OP_EBADLINK      We failed to find data we had seen before.
1606    \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
1607                               a starting timestamp that failed basic validity
1608                               checks.*/
1609 OP_WARN_UNUSED_RESULT int op_read_float_stereo(OggOpusFile *_of,
1610  float *_pcm,int _buf_size) OP_ARG_NONNULL(1);
1611
1612 /*@}*/
1613 /*@}*/
1614
1615 # if OP_GNUC_PREREQ(4,0)
1616 #  pragma GCC visibility pop
1617 # endif
1618
1619 # if defined(__cplusplus)
1620 }
1621 # endif
1622
1623 #endif