1 |
266 |
lampret |
|
2 |
|
|
mad - MPEG audio decoder
|
3 |
|
|
Copyright (C) 2000-2001 Robert Leslie
|
4 |
|
|
|
5 |
|
|
$Id: README,v 1.1.1.1 2001-11-04 19:00:21 lampret Exp $
|
6 |
|
|
|
7 |
|
|
===============================================================================
|
8 |
|
|
|
9 |
|
|
INTRODUCTION
|
10 |
|
|
|
11 |
|
|
MAD is a high-quality MPEG audio decoder. It currently supports MPEG-1 and
|
12 |
|
|
the MPEG-2 extension to Lower Sampling Frequencies, as well as the
|
13 |
|
|
so-called MPEG 2.5 format. All three audio layers (Layer I, Layer II, and
|
14 |
|
|
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 other copyrights. MAD is NOT a derivation of the ISO
|
38 |
|
|
reference source or any other code.
|
39 |
|
|
|
40 |
|
|
Because MAD is distributed under the terms of the GPL, its redistribution
|
41 |
|
|
is not generally restricted, so long as the terms of the GPL are followed.
|
42 |
|
|
This means MAD can be incorporated into other software as long as that
|
43 |
|
|
software is also distributed under the GPL. (Should this be undesirable,
|
44 |
|
|
alternate arrangements may be possible by contacting the author.)
|
45 |
|
|
|
46 |
|
|
===============================================================================
|
47 |
|
|
|
48 |
|
|
ABOUT THE CODE
|
49 |
|
|
|
50 |
|
|
The code currently consists of an MPEG audio decoding library (libmad) and
|
51 |
|
|
a simple front-end called `madplay' that supports several audio output
|
52 |
|
|
modules:
|
53 |
|
|
|
54 |
|
|
- an Open Sound System interface module (for Linux, et al.)
|
55 |
|
|
- a Sun audio interface module (for Solaris, NetBSD, et al.)
|
56 |
|
|
- a Win32 audio interface module (for Windows 95/98/NT, et al.)
|
57 |
|
|
- a raw PCM output module
|
58 |
|
|
- a WAVE file output module (*.wav)
|
59 |
|
|
- a Sun/NeXT audio file output module (*.au, *.snd)
|
60 |
|
|
- a hex output module (for debugging and compliance testing)
|
61 |
|
|
- a null module (for timing the decoder)
|
62 |
|
|
|
63 |
|
|
The code is optimized and performs very well, although specific
|
64 |
|
|
improvements can and will still be made. The output from the decoder
|
65 |
|
|
library consists of 32-bit signed linear fixed-point values which can be
|
66 |
|
|
easily scaled for any size PCM output, up to 24 bits per sample.
|
67 |
|
|
|
68 |
|
|
The API for libmad is likely to change, so it is not yet documented.
|
69 |
|
|
However, the header file `libmad/mad.h' may be informative, as may also be
|
70 |
|
|
the sample code in `minimad.c'. Note that the `libmad/mad.h' file is
|
71 |
|
|
automatically generated, and will not exist until you have built the
|
72 |
|
|
library.
|
73 |
|
|
|
74 |
|
|
There are two APIs available, one high-level, and the other low-level.
|
75 |
|
|
With the low-level API, each step of the decoding process must be handled
|
76 |
|
|
explicitly, offering the greatest amount of control. With the high-level
|
77 |
|
|
API, after callbacks are configured, a single routine will decode an
|
78 |
|
|
entire bitstream.
|
79 |
|
|
|
80 |
|
|
The high-level API may either be used synchronously or asynchronously. If
|
81 |
|
|
used asynchronously, decoding will occur in a separate process.
|
82 |
|
|
Communication is possible with the decoding process by passing control
|
83 |
|
|
messages.
|
84 |
|
|
|
85 |
|
|
The `madplay' front-end is written to use the high-level synchronous API.
|
86 |
|
|
|
87 |
|
|
The file `minimad.c' contains an example usage of the libmad API which is
|
88 |
|
|
less complex than `madplay.c' and shows only the bare minimum required to
|
89 |
|
|
implement a useful decoder. It expects a regular file to be redirected to
|
90 |
|
|
standard input, and it sends decoded 16-bit signed little-endian PCM
|
91 |
|
|
samples to standard output. It will abort at the first discovery of a
|
92 |
|
|
decoding error.
|
93 |
|
|
|
94 |
|
|
Integer Performance
|
95 |
|
|
|
96 |
|
|
To get the best possible performance, it is recommended that an assembly
|
97 |
|
|
version of the fixed-point multiply and related routines be selected.
|
98 |
|
|
Several such assembly routines have been written for various CPUs.
|
99 |
|
|
|
100 |
|
|
If an assembly version is not available, a fast approximation version will
|
101 |
|
|
be used. This will result in reduced accuracy of the decoder.
|
102 |
|
|
|
103 |
|
|
Alternatively, if 64-bit integers are supported as a datatype by the
|
104 |
|
|
compiler, another version can be used which is much more accurate.
|
105 |
|
|
However, using an assembly version is generally much faster and just as
|
106 |
|
|
accurate.
|
107 |
|
|
|
108 |
|
|
More information can be gathered from the `libmad/fixed.h' header file.
|
109 |
|
|
|
110 |
|
|
MAD's CPU-intensive subband synthesis routine can be further optimized at
|
111 |
|
|
the expense of a slight loss in output accuracy due to a modified method
|
112 |
|
|
for fixed-point multiplication with a small windowing constant. While this
|
113 |
|
|
is helpful for performance and the output accuracy loss is generally
|
114 |
|
|
undetectable, it is disabled by default and must be explicitly enabled.
|
115 |
|
|
|
116 |
|
|
Under some architectures, other special optimizations may also be
|
117 |
|
|
available.
|
118 |
|
|
|
119 |
|
|
Audio Quality
|
120 |
|
|
|
121 |
|
|
The output from MAD has been tested and found to satisfy the ISO/IEC
|
122 |
|
|
11172-4 computational accuracy requirements for compliance. In most
|
123 |
|
|
configurations, MAD is a Full Layer III ISO/IEC 11172-3 audio decoder as
|
124 |
|
|
defined by the standard.
|
125 |
|
|
|
126 |
|
|
When the approximation version of the fixed-point multiply is used, MAD is
|
127 |
|
|
a limited accuracy ISO/IEC 11172-3 audio decoder as defined by the
|
128 |
|
|
standard.
|
129 |
|
|
|
130 |
|
|
MAD can alternatively be configured to produce output with less or more
|
131 |
|
|
accuracy than the default, as a tradeoff with performance.
|
132 |
|
|
|
133 |
|
|
MAD produces output samples with a precision greater than 24 bits. Because
|
134 |
|
|
most output formats use fewer bits, typically 16, `madplay' implements a
|
135 |
|
|
dithering algorithm when truncating samples for output. This produces high
|
136 |
|
|
quality audio that generally sounds superior to the output of a simple
|
137 |
|
|
rounding algorithm. However, dithering may unfavorably affect an analytic
|
138 |
|
|
examination of the output (such as compliance testing), and therefore it
|
139 |
|
|
may optionally be disabled at runtime.
|
140 |
|
|
|
141 |
|
|
It is recommended that applications using the MAD library also implement
|
142 |
|
|
some form of dithering to obtain the best quality audio.
|
143 |
|
|
|
144 |
|
|
Portability Issues
|
145 |
|
|
|
146 |
|
|
GCC is probably required to compile the code, but your mileage may vary.
|
147 |
|
|
Besides the assembly code notation, a GNU extension was used in
|
148 |
|
|
`libmad/huffman.c' to specify union initialization of a member other than
|
149 |
|
|
the first.
|
150 |
|
|
|
151 |
|
|
The code should not be sensitive to word sizes or byte ordering, however it
|
152 |
|
|
does assume A % B has the same sign as A.
|
153 |
|
|
|
154 |
|
|
===============================================================================
|
155 |
|
|
|
156 |
|
|
INSTALLATION
|
157 |
|
|
|
158 |
|
|
If you are trying to build MAD under Windows, you will almost certainly
|
159 |
|
|
want to use Cygwin:
|
160 |
|
|
|
161 |
|
|
http://www.cygwin.com/
|
162 |
|
|
|
163 |
|
|
The code is distributed with a `configure' script which will generate for
|
164 |
|
|
you a `Makefile' and a `config.h' in both the `libmad' and top-level
|
165 |
|
|
subdirectories. See the file `INSTALL' for generic instructions.
|
166 |
|
|
|
167 |
|
|
The specific options you may want to give `configure' are:
|
168 |
|
|
|
169 |
|
|
--enable-speed optimize for speed over accuracy
|
170 |
|
|
|
171 |
|
|
--enable-accuracy optimize for accuracy over speed
|
172 |
|
|
|
173 |
|
|
--disable-debugging do not compile with debugging support, and
|
174 |
|
|
use more optimizations
|
175 |
|
|
|
176 |
|
|
--enable-shared build a shared library if possible
|
177 |
|
|
|
178 |
|
|
Note that you need not specify one of --enable-speed or --enable-accuracy;
|
179 |
|
|
in its default configuration, MAD is optimized for both. You should only
|
180 |
|
|
use one of these options if you wish to compromise speed or accuracy for
|
181 |
|
|
the other.
|
182 |
|
|
|
183 |
|
|
It is not normally necessary to use the following options, but you may
|
184 |
|
|
fine-tune the configuration with them if desired:
|
185 |
|
|
|
186 |
|
|
--enable-fpm= use the -specific version of the
|
187 |
|
|
fixed-point math assembly routines
|
188 |
|
|
(current options are: intel, arm, mips,
|
189 |
|
|
sparc, ppc; also allowed are: 64bit, approx)
|
190 |
|
|
|
191 |
|
|
--enable-sso use the subband synthesis optimization,
|
192 |
|
|
with reduced accuracy
|
193 |
|
|
|
194 |
|
|
--disable-aso do not use certain architecture-specific
|
195 |
|
|
optimizations
|
196 |
|
|
|
197 |
|
|
By default an appropriate fixed-point assembly routine will be selected
|
198 |
|
|
for the configured host type, if it can be determined. Thus if you are
|
199 |
|
|
cross-compiling for another architecture, you should be sure either to
|
200 |
|
|
give `configure' a host type argument or to use an explicit --enable-fpm
|
201 |
|
|
option.
|
202 |
|
|
|
203 |
|
|
If an appropriate assembly routine cannot be determined, the fast
|
204 |
|
|
approximation version will be used. In this case, use of an alternate
|
205 |
|
|
--enable-fpm is recommended.
|
206 |
|
|
|
207 |
|
|
==============================================================================
|
208 |
|
|
|
209 |
|
|
EXPERIMENTING AND DEVELOPING
|
210 |
|
|
|
211 |
|
|
Further options for `configure' that may be useful to developers and
|
212 |
|
|
experimenters are:
|
213 |
|
|
|
214 |
|
|
--enable-debugging enable diagnostic debugging support and
|
215 |
|
|
debugging symbols
|
216 |
|
|
|
217 |
|
|
--enable-profiling generate `gprof' profiling code
|
218 |
|
|
|
219 |
|
|
--enable-experimental enable code using the EXPERIMENTAL
|
220 |
|
|
preprocessor define
|
221 |
|
|
|
222 |
|
|
===============================================================================
|
223 |
|
|
|
224 |
|
|
COPYRIGHT AND AUTHOR
|
225 |
|
|
|
226 |
|
|
Please read the `COPYRIGHT' file for copyright and warranty information.
|
227 |
|
|
Also, the file `COPYING' contains the full text of the GNU GPL.
|
228 |
|
|
|
229 |
|
|
Send inquiries, comments, bug reports, suggestions, patches, etc. to:
|
230 |
|
|
|
231 |
|
|
Robert Leslie
|
232 |
|
|
|
233 |
|
|
See also the MAD home page on the Web:
|
234 |
|
|
|
235 |
|
|
http://www.mars.org/home/rob/proj/mpeg/
|
236 |
|
|
|
237 |
|
|
===============================================================================
|
238 |
|
|
|