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