manpagez: man pages & more
man mpg123(1)
Home | html | info | man
mpg123(1)                                                            mpg123(1)


       mpg123 - play audio MPEG 1.0/2.0/2.5 stream (layers 1, 2 and 3)


       mpg123 [ options ] file-or-URL...


       mpg123  reads  one  or more files (or standard input if ``-'' is speci-
       fied) or URLs and plays them on the audio device (default)  or  outputs
       them to stdout.  file/URL is assumed to be an MPEG audio bit stream.


       The following operands are supported:

       file(s) The  path  name(s)  of  one  or more input files.  They must be
               valid MPEG-1.0/2.0/2.5 audio layer 1, 2 or 3 bit streams.  If a
               dash  ``-'' is specified, MPEG data will be read from the stan-
               dard input.  Furthermore, any name starting with ``http://'' is
               recognized as URL (see next section).


       mpg123  options may be either the traditional POSIX one letter options,
       or the GNU style long options.  POSIX style options start with a single
       ``-'',  while GNU long options start with ``--''.  Option arguments (if
       needed) follow separated by whitespace (not  ``='').   Note  that  some
       options can be absent from your installation when disabled in the build


       -k num, --skip num
              Skip first num frames.  By default the decoding  starts  at  the
              first frame.

       -n num, --frames num
              Decode  only  num  frames.   By  default  the complete stream is

              Enable fuzzy seeks (guessing byte offsets or  using  approximate
              seek  points  from  Xing TOC).  Without that, seeks need a first
              scan through the file before they can jump  at  positions.   You
              can decide here: sample-accurate operation with gapless features
              or faster (fuzzy) seeking.

       -y, --no-resync
              Do NOT try to resync and continue decoding if an error occurs in
              the  input  file.  Normally,  mpg123  tries to keep the playback
              alive at all costs,  including  skipping  invalid  material  and
              searching  new  header  when  something  goes  wrong.  With this
              switch you can make it bail out  on  data  errors  (and  perhaps
              spare  your  ears  a  bad  time). Note that this switch has been
              renamed from --resync.  The old name still  works,  but  is  not
              advertised  or recommened to use (subject to removal in future).

       --resync-limit bytes
              Set number of bytes to search for valid MPEG data once  lost  in
              stream;  <0  means  search  whole stream.  If you know there are
              huge chunks of invalid data in your files... here is  your  ham-
              mer.   Note:  Only  since  version  1.14 this also increases the
              amount of junk skipped on beginning.

       -p URL | none, --proxy URL | none
              The specified proxy will be used for HTTP requests.   It  should
              be specified as full URL (``http://host.domain:port/''), but the
              ``http://'' prefix, the port number and the trailing  slash  are
              optional (the default port is 80).  Specifying none means not to
              use any proxy, and to retrieve files directly from  the  respec-
              tive servers.  See also the ``HTTP SUPPORT'' section.

       -u auth, --auth auth
              HTTP  authentication  to use when recieving files via HTTP.  The
              format used is user:password.

              Ignore MIME types given by HTTP server. If you know  better  and
              want  mpg123 to decode something the server thinks is image/png,
              then just do it.

              Disable the default micro-buffering of non-seekable streams that
              gives the parser a safer footing.

       -@ file, --list file
              Read filenames and/or URLs of MPEG audio streams from the speci-
              fied file in addition to the ones specified on the command  line
              (if any).  Note that file can be either an ordinary file, a dash
              ``-'' to indicate that a list of filenames/URLs is  to  be  read
              from  the standard input, or an URL pointing to a an appropriate
              list file.  Note: only one -@ option can be used (if  more  than
              one is specified, only the last one will be recognized).

       -l n, --listentry n
              Of  the playlist, play specified entry only.  n is the number of
              entry starting at 1. A value of  0  is  the  default  and  means
              playling  the whole list,  a negative value means showing of the
              list of titles with their numbers...

              Enable playlist continuation mode. This changes  frame  skipping
              to apply only to the first track and also continues to play fol-
              lowing tracks in playlist after  the  selected  one.  Also,  the
              option  to  play  a  number  of frames only applies to the whole
              playlist. Basically, this tries to treat the playlist more  like
              one  big stream (like, an audio book).  The current track number
              in list (1-based) and frame number (0-based) are printed at exit
              (useful if you interrupted playback and want to continue later).
              Note that the continuation info is printed  to  standard  output
              unless the switch for piping audio data to standard out is used.
              Also, it really makes sense to work with actual  playlist  files
              instead of lists of file names as arguments, to keep track posi-
              tions consistent.

       --loop times
              for looping track(s) a certain number of times, < 0 means  infi-
              nite loop (not with --random!).

              For  remote  control  mode: Keep loaded file open after reaching

       --timeout seconds
              Timeout in (integer) seconds before declaring a stream dead  (if
              <= 0, wait forever).

       -z, --shuffle
              Shuffle play.  Randomly shuffles the order of files specified on
              the command line, or in the list file.

       -Z, --random
              Continuous random play.  Keeps picking a random  file  from  the
              command  line or the play list.  Unlike shuffle play above, ran-
              dom play never ends, and plays individual songs more than  once.

              Do not accept ICY meta data.

       -i, --index
              Index  / scan through the track before playback.  This fills the
              index table for seeking (if enabled in libmpg123) and  may  make
              the  operating system cache the file contents for smoother oper-
              ating on playback.

       --index-size size
              Set the number of entries in the seek frame index table.

       --preframes num
              Set the number of frames to be read as lead-in before a  seeked-
              to  position.   This  serves  to fill the layer 3 bit reservoir,
              which is needed to faithfully reproduce a certain  sample  at  a
              certain  position.   Note  that  for  layer 3, a minimum of 1 is
              enforced (because of frame overlap), and for layer 1 and 2, this
              is limited to 2 (no bit reservoir in that case, but engine spin-
              up anyway).


       -o module, --output module
              Select audio output module. You can  provide  a  comma-separated
              list to use the first one that works.

              List the available modules.

       -a dev, --audiodevice dev
              Specify  the  audio device to use.  The default is system-depen-
              dent (usually /dev/audio or /dev/dsp).  Use this option  if  you
              have  multiple  audio  devices  and  the default is not what you

       -s, --stdout
              The decoded  audio  samples  are  written  to  standard  output,
              instead  of  playing them through the audio device.  This option
              must be used if your audio hardware is not supported by  mpg123.
              The  output  format  per  default is raw (headerless) linear PCM
              audio data, 16 bit, stereo, host byte order (you can force  mono
              or 8bit).

       -O file, --outfile
              Write  raw  output  into  a  file (instead of simply redirecting
              standard output to a file with the shell).

       -w file, --wav
              Write output as WAV file. This will cause the MPEG stream to  be
              decoded and saved as file file , or standard output if - is used
              as file name. You can also use --au and --cdr  for  AU  and  CDR
              format,  respectively.  Note that WAV/AU writing to non-seekable
              files, or redirected stdout, needs some thought.  Since  1.16.0,
              the  logic  changed  to writing the header with the first actual
              data. This avoids spurious WAV headers in a pipe,  for  example.
              The  result  of  decoding nothing to WAV/AU is a file consisting
              just of the header when it is seekable and really  nothing  when
              not  (not  even a header). Correctly writing data with prophetic
              headers to stdout is no easy business.

       --au file
              Does not play the MPEG file but writes it to file in  SUN  audio
              format.  If - is used as the filename, the AU file is written to
              stdout. See paragraph about WAV writing for header fun with non-
              seekable streams.

       --cdr file
              Does not play the MPEG file but writes it to file as a CDR file.
              If - is used as the filename, the CDR file is written to stdout.

              Forces reopen of the audiodevice after ever song

       --cpu decoder-type
              Selects  a  certain  decoder  (optimized  for specific CPU), for
              example i586 or MMX.  The list of available decoders  can  vary;
              depending on the build and what your CPU supports.  This options
              is only availabe when the build actually includes several  opti-
              mized decoders.

              Tests  your CPU and prints a list of possible choices for --cpu.

              Lists all available decoder choices, regardless  of  support  by
              your CPU.

       -g gain, --gain gain
              [DEPRECATED]  Set  audio  hardware  output  gain (default: don't
              change). The unit of the gain value is hardware and output  mod-
              ule  dependent.   (This parameter is only provided for backwards
              compatibility and may be removed in  the  future  without  prior
              notice.  Use  the  audio  player for playing and a mixer app for
              mixing, UNIX style!)

       -f factor, --scale factor
              Change scale factor (default: 32768).

       --rva-mix, --rva-radio
              Enable RVA (relative volume adjustment) using the values  stored
              for  ReplayGain  radio  mode  / mix mode with all tracks roughly
              equal loudness.  The first valid information found in ID3V2 Tags
              (Comment  named  RVA  or the RVA2 frame) or ReplayGain header in
              Lame/Info Tag is used.

       --rva-album, --rva-audiophile
              Enable RVA (relative volume adjustment) using the values  stored
              for  ReplayGain  audiophile  mode  / album mode with usually the
              effect of adjusting album loudness but keeping relative loudness
              inside  album.   The first valid information found in ID3V2 Tags
              (Comment named RVA_ALBUM or the RVA2 frame) or ReplayGain header
              in Lame/Info Tag is used.

       -0, --single0; -1, --single1
              Decode only channel 0 (left) or channel 1 (right), respectively.
              These options are available for stereo MPEG streams only.

       -m, --mono, --mix, --singlemix
              Mix both channels / decode mono. It takes  less  CPU  time  than
              full stereo decoding.

              Force stereo output

       -r rate, --rate rate
              Set  sample  rate  (default: automatic).  You may want to change
              this if you need a constant  bitrate  independent  of  the  mpeg
              stream  rate. mpg123 automagically converts the rate. You should
              then combine this with --stereo or --mono.

       -2, --2to1; -4, --4to1
              Performs a downsampling of ratio 2:1 (22 kHz) or 4:1 (11 kHz) on
              the  output  stream, respectively. Saves some CPU cycles, but at
              least the 4:1 ratio sounds ugly.

       --pitch value
              Set hardware pitch (speedup/down, 0 is  neutral;  0.05  is  5%).
              This  changes  the output sampling rate, so it only works in the
              range your audio system/hardware supports.

       --8bit Forces 8bit output

              Forces f32 encoding

       -e enc, --encoding enc
              Choose output sample encoding. Possible  values  look  like  f32
              (32-bit  floating  point),  s32  (32-bit  signed  integer),  u32
              (32-bit unsigned integer) and the variants with  different  num-
              bers of bits (s24, u24, s16, u16, s8, u8) and also special vari-
              ants like ulaw and alaw  8-bit.   See  the  output  of  mpg123's
              longhelp for actually available encodings.

       -d n, --doublespeed n
              Only  play every n'th frame.  This will cause the MPEG stream to
              be played n times faster, which can be used for special effects.
              Can  also  be combined with the --halfspeed option to play 3 out
              of 4 frames etc.  Don't expect great sound  quality  when  using
              this option.

       -h n, --halfspeed n
              Play  each frame n times.  This will cause the MPEG stream to be
              played at 1/n'th speed (n times slower), which can be  used  for
              special  effects.  Can  also  be combined with the --doublespeed
              option to double every third frame or things like  that.   Don't
              expect great sound quality when using this option.

       -E file, --equalizer
              Enables  equalization,  taken from file.  The file needs to con-
              tain 32 lines of data, additional comment lines may be  prefixed
              with  #.  Each data line consists of two floating-point entries,
              separated by whitespace.  They specify the multipliers for  left
              and  right  channel  of  a certain frequency band, respectively.
              The first line corresponds to the lowest, the 32nd to the  high-
              est  frequency  band.   Note  that you can control the equalizer
              interactively with the generic control interface.

              Enable code that cuts (junk) samples at  beginning  and  end  of
              tracks,  enabling  gapless  transitions  between MPEG files when
              encoder padding and codec delays  would  prevent  it.   This  is
              enabled per default beginning with mpg123 version 1.0.0 .

              Disable  the  gapless  code.  That  gives you MP3 decodings that
              include encoder delay and padding plus mpg123's decoder delay.

              Do not parse the Xing/Lame/VBR/Info  frame,  decode  it  instead
              just  like  a stupid old MP3 hardware player.  This implies dis-
              abling of gapless playback as the necessary  information  is  in
              said metadata frame.

       -D n, --delay n
              Insert a delay of n seconds before each track.

       -o h, --headphones
              Direct  audio  output  to the headphone connector (some hardware
              only; AIX, HP, SUN).

       -o s, --speaker
              Direct audio output to the speaker  (some  hardware  only;  AIX,
              HP, SUN).

       -o l, --lineout
              Direct  audio  output  to  the line-out connector (some hardware
              only; AIX, HP, SUN).

       -b size, --buffer size
              Use an audio output buffer of size Kbytes.  This  is  useful  to
              bypass  short periods of heavy system activity, which would nor-
              mally cause the audio output  to  be  interrupted.   You  should
              specify  a buffer size of at least 1024 (i.e. 1 Mb, which equals
              about 6 seconds of audio data) or more; less than about 300 does
              not  make  much  sense.  The default is 0, which turns buffering

       --preload fraction
              Wait for the buffer to be filled  to  fraction  before  starting
              playback  (fraction  between  0  and  1). You can tune this pre-
              buffering to either get faster sound to your ears or safer unin-
              terrupted web radio.  Default is 0.2 (wait for 20 % of buffer to
              be full, changed from 1 in version 1.23).

       --devbuffer seconds
              Set device buffer in seconds; <= 0 means default value. This  is
              the  small buffer between the application and the audio backend,
              possibly directly related to hardware buffers.

              Keep buffer over track boundaries -- meaning, do not  empty  the
              buffer between tracks for possibly some added smoothness.


       -t, --test
              Test mode.  The audio stream is decoded, but no output occurs.

       -c, --check
              Check  for  filter  range violations (clipping), and report them
              for each frame if any occur.

       -v, --verbose
              Increase the verbosity level.  For example, displays  the  frame
              numbers during decoding.

       -q, --quiet
              Quiet.  Suppress diagnostic messages.

       -C, --control
              Enable terminal control keys. This is enabled automatically if a
              terminal is detected.  By default use 's' or the  space  bar  to
              stop/restart  (pause,  unpause) playback, 'f' to jump forward to
              the next song, 'b' to jump back to the beginning  of  the  song,
              ','  to  rewind, '.' to fast forward, and 'q' to quit.  Type 'h'
              for a full list of available controls.

              Disable terminal control even if terminal is detected.

              In an xterm, rxvt, screen, iris-ansi (compatible, TERM  environ-
              ment  variable  is  examined),  change the window's title to the
              name of song currently playing.

       --name name
              Set the name of this instance, possibly used in various  places.
              This sets the client name for JACK output.

              Display  ID3  tag  info  always in long format with one line per
              item (artist, title, ...)

       --utf8 Regardless of environment, print metadata in  UTF-8  (otherwise,
              when not using UTF-8 locale, you'll get ASCII stripdown).

       -R, --remote
              Activate  generic  control interface.  mpg123 will then read and
              execute commands from stdin. Basic usage is ``load <filename> ''
              to  play some file and the obvious ``pause'', ``command.  ``jump
              <frame>'' will jump/seek to a given point (MPEG  frame  number).
              Issue ``help'' to get a full list of commands and syntax.

              Print  responses for generic control mode to standard error, not
              standard out.  This is automatically triggered when using -s  N.

       --fifo path
              Create  a  fifo  / named pipe on the given path and use that for
              reading commands instead of standard input.

              Tries to get higher priority

       -T, --realtime
              Tries to gain realtime priority.  This option  usually  requires
              root privileges to have any effect.

       -?, --help
              Shows short usage instructions.

              Shows long usage instructions.

              Print the version string.


       In  addition to reading MPEG audio streams from ordinary files and from
       the standard input, mpg123 supports retrieval of MPEG  audio  files  or
       playlists  via  the  HTTP protocol, which is used in the World Wide Web
       (WWW).  Such files are specified using a so-called  URL,  which  starts
       with  ``http://''.  When a file with that prefix is encountered, mpg123
       attempts to open an HTTP connection to the server in order to  retrieve
       that file to decode and play it.

       It  is  often useful to retrieve files through a WWW cache or so-called
       proxy.  To accomplish this, mpg123 examines the environment  for  vari-
       ables  named  MP3_HTTP_PROXY, http_proxy and HTTP_PROXY, in this order.
       The value of the first one that is set will be used as proxy specifica-
       tion.   To  override  this, you can use the -p command line option (see
       the ``OPTIONS'' section).  Specifying -p none will  enforce  contacting
       the  server  directly without using any proxy, even if one of the above
       environment variables is set.

       Note that, in order to play MPEG audio files from a WWW server,  it  is
       necessary that the connection to that server is fast enough.  For exam-
       ple, a 128 kbit/s MPEG file requires the network connection  to  be  at
       least  128  kbit/s  (16 kbyte/s) plus protocol overhead.  If you suffer
       from short network outages, you should try the -b  option  (buffer)  to
       bypass  such outages.  If your network connection is generally not fast
       enough to retrieve MPEG audio files in realtime, you can first download
       the  files  to  your  local harddisk (e.g. using wget(1)) and then play
       them from there.

       If authentication is needed to access the file it can be specified with
       the -u user:pass.


       When  in  terminal  control  mode, you can quit via pressing the q key,
       while any time you can abort mpg123 by pressing Ctrl-C. If not in  ter-
       minal  control  mode,  this will skip to the next file (if any). If you
       want to abort playing immediately in that case, press Ctrl-C  twice  in
       short succession (within about one second).

       Note  that  the  result of quitting mpg123 pressing Ctrl-C might not be
       audible immediately, due to audio data buffering in the  audio  device.
       This  delay is system dependent, but it is usually not more than one or
       two seconds.


       In verbose mode, mpg123 updates a line with various information center-
       ing  around  the current playback position. On any decent terminal, the
       line also works as a progress bar in  the  current  file  by  reversing
       video  for a fraction of the line according to the current position. An
       example for a full line is this:

            > 0291+0955  00:01.68+00:28.22 [00:05.30]  mix  100=085  192  kb/s
       576 B acc   18 clip p+0.014

       The information consists of, in order:

       >      single-character  playback  state  (``>'' for playing, ``='' for
              pausing/looping, ``_'' for stopped)

              current frame offset and number of remaining  frames  after  the
              plus sign

              current  position from and remaining time in human terms (hours,
              minutes, seconds)

              fill of the output buffer in terms  of  playback  time,  if  the
              buffer is enabled

       mix    selected  RVA  mode  (possible values: mix, alb (album), and ---
              (neutral, off))

              set volume and the RVA-modified effective volume after the equal

       192 kb/s
              current bitrate

       576 B  size of current frame in bytes

       acc    if positions are accurate, possible values are ``acc'' for accu-
              rate positions or ``fuz'' for fuzzy (with guessed  byte  offsets
              using mean frame size)

       18 clip
              amount of clipped samples, non-zero only if decoder reports that
              (generic does, some optimized ones not)

              pitch change (increased/decreased playback sampling rate on user


       MPEG audio decoding requires a good deal of CPU performance, especially
       layer-3.  To decode it  in  realtime,  you  should  have  at  least  an
       i486DX4,  Pentium,  Alpha, SuperSparc or equivalent processor.  You can
       also use the -m option to decode mono only, which reduces the CPU  load
       somewhat for layer-3 streams.  See also the -2 and -4 options.

       If  everything else fails, have mpg123 decode to a file and then use an
       appropriate utility to play that file with less CPU load.  Most  proba-
       bly  you  can  configure  mpg123  to produce a format suitable for your
       audio device (see above about encodings and sampling rates).

       If your system is generally fast enough  to  decode  in  realtime,  but
       there  are  sometimes  periods  of heavy system load (such as cronjobs,
       users logging in remotely, starting of ``big'' programs  etc.)  causing
       the  audio  output to be interrupted, then you should use the -b option
       to use a buffer of reasonable size (at least 1000 Kbytes).


       Mostly MPEG-1 layer 2 and 3 are tested in real life.  Please report any
       issues and provide test files to help fixing them.

       No CRC error checking is performed.

       Some  platforms lack audio hardware support; you may be able to use the
       -s switch to feed the decoded data to a program that  can  play  it  on
       your audio device.


              Thomas Orgis <>, <>

       Original Creator:
              Michael Hipp

       Uses code or ideas from various people, see the AUTHORS file accompany-
       ing the source code.


       mpg123 is licensed under the GNU Lesser/Library General Public License,
       LGPL, version 2.1 .


                                  29 Feb 2016                        mpg123(1)

mpg123 1.24.0 - Generated Sun Mar 12 07:00:06 CDT 2017
© 2000-2021
Individual documents may contain additional copyright information.