manual/mpg123/original/man1/mpg123.1

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