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 https://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://opus-codec.org/docs/opus_api-1.3.1/">libopus</a></tt>
32 libraries.
33
34 <tt>libopusfile</tt> provides several 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 \section Overview
55
56 The <tt>libopusfile</tt> API always decodes files to 48&nbsp;kHz.
57 The original sample rate is not preserved by the lossy compression, though
58 it is stored in the header to allow you to resample to it after decoding
59 (the <tt>libopusfile</tt> API does not currently provide a resampler,
60 but the
61 <a href="https://www.speex.org/docs/manual/speex-manual/node7.html#SECTION00760000000000000000">the
62 Speex resampler</a> is a good choice if you need one).
63 In general, if you are playing back the audio, you should leave it at
64 48&nbsp;kHz, provided your audio hardware supports it.
65 When decoding to a file, it may be worth resampling back to the original
66 sample rate, so as not to surprise users who might not expect the sample
67 rate to change after encoding to Opus and decoding.
68
69 Opus files can contain anywhere from 1 to 255 channels of audio.
70 The channel mappings for up to 8 channels are the same as the
71 <a href="https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-810004.3.9">Vorbis
72 mappings</a>.
73 A special stereo API can convert everything to 2 channels, making it simple
74 to support multichannel files in an application which only has stereo
75 output.
76 Although the <tt>libopusfile</tt> ABI provides support for the theoretical
77 maximum number of channels, the current implementation does not support
78 files with more than 8 channels, as they do not have well-defined channel
79 mappings.
80
81 Like all Ogg files, Opus files may be "chained".
82 That is, multiple Opus files may be combined into a single, longer file just
83 by concatenating the original files.
84 This is commonly done in internet radio streaming, as it allows the title
85 and artist to be updated each time the song changes, since each link in the
86 chain includes its own set of metadata.
87
88 <tt>libopusfile</tt> fully supports chained files.
89 It will decode the first Opus stream found in each link of a chained file
90 (ignoring any other streams that might be concurrently multiplexed with it,
91 such as a video stream).
92
93 The channel count can also change between links.
94 If your application is not prepared to deal with this, it can use the stereo
95 API to ensure the audio from all links will always get decoded into a
96 common format.
97 Since <tt>libopusfile</tt> always decodes to 48&nbsp;kHz, you do not have to
98 worry about the sample rate changing between links (as was possible with
99 Vorbis).
100 This makes application support for chained files with <tt>libopusfile</tt>
101 very easy.*/
102
103# if defined(__cplusplus)
104extern "C" {
105# endif
106
107# include <stdarg.h>
108# include <stdio.h>
109# include <ogg/ogg.h>
110# include <opus_multistream.h>
111
112/**@cond PRIVATE*/
113
114/*Enable special features for gcc and gcc-compatible compilers.*/
115# if !defined(OP_GNUC_PREREQ)
116# if defined(__GNUC__)&&defined(__GNUC_MINOR__)
117# define OP_GNUC_PREREQ(_maj,_min) \
118 ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min))
119# else
120# define OP_GNUC_PREREQ(_maj,_min) 0
121# endif
122# endif
123
124# if OP_GNUC_PREREQ(4,0)
125# pragma GCC visibility push(default)
126# endif
127
128typedef struct OpusHead OpusHead;
129typedef struct OpusTags OpusTags;
130typedef struct OpusPictureTag OpusPictureTag;
131typedef struct OpusServerInfo OpusServerInfo;
132typedef struct OpusFileCallbacks OpusFileCallbacks;
133typedef struct OggOpusFile OggOpusFile;
134
135/*Warning attributes for libopusfile functions.*/
136# if OP_GNUC_PREREQ(3,4)
137# define OP_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
138# else
139# define OP_WARN_UNUSED_RESULT
140# endif
141# if OP_GNUC_PREREQ(3,4)
142# define OP_ARG_NONNULL(_x) __attribute__((__nonnull__(_x)))
143# else
144# define OP_ARG_NONNULL(_x)
145# endif
146
147/**@endcond*/
148
149/**\defgroup error_codes Error Codes*/
150/*@{*/
151/**\name List of possible error codes
152 Many of the functions in this library return a negative error code when a
153 function fails.
154 This list provides a brief explanation of the common errors.
155 See each individual function for more details on what a specific error code
156 means in that context.*/
157/*@{*/
158
159/**A request did not succeed.*/
160#define OP_FALSE (-1)
161/*Currently not used externally.*/
162#define OP_EOF (-2)
163/**There was a hole in the page sequence numbers (e.g., a page was corrupt or
164 missing).*/
165#define OP_HOLE (-3)
166/**An underlying read, seek, or tell operation failed when it should have
167 succeeded.*/
168#define OP_EREAD (-128)
169/**A <code>NULL</code> pointer was passed where one was unexpected, or an
170 internal memory allocation failed, or an internal library error was
171 encountered.*/
172#define OP_EFAULT (-129)
173/**The stream used a feature that is not implemented, such as an unsupported
174 channel family.*/
175#define OP_EIMPL (-130)
176/**One or more parameters to a function were invalid.*/
177#define OP_EINVAL (-131)
178/**A purported Ogg Opus stream did not begin with an Ogg page, a purported
179 header packet did not start with one of the required strings, "OpusHead" or
180 "OpusTags", or a link in a chained file was encountered that did not
181 contain any logical Opus streams.*/
182#define OP_ENOTFORMAT (-132)
183/**A required header packet was not properly formatted, contained illegal
184 values, or was missing altogether.*/
185#define OP_EBADHEADER (-133)
186/**The ID header contained an unrecognized version number.*/
187#define OP_EVERSION (-134)
188/*Currently not used at all.*/
189#define OP_ENOTAUDIO (-135)
190/**An audio packet failed to decode properly.
191 This is usually caused by a multistream Ogg packet where the durations of
192 the individual Opus packets contained in it are not all the same.*/
193#define OP_EBADPACKET (-136)
194/**We failed to find data we had seen before, or the bitstream structure was
195 sufficiently malformed that seeking to the target destination was
196 impossible.*/
197#define OP_EBADLINK (-137)
198/**An operation that requires seeking was requested on an unseekable stream.*/
199#define OP_ENOSEEK (-138)
200/**The first or last granule position of a link failed basic validity checks.*/
201#define OP_EBADTIMESTAMP (-139)
202
203/*@}*/
204/*@}*/
205
206/**\defgroup header_info Header Information*/
207/*@{*/
208
209/**The maximum number of channels in an Ogg Opus stream.*/
210#define OPUS_CHANNEL_COUNT_MAX (255)
211
212/**Ogg Opus bitstream information.
213 This contains the basic playback parameters for a stream, and corresponds to
214 the initial ID header packet of an Ogg Opus stream.*/
215struct OpusHead{
216 /**The Ogg Opus format version, in the range 0...255.
217 The top 4 bits represent a "major" version, and the bottom four bits
218 represent backwards-compatible "minor" revisions.
219 The current specification describes version 1.
220 This library will recognize versions up through 15 as backwards compatible
221 with the current specification.
222 An earlier draft of the specification described a version 0, but the only
223 difference between version 1 and version 0 is that version 0 did
224 not specify the semantics for handling the version field.*/
225 int version;
226 /**The number of channels, in the range 1...255.*/
227 int channel_count;
228 /**The number of samples that should be discarded from the beginning of the
229 stream.*/
230 unsigned pre_skip;
231 /**The sampling rate of the original input.
232 All Opus audio is coded at 48 kHz, and should also be decoded at 48 kHz
233 for playback (unless the target hardware does not support this sampling
234 rate).
235 However, this field may be used to resample the audio back to the original
236 sampling rate, for example, when saving the output to a file.*/
237 opus_uint32 input_sample_rate;
238 /**The gain to apply to the decoded output, in dB, as a Q8 value in the range
239 -32768...32767.
240 The <tt>libopusfile</tt> API will automatically apply this gain to the
241 decoded output before returning it, scaling it by
242 <code>pow(10,output_gain/(20.0*256))</code>.
243 You can adjust this behavior with op_set_gain_offset().*/
244 int output_gain;
245 /**The channel mapping family, in the range 0...255.
246 Channel mapping family 0 covers mono or stereo in a single stream.
247 Channel mapping family 1 covers 1 to 8 channels in one or more streams,
248 using the Vorbis speaker assignments.
249 Channel mapping family 255 covers 1 to 255 channels in one or more
250 streams, but without any defined speaker assignment.*/
251 int mapping_family;
252 /**The number of Opus streams in each Ogg packet, in the range 1...255.*/
253 int stream_count;
254 /**The number of coupled Opus streams in each Ogg packet, in the range
255 0...127.
256 This must satisfy <code>0 <= coupled_count <= stream_count</code> and
257 <code>coupled_count + stream_count <= 255</code>.
258 The coupled streams appear first, before all uncoupled streams, in an Ogg
259 Opus packet.*/
260 int coupled_count;
261 /**The mapping from coded stream channels to output channels.
262 Let <code>index=mapping[k]</code> be the value for channel <code>k</code>.
263 If <code>index<2*coupled_count</code>, then it refers to the left channel
264 from stream <code>(index/2)</code> if even, and the right channel from
265 stream <code>(index/2)</code> if odd.
266 Otherwise, it refers to the output of the uncoupled stream
267 <code>(index-coupled_count)</code>.*/
268 unsigned char mapping[OPUS_CHANNEL_COUNT_MAX];
269};
270
271/**The metadata from an Ogg Opus stream.
272
273 This structure holds the in-stream metadata corresponding to the 'comment'
274 header packet of an Ogg Opus stream.
275 The comment header is meant to be used much like someone jotting a quick
276 note on the label of a CD.
277 It should be a short, to the point text note that can be more than a couple
278 words, but not more than a short paragraph.
279
280 The metadata is stored as a series of (tag, value) pairs, in length-encoded
281 string vectors, using the same format as Vorbis (without the final "framing
282 bit"), Theora, and Speex, except for the packet header.
283 The first occurrence of the '=' character delimits the tag and value.
284 A particular tag may occur more than once, and order is significant.
285 The character set encoding for the strings is always UTF-8, but the tag
286 names are limited to ASCII, and treated as case-insensitive.
287 See <a href="https://www.xiph.org/vorbis/doc/v-comment.html">the Vorbis
288 comment header specification</a> for details.
289
290 In filling in this structure, <tt>libopusfile</tt> will null-terminate the
291 #user_comments strings for safety.
292 However, the bitstream format itself treats them as 8-bit clean vectors,
293 possibly containing NUL characters, so the #comment_lengths array should be
294 treated as their authoritative length.
295
296 This structure is binary and source-compatible with a
297 <code>vorbis_comment</code>, and pointers to it may be freely cast to
298 <code>vorbis_comment</code> pointers, and vice versa.
299 It is provided as a separate type to avoid introducing a compile-time
300 dependency on the libvorbis headers.*/
301struct OpusTags{
302 /**The array of comment string vectors.*/
303 char **user_comments;
304 /**An array of the corresponding length of each vector, in bytes.*/
305 int *comment_lengths;
306 /**The total number of comment streams.*/
307 int comments;
308 /**The null-terminated vendor string.
309 This identifies the software used to encode the stream.*/
310 char *vendor;
311};
312
313/**\name Picture tag image formats*/
314/*@{*/
315
316/**The MIME type was not recognized, or the image data did not match the
317 declared MIME type.*/
318#define OP_PIC_FORMAT_UNKNOWN (-1)
319/**The MIME type indicates the image data is really a URL.*/
320#define OP_PIC_FORMAT_URL (0)
321/**The image is a JPEG.*/
322#define OP_PIC_FORMAT_JPEG (1)
323/**The image is a PNG.*/
324#define OP_PIC_FORMAT_PNG (2)
325/**The image is a GIF.*/
326#define OP_PIC_FORMAT_GIF (3)
327
328/*@}*/
329
330/**The contents of a METADATA_BLOCK_PICTURE tag.*/
331struct OpusPictureTag{
332 /**The picture type according to the ID3v2 APIC frame:
333 <ol start="0">
334 <li>Other</li>
335 <li>32x32 pixels 'file icon' (PNG only)</li>
336 <li>Other file icon</li>
337 <li>Cover (front)</li>
338 <li>Cover (back)</li>
339 <li>Leaflet page</li>
340 <li>Media (e.g. label side of CD)</li>
341 <li>Lead artist/lead performer/soloist</li>
342 <li>Artist/performer</li>
343 <li>Conductor</li>
344 <li>Band/Orchestra</li>
345 <li>Composer</li>
346 <li>Lyricist/text writer</li>
347 <li>Recording Location</li>
348 <li>During recording</li>
349 <li>During performance</li>
350 <li>Movie/video screen capture</li>
351 <li>A bright colored fish</li>
352 <li>Illustration</li>
353 <li>Band/artist logotype</li>
354 <li>Publisher/Studio logotype</li>
355 </ol>
356 Others are reserved and should not be used.
357 There may only be one each of picture type 1 and 2 in a file.*/
358 opus_int32 type;
359 /**The MIME type of the picture, in printable ASCII characters 0x20-0x7E.
360 The MIME type may also be <code>"-->"</code> to signify that the data part
361 is a URL pointing to the picture instead of the picture data itself.
362 In this case, a terminating NUL is appended to the URL string in #data,
363 but #data_length is set to the length of the string excluding that
364 terminating NUL.*/
365 char *mime_type;
366 /**The description of the picture, in UTF-8.*/
367 char *description;
368 /**The width of the picture in pixels.*/
369 opus_uint32 width;
370 /**The height of the picture in pixels.*/
371 opus_uint32 height;
372 /**The color depth of the picture in bits-per-pixel (<em>not</em>
373 bits-per-channel).*/
374 opus_uint32 depth;
375 /**For indexed-color pictures (e.g., GIF), the number of colors used, or 0
376 for non-indexed pictures.*/
377 opus_uint32 colors;
378 /**The length of the picture data in bytes.*/
379 opus_uint32 data_length;
380 /**The binary picture data.*/
381 unsigned char *data;
382 /**The format of the picture data, if known.
383 One of
384 <ul>
385 <li>#OP_PIC_FORMAT_UNKNOWN,</li>
386 <li>#OP_PIC_FORMAT_URL,</li>
387 <li>#OP_PIC_FORMAT_JPEG,</li>
388 <li>#OP_PIC_FORMAT_PNG, or</li>
389 <li>#OP_PIC_FORMAT_GIF.</li>
390 </ul>*/
391 int format;
392};
393
394/**\name Functions for manipulating header data
395
396 These functions manipulate the #OpusHead and #OpusTags structures,
397 which describe the audio parameters and tag-value metadata, respectively.
398 These can be used to query the headers returned by <tt>libopusfile</tt>, or
399 to parse Opus headers from sources other than an Ogg Opus stream, provided
400 they use the same format.*/
401/*@{*/
402
403/**Parses the contents of the ID header packet of an Ogg Opus stream.
404 \param[out] _head Returns the contents of the parsed packet.
405 The contents of this structure are untouched on error.
406 This may be <code>NULL</code> to merely test the header
407 for validity.
408 \param[in] _data The contents of the ID header packet.
409 \param _len The number of bytes of data in the ID header packet.
410 \return 0 on success or a negative value on error.
411 \retval #OP_ENOTFORMAT If the data does not start with the "OpusHead"
412 string.
413 \retval #OP_EVERSION If the version field signaled a version this library
414 does not know how to parse.
415 \retval #OP_EIMPL If the channel mapping family was 255, which general
416 purpose players should not attempt to play.
417 \retval #OP_EBADHEADER If the contents of the packet otherwise violate the
418 Ogg Opus specification:
419 <ul>
420 <li>Insufficient data,</li>
421 <li>Too much data for the known minor versions,</li>
422 <li>An unrecognized channel mapping family,</li>
423 <li>Zero channels or too many channels,</li>
424 <li>Zero coded streams,</li>
425 <li>Too many coupled streams, or</li>
426 <li>An invalid channel mapping index.</li>
427 </ul>*/
428OP_WARN_UNUSED_RESULT int opus_head_parse(OpusHead *_head,
429 const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
430
431/**Converts a granule position to a sample offset for a given Ogg Opus stream.
432 The sample offset is simply <code>_gp-_head->pre_skip</code>.
433 Granule position values smaller than OpusHead#pre_skip correspond to audio
434 that should never be played, and thus have no associated sample offset.
435 This function returns -1 for such values.
436 This function also correctly handles extremely large granule positions,
437 which may have wrapped around to a negative number when stored in a signed
438 ogg_int64_t value.
439 \param _head The #OpusHead information from the ID header of the stream.
440 \param _gp The granule position to convert.
441 \return The sample offset associated with the given granule position
442 (counting at a 48 kHz sampling rate), or the special value -1 on
443 error (i.e., the granule position was smaller than the pre-skip
444 amount).*/
445ogg_int64_t opus_granule_sample(const OpusHead *_head,ogg_int64_t _gp)
446 OP_ARG_NONNULL(1);
447
448/**Parses the contents of the 'comment' header packet of an Ogg Opus stream.
449 \param[out] _tags An uninitialized #OpusTags structure.
450 This returns the contents of the parsed packet.
451 The contents of this structure are untouched on error.
452 This may be <code>NULL</code> to merely test the header
453 for validity.
454 \param[in] _data The contents of the 'comment' header packet.
455 \param _len The number of bytes of data in the 'info' header packet.
456 \retval 0 Success.
457 \retval #OP_ENOTFORMAT If the data does not start with the "OpusTags"
458 string.
459 \retval #OP_EBADHEADER If the contents of the packet otherwise violate the
460 Ogg Opus specification.
461 \retval #OP_EFAULT If there wasn't enough memory to store the tags.*/
462OP_WARN_UNUSED_RESULT int opus_tags_parse(OpusTags *_tags,
463 const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
464
465/**Performs a deep copy of an #OpusTags structure.
466 \param _dst The #OpusTags structure to copy into.
467 If this function fails, the contents of this structure remain
468 untouched.
469 \param _src The #OpusTags structure to copy from.
470 \retval 0 Success.
471 \retval #OP_EFAULT If there wasn't enough memory to copy the tags.*/
472int opus_tags_copy(OpusTags *_dst,const OpusTags *_src) OP_ARG_NONNULL(1);
473
474/**Initializes an #OpusTags structure.
475 This should be called on a freshly allocated #OpusTags structure before
476 attempting to use it.
477 \param _tags The #OpusTags structure to initialize.*/
478void opus_tags_init(OpusTags *_tags) OP_ARG_NONNULL(1);
479
480/**Add a (tag, value) pair to an initialized #OpusTags structure.
481 \note Neither opus_tags_add() nor opus_tags_add_comment() support values
482 containing embedded NULs, although the bitstream format does support them.
483 To add such tags, you will need to manipulate the #OpusTags structure
484 directly.
485 \param _tags The #OpusTags structure to add the (tag, value) pair to.
486 \param _tag A NUL-terminated, case-insensitive, ASCII string containing
487 the tag to add (without an '=' character).
488 \param _value A NUL-terminated UTF-8 containing the corresponding value.
489 \return 0 on success, or a negative value on failure.
490 \retval #OP_EFAULT An internal memory allocation failed.*/
491int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value)
492 OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3);
493
494/**Add a comment to an initialized #OpusTags structure.
495 \note Neither opus_tags_add_comment() nor opus_tags_add() support comments
496 containing embedded NULs, although the bitstream format does support them.
497 To add such tags, you will need to manipulate the #OpusTags structure
498 directly.
499 \param _tags The #OpusTags structure to add the comment to.
500 \param _comment A NUL-terminated UTF-8 string containing the comment in
501 "TAG=value" form.
502 \return 0 on success, or a negative value on failure.
503 \retval #OP_EFAULT An internal memory allocation failed.*/
504int opus_tags_add_comment(OpusTags *_tags,const char *_comment)
505 OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
506
507/**Replace the binary suffix data at the end of the packet (if any).
508 \param _tags An initialized #OpusTags structure.
509 \param _data A buffer of binary data to append after the encoded user
510 comments.
511 The least significant bit of the first byte of this data must
512 be set (to ensure the data is preserved by other editors).
513 \param _len The number of bytes of binary data to append.
514 This may be zero to remove any existing binary suffix data.
515 \return 0 on success, or a negative value on error.
516 \retval #OP_EINVAL \a _len was negative, or \a _len was positive but
517 \a _data was <code>NULL</code> or the least significant
518 bit of the first byte was not set.
519 \retval #OP_EFAULT An internal memory allocation failed.*/
520int opus_tags_set_binary_suffix(OpusTags *_tags,
521 const unsigned char *_data,int _len) OP_ARG_NONNULL(1);
522
523/**Look up a comment value by its tag.
524 \param _tags An initialized #OpusTags structure.
525 \param _tag The tag to look up.
526 \param _count The instance of the tag.
527 The same tag can appear multiple times, each with a distinct
528 value, so an index is required to retrieve them all.
529 The order in which these values appear is significant and
530 should be preserved.
531 Use opus_tags_query_count() to get the legal range for the
532 \a _count parameter.
533 \return A pointer to the queried tag's value.
534 This points directly to data in the #OpusTags structure.
535 It should not be modified or freed by the application, and
536 modifications to the structure may invalidate the pointer.
537 \retval NULL If no matching tag is found.*/
538const char *opus_tags_query(const OpusTags *_tags,const char *_tag,int _count)
539 OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
540
541/**Look up the number of instances of a tag.
542 Call this first when querying for a specific tag and then iterate over the
543 number of instances with separate calls to opus_tags_query() to retrieve
544 all the values for that tag in order.
545 \param _tags An initialized #OpusTags structure.
546 \param _tag The tag to look up.
547 \return The number of instances of this particular tag.*/
548int opus_tags_query_count(const OpusTags *_tags,const char *_tag)
549 OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
550
551/**Retrieve the binary suffix data at the end of the packet (if any).
552 \param _tags An initialized #OpusTags structure.
553 \param[out] _len Returns the number of bytes of binary suffix data returned.
554 \return A pointer to the binary suffix data, or <code>NULL</code> if none
555 was present.*/
556const unsigned char *opus_tags_get_binary_suffix(const OpusTags *_tags,
557 int *_len) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
558
559/**Get the album gain from an R128_ALBUM_GAIN tag, if one was specified.
560 This searches for the first R128_ALBUM_GAIN tag with a valid signed,
561 16-bit decimal integer value and returns the value.
562 This routine is exposed merely for convenience for applications which wish
563 to do something special with the album gain (i.e., display it).
564 If you simply wish to apply the album gain instead of the header gain, you
565 can use op_set_gain_offset() with an #OP_ALBUM_GAIN type and no offset.
566 \param _tags An initialized #OpusTags structure.
567 \param[out] _gain_q8 The album gain, in 1/256ths of a dB.
568 This will lie in the range [-32768,32767], and should
569 be applied in <em>addition</em> to the header gain.
570 On error, no value is returned, and the previous
571 contents remain unchanged.
572 \return 0 on success, or a negative value on error.
573 \retval #OP_FALSE There was no album gain available in the given tags.*/
574int opus_tags_get_album_gain(const OpusTags *_tags,int *_gain_q8)
575 OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
576
577/**Get the track gain from an R128_TRACK_GAIN tag, if one was specified.
578 This searches for the first R128_TRACK_GAIN tag with a valid signed,
579 16-bit decimal integer value and returns the value.
580 This routine is exposed merely for convenience for applications which wish
581 to do something special with the track gain (i.e., display it).
582 If you simply wish to apply the track gain instead of the header gain, you
583 can use op_set_gain_offset() with an #OP_TRACK_GAIN type and no offset.
584 \param _tags An initialized #OpusTags structure.
585 \param[out] _gain_q8 The track gain, in 1/256ths of a dB.
586 This will lie in the range [-32768,32767], and should
587 be applied in <em>addition</em> to the header gain.
588 On error, no value is returned, and the previous
589 contents remain unchanged.
590 \return 0 on success, or a negative value on error.
591 \retval #OP_FALSE There was no track gain available in the given tags.*/
592int opus_tags_get_track_gain(const OpusTags *_tags,int *_gain_q8)
593 OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
594
595/**Clears the #OpusTags structure.
596 This should be called on an #OpusTags structure after it is no longer
597 needed.
598 It will free all memory used by the structure members.
599 \param _tags The #OpusTags structure to clear.*/
600void opus_tags_clear(OpusTags *_tags) OP_ARG_NONNULL(1);
601
602/**Check if \a _comment is an instance of a \a _tag_name tag.
603 \see opus_tagncompare
604 \param _tag_name A NUL-terminated, case-insensitive, ASCII string containing
605 the name of the tag to check for (without the terminating
606 '=' character).
607 \param _comment The comment string to check.
608 \return An integer less than, equal to, or greater than zero if \a _comment
609 is found respectively, to be less than, to match, or be greater
610 than a "tag=value" string whose tag matches \a _tag_name.*/
611int opus_tagcompare(const char *_tag_name,const char *_comment);
612
613/**Check if \a _comment is an instance of a \a _tag_name tag.
614 This version is slightly more efficient than opus_tagcompare() if the length
615 of the tag name is already known (e.g., because it is a constant).
616 \see opus_tagcompare
617 \param _tag_name A case-insensitive ASCII string containing the name of the
618 tag to check for (without the terminating '=' character).
619 \param _tag_len The number of characters in the tag name.
620 This must be non-negative.
621 \param _comment The comment string to check.
622 \return An integer less than, equal to, or greater than zero if \a _comment
623 is found respectively, to be less than, to match, or be greater
624 than a "tag=value" string whose tag matches the first \a _tag_len
625 characters of \a _tag_name.*/
626int opus_tagncompare(const char *_tag_name,int _tag_len,const char *_comment);
627
628/**Parse a single METADATA_BLOCK_PICTURE tag.
629 This decodes the BASE64-encoded content of the tag and returns a structure
630 with the MIME type, description, image parameters (if known), and the
631 compressed image data.
632 If the MIME type indicates the presence of an image format we recognize
633 (JPEG, PNG, or GIF) and the actual image data contains the magic signature
634 associated with that format, then the OpusPictureTag::format field will be
635 set to the corresponding format.
636 This is provided as a convenience to avoid requiring applications to parse
637 the MIME type and/or do their own format detection for the commonly used
638 formats.
639 In this case, we also attempt to extract the image parameters directly from
640 the image data (overriding any that were present in the tag, which the
641 specification says applications are not meant to rely on).
642 The application must still provide its own support for actually decoding the
643 image data and, if applicable, retrieving that data from URLs.
644 \param[out] _pic Returns the parsed picture data.
645 No sanitation is done on the type, MIME type, or
646 description fields, so these might return invalid values.
647 The contents of this structure are left unmodified on
648 failure.
649 \param _tag The METADATA_BLOCK_PICTURE tag contents.
650 The leading "METADATA_BLOCK_PICTURE=" portion is optional,
651 to allow the function to be used on either directly on the
652 values in OpusTags::user_comments or on the return value
653 of opus_tags_query().
654 \return 0 on success or a negative value on error.
655 \retval #OP_ENOTFORMAT The METADATA_BLOCK_PICTURE contents were not valid.
656 \retval #OP_EFAULT There was not enough memory to store the picture tag
657 contents.*/
658OP_WARN_UNUSED_RESULT int opus_picture_tag_parse(OpusPictureTag *_pic,
659 const char *_tag) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
660
661/**Initializes an #OpusPictureTag structure.
662 This should be called on a freshly allocated #OpusPictureTag structure
663 before attempting to use it.
664 \param _pic The #OpusPictureTag structure to initialize.*/
665void opus_picture_tag_init(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
666
667/**Clears the #OpusPictureTag structure.
668 This should be called on an #OpusPictureTag structure after it is no longer
669 needed.
670 It will free all memory used by the structure members.
671 \param _pic The #OpusPictureTag structure to clear.*/
672void opus_picture_tag_clear(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
673
674/*@}*/
675
676/*@}*/
677
678/**\defgroup url_options URL Reading Options*/
679/*@{*/
680/**\name URL reading options
681 Options for op_url_stream_create() and associated functions.
682 These allow you to provide proxy configuration parameters, skip SSL
683 certificate checks, etc.
684 Options are processed in order, and if the same option is passed multiple
685 times, only the value specified by the last occurrence has an effect
686 (unless otherwise specified).
687 They may be expanded in the future.*/
688/*@{*/
689
690/**@cond PRIVATE*/
691
692/*These are the raw numbers used to define the request codes.
693 They should not be used directly.*/
694#define OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST (6464)
695#define OP_HTTP_PROXY_HOST_REQUEST (6528)
696#define OP_HTTP_PROXY_PORT_REQUEST (6592)
697#define OP_HTTP_PROXY_USER_REQUEST (6656)
698#define OP_HTTP_PROXY_PASS_REQUEST (6720)
699#define OP_GET_SERVER_INFO_REQUEST (6784)
700
701#define OP_URL_OPT(_request) ((char *)(_request))
702
703/*These macros trigger compilation errors or warnings if the wrong types are
704 provided to one of the URL options.*/
705#define OP_CHECK_INT(_x) ((void)((_x)==(opus_int32)0),(opus_int32)(_x))
706#define OP_CHECK_CONST_CHAR_PTR(_x) ((_x)+((_x)-(const char *)(_x)))
707#define OP_CHECK_SERVER_INFO_PTR(_x) ((_x)+((_x)-(OpusServerInfo *)(_x)))
708
709/**@endcond*/
710
711/**HTTP/Shoutcast/Icecast server information associated with a URL.*/
712struct OpusServerInfo{
713 /**The name of the server (icy-name/ice-name).
714 This is <code>NULL</code> if there was no <code>icy-name</code> or
715 <code>ice-name</code> header.*/
716 char *name;
717 /**A short description of the server (icy-description/ice-description).
718 This is <code>NULL</code> if there was no <code>icy-description</code> or
719 <code>ice-description</code> header.*/
720 char *description;
721 /**The genre the server falls under (icy-genre/ice-genre).
722 This is <code>NULL</code> if there was no <code>icy-genre</code> or
723 <code>ice-genre</code> header.*/
724 char *genre;
725 /**The homepage for the server (icy-url/ice-url).
726 This is <code>NULL</code> if there was no <code>icy-url</code> or
727 <code>ice-url</code> header.*/
728 char *url;
729 /**The software used by the origin server (Server).
730 This is <code>NULL</code> if there was no <code>Server</code> header.*/
731 char *server;
732 /**The media type of the entity sent to the recepient (Content-Type).
733 This is <code>NULL</code> if there was no <code>Content-Type</code>
734 header.*/
735 char *content_type;
736 /**The nominal stream bitrate in kbps (icy-br/ice-bitrate).
737 This is <code>-1</code> if there was no <code>icy-br</code> or
738 <code>ice-bitrate</code> header.*/
739 opus_int32 bitrate_kbps;
740 /**Flag indicating whether the server is public (<code>1</code>) or not
741 (<code>0</code>) (icy-pub/ice-public).
742 This is <code>-1</code> if there was no <code>icy-pub</code> or
743 <code>ice-public</code> header.*/
744 int is_public;
745 /**Flag indicating whether the server is using HTTPS instead of HTTP.
746 This is <code>0</code> unless HTTPS is being used.
747 This may not match the protocol used in the original URL if there were
748 redirections.*/
749 int is_ssl;
750};
751
752/**Initializes an #OpusServerInfo structure.
753 All fields are set as if the corresponding header was not available.
754 \param _info The #OpusServerInfo structure to initialize.
755 \note If you use this function, you must link against <tt>libopusurl</tt>.*/
756void opus_server_info_init(OpusServerInfo *_info) OP_ARG_NONNULL(1);
757
758/**Clears the #OpusServerInfo structure.
759 This should be called on an #OpusServerInfo structure after it is no longer
760 needed.
761 It will free all memory used by the structure members.
762 \param _info The #OpusServerInfo structure to clear.
763 \note If you use this function, you must link against <tt>libopusurl</tt>.*/
764void opus_server_info_clear(OpusServerInfo *_info) OP_ARG_NONNULL(1);
765
766/**Skip the certificate check when connecting via TLS/SSL (https).
767 \param _b <code>opus_int32</code>: Whether or not to skip the certificate
768 check.
769 The check will be skipped if \a _b is non-zero, and will not be
770 skipped if \a _b is zero.
771 \hideinitializer*/
772#define OP_SSL_SKIP_CERTIFICATE_CHECK(_b) \
773 OP_URL_OPT(OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST),OP_CHECK_INT(_b)
774
775/**Proxy connections through the given host.
776 If no port is specified via #OP_HTTP_PROXY_PORT, the port number defaults
777 to 8080 (http-alt).
778 All proxy parameters are ignored for non-http and non-https URLs.
779 \param _host <code>const char *</code>: The proxy server hostname.
780 This may be <code>NULL</code> to disable the use of a proxy
781 server.
782 \hideinitializer*/
783#define OP_HTTP_PROXY_HOST(_host) \
784 OP_URL_OPT(OP_HTTP_PROXY_HOST_REQUEST),OP_CHECK_CONST_CHAR_PTR(_host)
785
786/**Use the given port when proxying connections.
787 This option only has an effect if #OP_HTTP_PROXY_HOST is specified with a
788 non-<code>NULL</code> \a _host.
789 If this option is not provided, the proxy port number defaults to 8080
790 (http-alt).
791 All proxy parameters are ignored for non-http and non-https URLs.
792 \param _port <code>opus_int32</code>: The proxy server port.
793 This must be in the range 0...65535 (inclusive), or the
794 URL function this is passed to will fail.
795 \hideinitializer*/
796#define OP_HTTP_PROXY_PORT(_port) \
797 OP_URL_OPT(OP_HTTP_PROXY_PORT_REQUEST),OP_CHECK_INT(_port)
798
799/**Use the given user name for authentication when proxying connections.
800 All proxy parameters are ignored for non-http and non-https URLs.
801 \param _user const char *: The proxy server user name.
802 This may be <code>NULL</code> to disable proxy
803 authentication.
804 A non-<code>NULL</code> value only has an effect
805 if #OP_HTTP_PROXY_HOST and #OP_HTTP_PROXY_PASS
806 are also specified with non-<code>NULL</code>
807 arguments.
808 \hideinitializer*/
809#define OP_HTTP_PROXY_USER(_user) \
810 OP_URL_OPT(OP_HTTP_PROXY_USER_REQUEST),OP_CHECK_CONST_CHAR_PTR(_user)
811
812/**Use the given password for authentication when proxying connections.
813 All proxy parameters are ignored for non-http and non-https URLs.
814 \param _pass const char *: The proxy server password.
815 This may be <code>NULL</code> to disable proxy
816 authentication.
817 A non-<code>NULL</code> value only has an effect
818 if #OP_HTTP_PROXY_HOST and #OP_HTTP_PROXY_USER
819 are also specified with non-<code>NULL</code>
820 arguments.
821 \hideinitializer*/
822#define OP_HTTP_PROXY_PASS(_pass) \
823 OP_URL_OPT(OP_HTTP_PROXY_PASS_REQUEST),OP_CHECK_CONST_CHAR_PTR(_pass)
824
825/**Parse information about the streaming server (if any) and return it.
826 Very little validation is done.
827 In particular, OpusServerInfo::url may not be a valid URL,
828 OpusServerInfo::bitrate_kbps may not really be in kbps, and
829 OpusServerInfo::content_type may not be a valid MIME type.
830 The character set of the string fields is not specified anywhere, and should
831 not be assumed to be valid UTF-8.
832 \param _info OpusServerInfo *: Returns information about the server.
833 If there is any error opening the stream, the
834 contents of this structure remain
835 unmodified.
836 On success, fills in the structure with the
837 server information that was available, if
838 any.
839 After a successful return, the contents of
840 this structure should be freed by calling
841 opus_server_info_clear().
842 \hideinitializer*/
843#define OP_GET_SERVER_INFO(_info) \
844 OP_URL_OPT(OP_GET_SERVER_INFO_REQUEST),OP_CHECK_SERVER_INFO_PTR(_info)
845
846/*@}*/
847/*@}*/
848
849/**\defgroup stream_callbacks Abstract Stream Reading Interface*/
850/*@{*/
851/**\name Functions for reading from streams
852 These functions define the interface used to read from and seek in a stream
853 of data.
854 A stream does not need to implement seeking, but the decoder will not be
855 able to seek if it does not do so.
856 These functions also include some convenience routines for working with
857 standard <code>FILE</code> pointers, complete streams stored in a single
858 block of memory, or URLs.*/
859/*@{*/
860
861/**Reads up to \a _nbytes bytes of data from \a _stream.
862 \param _stream The stream to read from.
863 \param[out] _ptr The buffer to store the data in.
864 \param _nbytes The maximum number of bytes to read.
865 This function may return fewer, though it will not
866 return zero unless it reaches end-of-file.
867 \return The number of bytes successfully read, or a negative value on
868 error.*/
869typedef int (*op_read_func)(void *_stream,unsigned char *_ptr,int _nbytes);
870
871/**Sets the position indicator for \a _stream.
872 The new position, measured in bytes, is obtained by adding \a _offset
873 bytes to the position specified by \a _whence.
874 If \a _whence is set to <code>SEEK_SET</code>, <code>SEEK_CUR</code>, or
875 <code>SEEK_END</code>, the offset is relative to the start of the stream,
876 the current position indicator, or end-of-file, respectively.
877 \retval 0 Success.
878 \retval -1 Seeking is not supported or an error occurred.
879 <code>errno</code> need not be set.*/
880typedef int (*op_seek_func)(void *_stream,opus_int64 _offset,int _whence);
881
882/**Obtains the current value of the position indicator for \a _stream.
883 \return The current position indicator.*/
884typedef opus_int64 (*op_tell_func)(void *_stream);
885
886/**Closes the underlying stream.
887 \retval 0 Success.
888 \retval EOF An error occurred.
889 <code>errno</code> need not be set.*/
890typedef int (*op_close_func)(void *_stream);
891
892/**The callbacks used to access non-<code>FILE</code> stream resources.
893 The function prototypes are basically the same as for the stdio functions
894 <code>fread()</code>, <code>fseek()</code>, <code>ftell()</code>, and
895 <code>fclose()</code>.
896 The differences are that the <code>FILE *</code> arguments have been
897 replaced with a <code>void *</code>, which is to be used as a pointer to
898 whatever internal data these functions might need, that #seek and #tell
899 take and return 64-bit offsets, and that #seek <em>must</em> return -1 if
900 the stream is unseekable.*/
901struct OpusFileCallbacks{
902 /**Used to read data from the stream.
903 This must not be <code>NULL</code>.*/
904 op_read_func read;
905 /**Used to seek in the stream.
906 This may be <code>NULL</code> if seeking is not implemented.*/
907 op_seek_func seek;
908 /**Used to return the current read position in the stream.
909 This may be <code>NULL</code> if seeking is not implemented.*/
910 op_tell_func tell;
911 /**Used to close the stream when the decoder is freed.
912 This may be <code>NULL</code> to leave the stream open.*/
913 op_close_func close;
914};
915
916/**Opens a stream with <code>fopen()</code> and fills in a set of callbacks
917 that can be used to access it.
918 This is useful to avoid writing your own portable 64-bit seeking wrappers,
919 and also avoids cross-module linking issues on Windows, where a
920 <code>FILE *</code> must be accessed by routines defined in the same module
921 that opened it.
922 \param[out] _cb The callbacks to use for this file.
923 If there is an error opening the file, nothing will be
924 filled in here.
925 \param _path The path to the file to open.
926 On Windows, this string must be UTF-8 (to allow access to
927 files whose names cannot be represented in the current
928 MBCS code page).
929 All other systems use the native character encoding.
930 \param _mode The mode to open the file in.
931 \return A stream handle to use with the callbacks, or <code>NULL</code> on
932 error.*/
933OP_WARN_UNUSED_RESULT void *op_fopen(OpusFileCallbacks *_cb,
934 const char *_path,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
935 OP_ARG_NONNULL(3);
936
937/**Opens a stream with <code>fdopen()</code> and fills in a set of callbacks
938 that can be used to access it.
939 This is useful to avoid writing your own portable 64-bit seeking wrappers,
940 and also avoids cross-module linking issues on Windows, where a
941 <code>FILE *</code> must be accessed by routines defined in the same module
942 that opened it.
943 \param[out] _cb The callbacks to use for this file.
944 If there is an error opening the file, nothing will be
945 filled in here.
946 \param _fd The file descriptor to open.
947 \param _mode The mode to open the file in.
948 \return A stream handle to use with the callbacks, or <code>NULL</code> on
949 error.*/
950OP_WARN_UNUSED_RESULT void *op_fdopen(OpusFileCallbacks *_cb,
951 int _fd,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(3);
952
953/**Opens a stream with <code>freopen()</code> and fills in a set of callbacks
954 that can be used to access it.
955 This is useful to avoid writing your own portable 64-bit seeking wrappers,
956 and also avoids cross-module linking issues on Windows, where a
957 <code>FILE *</code> must be accessed by routines defined in the same module
958 that opened it.
959 \param[out] _cb The callbacks to use for this file.
960 If there is an error opening the file, nothing will be
961 filled in here.
962 \param _path The path to the file to open.
963 On Windows, this string must be UTF-8 (to allow access
964 to files whose names cannot be represented in the
965 current MBCS code page).
966 All other systems use the native character encoding.
967 \param _mode The mode to open the file in.
968 \param _stream A stream previously returned by op_fopen(), op_fdopen(),
969 or op_freopen().
970 \return A stream handle to use with the callbacks, or <code>NULL</code> on
971 error.*/
972OP_WARN_UNUSED_RESULT void *op_freopen(OpusFileCallbacks *_cb,
973 const char *_path,const char *_mode,void *_stream) OP_ARG_NONNULL(1)
974 OP_ARG_NONNULL(2) OP_ARG_NONNULL(3) OP_ARG_NONNULL(4);
975
976/**Creates a stream that reads from the given block of memory.
977 This block of memory must contain the complete stream to decode.
978 This is useful for caching small streams (e.g., sound effects) in RAM.
979 \param[out] _cb The callbacks to use for this stream.
980 If there is an error creating the stream, nothing will be
981 filled in here.
982 \param _data The block of memory to read from.
983 \param _size The size of the block of memory.
984 \return A stream handle to use with the callbacks, or <code>NULL</code> on
985 error.*/
986OP_WARN_UNUSED_RESULT void *op_mem_stream_create(OpusFileCallbacks *_cb,
987 const unsigned char *_data,size_t _size) OP_ARG_NONNULL(1);
988
989/**Creates a stream that reads from the given URL.
990 This function behaves identically to op_url_stream_create(), except that it
991 takes a va_list instead of a variable number of arguments.
992 It does not call the <code>va_end</code> macro, and because it invokes the
993 <code>va_arg</code> macro, the value of \a _ap is undefined after the call.
994 \note If you use this function, you must link against <tt>libopusurl</tt>.
995 \param[out] _cb The callbacks to use for this stream.
996 If there is an error creating the stream, nothing will
997 be filled in here.
998 \param _url The URL to read from.
999 Currently only the <file:>, <http:>, and <https:>
1000 schemes are supported.
1001 Both <http:> and <https:> may be disabled at compile
1002 time, in which case opening such URLs will always fail.
1003 Currently this only supports URIs.
1004 IRIs should be converted to UTF-8 and URL-escaped, with
1005 internationalized domain names encoded in punycode,
1006 before passing them to this function.
1007 \param[in,out] _ap A list of the \ref url_options "optional flags" to use.
1008 This is a variable-length list of options terminated
1009 with <code>NULL</code>.
1010 \return A stream handle to use with the callbacks, or <code>NULL</code> on
1011 error.*/
1012OP_WARN_UNUSED_RESULT void *op_url_stream_vcreate(OpusFileCallbacks *_cb,
1013 const char *_url,va_list _ap) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
1014
1015/**Creates a stream that reads from the given URL.
1016 \note If you use this function, you must link against <tt>libopusurl</tt>.
1017 \param[out] _cb The callbacks to use for this stream.
1018 If there is an error creating the stream, nothing will be
1019 filled in here.
1020 \param _url The URL to read from.
1021 Currently only the <file:>, <http:>, and <https:> schemes
1022 are supported.
1023 Both <http:> and <https:> may be disabled at compile time,
1024 in which case opening such URLs will always fail.
1025 Currently this only supports URIs.
1026 IRIs should be converted to UTF-8 and URL-escaped, with
1027 internationalized domain names encoded in punycode, before
1028 passing them to this function.
1029 \param ... The \ref url_options "optional flags" to use.
1030 This is a variable-length list of options terminated with
1031 <code>NULL</code>.
1032 \return A stream handle to use with the callbacks, or <code>NULL</code> on
1033 error.*/
1034OP_WARN_UNUSED_RESULT void *op_url_stream_create(OpusFileCallbacks *_cb,
1035 const char *_url,...) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
1036
1037/*@}*/
1038/*@}*/
1039
1040/**\defgroup stream_open_close Opening and Closing*/
1041/*@{*/
1042/**\name Functions for opening and closing streams
1043
1044 These functions allow you to test a stream to see if it is Opus, open it,
1045 and close it.
1046 Several flavors are provided for each of the built-in stream types, plus a
1047 more general version which takes a set of application-provided callbacks.*/
1048/*@{*/
1049
1050/**Test to see if this is an Opus stream.
1051 For good results, you will need at least 57 bytes (for a pure Opus-only
1052 stream).
1053 Something like 512 bytes will give more reliable results for multiplexed
1054 streams.
1055 This function is meant to be a quick-rejection filter.
1056 Its purpose is not to guarantee that a stream is a valid Opus stream, but to
1057 ensure that it looks enough like Opus that it isn't going to be recognized
1058 as some other format (except possibly an Opus stream that is also
1059 multiplexed with other codecs, such as video).
1060 \param[out] _head The parsed ID header contents.
1061 You may pass <code>NULL</code> if you do not need
1062 this information.
1063 If the function fails, the contents of this structure
1064 remain untouched.
1065 \param _initial_data An initial buffer of data from the start of the
1066 stream.
1067 \param _initial_bytes The number of bytes in \a _initial_data.
1068 \return 0 if the data appears to be Opus, or a negative value on error.
1069 \retval #OP_FALSE There was not enough data to tell if this was an Opus
1070 stream or not.
1071 \retval #OP_EFAULT An internal memory allocation failed.
1072 \retval #OP_EIMPL The stream used a feature that is not implemented,
1073 such as an unsupported channel family.
1074 \retval #OP_ENOTFORMAT If the data did not contain a recognizable ID
1075 header for an Opus stream.
1076 \retval #OP_EVERSION If the version field signaled a version this library
1077 does not know how to parse.
1078 \retval #OP_EBADHEADER The ID header was not properly formatted or contained
1079 illegal values.*/
1080int op_test(OpusHead *_head,
1081 const unsigned char *_initial_data,size_t _initial_bytes);
1082
1083/**Open a stream from the given file path.
1084 \param _path The path to the file to open.
1085 \param[out] _error Returns 0 on success, or a failure code on error.
1086 You may pass in <code>NULL</code> if you don't want the
1087 failure code.
1088 The failure code will be #OP_EFAULT if the file could not
1089 be opened, or one of the other failure codes from
1090 op_open_callbacks() otherwise.
1091 \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
1092OP_WARN_UNUSED_RESULT OggOpusFile *op_open_file(const char *_path,int *_error)
1093 OP_ARG_NONNULL(1);
1094
1095/**Open a stream from a memory buffer.
1096 \param _data The memory buffer to open.
1097 \param _size The number of bytes in the buffer.
1098 \param[out] _error Returns 0 on success, or a failure code on error.
1099 You may pass in <code>NULL</code> if you don't want the
1100 failure code.
1101 See op_open_callbacks() for a full list of failure codes.
1102 \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
1103OP_WARN_UNUSED_RESULT OggOpusFile *op_open_memory(const unsigned char *_data,
1104 size_t _size,int *_error);
1105
1106/**Open a stream from a URL.
1107 This function behaves identically to op_open_url(), except that it
1108 takes a va_list instead of a variable number of arguments.
1109 It does not call the <code>va_end</code> macro, and because it invokes the
1110 <code>va_arg</code> macro, the value of \a _ap is undefined after the call.
1111 \note If you use this function, you must link against <tt>libopusurl</tt>.
1112 \param _url The URL to open.
1113 Currently only the <file:>, <http:>, and <https:>
1114 schemes are supported.
1115 Both <http:> and <https:> may be disabled at compile
1116 time, in which case opening such URLs will always
1117 fail.
1118 Currently this only supports URIs.
1119 IRIs should be converted to UTF-8 and URL-escaped,
1120 with internationalized domain names encoded in
1121 punycode, before passing them to this function.
1122 \param[out] _error Returns 0 on success, or a failure code on error.
1123 You may pass in <code>NULL</code> if you don't want
1124 the failure code.
1125 See op_open_callbacks() for a full list of failure
1126 codes.
1127 \param[in,out] _ap A list of the \ref url_options "optional flags" to
1128 use.
1129 This is a variable-length list of options terminated
1130 with <code>NULL</code>.
1131 \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
1132OP_WARN_UNUSED_RESULT OggOpusFile *op_vopen_url(const char *_url,
1133 int *_error,va_list _ap) OP_ARG_NONNULL(1);
1134
1135/**Open a stream from a URL.
1136 \note If you use this function, you must link against <tt>libopusurl</tt>.
1137 \param _url The URL to open.
1138 Currently only the <file:>, <http:>, and <https:> schemes
1139 are supported.
1140 Both <http:> and <https:> may be disabled at compile
1141 time, in which case opening such URLs will always fail.
1142 Currently this only supports URIs.
1143 IRIs should be converted to UTF-8 and URL-escaped, with
1144 internationalized domain names encoded in punycode,
1145 before passing them to this function.
1146 \param[out] _error Returns 0 on success, or a failure code on error.
1147 You may pass in <code>NULL</code> if you don't want the
1148 failure code.
1149 See op_open_callbacks() for a full list of failure codes.
1150 \param ... The \ref url_options "optional flags" to use.
1151 This is a variable-length list of options terminated with
1152 <code>NULL</code>.
1153 \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
1154OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
1155 int *_error,...) OP_ARG_NONNULL(1);
1156
1157/**Open a stream using the given set of callbacks to access it.
1158 \param _stream The stream to read from (e.g., a <code>FILE *</code>).
1159 This value will be passed verbatim as the first
1160 argument to all of the callbacks.
1161 \param _cb The callbacks with which to access the stream.
1162 <code><a href="#op_read_func">read()</a></code> must
1163 be implemented.
1164 <code><a href="#op_seek_func">seek()</a></code> and
1165 <code><a href="#op_tell_func">tell()</a></code> may
1166 be <code>NULL</code>, or may always return -1 to
1167 indicate a stream is unseekable, but if
1168 <code><a href="#op_seek_func">seek()</a></code> is
1169 implemented and succeeds on a particular stream, then
1170 <code><a href="#op_tell_func">tell()</a></code> must
1171 also.
1172 <code><a href="#op_close_func">close()</a></code> may
1173 be <code>NULL</code>, but if it is not, it will be
1174 called when the \c OggOpusFile is destroyed by
1175 op_free().
1176 It will not be called if op_open_callbacks() fails
1177 with an error.
1178 \param _initial_data An initial buffer of data from the start of the
1179 stream.
1180 Applications can read some number of bytes from the
1181 start of the stream to help identify this as an Opus
1182 stream, and then provide them here to allow the
1183 stream to be opened, even if it is unseekable.
1184 \param _initial_bytes The number of bytes in \a _initial_data.
1185 If the stream is seekable, its current position (as
1186 reported by
1187 <code><a href="#opus_tell_func">tell()</a></code>
1188 at the start of this function) must be equal to
1189 \a _initial_bytes.
1190 Otherwise, seeking to absolute positions will
1191 generate inconsistent results.
1192 \param[out] _error Returns 0 on success, or a failure code on error.
1193 You may pass in <code>NULL</code> if you don't want
1194 the failure code.
1195 The failure code will be one of
1196 <dl>
1197 <dt>#OP_EREAD</dt>
1198 <dd>An underlying read, seek, or tell operation
1199 failed when it should have succeeded, or we failed
1200 to find data in the stream we had seen before.</dd>
1201 <dt>#OP_EFAULT</dt>
1202 <dd>There was a memory allocation failure, or an
1203 internal library error.</dd>
1204 <dt>#OP_EIMPL</dt>
1205 <dd>The stream used a feature that is not
1206 implemented, such as an unsupported channel
1207 family.</dd>
1208 <dt>#OP_EINVAL</dt>
1209 <dd><code><a href="#op_seek_func">seek()</a></code>
1210 was implemented and succeeded on this source, but
1211 <code><a href="#op_tell_func">tell()</a></code>
1212 did not, or the starting position indicator was
1213 not equal to \a _initial_bytes.</dd>
1214 <dt>#OP_ENOTFORMAT</dt>
1215 <dd>The stream contained a link that did not have
1216 any logical Opus streams in it.</dd>
1217 <dt>#OP_EBADHEADER</dt>
1218 <dd>A required header packet was not properly
1219 formatted, contained illegal values, or was missing
1220 altogether.</dd>
1221 <dt>#OP_EVERSION</dt>
1222 <dd>An ID header contained an unrecognized version
1223 number.</dd>
1224 <dt>#OP_EBADLINK</dt>
1225 <dd>We failed to find data we had seen before after
1226 seeking.</dd>
1227 <dt>#OP_EBADTIMESTAMP</dt>
1228 <dd>The first or last timestamp in a link failed
1229 basic validity checks.</dd>
1230 </dl>
1231 \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.
1232 <tt>libopusfile</tt> does <em>not</em> take ownership of the stream
1233 if the call fails.
1234 The calling application is responsible for closing the stream if
1235 this call returns an error.*/
1236OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_stream,
1237 const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
1238 size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
1239
1240/**Partially open a stream from the given file path.
1241 \see op_test_callbacks
1242 \param _path The path to the file to open.
1243 \param[out] _error Returns 0 on success, or a failure code on error.
1244 You may pass in <code>NULL</code> if you don't want the
1245 failure code.
1246 The failure code will be #OP_EFAULT if the file could not
1247 be opened, or one of the other failure codes from
1248 op_open_callbacks() otherwise.
1249 \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
1250OP_WARN_UNUSED_RESULT OggOpusFile *op_test_file(const char *_path,int *_error)
1251 OP_ARG_NONNULL(1);
1252
1253/**Partially open a stream from a memory buffer.
1254 \see op_test_callbacks
1255 \param _data The memory buffer to open.
1256 \param _size The number of bytes in the buffer.
1257 \param[out] _error Returns 0 on success, or a failure code on error.
1258 You may pass in <code>NULL</code> if you don't want the
1259 failure code.
1260 See op_open_callbacks() for a full list of failure codes.
1261 \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
1262OP_WARN_UNUSED_RESULT OggOpusFile *op_test_memory(const unsigned char *_data,
1263 size_t _size,int *_error);
1264
1265/**Partially open a stream from a URL.
1266 This function behaves identically to op_test_url(), except that it
1267 takes a va_list instead of a variable number of arguments.
1268 It does not call the <code>va_end</code> macro, and because it invokes the
1269 <code>va_arg</code> macro, the value of \a _ap is undefined after the call.
1270 \note If you use this function, you must link against <tt>libopusurl</tt>.
1271 \see op_test_url
1272 \see op_test_callbacks
1273 \param _url The URL to open.
1274 Currently only the <file:>, <http:>, and <https:>
1275 schemes are supported.
1276 Both <http:> and <https:> may be disabled at compile
1277 time, in which case opening such URLs will always
1278 fail.
1279 Currently this only supports URIs.
1280 IRIs should be converted to UTF-8 and URL-escaped,
1281 with internationalized domain names encoded in
1282 punycode, before passing them to this function.
1283 \param[out] _error Returns 0 on success, or a failure code on error.
1284 You may pass in <code>NULL</code> if you don't want
1285 the failure code.
1286 See op_open_callbacks() for a full list of failure
1287 codes.
1288 \param[in,out] _ap A list of the \ref url_options "optional flags" to
1289 use.
1290 This is a variable-length list of options terminated
1291 with <code>NULL</code>.
1292 \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
1293OP_WARN_UNUSED_RESULT OggOpusFile *op_vtest_url(const char *_url,
1294 int *_error,va_list _ap) OP_ARG_NONNULL(1);
1295
1296/**Partially open a stream from a URL.
1297 \note If you use this function, you must link against <tt>libopusurl</tt>.
1298 \see op_test_callbacks
1299 \param _url The URL to open.
1300 Currently only the <file:>, <http:>, and <https:>
1301 schemes are supported.
1302 Both <http:> and <https:> may be disabled at compile
1303 time, in which case opening such URLs will always fail.
1304 Currently this only supports URIs.
1305 IRIs should be converted to UTF-8 and URL-escaped, with
1306 internationalized domain names encoded in punycode,
1307 before passing them to this function.
1308 \param[out] _error Returns 0 on success, or a failure code on error.
1309 You may pass in <code>NULL</code> if you don't want the
1310 failure code.
1311 See op_open_callbacks() for a full list of failure
1312 codes.
1313 \param ... The \ref url_options "optional flags" to use.
1314 This is a variable-length list of options terminated
1315 with <code>NULL</code>.
1316 \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
1317OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,
1318 int *_error,...) OP_ARG_NONNULL(1);
1319
1320/**Partially open a stream using the given set of callbacks to access it.
1321 This tests for Opusness and loads the headers for the first link.
1322 It does not seek (although it tests for seekability).
1323 You can query a partially open stream for the few pieces of basic
1324 information returned by op_serialno(), op_channel_count(), op_head(), and
1325 op_tags() (but only for the first link).
1326 You may also determine if it is seekable via a call to op_seekable().
1327 You cannot read audio from the stream, seek, get the size or duration,
1328 get information from links other than the first one, or even get the total
1329 number of links until you finish opening the stream with op_test_open().
1330 If you do not need to do any of these things, you can dispose of it with
1331 op_free() instead.
1332
1333 This function is provided mostly to simplify porting existing code that used
1334 <tt>libvorbisfile</tt>.
1335 For new code, you are likely better off using op_test() instead, which
1336 is less resource-intensive, requires less data to succeed, and imposes a
1337 hard limit on the amount of data it examines (important for unseekable
1338 streams, where all such data must be buffered until you are sure of the
1339 stream type).
1340 \param _stream The stream to read from (e.g., a <code>FILE *</code>).
1341 This value will be passed verbatim as the first
1342 argument to all of the callbacks.
1343 \param _cb The callbacks with which to access the stream.
1344 <code><a href="#op_read_func">read()</a></code> must
1345 be implemented.
1346 <code><a href="#op_seek_func">seek()</a></code> and
1347 <code><a href="#op_tell_func">tell()</a></code> may
1348 be <code>NULL</code>, or may always return -1 to
1349 indicate a stream is unseekable, but if
1350 <code><a href="#op_seek_func">seek()</a></code> is
1351 implemented and succeeds on a particular stream, then
1352 <code><a href="#op_tell_func">tell()</a></code> must
1353 also.
1354 <code><a href="#op_close_func">close()</a></code> may
1355 be <code>NULL</code>, but if it is not, it will be
1356 called when the \c OggOpusFile is destroyed by
1357 op_free().
1358 It will not be called if op_open_callbacks() fails
1359 with an error.
1360 \param _initial_data An initial buffer of data from the start of the
1361 stream.
1362 Applications can read some number of bytes from the
1363 start of the stream to help identify this as an Opus
1364 stream, and then provide them here to allow the
1365 stream to be tested more thoroughly, even if it is
1366 unseekable.
1367 \param _initial_bytes The number of bytes in \a _initial_data.
1368 If the stream is seekable, its current position (as
1369 reported by
1370 <code><a href="#opus_tell_func">tell()</a></code>
1371 at the start of this function) must be equal to
1372 \a _initial_bytes.
1373 Otherwise, seeking to absolute positions will
1374 generate inconsistent results.
1375 \param[out] _error Returns 0 on success, or a failure code on error.
1376 You may pass in <code>NULL</code> if you don't want
1377 the failure code.
1378 See op_open_callbacks() for a full list of failure
1379 codes.
1380 \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.
1381 <tt>libopusfile</tt> does <em>not</em> take ownership of the stream
1382 if the call fails.
1383 The calling application is responsible for closing the stream if
1384 this call returns an error.*/
1385OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_stream,
1386 const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
1387 size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
1388
1389/**Finish opening a stream partially opened with op_test_callbacks() or one of
1390 the associated convenience functions.
1391 If this function fails, you are still responsible for freeing the
1392 \c OggOpusFile with op_free().
1393 \param _of The \c OggOpusFile to finish opening.
1394 \return 0 on success, or a negative value on error.
1395 \retval #OP_EREAD An underlying read, seek, or tell operation failed
1396 when it should have succeeded.
1397 \retval #OP_EFAULT There was a memory allocation failure, or an
1398 internal library error.
1399 \retval #OP_EIMPL The stream used a feature that is not implemented,
1400 such as an unsupported channel family.
1401 \retval #OP_EINVAL The stream was not partially opened with
1402 op_test_callbacks() or one of the associated
1403 convenience functions.
1404 \retval #OP_ENOTFORMAT The stream contained a link that did not have any
1405 logical Opus streams in it.
1406 \retval #OP_EBADHEADER A required header packet was not properly
1407 formatted, contained illegal values, or was
1408 missing altogether.
1409 \retval #OP_EVERSION An ID header contained an unrecognized version
1410 number.
1411 \retval #OP_EBADLINK We failed to find data we had seen before after
1412 seeking.
1413 \retval #OP_EBADTIMESTAMP The first or last timestamp in a link failed basic
1414 validity checks.*/
1415int op_test_open(OggOpusFile *_of) OP_ARG_NONNULL(1);
1416
1417/**Release all memory used by an \c OggOpusFile.
1418 \param _of The \c OggOpusFile to free.*/
1419void op_free(OggOpusFile *_of);
1420
1421/*@}*/
1422/*@}*/
1423
1424/**\defgroup stream_info Stream Information*/
1425/*@{*/
1426/**\name Functions for obtaining information about streams
1427
1428 These functions allow you to get basic information about a stream, including
1429 seekability, the number of links (for chained streams), plus the size,
1430 duration, bitrate, header parameters, and meta information for each link
1431 (or, where available, the stream as a whole).
1432 Some of these (size, duration) are only available for seekable streams.
1433 You can also query the current stream position, link, and playback time,
1434 and instantaneous bitrate during playback.
1435
1436 Some of these functions may be used successfully on the partially open
1437 streams returned by op_test_callbacks() or one of the associated
1438 convenience functions.
1439 Their documention will indicate so explicitly.*/
1440/*@{*/
1441
1442/**Returns whether or not the stream being read is seekable.
1443 This is true if
1444 <ol>
1445 <li>The <code><a href="#op_seek_func">seek()</a></code> and
1446 <code><a href="#op_tell_func">tell()</a></code> callbacks are both
1447 non-<code>NULL</code>,</li>
1448 <li>The <code><a href="#op_seek_func">seek()</a></code> callback was
1449 successfully executed at least once, and</li>
1450 <li>The <code><a href="#op_tell_func">tell()</a></code> callback was
1451 successfully able to report the position indicator afterwards.</li>
1452 </ol>
1453 This function may be called on partially-opened streams.
1454 \param _of The \c OggOpusFile whose seekable status is to be returned.
1455 \return A non-zero value if seekable, and 0 if unseekable.*/
1456int op_seekable(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1457
1458/**Returns the number of links in this chained stream.
1459 This function may be called on partially-opened streams, but it will always
1460 return 1.
1461 The actual number of links is not known until the stream is fully opened.
1462 \param _of The \c OggOpusFile from which to retrieve the link count.
1463 \return For fully-open seekable streams, this returns the total number of
1464 links in the whole stream, which will be at least 1.
1465 For partially-open or unseekable streams, this always returns 1.*/
1466int op_link_count(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1467
1468/**Get the serial number of the given link in a (possibly-chained) Ogg Opus
1469 stream.
1470 This function may be called on partially-opened streams, but it will always
1471 return the serial number of the Opus stream in the first link.
1472 \param _of The \c OggOpusFile from which to retrieve the serial number.
1473 \param _li The index of the link whose serial number should be retrieved.
1474 Use a negative number to get the serial number of the current
1475 link.
1476 \return The serial number of the given link.
1477 If \a _li is greater than the total number of links, this returns
1478 the serial number of the last link.
1479 If the stream is not seekable, this always returns the serial number
1480 of the current link.*/
1481opus_uint32 op_serialno(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1482
1483/**Get the channel count of the given link in a (possibly-chained) Ogg Opus
1484 stream.
1485 This is equivalent to <code>op_head(_of,_li)->channel_count</code>, but
1486 is provided for convenience.
1487 This function may be called on partially-opened streams, but it will always
1488 return the channel count of the Opus stream in the first link.
1489 \param _of The \c OggOpusFile from which to retrieve the channel count.
1490 \param _li The index of the link whose channel count should be retrieved.
1491 Use a negative number to get the channel count of the current
1492 link.
1493 \return The channel count of the given link.
1494 If \a _li is greater than the total number of links, this returns
1495 the channel count of the last link.
1496 If the stream is not seekable, this always returns the channel count
1497 of the current link.*/
1498int op_channel_count(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1499
1500/**Get the total (compressed) size of the stream, or of an individual link in
1501 a (possibly-chained) Ogg Opus stream, including all headers and Ogg muxing
1502 overhead.
1503 \warning If the Opus stream (or link) is concurrently multiplexed with other
1504 logical streams (e.g., video), this returns the size of the entire stream
1505 (or link), not just the number of bytes in the first logical Opus stream.
1506 Returning the latter would require scanning the entire file.
1507 \param _of The \c OggOpusFile from which to retrieve the compressed size.
1508 \param _li The index of the link whose compressed size should be computed.
1509 Use a negative number to get the compressed size of the entire
1510 stream.
1511 \return The compressed size of the entire stream if \a _li is negative, the
1512 compressed size of link \a _li if it is non-negative, or a negative
1513 value on error.
1514 The compressed size of the entire stream may be smaller than that
1515 of the underlying stream if trailing garbage was detected in the
1516 file.
1517 \retval #OP_EINVAL The stream is not seekable (so we can't know the length),
1518 \a _li wasn't less than the total number of links in
1519 the stream, or the stream was only partially open.*/
1520opus_int64 op_raw_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1521
1522/**Get the total PCM length (number of samples at 48 kHz) of the stream, or of
1523 an individual link in a (possibly-chained) Ogg Opus stream.
1524 Users looking for <code>op_time_total()</code> should use op_pcm_total()
1525 instead.
1526 Because timestamps in Opus are fixed at 48 kHz, there is no need for a
1527 separate function to convert this to seconds (and leaving it out avoids
1528 introducing floating point to the API, for those that wish to avoid it).
1529 \param _of The \c OggOpusFile from which to retrieve the PCM offset.
1530 \param _li The index of the link whose PCM length should be computed.
1531 Use a negative number to get the PCM length of the entire stream.
1532 \return The PCM length of the entire stream if \a _li is negative, the PCM
1533 length of link \a _li if it is non-negative, or a negative value on
1534 error.
1535 \retval #OP_EINVAL The stream is not seekable (so we can't know the length),
1536 \a _li wasn't less than the total number of links in
1537 the stream, or the stream was only partially open.*/
1538ogg_int64_t op_pcm_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1539
1540/**Get the ID header information for the given link in a (possibly chained) Ogg
1541 Opus stream.
1542 This function may be called on partially-opened streams, but it will always
1543 return the ID header information of the Opus stream in the first link.
1544 \param _of The \c OggOpusFile from which to retrieve the ID header
1545 information.
1546 \param _li The index of the link whose ID header information should be
1547 retrieved.
1548 Use a negative number to get the ID header information of the
1549 current link.
1550 For an unseekable stream, \a _li is ignored, and the ID header
1551 information for the current link is always returned, if
1552 available.
1553 \return The contents of the ID header for the given link.*/
1554const OpusHead *op_head(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1555
1556/**Get the comment header information for the given link in a (possibly
1557 chained) Ogg Opus stream.
1558 This function may be called on partially-opened streams, but it will always
1559 return the tags from the Opus stream in the first link.
1560 \param _of The \c OggOpusFile from which to retrieve the comment header
1561 information.
1562 \param _li The index of the link whose comment header information should be
1563 retrieved.
1564 Use a negative number to get the comment header information of
1565 the current link.
1566 For an unseekable stream, \a _li is ignored, and the comment
1567 header information for the current link is always returned, if
1568 available.
1569 \return The contents of the comment header for the given link, or
1570 <code>NULL</code> if this is an unseekable stream that encountered
1571 an invalid link.*/
1572const OpusTags *op_tags(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1573
1574/**Retrieve the index of the current link.
1575 This is the link that produced the data most recently read by
1576 op_read_float() or its associated functions, or, after a seek, the link
1577 that the seek target landed in.
1578 Reading more data may advance the link index (even on the first read after a
1579 seek).
1580 \param _of The \c OggOpusFile from which to retrieve the current link index.
1581 \return The index of the current link on success, or a negative value on
1582 failure.
1583 For seekable streams, this is a number between 0 (inclusive) and the
1584 value returned by op_link_count() (exclusive).
1585 For unseekable streams, this value starts at 0 and increments by one
1586 each time a new link is encountered (even though op_link_count()
1587 always returns 1).
1588 \retval #OP_EINVAL The stream was only partially open.*/
1589int op_current_link(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1590
1591/**Computes the bitrate of the stream, or of an individual link in a
1592 (possibly-chained) Ogg Opus stream.
1593 The stream must be seekable to compute the bitrate.
1594 For unseekable streams, use op_bitrate_instant() to get periodic estimates.
1595 \warning If the Opus stream (or link) is concurrently multiplexed with other
1596 logical streams (e.g., video), this uses the size of the entire stream (or
1597 link) to compute the bitrate, not just the number of bytes in the first
1598 logical Opus stream.
1599 Returning the latter requires scanning the entire file, but this may be done
1600 by decoding the whole file and calling op_bitrate_instant() once at the
1601 end.
1602 Install a trivial decoding callback with op_set_decode_callback() if you
1603 wish to skip actual decoding during this process.
1604 \param _of The \c OggOpusFile from which to retrieve the bitrate.
1605 \param _li The index of the link whose bitrate should be computed.
1606 Use a negative number to get the bitrate of the whole stream.
1607 \return The bitrate on success, or a negative value on error.
1608 \retval #OP_EINVAL The stream was only partially open, the stream was not
1609 seekable, or \a _li was larger than the number of
1610 links.*/
1611opus_int32 op_bitrate(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1612
1613/**Compute the instantaneous bitrate, measured as the ratio of bits to playable
1614 samples decoded since a) the last call to op_bitrate_instant(), b) the last
1615 seek, or c) the start of playback, whichever was most recent.
1616 This will spike somewhat after a seek or at the start/end of a chain
1617 boundary, as pre-skip, pre-roll, and end-trimming causes samples to be
1618 decoded but not played.
1619 \param _of The \c OggOpusFile from which to retrieve the bitrate.
1620 \return The bitrate, in bits per second, or a negative value on error.
1621 \retval #OP_FALSE No data has been decoded since any of the events
1622 described above.
1623 \retval #OP_EINVAL The stream was only partially open.*/
1624opus_int32 op_bitrate_instant(OggOpusFile *_of) OP_ARG_NONNULL(1);
1625
1626/**Obtain the current value of the position indicator for \a _of.
1627 \param _of The \c OggOpusFile from which to retrieve the position indicator.
1628 \return The byte position that is currently being read from.
1629 \retval #OP_EINVAL The stream was only partially open.*/
1630opus_int64 op_raw_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1631
1632/**Obtain the PCM offset of the next sample to be read.
1633 If the stream is not properly timestamped, this might not increment by the
1634 proper amount between reads, or even return monotonically increasing
1635 values.
1636 \param _of The \c OggOpusFile from which to retrieve the PCM offset.
1637 \return The PCM offset of the next sample to be read.
1638 \retval #OP_EINVAL The stream was only partially open.*/
1639ogg_int64_t op_pcm_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1640
1641/*@}*/
1642/*@}*/
1643
1644/**\defgroup stream_seeking Seeking*/
1645/*@{*/
1646/**\name Functions for seeking in Opus streams
1647
1648 These functions let you seek in Opus streams, if the underlying stream
1649 support it.
1650 Seeking is implemented for all built-in stream I/O routines, though some
1651 individual streams may not be seekable (pipes, live HTTP streams, or HTTP
1652 streams from a server that does not support <code>Range</code> requests).
1653
1654 op_raw_seek() is the fastest: it is guaranteed to perform at most one
1655 physical seek, but, since the target is a byte position, makes no guarantee
1656 how close to a given time it will come.
1657 op_pcm_seek() provides sample-accurate seeking.
1658 The number of physical seeks it requires is still quite small (often 1 or
1659 2, even in highly variable bitrate streams).
1660
1661 Seeking in Opus requires decoding some pre-roll amount before playback to
1662 allow the internal state to converge (as if recovering from packet loss).
1663 This is handled internally by <tt>libopusfile</tt>, but means there is
1664 little extra overhead for decoding up to the exact position requested
1665 (since it must decode some amount of audio anyway).
1666 It also means that decoding after seeking may not return exactly the same
1667 values as would be obtained by decoding the stream straight through.
1668 However, such differences are expected to be smaller than the loss
1669 introduced by Opus's lossy compression.*/
1670/*@{*/
1671
1672/**Seek to a byte offset relative to the <b>compressed</b> data.
1673 This also scans packets to update the PCM cursor.
1674 It will cross a logical bitstream boundary, but only if it can't get any
1675 packets out of the tail of the link to which it seeks.
1676 \param _of The \c OggOpusFile in which to seek.
1677 \param _byte_offset The byte position to seek to.
1678 This must be between 0 and #op_raw_total(\a _of,\c -1)
1679 (inclusive).
1680 \return 0 on success, or a negative error code on failure.
1681 \retval #OP_EREAD The underlying seek operation failed.
1682 \retval #OP_EINVAL The stream was only partially open, or the target was
1683 outside the valid range for the stream.
1684 \retval #OP_ENOSEEK This stream is not seekable.
1685 \retval #OP_EBADLINK Failed to initialize a decoder for a stream for an
1686 unknown reason.*/
1687int op_raw_seek(OggOpusFile *_of,opus_int64 _byte_offset) OP_ARG_NONNULL(1);
1688
1689/**Seek to the specified PCM offset, such that decoding will begin at exactly
1690 the requested position.
1691 \param _of The \c OggOpusFile in which to seek.
1692 \param _pcm_offset The PCM offset to seek to.
1693 This is in samples at 48 kHz relative to the start of the
1694 stream.
1695 \return 0 on success, or a negative value on error.
1696 \retval #OP_EREAD An underlying read or seek operation failed.
1697 \retval #OP_EINVAL The stream was only partially open, or the target was
1698 outside the valid range for the stream.
1699 \retval #OP_ENOSEEK This stream is not seekable.
1700 \retval #OP_EBADLINK We failed to find data we had seen before, or the
1701 bitstream structure was sufficiently malformed that
1702 seeking to the target destination was impossible.*/
1703int op_pcm_seek(OggOpusFile *_of,ogg_int64_t _pcm_offset) OP_ARG_NONNULL(1);
1704
1705/*@}*/
1706/*@}*/
1707
1708/**\defgroup stream_decoding Decoding*/
1709/*@{*/
1710/**\name Functions for decoding audio data
1711
1712 These functions retrieve actual decoded audio data from the stream.
1713 The general functions, op_read() and op_read_float() return 16-bit or
1714 floating-point output, both using native endian ordering.
1715 The number of channels returned can change from link to link in a chained
1716 stream.
1717 There are special functions, op_read_stereo() and op_read_float_stereo(),
1718 which always output two channels, to simplify applications which do not
1719 wish to handle multichannel audio.
1720 These downmix multichannel files to two channels, so they can always return
1721 samples in the same format for every link in a chained file.
1722
1723 If the rest of your audio processing chain can handle floating point, the
1724 floating-point routines should be preferred, as they prevent clipping and
1725 other issues which might be avoided entirely if, e.g., you scale down the
1726 volume at some other stage.
1727 However, if you intend to consume 16-bit samples directly, the conversion in
1728 <tt>libopusfile</tt> provides noise-shaping dithering and, if compiled
1729 against <tt>libopus</tt>&nbsp;1.1 or later, soft-clipping prevention.
1730
1731 <tt>libopusfile</tt> can also be configured at compile time to use the
1732 fixed-point <tt>libopus</tt> API.
1733 If so, <tt>libopusfile</tt>'s floating-point API may also be disabled.
1734 In that configuration, nothing in <tt>libopusfile</tt> will use any
1735 floating-point operations, to simplify support on devices without an
1736 adequate FPU.
1737
1738 \warning HTTPS streams may be be vulnerable to truncation attacks if you do
1739 not check the error return code from op_read_float() or its associated
1740 functions.
1741 If the remote peer does not close the connection gracefully (with a TLS
1742 "close notify" message), these functions will return #OP_EREAD instead of 0
1743 when they reach the end of the file.
1744 If you are reading from an <https:> URL (particularly if seeking is not
1745 supported), you should make sure to check for this error and warn the user
1746 appropriately.*/
1747/*@{*/
1748
1749/**Indicates that the decoding callback should produce signed 16-bit
1750 native-endian output samples.*/
1751#define OP_DEC_FORMAT_SHORT (7008)
1752/**Indicates that the decoding callback should produce 32-bit native-endian
1753 float samples.*/
1754#define OP_DEC_FORMAT_FLOAT (7040)
1755
1756/**Indicates that the decoding callback did not decode anything, and that
1757 <tt>libopusfile</tt> should decode normally instead.*/
1758#define OP_DEC_USE_DEFAULT (6720)
1759
1760/**Called to decode an Opus packet.
1761 This should invoke the functional equivalent of opus_multistream_decode() or
1762 opus_multistream_decode_float(), except that it returns 0 on success
1763 instead of the number of decoded samples (which is known a priori).
1764 \param _ctx The application-provided callback context.
1765 \param _decoder The decoder to use to decode the packet.
1766 \param[out] _pcm The buffer to decode into.
1767 This will always have enough room for \a _nchannels of
1768 \a _nsamples samples, which should be placed into this
1769 buffer interleaved.
1770 \param _op The packet to decode.
1771 This will always have its granule position set to a valid
1772 value.
1773 \param _nsamples The number of samples expected from the packet.
1774 \param _nchannels The number of channels expected from the packet.
1775 \param _format The desired sample output format.
1776 This is either #OP_DEC_FORMAT_SHORT or
1777 #OP_DEC_FORMAT_FLOAT.
1778 \param _li The index of the link from which this packet was decoded.
1779 \return A non-negative value on success, or a negative value on error.
1780 Any error codes should be the same as those returned by
1781 opus_multistream_decode() or opus_multistream_decode_float().
1782 Success codes are as follows:
1783 \retval 0 Decoding was successful.
1784 The application has filled the buffer with
1785 exactly <code>\a _nsamples*\a
1786 _nchannels</code> samples in the requested
1787 format.
1788 \retval #OP_DEC_USE_DEFAULT No decoding was done.
1789 <tt>libopusfile</tt> should do the decoding
1790 by itself instead.*/
1791typedef int (*op_decode_cb_func)(void *_ctx,OpusMSDecoder *_decoder,void *_pcm,
1792 const ogg_packet *_op,int _nsamples,int _nchannels,int _format,int _li);
1793
1794/**Sets the packet decode callback function.
1795 If set, this is called once for each packet that needs to be decoded.
1796 This can be used by advanced applications to do additional processing on the
1797 compressed or uncompressed data.
1798 For example, an application might save the final entropy coder state for
1799 debugging and testing purposes, or it might apply additional filters
1800 before the downmixing, dithering, or soft-clipping performed by
1801 <tt>libopusfile</tt>, so long as these filters do not introduce any
1802 latency.
1803
1804 A call to this function is no guarantee that the audio will eventually be
1805 delivered to the application.
1806 <tt>libopusfile</tt> may discard some or all of the decoded audio data
1807 (i.e., at the beginning or end of a link, or after a seek), however the
1808 callback is still required to provide all of it.
1809 \param _of The \c OggOpusFile on which to set the decode callback.
1810 \param _decode_cb The callback function to call.
1811 This may be <code>NULL</code> to disable calling the
1812 callback.
1813 \param _ctx The application-provided context pointer to pass to the
1814 callback on each call.*/
1815void op_set_decode_callback(OggOpusFile *_of,
1816 op_decode_cb_func _decode_cb,void *_ctx) OP_ARG_NONNULL(1);
1817
1818/**Gain offset type that indicates that the provided offset is relative to the
1819 header gain.
1820 This is the default.*/
1821#define OP_HEADER_GAIN (0)
1822
1823/**Gain offset type that indicates that the provided offset is relative to the
1824 R128_ALBUM_GAIN value (if any), in addition to the header gain.*/
1825#define OP_ALBUM_GAIN (3007)
1826
1827/**Gain offset type that indicates that the provided offset is relative to the
1828 R128_TRACK_GAIN value (if any), in addition to the header gain.*/
1829#define OP_TRACK_GAIN (3008)
1830
1831/**Gain offset type that indicates that the provided offset should be used as
1832 the gain directly, without applying any the header or track gains.*/
1833#define OP_ABSOLUTE_GAIN (3009)
1834
1835/**Sets the gain to be used for decoded output.
1836 By default, the gain in the header is applied with no additional offset.
1837 The total gain (including header gain and/or track gain, if applicable, and
1838 this offset), will be clamped to [-32768,32767]/256 dB.
1839 This is more than enough to saturate or underflow 16-bit PCM.
1840 \note The new gain will not be applied to any already buffered, decoded
1841 output.
1842 This means you cannot change it sample-by-sample, as at best it will be
1843 updated packet-by-packet.
1844 It is meant for setting a target volume level, rather than applying smooth
1845 fades, etc.
1846 \param _of The \c OggOpusFile on which to set the gain offset.
1847 \param _gain_type One of #OP_HEADER_GAIN, #OP_ALBUM_GAIN,
1848 #OP_TRACK_GAIN, or #OP_ABSOLUTE_GAIN.
1849 \param _gain_offset_q8 The gain offset to apply, in 1/256ths of a dB.
1850 \return 0 on success or a negative value on error.
1851 \retval #OP_EINVAL The \a _gain_type was unrecognized.*/
1852int op_set_gain_offset(OggOpusFile *_of,
1853 int _gain_type,opus_int32 _gain_offset_q8) OP_ARG_NONNULL(1);
1854
1855/**Sets whether or not dithering is enabled for 16-bit decoding.
1856 By default, when <tt>libopusfile</tt> is compiled to use floating-point
1857 internally, calling op_read() or op_read_stereo() will first decode to
1858 float, and then convert to fixed-point using noise-shaping dithering.
1859 This flag can be used to disable that dithering.
1860 When the application uses op_read_float() or op_read_float_stereo(), or when
1861 the library has been compiled to decode directly to fixed point, this flag
1862 has no effect.
1863 \param _of The \c OggOpusFile on which to enable or disable dithering.
1864 \param _enabled A non-zero value to enable dithering, or 0 to disable it.*/
1865void op_set_dither_enabled(OggOpusFile *_of,int _enabled) OP_ARG_NONNULL(1);
1866
1867/**Reads more samples from the stream.
1868 \note Although \a _buf_size must indicate the total number of values that
1869 can be stored in \a _pcm, the return value is the number of samples
1870 <em>per channel</em>.
1871 This is done because
1872 <ol>
1873 <li>The channel count cannot be known a priori (reading more samples might
1874 advance us into the next link, with a different channel count), so
1875 \a _buf_size cannot also be in units of samples per channel,</li>
1876 <li>Returning the samples per channel matches the <code>libopus</code> API
1877 as closely as we're able,</li>
1878 <li>Returning the total number of values instead of samples per channel
1879 would mean the caller would need a division to compute the samples per
1880 channel, and might worry about the possibility of getting back samples
1881 for some channels and not others, and</li>
1882 <li>This approach is relatively fool-proof: if an application passes too
1883 small a value to \a _buf_size, they will simply get fewer samples back,
1884 and if they assume the return value is the total number of values, then
1885 they will simply read too few (rather than reading too many and going
1886 off the end of the buffer).</li>
1887 </ol>
1888 \param _of The \c OggOpusFile from which to read.
1889 \param[out] _pcm A buffer in which to store the output PCM samples, as
1890 signed native-endian 16-bit values at 48&nbsp;kHz
1891 with a nominal range of <code>[-32768,32767)</code>.
1892 Multiple channels are interleaved using the
1893 <a href="https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-810004.3.9">Vorbis
1894 channel ordering</a>.
1895 This must have room for at least \a _buf_size values.
1896 \param _buf_size The number of values that can be stored in \a _pcm.
1897 It is recommended that this be large enough for at
1898 least 120 ms of data at 48 kHz per channel (5760
1899 values per channel).
1900 Smaller buffers will simply return less data, possibly
1901 consuming more memory to buffer the data internally.
1902 <tt>libopusfile</tt> may return less data than
1903 requested.
1904 If so, there is no guarantee that the remaining data
1905 in \a _pcm will be unmodified.
1906 \param[out] _li The index of the link this data was decoded from.
1907 You may pass <code>NULL</code> if you do not need this
1908 information.
1909 If this function fails (returning a negative value),
1910 this parameter is left unset.
1911 \return The number of samples read per channel on success, or a negative
1912 value on failure.
1913 The channel count can be retrieved on success by calling
1914 <code>op_head(_of,*_li)</code>.
1915 The number of samples returned may be 0 if the buffer was too small
1916 to store even a single sample for all channels, or if end-of-file
1917 was reached.
1918 The list of possible failure codes follows.
1919 Most of them can only be returned by unseekable, chained streams
1920 that encounter a new link.
1921 \retval #OP_HOLE There was a hole in the data, and some samples
1922 may have been skipped.
1923 Call this function again to continue decoding
1924 past the hole.
1925 \retval #OP_EREAD An underlying read operation failed.
1926 This may signal a truncation attack from an
1927 <https:> source.
1928 \retval #OP_EFAULT An internal memory allocation failed.
1929 \retval #OP_EIMPL An unseekable stream encountered a new link that
1930 used a feature that is not implemented, such as
1931 an unsupported channel family.
1932 \retval #OP_EINVAL The stream was only partially open.
1933 \retval #OP_ENOTFORMAT An unseekable stream encountered a new link that
1934 did not have any logical Opus streams in it.
1935 \retval #OP_EBADHEADER An unseekable stream encountered a new link with a
1936 required header packet that was not properly
1937 formatted, contained illegal values, or was
1938 missing altogether.
1939 \retval #OP_EVERSION An unseekable stream encountered a new link with
1940 an ID header that contained an unrecognized
1941 version number.
1942 \retval #OP_EBADPACKET Failed to properly decode the next packet.
1943 \retval #OP_EBADLINK We failed to find data we had seen before.
1944 \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
1945 a starting timestamp that failed basic validity
1946 checks.*/
1947OP_WARN_UNUSED_RESULT int op_read(OggOpusFile *_of,
1948 opus_int16 *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
1949
1950/**Reads more samples from the stream.
1951 \note Although \a _buf_size must indicate the total number of values that
1952 can be stored in \a _pcm, the return value is the number of samples
1953 <em>per channel</em>.
1954 <ol>
1955 <li>The channel count cannot be known a priori (reading more samples might
1956 advance us into the next link, with a different channel count), so
1957 \a _buf_size cannot also be in units of samples per channel,</li>
1958 <li>Returning the samples per channel matches the <code>libopus</code> API
1959 as closely as we're able,</li>
1960 <li>Returning the total number of values instead of samples per channel
1961 would mean the caller would need a division to compute the samples per
1962 channel, and might worry about the possibility of getting back samples
1963 for some channels and not others, and</li>
1964 <li>This approach is relatively fool-proof: if an application passes too
1965 small a value to \a _buf_size, they will simply get fewer samples back,
1966 and if they assume the return value is the total number of values, then
1967 they will simply read too few (rather than reading too many and going
1968 off the end of the buffer).</li>
1969 </ol>
1970 \param _of The \c OggOpusFile from which to read.
1971 \param[out] _pcm A buffer in which to store the output PCM samples as
1972 signed floats at 48&nbsp;kHz with a nominal range of
1973 <code>[-1.0,1.0]</code>.
1974 Multiple channels are interleaved using the
1975 <a href="https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-810004.3.9">Vorbis
1976 channel ordering</a>.
1977 This must have room for at least \a _buf_size floats.
1978 \param _buf_size The number of floats that can be stored in \a _pcm.
1979 It is recommended that this be large enough for at
1980 least 120 ms of data at 48 kHz per channel (5760
1981 samples per channel).
1982 Smaller buffers will simply return less data, possibly
1983 consuming more memory to buffer the data internally.
1984 If less than \a _buf_size values are returned,
1985 <tt>libopusfile</tt> makes no guarantee that the
1986 remaining data in \a _pcm will be unmodified.
1987 \param[out] _li The index of the link this data was decoded from.
1988 You may pass <code>NULL</code> if you do not need this
1989 information.
1990 If this function fails (returning a negative value),
1991 this parameter is left unset.
1992 \return The number of samples read per channel on success, or a negative
1993 value on failure.
1994 The channel count can be retrieved on success by calling
1995 <code>op_head(_of,*_li)</code>.
1996 The number of samples returned may be 0 if the buffer was too small
1997 to store even a single sample for all channels, or if end-of-file
1998 was reached.
1999 The list of possible failure codes follows.
2000 Most of them can only be returned by unseekable, chained streams
2001 that encounter a new link.
2002 \retval #OP_HOLE There was a hole in the data, and some samples
2003 may have been skipped.
2004 Call this function again to continue decoding
2005 past the hole.
2006 \retval #OP_EREAD An underlying read operation failed.
2007 This may signal a truncation attack from an
2008 <https:> source.
2009 \retval #OP_EFAULT An internal memory allocation failed.
2010 \retval #OP_EIMPL An unseekable stream encountered a new link that
2011 used a feature that is not implemented, such as
2012 an unsupported channel family.
2013 \retval #OP_EINVAL The stream was only partially open.
2014 \retval #OP_ENOTFORMAT An unseekable stream encountered a new link that
2015 did not have any logical Opus streams in it.
2016 \retval #OP_EBADHEADER An unseekable stream encountered a new link with a
2017 required header packet that was not properly
2018 formatted, contained illegal values, or was
2019 missing altogether.
2020 \retval #OP_EVERSION An unseekable stream encountered a new link with
2021 an ID header that contained an unrecognized
2022 version number.
2023 \retval #OP_EBADPACKET Failed to properly decode the next packet.
2024 \retval #OP_EBADLINK We failed to find data we had seen before.
2025 \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
2026 a starting timestamp that failed basic validity
2027 checks.*/
2028OP_WARN_UNUSED_RESULT int op_read_float(OggOpusFile *_of,
2029 float *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
2030
2031/**Reads more samples from the stream and downmixes to stereo, if necessary.
2032 This function is intended for simple players that want a uniform output
2033 format, even if the channel count changes between links in a chained
2034 stream.
2035 \note \a _buf_size indicates the total number of values that can be stored
2036 in \a _pcm, while the return value is the number of samples <em>per
2037 channel</em>, even though the channel count is known, for consistency with
2038 op_read().
2039 \param _of The \c OggOpusFile from which to read.
2040 \param[out] _pcm A buffer in which to store the output PCM samples, as
2041 signed native-endian 16-bit values at 48&nbsp;kHz
2042 with a nominal range of <code>[-32768,32767)</code>.
2043 The left and right channels are interleaved in the
2044 buffer.
2045 This must have room for at least \a _buf_size values.
2046 \param _buf_size The number of values that can be stored in \a _pcm.
2047 It is recommended that this be large enough for at
2048 least 120 ms of data at 48 kHz per channel (11520
2049 values total).
2050 Smaller buffers will simply return less data, possibly
2051 consuming more memory to buffer the data internally.
2052 If less than \a _buf_size values are returned,
2053 <tt>libopusfile</tt> makes no guarantee that the
2054 remaining data in \a _pcm will be unmodified.
2055 \return The number of samples read per channel on success, or a negative
2056 value on failure.
2057 The number of samples returned may be 0 if the buffer was too small
2058 to store even a single sample for both channels, or if end-of-file
2059 was reached.
2060 The list of possible failure codes follows.
2061 Most of them can only be returned by unseekable, chained streams
2062 that encounter a new link.
2063 \retval #OP_HOLE There was a hole in the data, and some samples
2064 may have been skipped.
2065 Call this function again to continue decoding
2066 past the hole.
2067 \retval #OP_EREAD An underlying read operation failed.
2068 This may signal a truncation attack from an
2069 <https:> source.
2070 \retval #OP_EFAULT An internal memory allocation failed.
2071 \retval #OP_EIMPL An unseekable stream encountered a new link that
2072 used a feature that is not implemented, such as
2073 an unsupported channel family.
2074 \retval #OP_EINVAL The stream was only partially open.
2075 \retval #OP_ENOTFORMAT An unseekable stream encountered a new link that
2076 did not have any logical Opus streams in it.
2077 \retval #OP_EBADHEADER An unseekable stream encountered a new link with a
2078 required header packet that was not properly
2079 formatted, contained illegal values, or was
2080 missing altogether.
2081 \retval #OP_EVERSION An unseekable stream encountered a new link with
2082 an ID header that contained an unrecognized
2083 version number.
2084 \retval #OP_EBADPACKET Failed to properly decode the next packet.
2085 \retval #OP_EBADLINK We failed to find data we had seen before.
2086 \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
2087 a starting timestamp that failed basic validity
2088 checks.*/
2089OP_WARN_UNUSED_RESULT int op_read_stereo(OggOpusFile *_of,
2090 opus_int16 *_pcm,int _buf_size) OP_ARG_NONNULL(1);
2091
2092/**Reads more samples from the stream and downmixes to stereo, if necessary.
2093 This function is intended for simple players that want a uniform output
2094 format, even if the channel count changes between links in a chained
2095 stream.
2096 \note \a _buf_size indicates the total number of values that can be stored
2097 in \a _pcm, while the return value is the number of samples <em>per
2098 channel</em>, even though the channel count is known, for consistency with
2099 op_read_float().
2100 \param _of The \c OggOpusFile from which to read.
2101 \param[out] _pcm A buffer in which to store the output PCM samples, as
2102 signed floats at 48&nbsp;kHz with a nominal range of
2103 <code>[-1.0,1.0]</code>.
2104 The left and right channels are interleaved in the
2105 buffer.
2106 This must have room for at least \a _buf_size values.
2107 \param _buf_size The number of values that can be stored in \a _pcm.
2108 It is recommended that this be large enough for at
2109 least 120 ms of data at 48 kHz per channel (11520
2110 values total).
2111 Smaller buffers will simply return less data, possibly
2112 consuming more memory to buffer the data internally.
2113 If less than \a _buf_size values are returned,
2114 <tt>libopusfile</tt> makes no guarantee that the
2115 remaining data in \a _pcm will be unmodified.
2116 \return The number of samples read per channel on success, or a negative
2117 value on failure.
2118 The number of samples returned may be 0 if the buffer was too small
2119 to store even a single sample for both channels, or if end-of-file
2120 was reached.
2121 The list of possible failure codes follows.
2122 Most of them can only be returned by unseekable, chained streams
2123 that encounter a new link.
2124 \retval #OP_HOLE There was a hole in the data, and some samples
2125 may have been skipped.
2126 Call this function again to continue decoding
2127 past the hole.
2128 \retval #OP_EREAD An underlying read operation failed.
2129 This may signal a truncation attack from an
2130 <https:> source.
2131 \retval #OP_EFAULT An internal memory allocation failed.
2132 \retval #OP_EIMPL An unseekable stream encountered a new link that
2133 used a feature that is not implemented, such as
2134 an unsupported channel family.
2135 \retval #OP_EINVAL The stream was only partially open.
2136 \retval #OP_ENOTFORMAT An unseekable stream encountered a new link that
2137 that did not have any logical Opus streams in it.
2138 \retval #OP_EBADHEADER An unseekable stream encountered a new link with a
2139 required header packet that was not properly
2140 formatted, contained illegal values, or was
2141 missing altogether.
2142 \retval #OP_EVERSION An unseekable stream encountered a new link with
2143 an ID header that contained an unrecognized
2144 version number.
2145 \retval #OP_EBADPACKET Failed to properly decode the next packet.
2146 \retval #OP_EBADLINK We failed to find data we had seen before.
2147 \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
2148 a starting timestamp that failed basic validity
2149 checks.*/
2150OP_WARN_UNUSED_RESULT int op_read_float_stereo(OggOpusFile *_of,
2151 float *_pcm,int _buf_size) OP_ARG_NONNULL(1);
2152
2153/*@}*/
2154/*@}*/
2155
2156# if OP_GNUC_PREREQ(4,0)
2157# pragma GCC visibility pop
2158# endif
2159
2160# if defined(__cplusplus)
2161}
2162# endif
2163
2164#endif
2165