cog/Libraries/WavPack/Files/README

////////////////////////////////////////////////////////////////////////////
//                           **** WAVPACK ****                            //
//                  Hybrid Lossless Wavefile Compressor                   //
//              Copyright (c) 1998 - 2005 Conifer Software.               //
//                          All Rights Reserved.                          //
//      Distributed under the BSD Software License (see license.txt)      //
////////////////////////////////////////////////////////////////////////////

This package contains all the source code required to build the WavPack
command-line programs and the WavPack library and it has been tested on many
platforms. For example code using the library you might want to check some
of the plugin sources in the Windows source release.

To build everything, type:

1. ./configure
2. make
3. make install (optionally, to install into /usr/local/bin)

Notes:

1. This code is designed to be much easier to port to other platforms than
   the previous version of WavPack. File I/O is done with streams and all file
   functions (except "fopen") are handled in a wrapper in the "utils.c"
   module. The code is even written to be endian-independent and a compile
   option is provided to eliminate the DOS-specific directory searches.

   To maintain compatibility on various platforms, the following conventions
   are used:

   a "short" must be 16-bits
   an "int" must be at least 16-bits, but may be larger

   For version 4.2 references to "long" variables were eliminated to allow
   compilation on 64-bit machines. For version 4.3 "char" types may default
   to signed or unsigned.

2. For WavPack file decoding, a library interface in "wputils.c" provides all
   the functionality required for both the winamp plugin and the "wvunpack"
   command-line program (including the transparent decoding of "correction"
   files). There is also an alternate entry point that uses reader callbacks
   for all input, although in this case it is the caller's responsibility to
   to open the "correction" file. It is no longer necessary to manipulate the
   WavPack structures directly; everything is handled with function calls. In
   fact, a new header file called "wputils.h" can be used that hides all the
   WavPack internals from the application.

3. For WavPack file creation, the library interface in "wputils.c" provides
   all the functionality for both the Audition filter and the "wavpack"
   command-line program. No file I/O is performed by the library when creating
   WavPack files. Instead, the user supplies a "write_block" function that
   accepts completed WavPack blocks. For version 4.2 limited functionality
   has been added to append APEv2 tags to WavPack files during creation.

4. The following #define's are used to control the optimum configuration of
   the library for the desired application and must be the same for the
   compilation of ALL files:
   
   UNPACK          to unpack audio samples from WavPack files
   PACK            to create WavPack files from raw audio data
   INFO_ONLY       to obtain information from WavPack files, but not audio
   SEEKING         to allow seeking to a specific sample index (unpack only)
   USE_FSTREAMS    to open WavPack files by name using fstreams (via fopen)
   TAGS            to read specified fields from ID3v1 and APEv2 tags and
                    create APEv2 tags
   VER3            to handle WavPack files from versions prior to 4.0
   WIN32           required for Win32 platform

   The following files are required for various configurations:

   UNPACK or
   INFO_ONLY:      wputils.c unpack.c words.c bits.c metadata.c float.c

   PACK:           wputils.c pack.c extra1.c extra2.c
                   words.c bits.c metadata.c float.c

   PACK and
   UNPACK:         wputils.c unpack.c pack.c extra1.c extra2.c
                   words.c bits.c metadata.c float.c

5. An alternate version of this library is available specifically designed
   for "resource limited" CPUs or hardware decoding. This "tiny" decoder
   library works with less than 32k of code and less than 4k of data.

6. Questions or comments should be directed to david@wavpack.com