MADPLAY(1)

MADPLAY(1) — MPEG Audio Decoder 💅🎧

okay bestie, this is the madplay manual and we are keeping every single detail, no cap. 💖

---

✨ 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, --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, --quiet — Generally show less information than the default. Do not show any information during decoding except warnings. 🤫
• -Q, --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, --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, --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, --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, --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, --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, --attenuate=decibels, --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, --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, --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, --left — Output the first (left) channel only. ⬅️
• -2, --right — Output the second (right) channel only. ➡️
• -m, --mono — Mix the left and right channels together. 🔀
• -S, --stereo — Force stereo output, even if the stream is single or dual channel. 🎶

▶️ Playback ▶️

• -s, --start=time — Begin playing at time, given as an offset from the beginning of the first file (0:00:00), seeking as necessary. ⏩
• -t, --time=duration — Stop playback after the playing time of the output audio equals duration. ⏹️
• -z, --shuffle — Randomize the list of files given on the command line for playback. 🔀
• -r, --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, --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, --version — Display the effective version and build options for madplay and exit. ℹ️
• --license — Display copyright, license, and warranty information and exit. 📜
• -h, --help — Display usage information and exit. 🆘

✨ Output Formats ✨

Okay so besides just blasting audio out of your actual sound device, madplay can spit the decoded audio out in a whole lil menu of formats bestie:

• cdda — CD audio: 16-bit big-endian 44100 Hz stereo PCM, padded all the way out to a 2352-byte block boundary. Files look like *.cdr, *.cda 🎀
• aiff — Audio IFF, [16-bit] PCM. That's your *.aif, *.aiff girlies ✨
• wave — Microsoft RIFF/WAVE, [16-bit] PCM. Hellooo *.wav 💖
• snd — Sun/NeXT audio, 8-bit ISDN μ-law. *.au, *.snd 🌸
• raw — binary [16-bit] host-endian linear PCM, stereo interleaved. Just raw. No thoughts, no container, no vibes 💀
• hex — ASCII hexadecimal [24-bit] linear PCM, stereo interleaved, and it puts one sample per output line which is honestly so extra of it 🌈
• esd — Enlightened Sound Daemon (EsounD) [16-bit] — and you gotta hand it the speaker host as the path, iykyk 👑
• null — literally no output at all. Usually for testing or for timing the decoder, not for listening, obviously 🦋

The default bit depths sitting in those square brackets? Changeable with the -b (--bit-depth) option, slay.

Heads up bestie: EsounD support needs the libesd library. No lib, no EsounD, no exceptions 🫶

---

✨ Time Specifications ✨

Some options want a time or a duration, and when they do, here's the whole alphabet of what they'll accept:

• hh:mm:ss.ddd — hours, minutes, seconds, and decimal fractions of a second. And it's flexible flexible: hh:mm:ss, mmm:ss, :ss, sss.ddd, .ddd, and ssss all work. The components are not locked to any particular range or number of digits, so go off 🎀
• frac/unit — a length of time written as a rational number, in seconds. This one's for when you need sample-granularity precision — like 32/44100 for 32 samples, assuming a 44100 Hz sample frequency 🧚
• time1+time2 — a composite time made by adding two time values together. This lets you mix and match all the forms above, iconic behaviour honestly 💅

Real talk though: the resolution of any time value cannot exceed 1/352800000 seconds. That's the ceiling. Periodt.

---

💀 DIAGNOSTICS 💀

• error: frame #: lost synchronization If you see this at the beginning of a file, it means the file's got something before the MPEG audio data that isn't an ID3v2 tag. If you see it in the middle of a file, it might mean the file is corrupt 😭 But — and here's the plot twist — this message is most commonly seen at the end of a file, when the file has an ID3v1 tag that isn't aligned to an MPEG audio frame boundary. In that case, bestie, it's harmless and you can just ignore it. Not me getting stressed over nothing 🙈
• error: frame #: bad main_data_begin pointer This one shows up while decoding a Layer III stream that's 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 following frames. So it's doing its best, okay 🥺

Most other messages mean there's a deficiency in the input stream.

