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.