xenial (1) mpg123-pulse.1.gz

Provided by: mpg123_1.22.4-1ubuntu0.1_amd64 bug

NAME

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

SYNOPSIS

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

DESCRIPTION

       mpg123  reads  one  or more files (or standard input if ``-'' is specified) 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.

OPERANDS

       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 standard
               input.  Furthermore, any name starting with ``http://'' is recognized as URL (see next section).

OPTIONS

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

INPUT OPTIONS

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

       --fuzzy
              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 hammer.
              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 respective 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
              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.

       --no-seekbuffer
              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 specified 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...

       --continue
              Enable playlist continuation mode. This changes frame skipping to apply only to  the  first  track
              and  also  continues to play following 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 positions
              consistent.

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

       --keep-open
              For remote control mode: Keep loaded file open after reaching end.

       --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, random play never ends, and plays individual songs more than once.

       --no-icy-meta
              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
              operating 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).

OUTPUT and PROCESSING OPTIONS

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

       --list-modules
              List the available modules.

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

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

       --reopen
              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 optimized decoders.

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

       --list-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  module  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.

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

       --float
              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 numbers of bits
              (s24, u24, s16, u16, s8, u8) and also special variants 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 contain 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 highest
              frequency band.  Note that you can control the equalizer interactively with  the  generic  control
              interface.

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

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

       -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  normally  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 off.

       --preload fraction
              Wait  for the buffer to be filled to fraction before starting playback (fraction between 0 and 1).
              You can tune this prebuffering to either get faster sound to your ears or safer uninterrupted  web
              radio.  Default is 1 (wait for full buffer before playback).

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

MISC OPTIONS

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

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

       --long-tag
              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.

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

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

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

       --longhelp
              Shows long usage instructions.

       --version
              Print the version string.

HTTP SUPPORT

       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 variables 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 specification.  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 example, 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.

INTERRUPT

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

SEE ALSO

       wget(1), sox(1),

NOTES

       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, use the -s option to decode to standard output, direct it into a file and  then
       use an appropriate utility to play that file.  You might have to use a tool such as sox(1) to convert the
       output to an audio format suitable for your audio player.

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

BUGS

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

       Free format streams are not supported, but they could be (there is some code).

       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.  Notably, this includes Tru64 with MME, but you
       should be able to install and use OSS there (it perhaps will perform better as MME would anyway).

AUTHORS

       Maintainer:
              Thomas Orgis <maintainer@mpg123.org>, <thomas@orgis.org>

       Creator:
              Michael Hipp

       Uses code or ideas from various people, see the AUTHORS file accompanying the source code.

LICENSE

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

WEBSITE

       http://www.mpg123.org
       http://sourceforge.net/projects/mpg123

                                                   10 May 2014                                         mpg123(1)