madplay
is a command-line MPEG audio decoder and player based on the MAD library
(libmad).
MAD 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.
Among the special features of MAD are 24-bit PCM resolution and 100%
fixed-point (integer) computation. Since MAD is implemented entirely without
the use of floating point arithmetic, it performs especially well on
architectures without an FPU.
MAD does not yet support MPEG-2 multichannel audio (although it should be
backward compatible with such streams) nor does it currently support AAC.
By default
madplay
reads and decodes one or more input
files
containing MPEG audio data and plays them on the native audio device. If the
input file is a single dash (-), data is read from standard input.
Decoded output may optionally be redirected to a file instead of being played
on the audio device by using the
-o
(--output)
option.
For each
file,
madplay
will also attempt to read and display ID3 tag information. If data is being
read from standard input, ID3 tags will be displayed as they are encountered.
The supported tag versions are ID3v1, ID3v1.1, ID3v2.2, ID3v2.3, and ID3v2.4.
OPTIONS
Verbosity
-v or --verbose
Show information about the stream during decoding, including playing time,
audio layer, bit rate, sampling frequency, and stereo mode.
-q or --quiet
Do not show any information during decoding, except warnings.
-Q or --very-quiet
Do not show any information during decoding, including warnings.
Decoding
--downsample
Reduce the output sampling frequency 2:1. This also reduces the computational
overhead of the decoder.
-i or --ignore-crc
Ignore CRC information in the audio stream. This causes frames with CRC errors
to be decoded and played anyway. This option is not recommended, but since
some encoders have been known to generate bad CRC information, this option is
a work-around to play streams from such encoders.
Audio Output
-o or --output=[type:]path
Direct output to
path,
rather than playing audio on the native audio device. The format of the output
is specified by
type
which can be any of the supported output formats (see
Output Formats
below.) If a format is not specified, one will be inferred from
path.
If
path
is a single dash (-), the output will be written to standard output.
-b or --bit-depth=depth
Request an output precision of
depth
bits per sample. Higher bit depths yield higher quality sound. Typical bit
depths are 8, 16, 24, and 32, however other depths may also be possible. See
the
NOTES
section below for further details about this option.
-d or --no-dither
Do not dither output PCM samples. This may result in lower sound quality but
is useful for analyzing output from the decoder.
--fade-in[=duration]
Gradually fade-in the audio from each file over
duration.
If not specified, the default duration is
0:05
(five seconds.)
-a or --attenuate=decibels or --amplify=decibels
Attenuate or amplify the signal by
decibels
(dB).
The signal is attenuated if the decibel value is negative; it is amplified if
the value is positive.
The decibel value must be in the range -175 to +18.
The value may be fractional, e.g. -1.5.
A value of 0 will leave the signal unchanged.
Each step of 6 dB will approximately halve (in the negative direction) or
double (in the positive direction) the strength of the signal.
Channel Selection
For dual channel streams, an output channel should be selected. If one is not
selected, the first (left) channel will be used.
For stereo streams, making a channel selection other than stereo will cause
the output to become monaural.
-1 or --left
Output the first (left) channel only.
-2 or --right
Output the second (right) channel only.
-m or --mono
Mix the left and right channels together.
-S or --stereo
Force stereo output, even if the stream is single or dual channel.
Playback
-s or --start=time
Begin playing at
time,
given as an offset from the beginning of the first file
(0:00:00),
seeking as necessary.
-t or --time=duration
Stop playback after the playing time of the output audio equals
duration.
-z or --shuffle
Randomize the list of files given on the command line for playback.
-r or --repeat[=max]
Play the input files
max
times, or indefinitely. Playback can be stopped prematurely by giving a time
limit with the
-t
(--time)
option. If
-z
(--shuffle)
is also used, the files will be continuously shuffled and repeated in such a
way that the same file is not played again until at least half of the other
files have played in the interim.
--tty-control
Enable keyboard controls during playback. This is the default unless standard
input is not a terminal or output is redirected with
-o
(--output).
The keyboard controls are:
P
Pause; press any key to resume.
S
Stop; press any key to replay the current file from the beginning.
F
Forward; advance to the next file.
B
Back; replay the current file, unless it has been playing for less than 4
seconds, in which case replay the previous file.
T
Time display; change the time display mode. This only works with
-v
(--verbose).
The display mode alternates among overall playing time, current time
remaining, and current playing time.
Q
Quit; stop decoding and exit.
--no-tty-control
Disable keyboard controls during playback. This is the default when standard
input is not a terminal or output is redirected with
-o
(--output).
Miscellaneous
-V or --version
Display the effective version and build options for
madplay
and exit.
--license
Display a license message and exit.
-h or --help
Display a usage message and exit.
Output Formats
Other than playing on the native audio device, the following output formats
are supported:
cdda
CD audio, 16-bit 44100 Hz stereo PCM
(*.cdr,
*.cda)
aiff
Audio IFF, [16-bit] PCM
(*.aif,
*.aiff)
wave
Microsoft RIFF/WAVE, [16-bit] PCM
(*.wav)
snd
Sun/NeXT audio, 8-bit ISDN µ-law
(*.au,
*.snd)
raw
binary [16-bit] host-endian linear PCM, stereo interleaved
hex
ASCII hexadecimal [24-bit] linear PCM, stereo interleaved, one sample per
output line (debug builds only)
esd
Enlightened Sound Daemon (EsounD) [16-bit] (give speaker host as
path)
null
no output (usually for testing or timing the decoder)
Default bit depths shown in square brackets can be changed with the
-b
(--bit-depth)
option.
Note that EsounD support requires the
libesd
library.
Time Specifications
For options which accept a time or duration argument, the following time
specifications are recognized:
hh:mm:ss.ddd
Hours, minutes, seconds, and decimal fractions of a second. This specification
is flexible;
hh:mm:ss,
mmm:ss,
:ss,
sss.ddd,
.ddd, and
ssss
are all acceptable. The component values are not constrained to any particular
range or number of digits.
frac/unit
A length of time specified as a rational number, in seconds. This can be used
for sample-granularity, for example
32/44100
for 32 samples, assuming a 44100 Hz sample frequency.
time1+time2
A composite time made by adding two time values together. This permits mixing
the above specification forms.
The resolution of any time value cannot exceed 1/352800000 seconds.
DIAGNOSTICS
error: frame #: lost synchronization
If encountered at the beginning of a file, this means the file contains
something other than an ID3v2 tag before the MPEG audio data. If encountered
in the middle of a file, it may mean the file is corrupt. This message is most
commonly encountered, however, at the end of a file if the file contains an
ID3v1 tag that is not aligned to an MPEG audio frame boundary. In this case,
the message is harmless and may be ignored.
error: frame #: bad main_data_begin pointer
This message can occur while decoding a Layer III stream that has been cut or
spliced without preserving its bit reservoir. The affected frame cannot be
properly decoded, but it will be used to help restore the bit reservoir for
the next frame.
Most other messages indicate a deficiency in the input stream.
When a frame cannot be properly decoded, a concealment strategy is used as
follows:
*
If the previous frame was properly decoded, it is repeated in place of the
current frame.
*
If the previous frame was
not
properly decoded, the current frame is muted.
CONFORMING TO
MAD conforms to Part 3 of the ISO/IEC 11172 (MPEG-1) international standard
for decoding MPEG audio. In addition, MAD supports the extension to Lower
Sampling Frequencies (LSF) as defined in Part 3 of ISO/IEC 13818 (MPEG-2).
The output from MAD has been tested and 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.
The ID3 tag parsing library used by
madplay
conforms to the ID3v2.4.0 informal standard.
NOTES
Because MAD produces samples with a precision greater than 24 bits, by default
madplay
will dither the samples to the precision of the output format. This produces
high quality audio that generally sounds superior to the output of a simple
rounding algorithm. However, dithering may unfavorably affect an analytic
examination of the output, and therefore it may be disabled by using the
-d
(--no-dither)
option.
The actual precision of output samples can be requested with the
-b
(--bit-depth)
option. Whether this request can be honored depends on the output format. If
output is directed to an audio device, success depends on the capabilities of
the device. If this option is not specified, a typical default depth will be
used (often 16) or in the case of output to an audio device, the highest bit
depth determined to work reliably with the device will be used.
Note that bit depths greater than 24 are effectively the same as 24-bit
precision samples padded to the requested depth.
BUGS
The granularity of start and stop times
(--start
and
--time)
is not yet as fine as this document suggests.