apps/codecs/libmad/README

   1
   2  libmad - MPEG audio decoder library
   3  Copyright (C) 2000-2004 Underbit Technologies, Inc.
   4
   5  $Id$
   6
   7 ===============================================================================
   8
   9 INTRODUCTION
  10
  11   MAD (libmad) is a high-quality MPEG audio decoder. It currently supports
  12   MPEG-1 and the MPEG-2 extension to Lower Sampling Frequencies, as well as
  13   the so-called MPEG 2.5 format. All three audio layers (Layer I, Layer II,
  14   and Layer III a.k.a. MP3) are fully implemented.
  15
  16   MAD does not yet support MPEG-2 multichannel audio (although it should be
  17   backward compatible with such streams) nor does it currently support AAC.
  18
  19   MAD has the following special features:
  20
  21     - 24-bit PCM output
  22     - 100% fixed-point (integer) computation
  23     - completely new implementation based on the ISO/IEC standards
  24     - distributed under the terms of the GNU General Public License (GPL)
  25
  26   Because MAD provides full 24-bit PCM output, applications using MAD are
  27   able to produce high quality audio. Even when the output device supports
  28   only 16-bit PCM, applications can use the extra resolution to increase the
  29   audible dynamic range through the use of dithering or noise shaping.
  30
  31   Because MAD uses integer computation rather than floating point, it is
  32   well suited for architectures without a floating point unit. All
  33   calculations are performed with a 32-bit fixed-point integer
  34   representation.
  35
  36   Because MAD is a new implementation of the ISO/IEC standards, it is
  37   unencumbered by the errors of other implementations. MAD is NOT a
  38   derivation of the ISO reference source or any other code. Considerable
  39   effort has been expended to ensure a correct implementation, even in cases
  40   where the standards are ambiguous or misleading.
  41
  42   Because MAD is distributed under the terms of the GPL, its redistribution
  43   is not generally restricted, so long as the terms of the GPL are followed.
  44   This means MAD can be incorporated into other software as long as that
  45   software is also distributed under the GPL. (Should this be undesirable,
  46   alternate arrangements may be possible by contacting Underbit.)
  47
  48 ===============================================================================
  49
  50 ABOUT THE CODE
  51
  52   The code is optimized and performs very well, although specific
  53   improvements can still be made. The output from the decoder library
  54   consists of 32-bit signed linear fixed-point values that can be easily
  55   scaled for any size PCM output, up to 24 bits per sample.
  56
  57   The API for libmad can be found in the `mad.h' header file. Note that this
  58   file is automatically generated, and will not exist until after you have
  59   built the library.
  60
  61   There are two APIs available, one high-level, and the other low-level.
  62   With the low-level API, each step of the decoding process must be handled
  63   explicitly, offering the greatest amount of control. With the high-level
  64   API, after callbacks are configured, a single routine will decode an
  65   entire bitstream.
  66
  67   The high-level API may either be used synchronously or asynchronously. If
  68   used asynchronously, decoding will occur in a separate process.
  69   Communication is possible with the decoding process by passing control
  70   messages.
  71
  72   The file `minimad.c' contains an example usage of the libmad API that
  73   shows only the bare minimum required to implement a useful decoder. It
  74   expects a regular file to be redirected to standard input, and it sends
  75   decoded 16-bit signed little-endian PCM samples to standard output. If a
  76   decoding error occurs, it is reported to standard error and decoding
  77   continues. Note that the scale() routine in this code is only provided as
  78   an example; it rounds MAD's high-resolution samples down to 16 bits, but
  79   does not perform any dithering or noise shaping. It is therefore not
  80   recommended to use this routine as-is in your own code if sound quality is
  81   important.
  82
  83 Integer Performance
  84
  85   To get the best possible performance, it is recommended that an assembly
  86   version of the fixed-point multiply and related routines be selected.
  87   Several such assembly routines have been written for various CPUs.
  88
  89   If an assembly version is not available, a fast approximation version will
  90   be used. This will result in reduced accuracy of the decoder.
  91
  92   Alternatively, if 64-bit integers are supported as a datatype by the
  93   compiler, another version can be used that is much more accurate.
  94   However, using an assembly version is generally much faster and just as
  95   accurate.
  96
  97   More information can be gathered from the `fixed.h' header file.
  98
  99   MAD's CPU-intensive subband synthesis routine can be further optimized at
 100   the expense of a slight loss in output accuracy due to a modified method
 101   for fixed-point multiplication with a small windowing constant. While this
 102   is helpful for performance and the output accuracy loss is generally
 103   undetectable, it is disabled by default and must be explicitly enabled.
 104
 105   Under some architectures, other special optimizations may also be
 106   available.
 107
 108 Audio Quality
 109
 110   The output from MAD has been found to satisfy the ISO/IEC 11172-4
 111   computational accuracy requirements for compliance. In most
 112   configurations, MAD is a Full Layer III ISO/IEC 11172-3 audio decoder as
 113   defined by the standard.
 114
 115   When the approximation version of the fixed-point multiply is used, MAD is
 116   a limited accuracy ISO/IEC 11172-3 audio decoder as defined by the
 117   standard.
 118
 119   MAD can alternatively be configured to produce output with less or more
 120   accuracy than the default, as a tradeoff with performance.
 121
 122   MAD produces output samples with a precision greater than 24 bits. Because
 123   most output formats use fewer bits, typically 16, it is recommended that a
 124   dithering algorithm be used (rather than rounding or truncating) to obtain
 125   the highest quality audio. However, dithering may unfavorably affect an
 126   analytic examination of the output (such as compliance testing); you may
 127   therefore wish to use rounding in this case instead.
 128
 129 Portability Issues
 130
 131   GCC is preferred to compile the code, but other compilers may also work.
 132   The assembly code in `fixed.h' depends on the inline assembly features of
 133   your compiler. If you're not using GCC or MSVC++, you can either write
 134   your own assembly macros or use the default (low quality output) version.
 135
 136   The union initialization of `huffman.c' may not be portable to all
 137   platforms when GCC is not used.
 138
 139   The code should not be sensitive to word sizes or byte ordering, however
 140   it does assume A % B has the same sign as A.
 141
 142 ===============================================================================
 143
 144 BUILDING AND INSTALLING
 145
 146 Windows Platforms
 147
 148   MAD can be built under Windows using either MSVC++ or Cygwin. A MSVC++
 149   project file can be found under the `msvc++' subdirectory.
 150
 151   To build libmad using Cygwin, you will first need to install the Cygwin
 152   tools:
 153
 154       http://www.cygwin.com/
 155
 156   You may then proceed with the following POSIX instructions within the
 157   Cygwin shell.
 158
 159   Note that by default Cygwin will build a library that depends on the
 160   Cygwin DLL. You can use MinGW to build a library that does not depend on
 161   the Cygwin DLL. To do so, give the option --host=mingw32 to `configure'.
 162
 163 POSIX Platforms (including Cygwin)
 164
 165   The code is distributed with a `configure' script that will generate for
 166   you a `Makefile' and a `config.h' for your platform. See the file
 167   `INSTALL' for generic instructions.
 168
 169   The specific options you may want to give `configure' are:
 170
 171       --enable-speed            optimize for speed over accuracy
 172
 173       --enable-accuracy         optimize for accuracy over speed
 174
 175       --disable-debugging       do not compile with debugging support, and
 176                                 use more optimizations
 177
 178       --disable-shared          do not build a shared library
 179
 180   Note that you need not specify one of --enable-speed or --enable-accuracy;
 181   in its default configuration, MAD is optimized for both. You should only
 182   use one of these options if you wish to compromise speed or accuracy for
 183   the other.
 184
 185   By default the package will build a shared library if possible for your
 186   platform. If you want only a static library, use --disable-shared.
 187
 188   It is not normally necessary to use the following options, but you may
 189   fine-tune the configuration with them if desired:
 190
 191       --enable-fpm=ARCH         use the ARCH-specific version of the
 192                                 fixed-point math assembly routines
 193                                 (current options are: intel, arm, mips,
 194                                 sparc, ppc; also allowed are: 64bit, approx)
 195
 196       --enable-sso              use the subband synthesis optimization,
 197                                 with reduced accuracy
 198
 199       --disable-aso             do not use certain architecture-specific
 200                                 optimizations
 201
 202   By default an appropriate fixed-point assembly routine will be selected
 203   for the configured host type, if it can be determined. Thus if you are
 204   cross-compiling for another architecture, you should be sure either to
 205   give `configure' a host type argument (--host) or to use an explicit
 206   --enable-fpm option.
 207
 208   If an appropriate assembly routine cannot be determined, the default
 209   approximation version will be used. In this case, use of an alternate
 210   --enable-fpm is highly recommended.
 211
 212 Experimenting and Developing
 213
 214   Further options for `configure' that may be useful to developers and
 215   experimenters are:
 216
 217       --enable-debugging        enable diagnostic debugging support and
 218                                 debugging symbols
 219
 220       --enable-profiling        generate `gprof' profiling code
 221
 222       --enable-experimental     enable code using the EXPERIMENTAL
 223                                 preprocessor define
 224
 225 ===============================================================================
 226
 227 COPYRIGHT
 228
 229   Please read the `COPYRIGHT' file for copyright and warranty information.
 230   Also, the file `COPYING' contains the full text of the GNU GPL.
 231
 232   Send inquiries, comments, bug reports, suggestions, patches, etc. to:
 233
 234       Underbit Technologies, Inc. <support@underbit.com>
 235
 236   See also the MAD home page on the Web:
 237
 238       http://www.underbit.com/products/mad/
 239
 240 ===============================================================================
 241