This adds support for accessing any binary metadata at the end of
 the comment header, as first specified in
 <https://tools.ietf.org/html/draft-ietf-codec-oggopus-05>.
It also allows the data to be set and preserves the data when
 doing deep copies.

This includes convenience routines specifying the album gain should
 be applied and for parsing the tag.

If an Opus stream is currently multiplexed with other streams, we
 would have to scan the whole file to identify the pages that
 belong to just the stream we play back.
That's probably not what the user wants, and if it is, they have a
 way to do that (using op_bitrate_instant()).
Document this so as not to surprise developers.

Thanks to Lithopsian for the report.

This makes it clear they don't modify the state, which is a useful
 indicator of what is safe to call from the application decode
 callback.

Otherwise we would have failed to open the stream.

This is to correspond to the feature in opus-tools's opusdec.
opusdec itself probably won't be able to use it, because it still
 wants to do dithering after resampling, but the motivation for the
 feature is the same.

This is needed to allow advanced usage, like that of opusdec in
 opus-tools, which can simulate packet loss or save the range coder
 state for decoder verification.
It could also be used in a pinch to use libopusfile for access to
 the raw Ogg packets, though this is somewhat of a hack.

Also refactor the other tag functions to centralize the memory
 allocation logic, plus a few other minor cleanups.

It seems somewhat silly to have to write your own strcasecmp to
 satisfy the usage pattern found in opusfile_example: scanning the
 whole tags list and handling certain tags specially (as opposed to
 searching for specific tags, as opus_tags_query() does).
Given that we were already using an equivalent function internally
 to implement opus_tags_query, just expose it directly.

Mostly minor stuff.

This allows the application to report details about the server for
 HTTP[S] streams.
For all HTTP[S], this includes the server software, content-type,
 and whether or not it's using HTTPS.
For live streams, it also includes the station name, description,
 genre, homepage, nominal bitrate, and whether or not it's publicly
 listed.

I guess no one was using these.
Clearly we need to test this more often, but this is a pain without
 a reliable public proxy, or a local proxy server setup.

This makes it easier for applications to support album art.
This is still relatively untested.

As requested here:
http://www.hydrogenaudio.org/forums/index.php?showtopic=101817

A new op_set_gain_offset() allows the application to provide its own
 offset to the current decoder gain setting, as well as specify what
 offsets should be applied.
The header gain alone is still the default, but the application may
 also request that the track gain be applied, or that neither be
 applied.

In addition, an op_get_track_gain() function can parse the track
 gain out of a set of comment tags.
This is mainly provided as a convenience for applications that need
 this information, so they don't have to write their own parser.

- Provide an Overview section which describes some of the general
   design decisions of the libopusfile API.
- Explicitly state that we always decode at 48 kHz.
- Make it clearer that we always apply the header gain.
- Document the automatic soft-clipping support.
- Document that stream open failure does not close the source.
- Other minor fixes.

Thanks to tangobravo and siriusbtx for asking the questions which
 prompted this update.

stdarg.h should've been inside the include guard.

Thanks to e98 for the report.

Thanks to Ron Lee for the report.

This changes op_read_func to
a) Take a single byte count to read instead of an "item" count
    (which the http backend couldn't properly support anyway).
b) Use integers for buffer sizes to avoid having to worry about
    sign differences and whether size_t is larger or smaller than
    opus_int64, etc.
c) Return an explicit error code (instead of using errno like
    fread).
   We had already eliminated the use of errno, but we did it by
    treating read errors and EOF identically in all cases.
   This was preventing us from reporting SSL truncation attacks
    from the https backend.
   The https backend now properly reports such errors.

This commit also fixes a bug introduced in 9b57b0c2, where we
 accidentally started passing absolute offsets to the _boundary
 parameter of op_get_next_page() instead of relative offsets.
We now use absolute offsets in all places, as it is the simpler
 choice.
This matters now, because the error reported when encountering EOF
 before hitting the _boundary is no longer suppressed (but instead
 reported as OP_EBADLINK).

Finally, it removes the op_page_seek() function.
Except for the time needed to decode forward after seeking, this
 function was identical in performance to op_pcm_seek(), and Opus
 requires decoding 80 ms of data after seek anyway, so the relative
 benefit is much smaller than with Vorbis.
A survey of open-source code using libvorbisfile showed that the
 only usages of ov_page_seek() in the wild were calling it to seek
 to the start of the stream, for which op_pcm_seek() already has a
 special case that makes it just as fast.

The documentation was also updated to describe all of these chanes.

This is an incompatible API change.

Right now we have no way to add any more parameters beyond a set of
 basic binary flags.
This unifies op_url_stream_create() and
 op_url_stream_create_with_proxy() into a single function that
 takes a variable-length list of arguments, which can be extended
 in the future to include more options of any type.

This is an incompatible API change.

Thanks to Jean-Marc Valin for providing documentation feedback.
This also changes op_tags() to allow the tags to be queried on a
 partially-open file (because they've already been read and are
 available), and fixes a leak when a partially open file is freed
 instead of being fully opened.

* Now supports HTTP/1.1 persistent connections with pipelining.
  This speeds up chain enumeration on large files by almost a
   factor of 2 over http, and by roughly a factor of 4 over https.
  The difference between http and https is now much smaller.
* Add timeouts to all the socket I/O.
* Estimate the number of available bytes to read and use it when
   making connection re-use decisions.
* Add support for https with proxies using HTTP/1.1 CONNECT
   tunnels.
* Fix TLS session re-use (it requires clean shutdown).
* Various other code re-organization and minor improvements.

* Add Opus logo.
* Use @VERSION@ consistently.
* Fix some warnings/formatting exposed by a newer Doxygen versions.

The most important for the https backend:
- Implement RFC 6066 Server Name Indication.
- Implement SSL session resumption.
  This gives less of a speed improvement than you might think.

Splits the documentation into sections and provides an overview.
Also explicitly document which functions can and cannot be called on
 partially-open streams, and fix-up a few things to behave as
 documented.

This is pretty preliminary for now.
Seeking performance isn't great, and there's no caching.
I'm sure there's also lots of bugs.

Apparently just declaring the functions in the header is not good
 enough.
Currently completely untested.

3f18c55f moved it out of opus/, so strip the prefix.

This matches the convention used by opus itself, where
headers are included without a prefix, and the build
must do -I/path/to/opus to find the appropriate versions.

More consistent formatting, s/file/stream/g, and finish adding
 function warning attributes.

Move this out of opusfile_example and into the API proper.

This fixes the build to use the headers returned by pkg-config.
The opus library assumes the called will pass -I/path/to/opus
so #include <opus.h> will work.

It wasn't actually implemented.

Seeking and playback work, at least as far as the examples test
 them.
There are probably still lots of bugs.