Subversion Repositories Games.Prince of Persia

/********************************************************************

 *                                                                  *

 * THIS FILE IS PART OF THE libopusfile SOFTWARE CODEC SOURCE CODE. *

 * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS     *

 * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *

 * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING.       *

 *                                                                  *

 * THE libopusfile SOURCE CODE IS (C) COPYRIGHT 1994-2012           *

 * by the Xiph.Org Foundation and contributors http://www.xiph.org/ *

 *                                                                  *

 ********************************************************************

 function: stdio-based convenience library for opening/seeking/decoding

 last mod: $Id: vorbisfile.h 17182 2010-04-29 03:48:32Z xiphmont $

 ********************************************************************/

#if !defined(_opusfile_h)

# define _opusfile_h (1)

/**\mainpage

   \section Introduction

   This is the documentation for the <tt>libopusfile</tt> C API.

   The <tt>libopusfile</tt> package provides a convenient high-level API for

    decoding and basic manipulation of all Ogg Opus audio streams.

   <tt>libopusfile</tt> is implemented as a layer on top of Xiph.Org's

    reference

    <tt><a href="https://www.xiph.org/ogg/doc/libogg/reference.html">libogg</a></tt>

    and

    <tt><a href="https://mf4.xiph.org/jenkins/view/opus/job/opus/ws/doc/html/index.html">libopus</a></tt>

    libraries.

   <tt>libopusfile</tt> provides several sets of built-in routines for

    file/stream access, and may also use custom stream I/O routines provided by

    the embedded environment.

   There are built-in I/O routines provided for ANSI-compliant

    <code>stdio</code> (<code>FILE *</code>), memory buffers, and URLs

    (including <file:> URLs, plus optionally <http:> and <https:> URLs).

   \section Organization

   The main API is divided into several sections:

   - \ref stream_open_close

   - \ref stream_info

   - \ref stream_decoding

   - \ref stream_seeking

   Several additional sections are not tied to the main API.

   - \ref stream_callbacks

   - \ref header_info

   - \ref error_codes

   \section Overview

   The <tt>libopusfile</tt> API always decodes files to 48&nbsp;kHz.

   The original sample rate is not preserved by the lossy compression, though

    it is stored in the header to allow you to resample to it after decoding

    (the <tt>libopusfile</tt> API does not currently provide a resampler,

    but the

    <a href="http://www.speex.org/docs/manual/speex-manual/node7.html#SECTION00760000000000000000">the

    Speex resampler</a> is a good choice if you need one).

   In general, if you are playing back the audio, you should leave it at

    48 kHz, provided your audio hardware supports it.

   When decoding to a file, it may be worth resampling back to the original

    sample rate, so as not to surprise users who might not expect the sample

    rate to change after encoding to Opus and decoding.

   Opus files can contain anywhere from 1 to 255 channels of audio.

   The channel mappings for up to 8 channels are the same as the

    <a href="http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-800004.3.9">Vorbis

    mappings</a>.

   A special stereo API can convert everything to 2 channels, making it simple

    to support multichannel files in an application which only has stereo

    output.

   Although the <tt>libopusfile</tt> ABI provides support for the theoretical

    maximum number of channels, the current implementation does not support

    files with more than 8 channels, as they do not have well-defined channel

    mappings.

   Like all Ogg files, Opus files may be "chained".

   That is, multiple Opus files may be combined into a single, longer file just

    by concatenating the original files.

   This is commonly done in internet radio streaming, as it allows the title

    and artist to be updated each time the song changes, since each link in the

    chain includes its own set of metadata.

   <tt>libopusfile</tt> fully supports chained files.

   It will decode the first Opus stream found in each link of a chained file

    (ignoring any other streams that might be concurrently multiplexed with it,

    such as a video stream).

   The channel count can also change between links.

   If your application is not prepared to deal with this, it can use the stereo

    API to ensure the audio from all links will always get decoded into a

    common format.

   Since <tt>libopusfile</tt> always decodes to 48&nbsp;kHz, you do not have to

    worry about the sample rate changing between links (as was possible with

    Vorbis).

   This makes application support for chained files with <tt>libopusfile</tt>

    very easy.*/

# if defined(__cplusplus)

extern "C" {

# endif

# include <stdarg.h>

# include <stdio.h>

# include <ogg/ogg.h>

# include <opus_multistream.h>

/**@cond PRIVATE*/

/*Enable special features for gcc and gcc-compatible compilers.*/

# if !defined(OP_GNUC_PREREQ)

#  if defined(__GNUC__)&&defined(__GNUC_MINOR__)

#   define OP_GNUC_PREREQ(_maj,_min) \

 ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min))

#  else

#   define OP_GNUC_PREREQ(_maj,_min) 0

#  endif

# endif

# if OP_GNUC_PREREQ(4,0)

#  pragma GCC visibility push(default)

# endif

typedef struct OpusHead          OpusHead;

typedef struct OpusTags          OpusTags;

typedef struct OpusPictureTag    OpusPictureTag;

typedef struct OpusServerInfo    OpusServerInfo;

typedef struct OpusFileCallbacks OpusFileCallbacks;

typedef struct OggOpusFile       OggOpusFile;

/*Warning attributes for libopusfile functions.*/

# if OP_GNUC_PREREQ(3,4)

