diff options
Diffstat (limited to 'lib/rbcodec/codecs/libmad/README')
-rw-r--r-- | lib/rbcodec/codecs/libmad/README | 241 |
1 files changed, 241 insertions, 0 deletions
diff --git a/lib/rbcodec/codecs/libmad/README b/lib/rbcodec/codecs/libmad/README new file mode 100644 index 0000000000..524a94b29d --- /dev/null +++ b/lib/rbcodec/codecs/libmad/README | |||
@@ -0,0 +1,241 @@ | |||
1 | |||
2 | libmad - MPEG audio decoder library | ||
3 | Copyright (C) 2000-2004 Underbit Technologies, Inc. | ||
4 | |||
5 | $Id$ | ||
6 | |||
7 | =============================================================================== | ||
8 | |||
9 | INTRODUCTION | ||
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 | |||
50 | ABOUT 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 | |||
83 | Integer 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 | |||
108 | Audio 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 | |||
129 | Portability 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 | |||
144 | BUILDING AND INSTALLING | ||
145 | |||
146 | Windows 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 | |||
163 | POSIX 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 | |||
212 | Experimenting 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 | |||
227 | COPYRIGHT | ||
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 | |||