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