#  define OP_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))

# else

#  define OP_WARN_UNUSED_RESULT

# endif

# if OP_GNUC_PREREQ(3,4)

#  define OP_ARG_NONNULL(_x) __attribute__((__nonnull__(_x)))

# else

#  define OP_ARG_NONNULL(_x)

# endif

/**@endcond*/

/**\defgroup error_codes Error Codes*/

/*@{*/

/**\name List of possible error codes

   Many of the functions in this library return a negative error code when a

    function fails.

   This list provides a brief explanation of the common errors.

   See each individual function for more details on what a specific error code

    means in that context.*/

/*@{*/

/**A request did not succeed.*/

#define OP_FALSE         (-1)

/*Currently not used externally.*/

#define OP_EOF           (-2)

/**There was a hole in the page sequence numbers (e.g., a page was corrupt or

    missing).*/

#define OP_HOLE          (-3)

/**An underlying read, seek, or tell operation failed when it should have

    succeeded.*/

#define OP_EREAD         (-128)

/**A <code>NULL</code> pointer was passed where one was unexpected, or an

    internal memory allocation failed, or an internal library error was

    encountered.*/

#define OP_EFAULT        (-129)

/**The stream used a feature that is not implemented, such as an unsupported

    channel family.*/

#define OP_EIMPL         (-130)

/**One or more parameters to a function were invalid.*/

#define OP_EINVAL        (-131)

/**A purported Ogg Opus stream did not begin with an Ogg page, a purported

    header packet did not start with one of the required strings, "OpusHead" or

    "OpusTags", or a link in a chained file was encountered that did not

    contain any logical Opus streams.*/

#define OP_ENOTFORMAT    (-132)

/**A required header packet was not properly formatted, contained illegal

    values, or was missing altogether.*/

#define OP_EBADHEADER    (-133)

/**The ID header contained an unrecognized version number.*/

#define OP_EVERSION      (-134)

/*Currently not used at all.*/

#define OP_ENOTAUDIO     (-135)

/**An audio packet failed to decode properly.

   This is usually caused by a multistream Ogg packet where the durations of

    the individual Opus packets contained in it are not all the same.*/

#define OP_EBADPACKET    (-136)

/**We failed to find data we had seen before, or the bitstream structure was

    sufficiently malformed that seeking to the target destination was

    impossible.*/

#define OP_EBADLINK      (-137)

/**An operation that requires seeking was requested on an unseekable stream.*/

#define OP_ENOSEEK       (-138)

/**The first or last granule position of a link failed basic validity checks.*/

#define OP_EBADTIMESTAMP (-139)

/*@}*/

/*@}*/

/**\defgroup header_info Header Information*/

/*@{*/

/**The maximum number of channels in an Ogg Opus stream.*/

#define OPUS_CHANNEL_COUNT_MAX (255)

/**Ogg Opus bitstream information.

   This contains the basic playback parameters for a stream, and corresponds to

    the initial ID header packet of an Ogg Opus stream.*/

struct OpusHead{

  /**The Ogg Opus format version, in the range 0...255.

     The top 4 bits represent a "major" version, and the bottom four bits

      represent backwards-compatible "minor" revisions.

     The current specification describes version 1.

     This library will recognize versions up through 15 as backwards compatible

      with the current specification.

     An earlier draft of the specification described a version 0, but the only

      difference between version 1 and version 0 is that version 0 did

      not specify the semantics for handling the version field.*/

  int           version;

  /**The number of channels, in the range 1...255.*/

  int           channel_count;

  /**The number of samples that should be discarded from the beginning of the

      stream.*/

  unsigned      pre_skip;

  /**The sampling rate of the original input.

     All Opus audio is coded at 48 kHz, and should also be decoded at 48 kHz

      for playback (unless the target hardware does not support this sampling

      rate).

     However, this field may be used to resample the audio back to the original

      sampling rate, for example, when saving the output to a file.*/

  opus_uint32   input_sample_rate;

  /**The gain to apply to the decoded output, in dB, as a Q8 value in the range

      -32768...32767.

     The <tt>libopusfile</tt> API will automatically apply this gain to the

      decoded output before returning it, scaling it by

      <code>pow(10,output_gain/(20.0*256))</code>.

     You can adjust this behavior with op_set_gain_offset().*/

  int           output_gain;

  /**The channel mapping family, in the range 0...255.

     Channel mapping family 0 covers mono or stereo in a single stream.

     Channel mapping family 1 covers 1 to 8 channels in one or more streams,

      using the Vorbis speaker assignments.

     Channel mapping family 255 covers 1 to 255 channels in one or more

      streams, but without any defined speaker assignment.*/

  int           mapping_family;

  /**The number of Opus streams in each Ogg packet, in the range 1...255.*/

  int           stream_count;

  /**The number of coupled Opus streams in each Ogg packet, in the range

      0...127.

     This must satisfy <code>0 <= coupled_count <= stream_count</code> and

      <code>coupled_count + stream_count <= 255</code>.

     The coupled streams appear first, before all uncoupled streams, in an Ogg

      Opus packet.*/

  int           coupled_count;

