madplay - decode and play MPEG audio stream(s)
madplay [
options]
file ...
madplay [
options]
-o [
type:]
path
file ...
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. The supported tag versions are ID3v1, ID3v1.1, ID3v2.2,
ID3v2.3, and ID3v2.4. If a tag contains relative volume adjustment information
(RVA2),
madplay will use the information to adjust the master volume
for output. This behavior can be changed with the
-A
(
--adjust-volume) and
-G (
--replay-gain) options.
If the
-T (
--show-tags-only) option is used, decoding is not
performed but tag information is still displayed. When used in conjunction
with
-v (
--verbose), encoder as well as ID3 tags are shown.
-
-v or --verbose
- Generally show more information than the default. During
decoding, show information about the stream including playing time, audio
layer, bit rate, sampling frequency, and stereo mode.
-
-q or --quiet
- Generally show less information than the default. Do not
show any information during decoding except warnings.
-
-Q or --very-quiet
- Generally show no information except severe errors. Do not
show any information or warnings during decoding.
-
--display-time=mode
- Set the default verbose time display mode to mode,
which must be one of remaining, current, or overall.
This is only relevant with -v (--verbose). See
--tty-control below for details on changing the time display mode
during playback.
- --downsample
- Reduce the decoded 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.
-
--ancillary-output=path
- Write ancillary data from the MPEG audio stream to
path. If path is a single dash (-), the data will be written
to standard output. Bits from the ancillary data stream are packed into
octets; if any bits remain, the final octet will be padded with zero bits.
See the NOTES section below for further information about this
option.
-
-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. Whether
the request can be honored depends on the capabilities of the audio device
or output format. See the NOTES section below for further details
about this option.
-
-R or --sample-rate=hertz
- Request an output sampling frequency of hertz
samples per second (Hz). The sample rate must be in the range 1000 to
65535 Hz. Whether the request can be honored depends on the
capabilities of the audio device or output format. If the effective rate
is not the same as the rate of the decoded audio, output may be resampled,
possibly resulting in lower quality sound.
-
-d or --no-dither
- Do not dither output PCM samples. This may result in lower
quality sound 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 value must be in the range -175 to
+18 dB. The value may be fractional, e.g. -1.5 dB. A value
of 0 dB 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.
-
-A or --adjust-volume=decibels
- Adjust the relative volume for all files. This option
overrides any per-file volume adjustment settings. For example, -A0
may be used to ignore relative volume adjustments given by ID3 tags.
Relative volume adjustments specified by this option or by ID3 tags are
used as the base volume against which the signal is further attenuated or
amplified using the -a (--attenuate, --amplify)
option or keyboard controls. This option cannot be used together with
-G (--replay-gain).
-
-G or
--replay-gain[=profile]
- Enable Replay Gain volume adjustments. Replay Gain
information contained in the decoded files (if any) is used to make volume
adjustments for output. The profile may be one of radio (the
default) or audiophile. See the NOTES section below for
further details. When Replay Gain is enabled, a default pre-amp gain of
+6 dB is also applied; this can be changed with the -a
(--attenuate, --amplify) option.
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.
-
-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, output is redirected with
-o (--output), or either of -q (--quiet) or
-Q (--very-quiet) is given. 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.
- +
- Increase gain; increase the audio output gain by
0.5 dB.
- -
- Decrease gain; decrease the audio output gain by
0.5 dB.
- 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, output is redirected with
-o (--output), or either of -q (--quiet) or
-Q (--very-quiet) is given.
-
-T or --show-tags-only
- Show ID3 and/or encoder tags from the input files
but do not otherwise decode or play any audio. By default only ID3 tags
are shown (if any). With -v (--verbose), all tags are shown.
Encoder tags recognized by madplay include the Xing VBR header tag
and the header tag format written by lame(1).
-
-V or --version
- Display the effective version and build options for
madplay and exit.
- --license
- Display copyright, license, and warranty information and
exit.
-
-h or --help
- Display usage information and exit.
Other than playing on the native audio device, the following output formats are
supported:
- cdda
- CD audio, 16-bit big-endian 44100 Hz stereo PCM,
padded to 2352-byte block boundary (*.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
- 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.
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.
- 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 will be used to help
restore the bit reservoir for following frames.
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.
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 the request can be honored depends on the
capabilities of the audio device or output format. 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.
MPEG audio streams contain an ancillary data stream in addition to audio data.
Most often this does not contain any useful information and may simply consist
of padding bits. The MPEG-2 extension to multichannel audio uses part of this
ancillary stream to convey multichannel information; presently MAD does not
interpret such data.
For applications which have uses for the stream, ancillary data can be extracted
with the
--ancillary-output option.
madplay optionally supports the Replay Gain proposed standard with the
-G (
--replay-gain) option to make compensating volume
adjustments when playing decoded audio from different sources. There are two
Replay Gain profiles:
radio strives to make gain adjustments that give
all tracks equal loudness, while
audiophile attempts to give ideal
listening loudness. These adjustments are relative to a reference of
83 dB SPL.
A pre-amp gain is also used in conjunction with Replay Gain to achieve the
overall desired loudness. When Replay Gain is enabled, this pre-amp gain
defaults to +6 dB, however it can be changed with the
-a
(
--attenuate,
--amplify) option or keyboard controls.
Note that when enabled, Replay Gain overrides any relative volume adjustments
specified by ID3 tags (RVA2). Replay Gain is also incompatible with the
-A (
--adjust-volume) option; any attempt to use it will be
ignored.
Replay Gain information is read either from an ID3 tag (RGAD) or from an encoder
tag written by
lame(1). If both are present, the information in the ID3
tag takes precedence. In accordance with the proposed standard, if the
requested Replay Gain profile is not available but the alternate is, the
alternate is used instead.
Due to an unfortunate heresy, versions of
lame(1) since 3.95.1 write
Replay Gain information using a reference of 89 dB SPL instead of the
83 dB specified in the Replay Gain proposed standard. To compensate,
madplay automatically subtracts 6 dB from the Replay Gain values
read from such tags.
Note that
madplay does not yet support hard limiting as suggested by the
Replay Gain proposed standard; nor does it automatically reduce the pre-amp
gain to avoid clipping.
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.
With the exception of the clipping prevention provisions, Replay Gain support
provided by
madplay is in accordance with the Replay Gain proposed
standard published on July 10, 2001 by David Robinson.
The resampling algorithm used by
madplay is one of a linear
interpolation, and does not produce optimum quality sound.
The granularity of start and stop times (
--start and
--time) is
not yet as fine as this document suggests.
Robert Leslie <
[email protected]>
lame(1),
normalize(1),
sox(1),
wget(1)