////////////////////////////////////////////////////////////////////////////
//                       **** WAVPACK-STREAM ****                         //
//                      Streaming Audio Compressor                        //
//                Copyright (c) 1998 - 2018 David Bryant                  //
//                          All Rights Reserved.                          //
//      Distributed under the BSD Software License (see license.txt)      //
////////////////////////////////////////////////////////////////////////////
//                                                                        //
// IMPORTANT: This is a special version of the WavPack library targeting  //
//            streaming applications. This library has NO compatibility   //
//            with standard WavPack files and the command-line utilities  //
//            "wavpack" and "wvunpack" are provided here for testing only //
//            (normally the audio blocks would never be stored in files). //
//                                                                        //
////////////////////////////////////////////////////////////////////////////

This package contains all the source code required to build the WavPack
streaming library (libwavpack-stream) and the command-line programs and it
has been tested on many platforms. Assembly language optimizations are
provided for x86 and x86-64 (AMD64) processors (encoding and decoding) and
ARMv7 (decoding only). The x86 assembly code includes a runtime check for
MMX capability, so it will work on legacy i386 processors.

Visual Studio 2008 does not support projects with x64 assembly very well. I
have provided a copy of the edited masm.rules file that works for me, but I
can't provide support if your build does not work. Please make a copy of
your masm.rules file first. On my system it lives here:

C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\VCProjectDefaults

To build everything on Linux, type:

1. ./configure [--disable-asm] [--enable-man] [--enable-rpath] [--enable-tests]
               [--disable-apps] [--disable-dsd]
2. make

The library can be installed if required, but keep in mind that it is not
compatible with or a replacement for the official libwavpack library. The C
namespaces are different and the header files are compatible, so it is
possible to have both libwavpack-stream and libwavpack installed at the
same time and even used by the same application.

If you are using the code directly from Git (rather than a distribution)
then you will need to do a ./autogen.sh instead of the configure step. If
assembly optimizations are available for your processor they will be
automatically enabled, but if there is a problem with them then use the
--disable-asm option to revert to pure C. For Clang-based build systems
(Darwin, FreeBSD, etc.) Clang version 3.5 or higher is required.

If you get a WARNING about unexpected libwavpack version when you run the
command-line programs, you might try using --enable-rpath to hardcode the
library location in the executables, or simply force static linking with
--disable-shared.

There is now a cli program to do a full suite of stress tests for libwavpack,
and this is particularly useful for packagers to make sure that the assembly
language optimizations are working correctly on various platforms. It is
built with the configure option --enable-tests and requires Pthreads (it
worked out-of-the-box on all the platforms I tried it on). There are lots of
options, but the default test suite (consisting of 192 tests) is executed
with "wvtest --default". There is also a seeking test. On Windows a third-
party Pthreads library is required, so I am not including this in the build
for now.

Notes:

1. This is a special version of the WavPack library targeting streaming
   or low-latency applications. This is accomplished by significantly
   reducing the overhead for each block (compared to regular WavPack),
   while still leaving them independently decodable. This library works very
   much like the regular libwavpack, but there are two important features
   deleted that should be noted: seeking and tagging. It is assumed that
   in the target applications, these would be handled elsewhere.

   The "wavpack" and "wvunpack" command-line programs are included for
   testing, but they use a different extension (.wps) than the standard
   WavPack programs, and there is no interchangeability in the files. Also,
   I reserve the right to modify this library with improvements that might
   break compatibility with old encoders (although I will of course point
   this out in the change log).

   The blocks generated by this library start with a 12-byte header, the
   first 6 bytes of which just contain "wpsb" and a 16-bit block length.
   If the encoded audio blocks are being packetized in some way, then this
   data could be omitted (assuming the length was communicated some other
   way) and reconstructed for decoding, thereby further reducing the block
   overhead.

   In version 0.2.0 an option has been added to have the wavpack-stream blocks
   terminate at a specfied byte size limit rather than have a fixed number of
   audio samples per block. This might be useful in networking environments
   where there is a maximum (or perhaps an optimum) packet size. Obviously
   this will result in a widely varying number of blocks per second, as
   opposed to the widely varying block size in the regular mode. This feature
   does not work with 32-bit audio (neither floating-point nor integer),
   multichannel, nor the "extra" processing modes. It also does not work with
   DSD audio, although it could easily be adapted to work with the "high" DSD
   mode. The new "--block-bytes" option in the demo wavpack-stream program can
   be used to experiment with this new feature.

   The descriptions referenced below refer to the regular libwavpack,
   but most of the material is applicable to this version.

2. There are four documentation files contained in the distribution:

   doc/wavpack_doc.html:  contains user-targeted documentation for the
                          command-line programs

   doc/WavPack5PortingGuide.pdf:  this document is targeted at developers who
                          are migrating to WavPack 5, and it provides a short
                          description of the major improvements and how to
                          utilize them

   doc/WavPack5LibraryDoc.pdf:  contains a detailed description of the API
                          provided by WavPack library appropriate for read
                          and writing WavPack files and manipulating APEv2 tags

   doc/WavPack5FileFormat.pdf:  contains a description of the WavPack file
                          format, including details needed for parsing WavPack
                          blocks and interpreting the block header and flags

   There is also a description of the WavPack algorithms in the forth edition
   of David Salomon's book "Data Compression: The Complete Reference". The
   section on WavPack can be found here:

   www.wavpack.com/WavPack.pdf

3. This code is designed to be easy to port to other platforms. It is endian-
   agnostic and usually uses callbacks for I/O, although there's a convenience
   function for reading files that accepts filename strings and automatically
   handles correction files (and on Windows there is now an option to select
   UTF-8 instead of ANSI).

   To maintain compatibility on various platforms, the following conventions
   are used: the "char" type must be 8-bits (signed or unsigned), a "short"
   must be 16-bits and the "int" and "long" types must be at least 32-bits.

4. The code's modules are organized in such a way that if major chunks of the
   functionality are not referenced (for example, creating WavPack files) then
   link-time dependency resolution should provide optimum binary sizes.

   However, the DSD functionality could not be easily excluded in this way and
   so there is an additional macro that may be used to further reduce the size
   of the binary. Note that this must be defined for all modules:

   ENABLE_DSD      include support for DSD audio (new for WavPack 5 and the
                    default, but obviously not universally required)

5. Questions or comments should be directed to [email protected]