initial

utils/libmad/README

@@ -0,0 +1,241 @@
+
+ libmad - MPEG audio decoder library
+ Copyright (C) 2000-2004 Underbit Technologies, Inc.
+
+ $Id: README,v 1.4 2004/01/23 09:41:32 rob Exp $
+
+===============================================================================
+
+INTRODUCTION
+
+  MAD (libmad) is a high-quality MPEG audio decoder. It currently supports
+  MPEG-1 and the MPEG-2 extension to Lower Sampling Frequencies, as well as
+  the so-called MPEG 2.5 format. All three audio layers (Layer I, Layer II,
+  and Layer III a.k.a. MP3) are fully implemented.
+
+  MAD does not yet support MPEG-2 multichannel audio (although it should be
+  backward compatible with such streams) nor does it currently support AAC.
+
+  MAD has the following special features:
+
+    - 24-bit PCM output
+    - 100% fixed-point (integer) computation
+    - completely new implementation based on the ISO/IEC standards
+    - distributed under the terms of the GNU General Public License (GPL)
+
+  Because MAD provides full 24-bit PCM output, applications using MAD are
+  able to produce high quality audio. Even when the output device supports
+  only 16-bit PCM, applications can use the extra resolution to increase the
+  audible dynamic range through the use of dithering or noise shaping.
+
+  Because MAD uses integer computation rather than floating point, it is
+  well suited for architectures without a floating point unit. All
+  calculations are performed with a 32-bit fixed-point integer
+  representation.
+
+  Because MAD is a new implementation of the ISO/IEC standards, it is
+  unencumbered by the errors of other implementations. MAD is NOT a
+  derivation of the ISO reference source or any other code. Considerable
+  effort has been expended to ensure a correct implementation, even in cases
+  where the standards are ambiguous or misleading.
+
+  Because MAD is distributed under the terms of the GPL, its redistribution
+  is not generally restricted, so long as the terms of the GPL are followed.
+  This means MAD can be incorporated into other software as long as that
+  software is also distributed under the GPL. (Should this be undesirable,
+  alternate arrangements may be possible by contacting Underbit.)
+
+===============================================================================
+
+ABOUT THE CODE
+
+  The code is optimized and performs very well, although specific
+  improvements can still be made. The output from the decoder library
+  consists of 32-bit signed linear fixed-point values that can be easily
+  scaled for any size PCM output, up to 24 bits per sample.
+
+  The API for libmad can be found in the `mad.h' header file. Note that this
+  file is automatically generated, and will not exist until after you have
+  built the library.
+
+  There are two APIs available, one high-level, and the other low-level.
+  With the low-level API, each step of the decoding process must be handled
+  explicitly, offering the greatest amount of control. With the high-level
+  API, after callbacks are configured, a single routine will decode an
+  entire bitstream.
+
+  The high-level API may either be used synchronously or asynchronously. If
+  used asynchronously, decoding will occur in a separate process.
+  Communication is possible with the decoding process by passing control
+  messages.
+
+  The file `minimad.c' contains an example usage of the libmad API that
+  shows only the bare minimum required to implement a useful decoder. It
+  expects a regular file to be redirected to standard input, and it sends
+  decoded 16-bit signed little-endian PCM samples to standard output. If a
+  decoding error occurs, it is reported to standard error and decoding
+  continues. Note that the scale() routine in this code is only provided as
+  an example; it rounds MAD's high-resolution samples down to 16 bits, but
+  does not perform any dithering or noise shaping. It is therefore not
+  recommended to use this routine as-is in your own code if sound quality is
+  important.
+
+Integer Performance
+
+  To get the best possible performance, it is recommended that an assembly
+  version of the fixed-point multiply and related routines be selected.
+  Several such assembly routines have been written for various CPUs.
+
+  If an assembly version is not available, a fast approximation version will
+  be used. This will result in reduced accuracy of the decoder.
+
+  Alternatively, if 64-bit integers are supported as a datatype by the
+  compiler, another version can be used that is much more accurate.
+  However, using an assembly version is generally much faster and just as
+  accurate.
+
+  More information can be gathered from the `fixed.h' header file.
+
+  MAD's CPU-intensive subband synthesis routine can be further optimized at
+  the expense of a slight loss in output accuracy due to a modified method
+  for fixed-point multiplication with a small windowing constant. While this
+  is helpful for performance and the output accuracy loss is generally
+  undetectable, it is disabled by default and must be explicitly enabled.
+
+  Under some architectures, other special optimizations may also be
+  available.
+
+Audio Quality
+
+  The output from MAD has been found to satisfy the ISO/IEC 11172-4
+  computational accuracy requirements for compliance. In most
+  configurations, MAD is a Full Layer III ISO/IEC 11172-3 audio decoder as
+  defined by the standard.
+
+  When the approximation version of the fixed-point multiply is used, MAD is
+  a limited accuracy ISO/IEC 11172-3 audio decoder as defined by the
+  standard.
+
+  MAD can alternatively be configured to produce output with less or more
+  accuracy than the default, as a tradeoff with performance.
+
+  MAD produces output samples with a precision greater than 24 bits. Because
+  most output formats use fewer bits, typically 16, it is recommended that a
+  dithering algorithm be used (rather than rounding or truncating) to obtain
+  the highest quality audio. However, dithering may unfavorably affect an
+  analytic examination of the output (such as compliance testing); you may
+  therefore wish to use rounding in this case instead.
+
+Portability Issues
+
+  GCC is preferred to compile the code, but other compilers may also work.
+  The assembly code in `fixed.h' depends on the inline assembly features of
+  your compiler. If you're not using GCC or MSVC++, you can either write
+  your own assembly macros or use the default (low quality output) version.
+
+  The union initialization of `huffman.c' may not be portable to all
+  platforms when GCC is not used.
+
+  The code should not be sensitive to word sizes or byte ordering, however
+  it does assume A % B has the same sign as A.
+
+===============================================================================
+
+BUILDING AND INSTALLING
+
+Windows Platforms
+
+  MAD can be built under Windows using either MSVC++ or Cygwin. A MSVC++
+  project file can be found under the `msvc++' subdirectory.
+
+  To build libmad using Cygwin, you will first need to install the Cygwin
+  tools:
+
+      http://www.cygwin.com/
+
+  You may then proceed with the following POSIX instructions within the
+  Cygwin shell.
+
+  Note that by default Cygwin will build a library that depends on the
+  Cygwin DLL. You can use MinGW to build a library that does not depend on
+  the Cygwin DLL. To do so, give the option --host=mingw32 to `configure'.
+
+POSIX Platforms (including Cygwin)
+
+  The code is distributed with a `configure' script that will generate for
+  you a `Makefile' and a `config.h' for your platform. See the file
+  `INSTALL' for generic instructions.
+
+  The specific options you may want to give `configure' are:
+
+      --enable-speed            optimize for speed over accuracy
+
+      --enable-accuracy         optimize for accuracy over speed
+
+      --disable-debugging       do not compile with debugging support, and
+                                use more optimizations
+
+      --disable-shared          do not build a shared library
+
+  Note that you need not specify one of --enable-speed or --enable-accuracy;
+  in its default configuration, MAD is optimized for both. You should only
+  use one of these options if you wish to compromise speed or accuracy for
+  the other.
+
+  By default the package will build a shared library if possible for your
+  platform. If you want only a static library, use --disable-shared.
+
+  It is not normally necessary to use the following options, but you may
+  fine-tune the configuration with them if desired:
+
+      --enable-fpm=ARCH         use the ARCH-specific version of the
+                                fixed-point math assembly routines
+                                (current options are: intel, arm, mips,
+                                sparc, ppc; also allowed are: 64bit, approx)
+
+      --enable-sso              use the subband synthesis optimization,
+                                with reduced accuracy
+
+      --disable-aso             do not use certain architecture-specific
+                                optimizations
+
+  By default an appropriate fixed-point assembly routine will be selected
+  for the configured host type, if it can be determined. Thus if you are
+  cross-compiling for another architecture, you should be sure either to
+  give `configure' a host type argument (--host) or to use an explicit
+  --enable-fpm option.
+
+  If an appropriate assembly routine cannot be determined, the default
+  approximation version will be used. In this case, use of an alternate
+  --enable-fpm is highly recommended.
+
+Experimenting and Developing
+
+  Further options for `configure' that may be useful to developers and
+  experimenters are:
+
+      --enable-debugging        enable diagnostic debugging support and
+                                debugging symbols
+
+      --enable-profiling        generate `gprof' profiling code
+
+      --enable-experimental     enable code using the EXPERIMENTAL
+                                preprocessor define
+
+===============================================================================
+
+COPYRIGHT
+
+  Please read the `COPYRIGHT' file for copyright and warranty information.
+  Also, the file `COPYING' contains the full text of the GNU GPL.
+
+  Send inquiries, comments, bug reports, suggestions, patches, etc. to:
+
+      Underbit Technologies, Inc. <support@underbit.com>
+
+  See also the MAD home page on the Web:
+
+      http://www.underbit.com/products/mad/
+
+===============================================================================
+