Provided by: madplay_0.15.2b-7build1_i386 bug

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 u-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:

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