1MADPLAY(1) MPEG Audio Decoder MADPLAY(1)
2
6 madplay - decode and play MPEG audio stream(s)
7
9 madplay [options] file ...
10 madplay [options] -o [type:]path file ...
11
13 madplay is a command-line MPEG audio decoder and player based on the
14 MAD library (libmad).
15 MAD is a high-quality MPEG audio decoder. It currently supports MPEG-1
17 and the MPEG-2 extension to Lower Sampling Frequencies, as well as the
18 so-called MPEG 2.5 format. All three audio layers (Layer I, Layer II,
19 and Layer III a.k.a. MP3) are fully implemented.
20 Among the special features of MAD are 24-bit PCM resolution and 100%
22 fixed-point (integer) computation. Since MAD is implemented entirely
23 without the use of floating point arithmetic, it performs especially
24 well on architectures without an FPU.
25 MAD does not yet support MPEG-2 multichannel audio (although it should
27 be backward compatible with such streams) nor does it currently support
28 AAC.
29 By default madplay reads and decodes one or more input files containing
31 MPEG audio data and plays them on the native audio device. If the input
32 file is a single dash (-), data is read from standard input.
33 Decoded output may optionally be redirected to a file instead of being
35 played on the audio device by using the -o (--output) option.
36 For each file, madplay will also attempt to read and display ID3 tag
38 information. The supported tag versions are ID3v1, ID3v1.1, ID3v2.2,
39 ID3v2.3, and ID3v2.4. If a tag contains relative volume adjustment
40 information (RVA2), madplay will use the information to adjust the mas‐
41 ter volume for output. This behavior can be changed with the -A
42 (--adjust-volume) and -G (--replay-gain) options.
43 If the -T (--show-tags-only) option is used, decoding is not performed
45 but tag information is still displayed. When used in conjunction with
46 -v (--verbose), encoder as well as ID3 tags are shown.
47
49 Verbosity
50 -v or --verbose
51 Generally show more information than the default. During decod‐
52 ing, show information about the stream including playing time,
53 audio layer, bit rate, sampling frequency, and stereo mode.
54 -q or --quiet
56 Generally show less information than the default. Do not show
57 any information during decoding except warnings.
58 -Q or --very-quiet
60 Generally show no information except severe errors. Do not show
61 any information or warnings during decoding.
62 --display-time=mode
64 Set the default verbose time display mode to mode, which must be
65 one of remaining, current, or overall. This is only relevant
66 with -v (--verbose). See --tty-control below for details on
67 changing the time display mode during playback.
68 Decoding
70 --downsample
71 Reduce the decoded sampling frequency 2:1. This also reduces the
72 computational overhead of the decoder.
73 -i or --ignore-crc
75 Ignore CRC information in the audio stream. This causes frames
76 with CRC errors to be decoded and played anyway. This option is
77 not recommended, but since some encoders have been known to gen‐
78 erate bad CRC information, this option is a work-around to play
79 streams from such encoders.
80 --ancillary-output=path
82 Write ancillary data from the MPEG audio stream to path. If
83 path is a single dash (-), the data will be written to standard
84 output. Bits from the ancillary data stream are packed into
85 octets; if any bits remain, the final octet will be padded with
86 zero bits. See the NOTES section below for further information
87 about this option.
88 Audio Output
90 -o or --output=[type:]path
91 Direct output to path, rather than playing audio on the native
92 audio device. The format of the output is specified by type
93 which can be any of the supported output formats (see Output
94 Formats below.) If a format is not specified, one will be
95 inferred from path. If path is a single dash (-), the output
96 will be written to standard output.
97 -b or --bit-depth=depth
99 Request an output precision of depth bits per sample. Higher bit
100 depths yield higher quality sound. Typical bit depths are 8, 16,
101 24, and 32, however other depths may also be possible. Whether
102 the request can be honored depends on the capabilities of the
103 audio device or output format. See the NOTES section below for
104 further details about this option.
105 -R or --sample-rate=hertz
107 Request an output sampling frequency of hertz samples per second
108 (Hz). The sample rate must be in the range 1000 to 65535 Hz.
109 Whether the request can be honored depends on the capabilities
110 of the audio device or output format. If the effective rate is
111 not the same as the rate of the decoded audio, output may be
112 resampled, possibly resulting in lower quality sound.
113 -d or --no-dither
115 Do not dither output PCM samples. This may result in lower qual‐
116 ity sound but is useful for analyzing output from the decoder.
117 --fade-in[=duration]
119 Gradually fade-in the audio from each file over duration. If
120 not specified, the default duration is 0:05 (five seconds.)
121 -a or --attenuate=decibels or --amplify=decibels
123 Attenuate or amplify the signal by decibels (dB). The signal is
124 attenuated if the decibel value is negative; it is amplified if
125 the value is positive. The value must be in the range -175 to
126 +18 dB. The value may be fractional, e.g. -1.5 dB. A value of
127 0 dB will leave the signal unchanged. Each step of 6 dB will
128 approximately halve (in the negative direction) or double (in
129 the positive direction) the strength of the signal.
130 -A or --adjust-volume=decibels
132 Adjust the relative volume for all files. This option overrides
133 any per-file volume adjustment settings. For example, -A0 may be
134 used to ignore relative volume adjustments given by ID3 tags.
135 Relative volume adjustments specified by this option or by ID3
136 tags are used as the base volume against which the signal is
137 further attenuated or amplified using the -a (--attenuate,
138 --amplify) option or keyboard controls. This option cannot be
139 used together with -G (--replay-gain).
140 -G or --replay-gain[=profile]
142 Enable Replay Gain volume adjustments. Replay Gain information
143 contained in the decoded files (if any) is used to make volume
144 adjustments for output. The profile may be one of radio (the
145 default) or audiophile. See the NOTES section below for further
146 details. When Replay Gain is enabled, a default pre-amp gain of
147 +6 dB is also applied; this can be changed with the -a (--atten‐
148 uate, --amplify) option.
149 Channel Selection
151 For dual channel streams, an output channel should be selected. If one
152 is not selected, the first (left) channel will be used.
153 For stereo streams, making a channel selection other than stereo will
155 cause the output to become monaural.
156 -1 or --left
158 Output the first (left) channel only.
159 -2 or --right
161 Output the second (right) channel only.
162 -m or --mono
164 Mix the left and right channels together.
165 -S or --stereo
167 Force stereo output, even if the stream is single or dual chan‐
168 nel.
169 Playback
171 -s or --start=time
172 Begin playing at time, given as an offset from the beginning of
173 the first file (0:00:00), seeking as necessary.
174 -t or --time=duration
176 Stop playback after the playing time of the output audio equals
177 duration.
178 -z or --shuffle
180 Randomize the list of files given on the command line for play‐
181 back.
182 -r or --repeat[=max]
184 Play the input files max times, or indefinitely. Playback can be
185 stopped prematurely by giving a time limit with the -t (--time)
186 option. If -z (--shuffle) is also used, the files will be con‐
187 tinuously shuffled and repeated in such a way that the same file
188 is not played again until at least half of the other files have
189 played in the interim.
190 --tty-control
192 Enable keyboard controls during playback. This is the default
193 unless standard input is not a terminal, output is redirected
194 with -o (--output), or either of -q (--quiet) or -Q
195 (--very-quiet) is given. The keyboard controls are:
196 P Pause; press any key to resume.
198 S Stop; press any key to replay the current file from the
200 beginning.
201 F Forward; advance to the next file.
203 B Back; replay the current file, unless it has been playing for
205 less than 4 seconds, in which case replay the previous file.
206 T Time display; change the time display mode. This only works
208 with -v (--verbose). The display mode alternates among over‐
209 all playing time, current time remaining, and current playing
210 time.
211 + Increase gain; increase the audio output gain by 0.5 dB.
213 - Decrease gain; decrease the audio output gain by 0.5 dB.
215 Q Quit; stop decoding and exit.
217 --no-tty-control
219 Disable keyboard controls during playback. This is the default
220 when standard input is not a terminal, output is redirected with
221 -o (--output), or either of -q (--quiet) or -Q (--very-quiet) is
222 given.
223 Miscellaneous
225 -T or --show-tags-only
226 Show ID3 and/or encoder tags from the input files but do not
227 otherwise decode or play any audio. By default only ID3 tags are
228 shown (if any). With -v (--verbose), all tags are shown. Encoder
229 tags recognized by madplay include the Xing VBR header tag and
230 the header tag format written by lame(1).
231 -V or --version
233 Display the effective version and build options for madplay and
234 exit.
235 --license
237 Display copyright, license, and warranty information and exit.
238 -h or --help
240 Display usage information and exit.
241
243 Other than playing on the native audio device, the following output
244 formats are supported:
245 cdda CD audio, 16-bit big-endian 44100 Hz stereo PCM, padded to
247 2352-byte block boundary (*.cdr, *.cda)
248 aiff Audio IFF, [16-bit] PCM (*.aif, *.aiff)
250 wave Microsoft RIFF/WAVE, [16-bit] PCM (*.wav)
252 snd Sun/NeXT audio, 8-bit ISDN μ-law (*.au, *.snd)
254 raw binary [16-bit] host-endian linear PCM, stereo interleaved
256 hex ASCII hexadecimal [24-bit] linear PCM, stereo interleaved, one
258 sample per output line
259 esd Enlightened Sound Daemon (EsounD) [16-bit] (give speaker host as
261 path)
262 null no output (usually for testing or timing the decoder)
264 Default bit depths shown in square brackets can be changed with the -b
266 (--bit-depth) option.
267 Note that EsounD support requires the libesd library.
269
271 For options which accept a time or duration argument, the following
272 time specifications are recognized:
273 hh:mm:ss.ddd
275 Hours, minutes, seconds, and decimal fractions of a second. This
276 specification is flexible; hh:mm:ss, mmm:ss, :ss, sss.ddd, .ddd,
277 and ssss are all acceptable. The component values are not con‐
278 strained to any particular range or number of digits.
279 frac/unit
281 A length of time specified as a rational number, in seconds.
282 This can be used for sample-granularity, for example 32/44100
283 for 32 samples, assuming a 44100 Hz sample frequency.
284 time1+time2
286 A composite time made by adding two time values together. This
287 permits mixing the above specification forms.
288 The resolution of any time value cannot exceed 1/352800000 seconds.
290
292 error: frame #: lost synchronization
293 If encountered at the beginning of a file, this means the file
294 contains something other than an ID3v2 tag before the MPEG audio
295 data. If encountered in the middle of a file, it may mean the
296 file is corrupt. This message is most commonly encountered, how‐
297 ever, at the end of a file if the file contains an ID3v1 tag
298 that is not aligned to an MPEG audio frame boundary. In this
299 case, the message is harmless and may be ignored.
300 error: frame #: bad main_data_begin pointer
302 This message can occur while decoding a Layer III stream that
303 has been cut or spliced without preserving its bit reservoir.
304 The affected frame cannot be properly decoded, but will be used
305 to help restore the bit reservoir for following frames.
306 Most other messages indicate a deficiency in the input stream.
308 When a frame cannot be properly decoded, a concealment strategy is used
310 as follows:
311 · If the previous frame was properly decoded, it is repeated in place
313 of the current frame.
314 · If the previous frame was not properly decoded, the current frame is
316 muted.
317
319 Output Precision
320 Because MAD produces samples with a precision greater than 24 bits, by
321 default madplay will dither the samples to the precision of the output
322 format. This produces high quality audio that generally sounds superior
323 to the output of a simple rounding algorithm. However, dithering may
324 unfavorably affect an analytic examination of the output, and therefore
325 it may be disabled by using the -d (--no-dither) option.
326 The actual precision of output samples can be requested with the -b
328 (--bit-depth) option. Whether the request can be honored depends on the
329 capabilities of the audio device or output format. If this option is
330 not specified, a typical default depth will be used (often 16) or in
331 the case of output to an audio device, the highest bit depth determined
332 to work reliably with the device will be used.
333 Note that bit depths greater than 24 are effectively the same as 24-bit
335 precision samples padded to the requested depth.
336 Ancillary Data
338 MPEG audio streams contain an ancillary data stream in addition to
339 audio data. Most often this does not contain any useful information
340 and may simply consist of padding bits. The MPEG-2 extension to multi‐
341 channel audio uses part of this ancillary stream to convey multichannel
342 information; presently MAD does not interpret such data.
343 For applications which have uses for the stream, ancillary data can be
345 extracted with the --ancillary-output option.
346 Replay Gain
348 madplay optionally supports the Replay Gain proposed standard with the
349 -G (--replay-gain) option to make compensating volume adjustments when
350 playing decoded audio from different sources. There are two Replay Gain
351 profiles: radio strives to make gain adjustments that give all tracks
352 equal loudness, while audiophile attempts to give ideal listening loud‐
353 ness. These adjustments are relative to a reference of 83 dB SPL.
354 A pre-amp gain is also used in conjunction with Replay Gain to achieve
356 the overall desired loudness. When Replay Gain is enabled, this pre-amp
357 gain defaults to +6 dB, however it can be changed with the -a (--atten‐
358 uate, --amplify) option or keyboard controls.
359 Note that when enabled, Replay Gain overrides any relative volume
361 adjustments specified by ID3 tags (RVA2). Replay Gain is also incompat‐
362 ible with the -A (--adjust-volume) option; any attempt to use it will
363 be ignored.
364 Replay Gain information is read either from an ID3 tag (RGAD) or from
366 an encoder tag written by lame(1). If both are present, the informa‐
367 tion in the ID3 tag takes precedence. In accordance with the proposed
368 standard, if the requested Replay Gain profile is not available but the
369 alternate is, the alternate is used instead.
370 Due to an unfortunate heresy, versions of lame(1) since 3.95.1 write
372 Replay Gain information using a reference of 89 dB SPL instead of the
373 83 dB specified in the Replay Gain proposed standard. To compensate,
374 madplay automatically subtracts 6 dB from the Replay Gain values read
375 from such tags.
376 Note that madplay does not yet support hard limiting as suggested by
378 the Replay Gain proposed standard; nor does it automatically reduce the
379 pre-amp gain to avoid clipping.
380
382 MAD conforms to Part 3 of the ISO/IEC 11172 (MPEG-1) international
383 standard for decoding MPEG audio. In addition, MAD supports the exten‐
384 sion to Lower Sampling Frequencies (LSF) as defined in Part 3 of
385 ISO/IEC 13818 (MPEG-2).
386 The output from MAD has been tested and found to satisfy the
388 ISO/IEC 11172-4 computational accuracy requirements for compliance. In
389 most configurations, MAD is a Full Layer III ISO/IEC 11172-3 audio
390 decoder as defined by the standard.
391 The ID3 tag parsing library used by madplay conforms to the ID3v2.4.0
393 informal standard.
394 With the exception of the clipping prevention provisions, Replay Gain
396 support provided by madplay is in accordance with the Replay Gain pro‐
397 posed standard published on July 10, 2001 by David Robinson.
398
400 The resampling algorithm used by madplay is one of a linear interpola‐
401 tion, and does not produce optimum quality sound.
402 The granularity of start and stop times (--start and --time) is not yet
404 as fine as this document suggests.
405
407 Robert Leslie <rob@mars.org>
408
410 lame(1), normalize(1), sox(1), wget(1)
411MAD 22 February 2004 MADPLAY(1)