Subversion Repositories or1k

 mad - MPEG audio decoder

 Copyright (C) 2000-2001 Robert Leslie

 $Id: README,v 1.1.1.1 2001-11-04 19:00:21 lampret Exp $

===============================================================================

INTRODUCTION

  MAD 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 other copyrights. MAD is NOT a derivation of the ISO

  reference source or any other code.

  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 the author.)

===============================================================================

ABOUT THE CODE

  The code currently consists of an MPEG audio decoding library (libmad) and

  a simple front-end called `madplay' that supports several audio output

  modules:

    - an Open Sound System interface module (for Linux, et al.)

    - a Sun audio interface module (for Solaris, NetBSD, et al.)

    - a Win32 audio interface module (for Windows 95/98/NT, et al.)

    - a raw PCM output module

    - a WAVE file output module (*.wav)

    - a Sun/NeXT audio file output module (*.au, *.snd)

    - a hex output module (for debugging and compliance testing)

    - a null module (for timing the decoder)

  The code is optimized and performs very well, although specific

  improvements can and will still be made. The output from the decoder

  library consists of 32-bit signed linear fixed-point values which can be

  easily scaled for any size PCM output, up to 24 bits per sample.

  The API for libmad is likely to change, so it is not yet documented.

  However, the header file `libmad/mad.h' may be informative, as may also be

  the sample code in `minimad.c'. Note that the `libmad/mad.h' file is

  automatically generated, and will not exist until 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 `madplay' front-end is written to use the high-level synchronous API.

  The file `minimad.c' contains an example usage of the libmad API which is

  less complex than `madplay.c' and 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. It will abort at the first discovery of a

  decoding error.

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 which is much more accurate.

  However, using an assembly version is generally much faster and just as

  accurate.

  More information can be gathered from the `libmad/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 tested and 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, `madplay' implements a

  dithering algorithm when truncating samples for output. This produces high

  quality audio that generally sounds superior to the output of a simple

  rounding algorithm. However, dithering may unfavorably affect an analytic

  examination of the output (such as compliance testing), and therefore it

  may optionally be disabled at runtime.

  It is recommended that applications using the MAD library also implement

  some form of dithering to obtain the best quality audio.

Portability Issues

  GCC is probably required to compile the code, but your mileage may vary.

  Besides the assembly code notation, a GNU extension was used in

  `libmad/huffman.c' to specify union initialization of a member other than

  the first.

  The code should not be sensitive to word sizes or byte ordering, however it

  does assume A % B has the same sign as A.

===============================================================================

INSTALLATION

  If you are trying to build MAD under Windows, you will almost certainly

  want to use Cygwin:

      http://www.cygwin.com/

  The code is distributed with a `configure' script which will generate for

  you a `Makefile' and a `config.h' in both the `libmad' and top-level

  subdirectories. 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

      --enable-shared           build a shared library if possible

  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.

  It is not normally necessary to use the following options, but you may

  fine-tune the configuration with them if desired:

      --enable-fpm=       use the -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 or to use an explicit --enable-fpm

  option.

  If an appropriate assembly routine cannot be determined, the fast

  approximation version will be used. In this case, use of an alternate

  --enable-fpm is 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 AND AUTHOR

  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:

      Robert Leslie 

  See also the MAD home page on the Web:

      http://www.mars.org/home/rob/proj/mpeg/

===============================================================================