  /**The mapping from coded stream channels to output channels.

     Let <code>index=mapping[k]</code> be the value for channel <code>k</code>.

     If <code>index<2*coupled_count</code>, then it refers to the left channel

      from stream <code>(index/2)</code> if even, and the right channel from

      stream <code>(index/2)</code> if odd.

     Otherwise, it refers to the output of the uncoupled stream

      <code>(index-coupled_count)</code>.*/

  unsigned char mapping[OPUS_CHANNEL_COUNT_MAX];

};

/**The metadata from an Ogg Opus stream.

   This structure holds the in-stream metadata corresponding to the 'comment'

    header packet of an Ogg Opus stream.

   The comment header is meant to be used much like someone jotting a quick

    note on the label of a CD.

   It should be a short, to the point text note that can be more than a couple

    words, but not more than a short paragraph.

   The metadata is stored as a series of (tag, value) pairs, in length-encoded

    string vectors, using the same format as Vorbis (without the final "framing

    bit"), Theora, and Speex, except for the packet header.

   The first occurrence of the '=' character delimits the tag and value.

   A particular tag may occur more than once, and order is significant.

   The character set encoding for the strings is always UTF-8, but the tag

    names are limited to ASCII, and treated as case-insensitive.

   See <a href="http://www.xiph.org/vorbis/doc/v-comment.html">the Vorbis

    comment header specification</a> for details.

   In filling in this structure, <tt>libopusfile</tt> will null-terminate the

    #user_comments strings for safety.

   However, the bitstream format itself treats them as 8-bit clean vectors,

    possibly containing NUL characters, so the #comment_lengths array should be

    treated as their authoritative length.

   This structure is binary and source-compatible with a

    <code>vorbis_comment</code>, and pointers to it may be freely cast to

    <code>vorbis_comment</code> pointers, and vice versa.

   It is provided as a separate type to avoid introducing a compile-time

    dependency on the libvorbis headers.*/

struct OpusTags{

  /**The array of comment string vectors.*/

  char **user_comments;

  /**An array of the corresponding length of each vector, in bytes.*/

  int   *comment_lengths;

  /**The total number of comment streams.*/

  int    comments;

  /**The null-terminated vendor string.

     This identifies the software used to encode the stream.*/

  char  *vendor;

};

/**\name Picture tag image formats*/

/*@{*/

/**The MIME type was not recognized, or the image data did not match the

    declared MIME type.*/

#define OP_PIC_FORMAT_UNKNOWN (-1)

/**The MIME type indicates the image data is really a URL.*/

#define OP_PIC_FORMAT_URL     (0)

/**The image is a JPEG.*/

#define OP_PIC_FORMAT_JPEG    (1)

/**The image is a PNG.*/

#define OP_PIC_FORMAT_PNG     (2)

/**The image is a GIF.*/

#define OP_PIC_FORMAT_GIF     (3)

/*@}*/

/**The contents of a METADATA_BLOCK_PICTURE tag.*/

struct OpusPictureTag{

  /**The picture type according to the ID3v2 APIC frame:

     <ol start="0">

     <li>Other</li>

     <li>32x32 pixels 'file icon' (PNG only)</li>

     <li>Other file icon</li>

     <li>Cover (front)</li>

     <li>Cover (back)</li>

     <li>Leaflet page</li>

     <li>Media (e.g. label side of CD)</li>

     <li>Lead artist/lead performer/soloist</li>

     <li>Artist/performer</li>

     <li>Conductor</li>

     <li>Band/Orchestra</li>

     <li>Composer</li>

     <li>Lyricist/text writer</li>

     <li>Recording Location</li>

     <li>During recording</li>

     <li>During performance</li>

     <li>Movie/video screen capture</li>

     <li>A bright colored fish</li>

     <li>Illustration</li>

     <li>Band/artist logotype</li>

     <li>Publisher/Studio logotype</li>

     </ol>

     Others are reserved and should not be used.

     There may only be one each of picture type 1 and 2 in a file.*/

  opus_int32     type;

  /**The MIME type of the picture, in printable ASCII characters 0x20-0x7E.

     The MIME type may also be <code>"-->"</code> to signify that the data part

      is a URL pointing to the picture instead of the picture data itself.

     In this case, a terminating NUL is appended to the URL string in #data,

      but #data_length is set to the length of the string excluding that

      terminating NUL.*/

  char          *mime_type;

  /**The description of the picture, in UTF-8.*/

  char          *description;

  /**The width of the picture in pixels.*/

  opus_uint32    width;

  /**The height of the picture in pixels.*/

  opus_uint32    height;

  /**The color depth of the picture in bits-per-pixel (<em>not</em>

      bits-per-channel).*/

  opus_uint32    depth;

  /**For indexed-color pictures (e.g., GIF), the number of colors used, or 0

      for non-indexed pictures.*/

  opus_uint32    colors;

  /**The length of the picture data in bytes.*/

  opus_uint32    data_length;

  /**The binary picture data.*/

  unsigned char *data;

  /**The format of the picture data, if known.

     One of

     <ul>

     <li>#OP_PIC_FORMAT_UNKNOWN,</li>

     <li>#OP_PIC_FORMAT_URL,</li>

     <li>#OP_PIC_FORMAT_JPEG,</li>

     <li>#OP_PIC_FORMAT_PNG, or</li>

     <li>#OP_PIC_FORMAT_GIF.</li>

     </ul>*/

  int            format;

};

