madplay(1)
NAME
madplay - decode and play MPEG audio stream(s)
SYNOPSIS
madplay [options] file ... madplay [options] -o [type:]path file ...
DESCRIPTION
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.
OPTIONS
Verbosity
-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.
Decoding
--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.
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. 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.
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, 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.
Miscellaneous
-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.
Output Formats
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.
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 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.
NOTES
Output Precision 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. Ancillary Data 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. Replay Gain 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.
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. 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.
BUGS
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.
AUTHOR
Robert Leslie <rob@mars.org>
SEE ALSO
lame(1), normalize(1), sox(1), wget(1)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
