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