/**\name Functions for manipulating header data

   These functions manipulate the #OpusHead and #OpusTags structures,

    which describe the audio parameters and tag-value metadata, respectively.

   These can be used to query the headers returned by <tt>libopusfile</tt>, or

    to parse Opus headers from sources other than an Ogg Opus stream, provided

    they use the same format.*/

/*@{*/

/**Parses the contents of the ID header packet of an Ogg Opus stream.

   \param[out] _head Returns the contents of the parsed packet.

                     The contents of this structure are untouched on error.

                     This may be <code>NULL</code> to merely test the header

                      for validity.

   \param[in]  _data The contents of the ID header packet.

   \param      _len  The number of bytes of data in the ID header packet.

   \return 0 on success or a negative value on error.

   \retval #OP_ENOTFORMAT If the data does not start with the "OpusHead"

                           string.

   \retval #OP_EVERSION   If the version field signaled a version this library

                           does not know how to parse.

   \retval #OP_EIMPL      If the channel mapping family was 255, which general

                           purpose players should not attempt to play.

   \retval #OP_EBADHEADER If the contents of the packet otherwise violate the

                           Ogg Opus specification:

                          <ul>

                           <li>Insufficient data,</li>

                           <li>Too much data for the known minor versions,</li>

                           <li>An unrecognized channel mapping family,</li>

                           <li>Zero channels or too many channels,</li>

                           <li>Zero coded streams,</li>

                           <li>Too many coupled streams, or</li>

                           <li>An invalid channel mapping index.</li>

                          </ul>*/

OP_WARN_UNUSED_RESULT int opus_head_parse(OpusHead *_head,

 const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);

/**Converts a granule position to a sample offset for a given Ogg Opus stream.

   The sample offset is simply <code>_gp-_head->pre_skip</code>.

   Granule position values smaller than OpusHead#pre_skip correspond to audio

    that should never be played, and thus have no associated sample offset.

   This function returns -1 for such values.

   This function also correctly handles extremely large granule positions,

    which may have wrapped around to a negative number when stored in a signed

    ogg_int64_t value.

   \param _head The #OpusHead information from the ID header of the stream.

   \param _gp   The granule position to convert.

   \return The sample offset associated with the given granule position

            (counting at a 48 kHz sampling rate), or the special value -1 on

            error (i.e., the granule position was smaller than the pre-skip

            amount).*/

ogg_int64_t opus_granule_sample(const OpusHead *_head,ogg_int64_t _gp)

 OP_ARG_NONNULL(1);

/**Parses the contents of the 'comment' header packet of an Ogg Opus stream.

   \param[out] _tags An uninitialized #OpusTags structure.

                     This returns the contents of the parsed packet.

                     The contents of this structure are untouched on error.

                     This may be <code>NULL</code> to merely test the header

                      for validity.

   \param[in]  _data The contents of the 'comment' header packet.

   \param      _len  The number of bytes of data in the 'info' header packet.

   \retval 0              Success.

   \retval #OP_ENOTFORMAT If the data does not start with the "OpusTags"

                           string.

   \retval #OP_EBADHEADER If the contents of the packet otherwise violate the

                           Ogg Opus specification.

   \retval #OP_EFAULT     If there wasn't enough memory to store the tags.*/

OP_WARN_UNUSED_RESULT int opus_tags_parse(OpusTags *_tags,

 const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);

/**Performs a deep copy of an #OpusTags structure.

   \param _dst The #OpusTags structure to copy into.

               If this function fails, the contents of this structure remain

                untouched.

   \param _src The #OpusTags structure to copy from.

   \retval 0          Success.

   \retval #OP_EFAULT If there wasn't enough memory to copy the tags.*/

int opus_tags_copy(OpusTags *_dst,const OpusTags *_src) OP_ARG_NONNULL(1);

/**Initializes an #OpusTags structure.

   This should be called on a freshly allocated #OpusTags structure before

    attempting to use it.

   \param _tags The #OpusTags structure to initialize.*/

void opus_tags_init(OpusTags *_tags) OP_ARG_NONNULL(1);

/**Add a (tag, value) pair to an initialized #OpusTags structure.

   \note Neither opus_tags_add() nor opus_tags_add_comment() support values

    containing embedded NULs, although the bitstream format does support them.

   To add such tags, you will need to manipulate the #OpusTags structure

    directly.

   \param _tags  The #OpusTags structure to add the (tag, value) pair to.

   \param _tag   A NUL-terminated, case-insensitive, ASCII string containing

                  the tag to add (without an '=' character).

   \param _value A NUL-terminated UTF-8 containing the corresponding value.

   \return 0 on success, or a negative value on failure.

   \retval #OP_EFAULT An internal memory allocation failed.*/

int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value)

 OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3);

/**Add a comment to an initialized #OpusTags structure.

   \note Neither opus_tags_add_comment() nor opus_tags_add() support comments

    containing embedded NULs, although the bitstream format does support them.

   To add such tags, you will need to manipulate the #OpusTags structure

    directly.

   \param _tags    The #OpusTags structure to add the comment to.

   \param _comment A NUL-terminated UTF-8 string containing the comment in

                    "TAG=value" form.

   \return 0 on success, or a negative value on failure.

   \retval #OP_EFAULT An internal memory allocation failed.*/