When a frame can't be properly decoded, madplay runs this concealment strategy:

• If the previous frame was properly decoded, it gets repeated in place of the current frame 🔁
• If the previous frame was not properly decoded, the current frame gets muted 🤫

---

📝 NOTES 📝

🎚️ Output Precision 🎚️

So MAD produces samples with a precision greater than 24 bits, which means by default madplay will dither the samples down to the precision of the output format. And that's a good thing — it produces high quality audio that generally sounds superior to what a simple rounding algorithm would give you. Chef's kiss 👑

But — dithering may unfavorably affect an analytic examination of the output. So if you're doing science and not vibes, you can disable it with the -d (--no-dither) option 🧪

You can request the actual precision of output samples with the -b (--bit-depth) option. Whether that request gets honored depends on the capabilities of the audio device or the output format. If you don't specify it, a typical default depth gets used (often 16) — or, in the case of output to an audio device, the highest bit depth that's been determined to work reliably with that device gets used. Very demure, very mindful of your hardware 💅

Note that bit depths greater than 24 are effectively the same as 24-bit precision samples padded out to whatever depth you asked for. Just padding, no extra truth ✨

🍓 Ancillary Data 🍓

MPEG audio streams carry an ancillary data stream alongside the actual audio data. Most of the time it's carrying absolutely nothing useful and might just be padding bits — filler, background character energy 🌸

The MPEG-2 extension to multichannel audio uses part of this ancillary stream to convey multichannel information, but presently MAD does not interpret that kind of data. It's not on MAD's radar yet 🙈

For applications that do have a use for the stream, you can extract the ancillary data with the --ancillary-output option 💖

🔊 Replay Gain 🔊

madplay optionally supports the Replay Gain proposed standard with the -G (--replay-gain) option, so it can make compensating volume adjustments when you're playing decoded audio from all different sources. There are two Replay Gain profiles:

• radio — strives to make gain adjustments that give all tracks equal loudness 📻
• 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 hit the overall desired loudness. When Replay Gain is enabled, this pre-amp gain defaults to +6 dB — but you can change it with the -a (--attenuate, --amplify) option or with the keyboard controls 🎹

Careful bestie: when enabled, Replay Gain overrides any relative volume adjustments specified by ID3 tags (RVA2). And Replay Gain is also incompatible with the -A (--adjust-volume) option — any attempt to use them together will be ignored. It's giving pick a lane 💅

Replay Gain info 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. And in accordance with the proposed standard, if the Replay Gain profile you asked for isn't available but the alternate one is, the alternate gets used instead. Flexible, adaptable, iconic 🦋

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. Cleaning up someone else's mess, we love that for us 😭

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. So watch your levels, okay? 🚨

---

🌈 CONFORMING TO 🌈

MAD conforms to Part 3 of the ISO/IEC 11172 (MPEG-1) international standard for decoding MPEG audio. On top of that, MAD supports the extension to Lower Sampling Frequencies (LSF) as defined in Part 3 of ISO/IEC 13818 (MPEG-2). Standards-compliant and well-read 📚

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. Main character behaviour, honestly 👑

The ID3 tag parsing library used by madplay conforms to the ID3v2.4.0 informal standard 💖

With the exception of the clipping prevention provisions, the Replay Gain support provided by madplay is in accordance with the Replay Gain proposed standard published on July 10, 2001 by David Robinson. Shoutout David 🫶

---

🐛 BUGS 🐛

• The resampling algorithm used by madplay is one of a linear interpolation, and it does not produce optimum quality sound. It's doing its best and its best is linear interpolation 😔
• The granularity of start and stop times (--start and --time) is not yet as fine as this document suggests. The docs are out here making promises the code hasn't kept 💀

---

👑 AUTHOR 👑

Robert Leslie <rob@mars.org>

---

🔗 SEE ALSO 🔗

lame(1), normalize(1), sox(1), wget(1)

---

And that's the whole page bestie!! 🎀 This one's from the MAD manual, dated 22 February 2004, and it's MADPLAY(1) — go forth and decode some MPEG audio, you absolute legend 💖✨👑