1 2 libmad - MPEG audio decoder library 3 Copyright (C) 2000-2004 Underbit Technologies, Inc. 4 5 $Id: README,v 1.4 2004/01/23 09:41:32 rob Exp $ 6 7=============================================================================== 8 9INTRODUCTION 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 50ABOUT 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 83Integer 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 108Audio 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 129Portability 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 144BUILDING AND INSTALLING 145 146Windows 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 163POSIX 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 212Experimenting 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 227COPYRIGHT 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 242