int opus_tags_add_comment(OpusTags *_tags,const char *_comment)

 OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);

/**Replace the binary suffix data at the end of the packet (if any).

   \param _tags An initialized #OpusTags structure.

   \param _data A buffer of binary data to append after the encoded user

                 comments.

                The least significant bit of the first byte of this data must

                 be set (to ensure the data is preserved by other editors).

   \param _len  The number of bytes of binary data to append.

                This may be zero to remove any existing binary suffix data.

   \return 0 on success, or a negative value on error.

   \retval #OP_EINVAL \a _len was negative, or \a _len was positive but

                       \a _data was <code>NULL</code> or the least significant

                       bit of the first byte was not set.

   \retval #OP_EFAULT An internal memory allocation failed.*/

int opus_tags_set_binary_suffix(OpusTags *_tags,

 const unsigned char *_data,int _len) OP_ARG_NONNULL(1);

/**Look up a comment value by its tag.

   \param _tags  An initialized #OpusTags structure.

   \param _tag   The tag to look up.

   \param _count The instance of the tag.

                 The same tag can appear multiple times, each with a distinct

                  value, so an index is required to retrieve them all.

                 The order in which these values appear is significant and

                  should be preserved.

                 Use opus_tags_query_count() to get the legal range for the

                  \a _count parameter.

   \return A pointer to the queried tag's value.

           This points directly to data in the #OpusTags structure.

           It should not be modified or freed by the application, and

            modifications to the structure may invalidate the pointer.

   \retval NULL If no matching tag is found.*/

const char *opus_tags_query(const OpusTags *_tags,const char *_tag,int _count)

 OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);

/**Look up the number of instances of a tag.

   Call this first when querying for a specific tag and then iterate over the

    number of instances with separate calls to opus_tags_query() to retrieve

    all the values for that tag in order.

   \param _tags An initialized #OpusTags structure.

   \param _tag  The tag to look up.

   \return The number of instances of this particular tag.*/

int opus_tags_query_count(const OpusTags *_tags,const char *_tag)

 OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);

/**Retrieve the binary suffix data at the end of the packet (if any).

   \param      _tags An initialized #OpusTags structure.

   \param[out] _len  Returns the number of bytes of binary suffix data returned.

   \return A pointer to the binary suffix data, or <code>NULL</code> if none

            was present.*/

const unsigned char *opus_tags_get_binary_suffix(const OpusTags *_tags,

 int *_len) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);

/**Get the album gain from an R128_ALBUM_GAIN tag, if one was specified.

   This searches for the first R128_ALBUM_GAIN tag with a valid signed,

    16-bit decimal integer value and returns the value.

   This routine is exposed merely for convenience for applications which wish

    to do something special with the album gain (i.e., display it).

   If you simply wish to apply the album gain instead of the header gain, you

    can use op_set_gain_offset() with an #OP_ALBUM_GAIN type and no offset.

   \param      _tags    An initialized #OpusTags structure.

   \param[out] _gain_q8 The album gain, in 1/256ths of a dB.

                        This will lie in the range [-32768,32767], and should

                         be applied in <em>addition</em> to the header gain.

                        On error, no value is returned, and the previous

                         contents remain unchanged.

   \return 0 on success, or a negative value on error.

   \retval #OP_FALSE There was no album gain available in the given tags.*/

int opus_tags_get_album_gain(const OpusTags *_tags,int *_gain_q8)

 OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);

/**Get the track gain from an R128_TRACK_GAIN tag, if one was specified.

   This searches for the first R128_TRACK_GAIN tag with a valid signed,

    16-bit decimal integer value and returns the value.

   This routine is exposed merely for convenience for applications which wish

    to do something special with the track gain (i.e., display it).

   If you simply wish to apply the track gain instead of the header gain, you

    can use op_set_gain_offset() with an #OP_TRACK_GAIN type and no offset.

   \param      _tags    An initialized #OpusTags structure.

   \param[out] _gain_q8 The track gain, in 1/256ths of a dB.

                        This will lie in the range [-32768,32767], and should

                         be applied in <em>addition</em> to the header gain.

                        On error, no value is returned, and the previous

                         contents remain unchanged.

   \return 0 on success, or a negative value on error.

   \retval #OP_FALSE There was no track gain available in the given tags.*/

int opus_tags_get_track_gain(const OpusTags *_tags,int *_gain_q8)

 OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);

/**Clears the #OpusTags structure.

   This should be called on an #OpusTags structure after it is no longer

    needed.

   It will free all memory used by the structure members.

   \param _tags The #OpusTags structure to clear.*/

void opus_tags_clear(OpusTags *_tags) OP_ARG_NONNULL(1);

/**Check if \a _comment is an instance of a \a _tag_name tag.

   \see opus_tagncompare

   \param _tag_name A NUL-terminated, case-insensitive, ASCII string containing

                     the name of the tag to check for (without the terminating

                     '=' character).

   \param _comment  The comment string to check.

   \return An integer less than, equal to, or greater than zero if \a _comment

            is found respectively, to be less than, to match, or be greater

            than a "tag=value" string whose tag matches \a _tag_name.*/

int opus_tagcompare(const char *_tag_name,const char *_comment);

