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.

Not all the failure paths cleaned up after themselves properly.
Thanks to tangobravo for complaining about similar issues in
 libvorbisfile, which prompted me to audit this code.

The LL suffix isn't C89, so it may not work everywhere.

This avoids at least one case where ./autogen.sh && ./configure && make
will re-run configure because the makefile rules updated something that
it depends upon. Pulling a new version from git will change the version
so we should update that at the first step rather than iterating after
the last one.

The main motivation for this is it ensures the files will actually be
rebuilt if the configuration options are changed.

Don't let AC_SEARCH_LIBS([lrintf]) add -lm to LIBS, otherwise we'll
unconditionally link everything with it.

Correctly handle the third possibility of AC_SEARCH_LIBS, that no
library at all was found.

Link libopusfile with $lrintf_lib, it uses it and will otherwise fail
with linkers that use --no-add-needed / --no-copy-dt-needed-entries.

Don't bother to test for doxygen if using it is --disable'd.

We shouldn't ever have any trailing newlines that need trimming here,
and the _s version wasn't added to m4sugar.m4 until autoconf 2.63b,
so this will let it work with 2.13 again.

This shouldn't really be necessary when static linking, but would
 be if someone wanted chang the Makefile to build shared libraries.

Partly just to give us an extra commit to test the versioning,
but they really aren't needed in any of those cases, and now
we're consistent about not using them everywhere.

This one meets or exceeds the following requirements:

 - Version is checked/updated for every build action when in the git repo.
   Does not require the user to re- ./configure to get the correct version.

 - Version is not updated automatically when using exported tarball source.
   Avoids accidentally getting a wrong version from some other git repo in
   a parent directory of the source, and allows setting the correct version
   for distro package exports.

 - Automatic updating can be manually suppressed.
   For developers doing lots of change/rebuild cycles they don't plan to
   release, when they don't want a full rebuild triggered for every commit,
   and again for every change made immediately after a commit.
   The version will still always be updated if they do a `make dist`.

 - Does not require any manual updating of versions in the mainline git
   repo for each release aside from normal tagging.  The version is
   recorded in one file only, that is automatically generated and will
   never need to be committed.

 - Does not require gnu-make features for the autoconf builds.

It does not currently:

 - Keep a checksum of every source file in tarball releases to mangle the
   version if people modify the tarball source.  Responsible people can
   manually update the version easily though in such cases.

This reverts commit 4e06a90e.
We don't need this if we always build libopusurl.

If --disable-http is used it will just only have file URL support.

This makes it easier to split http.c and friends into their own
 library.
This allows distributions to ship a libopusfile with generic Opus
 parsing support, and a libopusurl with http/https support.
Keeping the latter in a separate library means that GPL
 applications don't have to link against the GPL-incompatible
 openssl, and distributions don't have to disable http support to
 allow GPL applications to use libopusfile.

If we actually have 255 packets on a page, this assertion always
 triggers, because ogg_stream_packetout doesn't fail until we ask
 for the _next_ packet.

If a stream starts with a non-zero granpos, we would subtract 80 ms
 from the target time, and then report failure when the best page
 we could find (the first page in the link) had a granpos larger
 than that.
This worked for normal streams because the subtraction would fail
 (granpos can't wrap past -1) and we checked for that.

This shouldn't be necessary, but apparently on OS X 10.4 fseeko()
 takes fpos_t instead of off_t, and thus doesn't guarantee that
 off_t is defined.

Matthew Chung authored 12 years ago and Timothy B. Terriberry committed 11 years ago

Signed-off-by: Timothy B. Terriberry <tterribe@xiph.org>

Ulrich Klauer authored 11 years ago and Timothy B. Terriberry committed 11 years ago

Libraries that are used internally by opusfile but are not part of
 its API should be listed in pkg-config "private" clauses.
Otherwise executables that are linked dynamically against opusfile
 will have unneeded direct dependencies (overlinking).

Signed-off-by: Timothy B. Terriberry <tterribe@xiph.org>

Ulrich Klauer authored 11 years ago and Timothy B. Terriberry committed 11 years ago

The library does not actually do any playback, as it does no sound
 output.

Signed-off-by: Timothy B. Terriberry <tterribe@xiph.org>

Ulrich Klauer authored 12 years ago and Timothy B. Terriberry committed 11 years ago

Signed-off-by: Timothy B. Terriberry <tterribe@xiph.org>

Ulrich Klauer authored 12 years ago and Timothy B. Terriberry committed 11 years ago

AC_SEARCH_LIBS will give a result of "none required" if the relevant
 function is available without any special libraries.
This is the case for lrintf on MinGW.
Make sure this special value isn't put verbatim into the pkg-config
 files, as it would cause the linker to search for files named
 "none" and "required", and fail.

Signed-off-by: Timothy B. Terriberry <tterribe@xiph.org>

I thought I had tested this before, but it was sufficiently broken
 that clearly I had not.

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

- Made OP_SOFT_CLIP defined only when using floating point (libopus
   handles clipping when using the fixed-point API).
- Struct rearrangement for theoretically better packing on some
   platforms.
- Reset the state tracking channel count when re-initializing a
   decoder (and not the dither mute, because that gets reset for
   free).

When we decode using libopus's fixed-point APIs, libopus internally
 applies soft clipping prevention.
When we decode using libopus's floating-point APIs, this behavior
 is disabled.
If we're ultimately planning to output the data to the user in
 fixed-point, we need to apply the clipping prevention ourselves.

The caller can switch between the fixed/float APIs and the
 stereo/multichannel APIs on every call.
Detect this and reset the dither state to avoid potentially
 injecting noise from a very out-of-date state when switching from
 fixed to float back to fixed, or from the wrong channels when
 switching between stereo and multichannel.
Normal applications won't do this stuff, but we should be
 well-behaved if they do.

For multichannel files, this potentially caused writes beyond the
 end of the output buffer provided by the user.

Reduces cruft on 'make clean'. I've rearranged some of the
non-functional self-test targets, but not really fixed them.

The old ones gave a different warning on Apple's clang 4.2.