Alexander Traud authored 3 years ago and Ralph Giles committed 3 years ago

HREF based links work in the PDF documentation but not in the HTML
documentation because the callback routines are on a different HTML
page.

Signed-off-by: Ralph Giles <giles@thaumas.net>

Alexander Traud authored 3 years ago and Ralph Giles committed 3 years ago

Since doxygen 1.8.16, opening and closing a group must not be done as
C comment but as doxygen command. In other words, not one but two
asterisk characters are required so that doxygen finds a group.

Fixes #2332

Signed-off-by: Ralph Giles <giles@thaumas.net>

Alexander Traud authored 3 years ago and Ralph Giles committed 3 years ago

It is OK to say, those are not used, yet.

Signed-off-by: Ralph Giles <giles@thaumas.net>

Use a secure link by default. Drop the redundant www subdomain
to keep within the 70-column width of the header.

Replace broken link to jenkins build of the opus api docs
with the current release on the website.

Fix broken links into the vorbis spec.

Update other links to use https.

We inherited the term "source" from vorbisfile's "datasource", but
 were using it interchangeably with stream.
At least one user did not even realize the that the _source
 parameter passed to op_open_callbacks() was the same as the
 _stream parameter taken by those callbacks, which is reasonable
 because we never said so.
Consistently use "stream" instead of "source" in both the
 documentation and the code.

Let people reading about the output_gain field know how to change
 the way it gets applied.

Clarify that the value returned by op_current_link() is strictly
 less than the value returned by op_link_count() for seekable
 sources.

op_raw_seek() will fail if you try to seek to a byte position
 beyond the end of the file.
However, the "end" is defined in terms of _of->end, which is
 specifically the end of the last Ogg page found in the underlying
 source (excluding any trailing non-Ogg data).
op_raw_total(_of,-1) returns the total size of the stream by using
 _of->end, but it was also subtracting the offset of the first Opus
 page in the first link.
Since there might have been other Ogg streams concurrently
 multiplexed with the first Opus stream whose BOS pages appear
 first, or there might simply be non-Ogg junk at the start, that
 left the caller with no way to determine the valid range of byte
 offsets that could be passed to op_raw_seek().

Instead, make op_raw_total() pretend the first link starts at
 offset 0, and explicitly document that it's what defines the range
 of valid values to op_raw_seek().
This is how our own seeking_example.c was using it, anyway.

Just improving the clarity in some places.

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.