/**Check if \a _comment is an instance of a \a _tag_name tag.

   This version is slightly more efficient than opus_tagcompare() if the length

    of the tag name is already known (e.g., because it is a constant).

   \see opus_tagcompare

   \param _tag_name A case-insensitive ASCII string containing the name of the

                     tag to check for (without the terminating '=' character).

   \param _tag_len  The number of characters in the tag name.

                    This must be non-negative.

   \param _comment  The comment string to check.

   \return An integer less than, equal to, or greater than zero if \a _comment

            is found respectively, to be less than, to match, or be greater

            than a "tag=value" string whose tag matches the first \a _tag_len

            characters of \a _tag_name.*/

int opus_tagncompare(const char *_tag_name,int _tag_len,const char *_comment);

/**Parse a single METADATA_BLOCK_PICTURE tag.

   This decodes the BASE64-encoded content of the tag and returns a structure

    with the MIME type, description, image parameters (if known), and the

    compressed image data.

   If the MIME type indicates the presence of an image format we recognize

    (JPEG, PNG, or GIF) and the actual image data contains the magic signature

    associated with that format, then the OpusPictureTag::format field will be

    set to the corresponding format.

   This is provided as a convenience to avoid requiring applications to parse

    the MIME type and/or do their own format detection for the commonly used

    formats.

   In this case, we also attempt to extract the image parameters directly from

    the image data (overriding any that were present in the tag, which the

    specification says applications are not meant to rely on).

   The application must still provide its own support for actually decoding the

    image data and, if applicable, retrieving that data from URLs.

   \param[out] _pic Returns the parsed picture data.

                    No sanitation is done on the type, MIME type, or

                     description fields, so these might return invalid values.

                    The contents of this structure are left unmodified on

                     failure.

   \param      _tag The METADATA_BLOCK_PICTURE tag contents.

                    The leading "METADATA_BLOCK_PICTURE=" portion is optional,

                     to allow the function to be used on either directly on the

                     values in OpusTags::user_comments or on the return value

                     of opus_tags_query().

   \return 0 on success or a negative value on error.

   \retval #OP_ENOTFORMAT The METADATA_BLOCK_PICTURE contents were not valid.

   \retval #OP_EFAULT     There was not enough memory to store the picture tag

                           contents.*/

OP_WARN_UNUSED_RESULT int opus_picture_tag_parse(OpusPictureTag *_pic,

 const char *_tag) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);

/**Initializes an #OpusPictureTag structure.

   This should be called on a freshly allocated #OpusPictureTag structure

    before attempting to use it.

   \param _pic The #OpusPictureTag structure to initialize.*/

void opus_picture_tag_init(OpusPictureTag *_pic) OP_ARG_NONNULL(1);

/**Clears the #OpusPictureTag structure.

   This should be called on an #OpusPictureTag structure after it is no longer

    needed.

   It will free all memory used by the structure members.

   \param _pic The #OpusPictureTag structure to clear.*/

void opus_picture_tag_clear(OpusPictureTag *_pic) OP_ARG_NONNULL(1);

/*@}*/

/*@}*/

/**\defgroup url_options URL Reading Options*/

/*@{*/

/**\name URL reading options

   Options for op_url_stream_create() and associated functions.

   These allow you to provide proxy configuration parameters, skip SSL

    certificate checks, etc.

   Options are processed in order, and if the same option is passed multiple

    times, only the value specified by the last occurrence has an effect

    (unless otherwise specified).

   They may be expanded in the future.*/

/*@{*/

/**@cond PRIVATE*/

/*These are the raw numbers used to define the request codes.

  They should not be used directly.*/

#define OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST (6464)

#define OP_HTTP_PROXY_HOST_REQUEST            (6528)

#define OP_HTTP_PROXY_PORT_REQUEST            (6592)

#define OP_HTTP_PROXY_USER_REQUEST            (6656)

#define OP_HTTP_PROXY_PASS_REQUEST            (6720)

#define OP_GET_SERVER_INFO_REQUEST            (6784)

#define OP_URL_OPT(_request) ((_request)+(char *)0)

/*These macros trigger compilation errors or warnings if the wrong types are

   provided to one of the URL options.*/

#define OP_CHECK_INT(_x) ((void)((_x)==(opus_int32)0),(opus_int32)(_x))

#define OP_CHECK_CONST_CHAR_PTR(_x) ((_x)+((_x)-(const char *)(_x)))

#define OP_CHECK_SERVER_INFO_PTR(_x) ((_x)+((_x)-(OpusServerInfo *)(_x)))

/**@endcond*/

/**HTTP/Shoutcast/Icecast server information associated with a URL.*/

struct OpusServerInfo{

  /**The name of the server (icy-name/ice-name).

     This is <code>NULL</code> if there was no <code>icy-name</code> or

      <code>ice-name</code> header.*/

  char        *name;

  /**A short description of the server (icy-description/ice-description).

     This is <code>NULL</code> if there was no <code>icy-description</code> or

      <code>ice-description</code> header.*/

  char        *description;

  /**The genre the server falls under (icy-genre/ice-genre).

     This is <code>NULL</code> if there was no <code>icy-genre</code> or

      <code>ice-genre</code> header.*/

  char        *genre;

  /**The homepage for the server (icy-url/ice-url).

     This is <code>NULL</code> if there was no <code>icy-url</code> or

      <code>ice-url</code> header.*/

