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