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