1MADPLAY(1) MPEG Audio Decoder MADPLAY(1)
2
3
4
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
16 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
21 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
26 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
30 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
34 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
37 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
44 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
55 -q or --quiet
56 Generally show less information than the default. Do not show
57 any information during decoding except warnings.
58
59 -Q or --very-quiet
60 Generally show no information except severe errors. Do not show
61 any information or warnings during decoding.
62
63 --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
69 Decoding
70 --downsample
71 Reduce the decoded sampling frequency 2:1. This also reduces the
72 computational overhead of the decoder.
73
74 -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
81 --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
89 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
98 -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
106 -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
114 -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
118 --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
122 -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
131 -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
141 -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
150 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
154 For stereo streams, making a channel selection other than stereo will
155 cause the output to become monaural.
156
157 -1 or --left
158 Output the first (left) channel only.
159
160 -2 or --right
161 Output the second (right) channel only.
162
163 -m or --mono
164 Mix the left and right channels together.
165
166 -S or --stereo
167 Force stereo output, even if the stream is single or dual chan‐
168 nel.
169
170 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
175 -t or --time=duration
176 Stop playback after the playing time of the output audio equals
177 duration.
178
179 -z or --shuffle
180 Randomize the list of files given on the command line for play‐
181 back.
182
183 -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
191 --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
197 P Pause; press any key to resume.
198
199 S Stop; press any key to replay the current file from the
200 beginning.
201
202 F Forward; advance to the next file.
203
204 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
207 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
212 + Increase gain; increase the audio output gain by 0.5 dB.
213
214 - Decrease gain; decrease the audio output gain by 0.5 dB.
215
216 Q Quit; stop decoding and exit.
217
218 --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
224 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
232 -V or --version
233 Display the effective version and build options for madplay and
234 exit.
235
236 --license
237 Display copyright, license, and warranty information and exit.
238
239 -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
246 cdda CD audio, 16-bit big-endian 44100 Hz stereo PCM, padded to
247 2352-byte block boundary (*.cdr, *.cda)
248
249 aiff Audio IFF, [16-bit] PCM (*.aif, *.aiff)
250
251 wave Microsoft RIFF/WAVE, [16-bit] PCM (*.wav)
252
253 snd Sun/NeXT audio, 8-bit ISDN μ-law (*.au, *.snd)
254
255 raw binary [16-bit] host-endian linear PCM, stereo interleaved
256
257 hex ASCII hexadecimal [24-bit] linear PCM, stereo interleaved, one
258 sample per output line
259
260 esd Enlightened Sound Daemon (EsounD) [16-bit] (give speaker host as
261 path)
262
263 null no output (usually for testing or timing the decoder)
264
265 Default bit depths shown in square brackets can be changed with the -b
266 (--bit-depth) option.
267
268 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
274 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
280 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
285 time1+time2
286 A composite time made by adding two time values together. This
287 permits mixing the above specification forms.
288
289 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
301 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
307 Most other messages indicate a deficiency in the input stream.
308
309 When a frame cannot be properly decoded, a concealment strategy is used
310 as follows:
311
312 · If the previous frame was properly decoded, it is repeated in place
313 of the current frame.
314
315 · 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
327 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
334 Note that bit depths greater than 24 are effectively the same as 24-bit
335 precision samples padded to the requested depth.
336
337 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
344 For applications which have uses for the stream, ancillary data can be
345 extracted with the --ancillary-output option.
346
347 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
355 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
360 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
365 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
371 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
377 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
387 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
392 The ID3 tag parsing library used by madplay conforms to the ID3v2.4.0
393 informal standard.
394
395 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
403 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)
411
412
413
414MAD 22 February 2004 MADPLAY(1)