  char        *url;

  /**The software used by the origin server (Server).

     This is <code>NULL</code> if there was no <code>Server</code> header.*/

  char        *server;

  /**The media type of the entity sent to the recepient (Content-Type).

     This is <code>NULL</code> if there was no <code>Content-Type</code>

      header.*/

  char        *content_type;

  /**The nominal stream bitrate in kbps (icy-br/ice-bitrate).

     This is <code>-1</code> if there was no <code>icy-br</code> or

      <code>ice-bitrate</code> header.*/

  opus_int32   bitrate_kbps;

  /**Flag indicating whether the server is public (<code>1</code>) or not

      (<code>0</code>) (icy-pub/ice-public).

     This is <code>-1</code> if there was no <code>icy-pub</code> or

      <code>ice-public</code> header.*/

  int          is_public;

  /**Flag indicating whether the server is using HTTPS instead of HTTP.

     This is <code>0</code> unless HTTPS is being used.

     This may not match the protocol used in the original URL if there were

      redirections.*/

  int          is_ssl;

};

/**Initializes an #OpusServerInfo structure.

   All fields are set as if the corresponding header was not available.

   \param _info The #OpusServerInfo structure to initialize.

   \note If you use this function, you must link against <tt>libopusurl</tt>.*/

void opus_server_info_init(OpusServerInfo *_info) OP_ARG_NONNULL(1);

/**Clears the #OpusServerInfo structure.

   This should be called on an #OpusServerInfo structure after it is no longer

    needed.

   It will free all memory used by the structure members.

   \param _info The #OpusServerInfo structure to clear.

   \note If you use this function, you must link against <tt>libopusurl</tt>.*/

void opus_server_info_clear(OpusServerInfo *_info) OP_ARG_NONNULL(1);

/**Skip the certificate check when connecting via TLS/SSL (https).

   \param _b <code>opus_int32</code>: Whether or not to skip the certificate

              check.

             The check will be skipped if \a _b is non-zero, and will not be

              skipped if \a _b is zero.

   \hideinitializer*/

#define OP_SSL_SKIP_CERTIFICATE_CHECK(_b) \

 OP_URL_OPT(OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST),OP_CHECK_INT(_b)

/**Proxy connections through the given host.

   If no port is specified via #OP_HTTP_PROXY_PORT, the port number defaults

    to 8080 (http-alt).

   All proxy parameters are ignored for non-http and non-https URLs.

   \param _host <code>const char *</code>: The proxy server hostname.

                This may be <code>NULL</code> to disable the use of a proxy

                 server.

   \hideinitializer*/

#define OP_HTTP_PROXY_HOST(_host) \

 OP_URL_OPT(OP_HTTP_PROXY_HOST_REQUEST),OP_CHECK_CONST_CHAR_PTR(_host)

/**Use the given port when proxying connections.

   This option only has an effect if #OP_HTTP_PROXY_HOST is specified with a

    non-<code>NULL</code> \a _host.

   If this option is not provided, the proxy port number defaults to 8080

    (http-alt).

   All proxy parameters are ignored for non-http and non-https URLs.

   \param _port <code>opus_int32</code>: The proxy server port.

                This must be in the range 0...65535 (inclusive), or the

                 URL function this is passed to will fail.

   \hideinitializer*/

#define OP_HTTP_PROXY_PORT(_port) \

 OP_URL_OPT(OP_HTTP_PROXY_PORT_REQUEST),OP_CHECK_INT(_port)

/**Use the given user name for authentication when proxying connections.

   All proxy parameters are ignored for non-http and non-https URLs.

   \param _user const char *: The proxy server user name.

                              This may be <code>NULL</code> to disable proxy

                               authentication.

                              A non-<code>NULL</code> value only has an effect

                               if #OP_HTTP_PROXY_HOST and #OP_HTTP_PROXY_PASS

                               are also specified with non-<code>NULL</code>

                               arguments.

   \hideinitializer*/

#define OP_HTTP_PROXY_USER(_user) \

 OP_URL_OPT(OP_HTTP_PROXY_USER_REQUEST),OP_CHECK_CONST_CHAR_PTR(_user)

/**Use the given password for authentication when proxying connections.

   All proxy parameters are ignored for non-http and non-https URLs.

   \param _pass const char *: The proxy server password.

                              This may be <code>NULL</code> to disable proxy

                               authentication.

                              A non-<code>NULL</code> value only has an effect

                               if #OP_HTTP_PROXY_HOST and #OP_HTTP_PROXY_USER

                               are also specified with non-<code>NULL</code>

                               arguments.

   \hideinitializer*/

#define OP_HTTP_PROXY_PASS(_pass) \

 OP_URL_OPT(OP_HTTP_PROXY_PASS_REQUEST),OP_CHECK_CONST_CHAR_PTR(_pass)

/**Parse information about the streaming server (if any) and return it.

   Very little validation is done.

   In particular, OpusServerInfo::url may not be a valid URL,

    OpusServerInfo::bitrate_kbps may not really be in kbps, and

    OpusServerInfo::content_type may not be a valid MIME type.

   The character set of the string fields is not specified anywhere, and should

    not be assumed to be valid UTF-8.

   \param _info OpusServerInfo *: Returns information about the server.

                                  If there is any error opening the stream, the

                                   contents of this structure remain

                                   unmodified.

                                  On success, fills in the structure with the

                                   server information that was available, if

                                   any.

                                  After a successful return, the contents of

                                   this structure should be freed by calling

                                   opus_server_info_clear().

   \hideinitializer*/

