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