Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MADPLAY(1)		      MPEG Audio Decoder		    MADPLAY(1)

       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

       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 in-
       formation (RVA2), madplay will use the information to adjust the	master
       volume  for  output.  This  behavior  can be changed with the -A	(--ad-
       just-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	decod-
	      ing,  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.

	      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.

	      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 gen-
	      erate  bad CRC information, this option is a work-around to play
	      streams from such	encoders.

	      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  in-
	      ferred 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 re-
	      sampled, possibly	resulting in lower quality sound.

       -d or --no-dither
	      Do not dither output PCM samples.	This may result	in lower qual-
	      ity sound	but is useful for analyzing output from	the decoder.

	      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, --am-
	      plify) 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 de-
	      fault) 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 (--atten-
	      uate, --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 chan-

       -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

       -z or --shuffle
	      Randomize	the list of files given	on the command line for	 play-

       -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 con-
	      tinuously	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.

	      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 be-

	      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 over-
		 all playing time, current time	remaining, and current playing

	      +	 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.

	      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

       -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

	      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 <mu>-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

       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:

	      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  con-
	      strained to any particular range or number of digits.

	      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.

	      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, how-
	      ever, 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:

       o If the	previous frame was properly decoded, it	is repeated  in	 place
	 of the	current	frame.

       o If  the previous frame	was not	properly decoded, the current frame is

   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 au-
       dio data.  Most often this does not contain any useful information  and
       may  simply consist of padding bits. The	MPEG-2 extension to multichan-
       nel audio uses part of this ancillary stream to convey multichannel in-
       formation; 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 loud-
       ness. 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 (--atten-
       uate, --amplify)	option or keyboard controls.

       Note that when enabled, Replay Gain overrides any relative  volume  ad-
       justments  specified by ID3 tags	(RVA2).	Replay Gain is also incompati-
       ble with	the -A (--adjust-volume) option; any attempt to	use it will be

       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  informa-
       tion  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	exten-
       sion  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  de-
       coder 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 pro-
       posed standard published	on July	10, 2001 by David Robinson.

       The resampling algorithm	used by	madplay	is one of a linear  interpola-
       tion, 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 <>

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

MAD			       22 February 2004			    MADPLAY(1)


Want to link to this manual page? Use this URL:

home | help