#define OP_GET_SERVER_INFO(_info) \

 OP_URL_OPT(OP_GET_SERVER_INFO_REQUEST),OP_CHECK_SERVER_INFO_PTR(_info)

/*@}*/

/*@}*/

/**\defgroup stream_callbacks Abstract Stream Reading Interface*/

/*@{*/

/**\name Functions for reading from streams

   These functions define the interface used to read from and seek in a stream

    of data.

   A stream does not need to implement seeking, but the decoder will not be

    able to seek if it does not do so.

   These functions also include some convenience routines for working with

    standard <code>FILE</code> pointers, complete streams stored in a single

    block of memory, or URLs.*/

/*@{*/

/**Reads up to \a _nbytes bytes of data from \a _stream.

   \param      _stream The stream to read from.

   \param[out] _ptr    The buffer to store the data in.

   \param      _nbytes The maximum number of bytes to read.

                       This function may return fewer, though it will not

                        return zero unless it reaches end-of-file.

   \return The number of bytes successfully read, or a negative value on

            error.*/

typedef int (*op_read_func)(void *_stream,unsigned char *_ptr,int _nbytes);

/**Sets the position indicator for \a _stream.

   The new position, measured in bytes, is obtained by adding \a _offset

    bytes to the position specified by \a _whence.

   If \a _whence is set to <code>SEEK_SET</code>, <code>SEEK_CUR</code>, or

    <code>SEEK_END</code>, the offset is relative to the start of the stream,

    the current position indicator, or end-of-file, respectively.

   \retval 0  Success.

   \retval -1 Seeking is not supported or an error occurred.

              <code>errno</code> need not be set.*/

typedef int (*op_seek_func)(void *_stream,opus_int64 _offset,int _whence);

/**Obtains the current value of the position indicator for \a _stream.

   \return The current position indicator.*/

typedef opus_int64 (*op_tell_func)(void *_stream);

/**Closes the underlying stream.

   \retval 0   Success.

   \retval EOF An error occurred.

               <code>errno</code> need not be set.*/

typedef int (*op_close_func)(void *_stream);

/**The callbacks used to access non-<code>FILE</code> stream resources.

   The function prototypes are basically the same as for the stdio functions

    <code>fread()</code>, <code>fseek()</code>, <code>ftell()</code>, and

    <code>fclose()</code>.

   The differences are that the <code>FILE *</code> arguments have been

    replaced with a <code>void *</code>, which is to be used as a pointer to

    whatever internal data these functions might need, that #seek and #tell

    take and return 64-bit offsets, and that #seek <em>must</em> return -1 if

    the stream is unseekable.*/

struct OpusFileCallbacks{

  /**Used to read data from the stream.

     This must not be <code>NULL</code>.*/

  op_read_func  read;

  /**Used to seek in the stream.

     This may be <code>NULL</code> if seeking is not implemented.*/

  op_seek_func  seek;

  /**Used to return the current read position in the stream.

     This may be <code>NULL</code> if seeking is not implemented.*/

  op_tell_func  tell;

  /**Used to close the stream when the decoder is freed.

     This may be <code>NULL</code> to leave the stream open.*/

  op_close_func close;

};

/**Opens a stream with <code>fopen()</code> and fills in a set of callbacks

    that can be used to access it.

   This is useful to avoid writing your own portable 64-bit seeking wrappers,

    and also avoids cross-module linking issues on Windows, where a

    <code>FILE *</code> must be accessed by routines defined in the same module

    that opened it.

   \param[out] _cb   The callbacks to use for this file.

                     If there is an error opening the file, nothing will be

                      filled in here.

   \param      _path The path to the file to open.

                     On Windows, this string must be UTF-8 (to allow access to

                      files whose names cannot be represented in the current

                      MBCS code page).

                     All other systems use the native character encoding.

   \param      _mode The mode to open the file in.

   \return A stream handle to use with the callbacks, or <code>NULL</code> on

            error.*/

OP_WARN_UNUSED_RESULT void *op_fopen(OpusFileCallbacks *_cb,

 const char *_path,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)

 OP_ARG_NONNULL(3);

/**Opens a stream with <code>fdopen()</code> and fills in a set of callbacks

    that can be used to access it.

   This is useful to avoid writing your own portable 64-bit seeking wrappers,

    and also avoids cross-module linking issues on Windows, where a

    <code>FILE *</code> must be accessed by routines defined in the same module

    that opened it.

   \param[out] _cb   The callbacks to use for this file.

                     If there is an error opening the file, nothing will be

                      filled in here.

   \param      _fd   The file descriptor to open.

   \param      _mode The mode to open the file in.

   \return A stream handle to use with the callbacks, or <code>NULL</code> on

            error.*/

OP_WARN_UNUSED_RESULT void *op_fdopen(OpusFileCallbacks *_cb,

 int _fd,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(3);

/**Opens a stream with <code>freopen()</code> and fills in a set of callbacks

    that can be used to access it.

   This is useful to avoid writing your own portable 64-bit seeking wrappers,