home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: Multimed / Multimed.zip / mpg123.zip / manual < prev    next >
Text File  |  1999-08-20  |  14KB  |  361 lines
  1. mpg123(1)                                               mpg123(1)
  2.  
  3.  
  4. NAME
  5.        mpg123 - play audio MPEG 1.0/2.0 file (layers 1, 2 and 3)
  6.  
  7. SYNOPSIS
  8.        mpg123  [ -tscvqy01m24 ] [ -b size ] [ -k num ] [ -n num ]
  9.        [ -f factor ] [ -r rate ] [ -g gain ] [ -a dev ] [ -o s  |
  10.        -o  h  | -o l ] [ -d n ] [ -h n ] [ -p proxy ] [ -@ file ]
  11.        file ... | URL ... | -
  12.  
  13. DESCRIPTION
  14.        mpg123 reads one or more files (or standard input if ``-''
  15.        is  specified)  or URLs and plays them on the audio device
  16.        (default) or outputs them to stdout.  file/URL is  assumed
  17.        to be an MPEG-1/2 audio bit stream.
  18.  
  19. OPTIONS
  20.        mpg123  options  may  be  either the traditional POSIX one
  21.        letter options, or the  GNU  style  long  options.   POSIX
  22.        style  options  start  with a single ``-'', while GNU long
  23.        options start with ``--''.
  24.        
  25.        -t, --test
  26.               Test mode.  The audio stream  is  decoded,  but  no
  27.               output occurs.
  28.  
  29.        -s, --stdout
  30.               The  decoded  audio samples are written to standard
  31.               output, instead of playing them through  the  audio
  32.               device.   This  option  must  be used if your audio
  33.               hardware is not supported by  mpg123.   The  output
  34.               format  is  raw (headerless) linear PCM audio data,
  35.               16 bit, stereo, host byte order.
  36.  
  37.        -c, --check
  38.               Check for filter range violations, and report  them
  39.               for each frame if any occur.
  40.  
  41.        -v, --verbose
  42.               Increase  the  verbosity  level.  For example, dis-
  43.               plays the frame numbers during decoding.
  44.  
  45.        -q, --quiet
  46.               Quiet.  Suppress diagnostic messages.       
  47.               
  48.        -y, --resync
  49.               Try to resync and continue  decoding  if  an  error
  50.               occurs in the input file.  Also try to recover from
  51.               certain broken headers.  Useful if you have a  bro-
  52.               ken  MPEG  file,  on which mpg123 normally gives up
  53.               saying `Illegal header'.  Be careful: Broken  loca-
  54.               tions in MPEG files might cause sharp, loud pops or
  55.               clicks, which might damage your speakers if  played
  56.               too loud.
  57.  
  58.  
  59.  
  60.  
  61.                            21 Apr 1997                          1
  62.  
  63.  
  64.  
  65.  
  66.  
  67. mpg123(1)                                               mpg123(1)
  68.               
  69.        -0, --single0; -1, --single1
  70.               Decode  only channel 0 (left) or channel 1 (right),
  71.               respectively.   These  options  are  available  for
  72.               stereo MPEG streams only.
  73.  
  74.        -m, --singlemix
  75.               Mix  both  channels.   This option is available for
  76.               stereo MPEG layer-3 streams only.   It  takes  less
  77.               CPU time than full stereo decoding.
  78.  
  79.        -2, --2to1; -4, --4to1
  80.               Performs  a  downsampling  of ratio 2:1 (22 kHz) or
  81.               4:1 (11 kHz) on the  output  stream,  respectively.
  82.               Saves  some  CPU cycles, but at least the 4:1 ratio
  83.               sounds ugly.
  84.  
  85.        -b size, --buffer size
  86.               Use an audio output buffer of size Kbytes.  This is
  87.               useful  to  bypass  short  periods  of heavy system
  88.               activity, which would normally cause the audio out-
  89.               put to be interrupted.  You should specify a buffer
  90.               size of at least 1024  (i.e.  1  Mb,  which  equals
  91.               about  6  seconds of audio data) or more; less than
  92.               about 300 does not make much sense.  The default is
  93.               0, which turns buffering off.
  94.  
  95.        -k num, --skip num
  96.               Skip  first  num  frames.   By default the decoding
  97.               starts at the first frame.
  98.  
  99.        -n num, --frames num
  100.               Decode only num frames.  By  default  the  complete
  101.               stream is decoded.
  102.  
  103.        -f factor, --scale factor
  104.               Change scale factor (default: 32768).
  105.  
  106.        -r rate, --rate rate
  107.               Set sample rate (default: automatic).  You may want
  108.               to change this if you need a constant bitrate inde-
  109.               pended  of  the  mpeg stream rate. mpg123 automagi-
  110.               cally converts the rate. You  should  then  combine
  111.               this with --stereo or --mono.
  112.  
  113.  
  114.        -g gain, --gain gain              
  115.               Set  audio  hardware  output  gain  (default: don't
  116.               change).
  117.  
  118.        -a dev, --audiodevice dev
  119.               Specify the audio device to use.   The  default  is
  120.               system-dependent  (usually /dev/audio or /dev/dsp).
  121.               Use this option if you have multiple audio  devices
  122.               and the default is not what you want.
  123.  
  124.  
  125.  
  126.                            21 Apr 1997                          2
  127.  
  128.  
  129.  
  130.  
  131.  
  132. mpg123(1)                                               mpg123(1)
  133.  
  134.  
  135.        -o s, --speaker
  136.               Direct audio output to the speaker.       
  137.               
  138.        -o h, --headphones
  139.               Direct audio output to the headphone connector.
  140.  
  141.        -o l, --lineout
  142.               Direct audio output to the line-out connector.
  143.  
  144.        -d n, --doublespeed n
  145.               Only  play  every  n'th frame.  This will cause the
  146.               MPEG stream to be played n times faster, which  can
  147.               be  used for special effects.  Can also be combined
  148.               with the --halfspeed option to  play  3  out  of  4
  149.               frames  etc.  Don't expect great sound quality when
  150.               using this option.
  151.  
  152.        -h n, --halfspeed n
  153.               Play each frame n times.  This will cause the  MPEG
  154.               stream  to  be  played  at  1/n'th  speed  (n times
  155.               slower), which can be used for special effects. Can
  156.               also  be  combined with the --doublespeed option to
  157.               double every  third  frame  or  things  like  that.
  158.               Don't  expect  great  sound quality when using this
  159.               option.
  160.  
  161.        -p URL | none, --proxy URL | none
  162.               The specified proxy will be used for HTTP requests.
  163.               It    should    be    specified    as    full   URL
  164.               (``http://host.domain:port/''), but the ``http://''
  165.               prefix,  the port number and the trailing slash are
  166.               optional (the default port is 80).  Specifying none
  167.               means  not  to use any proxy, and to retrieve files
  168.               directly from the respective servers.  See also the
  169.               ``HTTP SUPPORT'' section.
  170.  
  171.        -u auth, --auth auth
  172.               HTTP authentication to use when recieving files via
  173.               HTTP.  The format used is user:password.
  174.  
  175.        -@ file, --list file
  176.               Read filenames and/or URLs of  MPEG  audio  streams
  177.               from  the  specified  file  in addition to the ones
  178.               specified on the command line (if any).  Note  that
  179.               file  can  be either an ordinary file, a dash ``-''
  180.               to indicate that a list of filenames/URLs is to  be
  181.               read from the standard input, or an URL pointing to
  182.               a an appropriate list  file.   Note:  only  one  -@
  183.               option  can be used (if more than one is specified,
  184.               only the last one will be recognized).
  185.  
  186.        -z, --shuffle
  187.               Shuffle play.  Randomly shuffles the  files  speci-
  188.               fied on the command line and in the list file.
  189.  
  190.  
  191.  
  192.                            21 Apr 1997                          3
  193.  
  194.  
  195.  
  196.  
  197.  
  198. mpg123(1)                                               mpg123(1)
  199.  
  200.  
  201.        --stereo
  202.               Force stereo output
  203.  
  204.        --reopen
  205.               Forces reopen of the audiodevice after ever song              
  206.               
  207.        --8bit Forces 8bit output
  208.  
  209.        -Z, --random
  210.               Full random play
  211.  
  212. OPERANDS
  213.        The following operands are supported:
  214.  
  215.        file(s) The path name(s) of one or more input files.  They
  216.                must be valid MPEG-1/2 audio layer-1, -2 or -3 bit
  217.                streams.   If a dash ``-'' is specified, MPEG data
  218.                will be read from the  standard  input.   Further-
  219.                more, any name starting with ``http://'' is recog-
  220.                nized as URL (see next section).
  221.  
  222. HTTP SUPPORT
  223.        In addition to reading MPEG audio  streams  from  ordinary
  224.        files   and  from  the  standard  input,  mpg123  supports
  225.        retrieval of MPEG audio files via the HTTP protocol, which
  226.        is used in the World Wide Web (WWW).  Such files are spec-
  227.        ified using a so-called URL (universal resource location),
  228.        which starts with ``http://''.  When a file with that pre-              
  229.        fix is encountered, mpg123 attempts to open an  HTTP  con-
  230.        nection  to  the  server in order to retrieve that file to
  231.        decode and play it.
  232.  
  233.        It is often useful to retrieve files through a  WWW  cache
  234.        or  so-called  proxy.  To accomplish this, mpg123 examines
  235.        the  environment  for  variables   named   MP3_HTTP_PROXY,
  236.        http_proxy  and  HTTP_PROXY,  in this order.  The value of
  237.        the first one that is set will be used as proxy specifica-
  238.        tion.   To  override this, you can use the -p command line
  239.        option (see the ``OPTIONS'' section).  Specifying -p  none
  240.        will  enforce contacting the server directly without using
  241.        any proxy, even if one of the above environment  variables
  242.        is set.
  243.  
  244.        Note  that,  in  order to play MPEG audio files from a WWW
  245.        server, it is necessary that the connection to that server
  246.        is  fast  enough.   For  example,  a  128 kbit/s MPEG file
  247.        requires the network connection to be at least 128  kbit/s
  248.        (16  kbyte/s)  plus protocol overhead.  If you suffer from
  249.        short network  outages,  you  should  try  the  -b  option
  250.        (buffer)  to bypass such outages.  If your network connec-
  251.        tion is generally not fast enough to retrieve  MPEG  audio       
  252.        files  in  realtime,  you  can first download the files to
  253.        your local harddisk (e.g. using  lynx(1))  and  then  play
  254.        them from there.
  255.  
  256.  
  257.  
  258.                            21 Apr 1997                          4
  259.  
  260.  
  261.  
  262.  
  263.  
  264. mpg123(1)                                               mpg123(1)
  265.  
  266.  
  267.        If  authentication  is needed to access the file it can be
  268.        specified with the -u user:pass.
  269.  
  270. INTERRUPT
  271.        You can abort mpg123 at any time by pressing  Ctrl-C.   If
  272.        you are playing multiple files, this will stop the current
  273.        file and begin playing the next one.  If you want to abort
  274.        playing  immediately instead of skipping to the next file,       
  275.        press Ctrl-C twice in short succession (within  about  one
  276.        second).
  277.  
  278.        Note that the result of pressing Ctrl-C might not be audi-
  279.        ble immediately, due to audio data buffering in the  audio
  280.        device.  This delay is system dependent, but it is usually
  281.        not more than one or two seconds.
  282.  
  283. SEE ALSO
  284.        lynx(1), sox(1), intro(1)
  285.  
  286. NOTES
  287.        MPEG audio decoding requires a good deal  of  CPU  perfor-
  288.        mance,  especially layer-3.  To decode it in realtime, you
  289.        should have at  least  a  Pentium,  Alpha,  SuperSparc  or
  290.        equivalent  processor.   You  can  also use the -singlemix
  291.        option to decode mono only, which  reduces  the  CPU  load
  292.        somewhat  for  layer-3  streams.   See  also the -2 and -4
  293.        options.
  294.  
  295.        If everything else fails, use the -s option to  decode  to
  296.        standard  output,  direct  it  into a file and then use an
  297.        appropriate utility to play that file.  You might have  to       
  298.        use  a  tool  such  as  sox(1) to convert the output to an
  299.        audio format suitable for your audio player.
  300.  
  301.        Also note that mpg123 always generates 16 bit stereo  data
  302.        (if  one  of  the  -single* options is used, two identical
  303.        stereo channels are generated).  If your hardware requires
  304.        some  other  format, for example 8 bit mono, you also have
  305.        to use a converter such as sox(1).
  306.  
  307.        If your system is generally fast enough to decode in real-
  308.        time, but there are sometimes periods of heavy system load
  309.        (such as cronjobs, users logging in remotely, starting  of
  310.        ``big''  programs  etc.)  causing  the  audio output to be
  311.        interrupted, then you should use the -b option  to  use  a
  312.        buffer of at least 1000 Kbytes.
  313.  
  314. BUGS
  315.        Known bugs and limitations:
  316.               MPEG-2,  Layer  1  and  2 not tested. May not work.
  317.               (Layer 3 should work.)
  318.               Free format streams are not supported.
  319.               Layer-1 support is not heavily tested.
  320.               No CRC error checking is performed.       
  321.               
  322.  
  323.  
  324.                            21 Apr 1997                          5
  325.  
  326.  
  327.  
  328.  
  329.  
  330. mpg123(1)                                               mpg123(1)
  331.  
  332.  
  333.               There is currently no support for audio hardware on
  334.               DEC Digital Unix, Ultrix and IBM AIX, therefore the
  335.               -s option has to be used on those platforms.
  336.  
  337. AUTHORS
  338.        Main author:
  339.               Michael Hipp <hippm@informatik.uni-tuebingen.de>
  340.  
  341.        Uses code (or at least ideas) from:
  342.               MPEG Software Simulation Group (Base package)
  343.               Philipp Knirsch <phil@mpik-tueb.mpg.de> (DCT36/man-
  344.               ual unroll)
  345.               Tobias   Bading  <bading@cs.tu-berlin.de>  (subband
  346.               synthesis)
  347.               Jeff Tsay <ctsay@pasteur.eecs.berkeley.edu> (DCT36)
  348.               Thomas Woerner (SGI Audio)
  349.               Damien  Clermonte  <clermond@esiee.fr> (HP-UX audio
  350.               fixes)
  351.               Oliver Fromme <oliver.fromme@heim3.tu-clausthal.de>
  352.  
  353.        Internet references:
  354.        http://www.sfs.nphil.uni-tuebingen.de/~hipp/mpg123.html
  355.        http://www.heim3.tu-clausthal.de/~olli/mpg123/
  356.        (includes information about the mpg123 mailing list)
  357.  
  358.        The latest version is also available from here:
  359.        ftp.tu-clausthal.de:/pub/unix/audio/mpg123
  360.        http://ftp.tu-clausthal.de/pub/unix/audio/mpg123              
  361.