.TH mpg123 1 "20 Oct 2006".SH NAMEmpg123 \- play audio MPEG 1.0/2.0/2.5 stream (layers 1, 2 and 3).SH SYNOPSIS.B mpg123[.B options].IR file " ... | " URL " ... | ".B \-.SH DESCRIPTION.B mpg123reads one or more.IR file\^ s(or standard input if ``\-'' is specified) or.IR URL\^ sand plays them on the audio device (default) oroutputs them to stdout..IR file\^ / URLis assumed to be an MPEG audio bit stream..SH OPERANDSThe following operands are supported:.TP 8.IR file (s)The path name(s) of one or more input files.  They must bevalid MPEG-1.0/2.0/2.5 audio layer 1, 2 or 3 bit streams.If a dash ``\-'' is specified, MPEG data willbe read from the standard input.  Furthermore, any namestarting with ``http://'' is recognized as.I URL(see next section)..SH OPTIONS.B mpg123options may be either the traditional POSIX one letter options,or the GNU style long options.  POSIX style options start with asingle ``\-'', while GNU long options start with ``\-\^\-''.Option arguments (if needed) follow separated by whitespace (not ``='')..SH INPUT OPTIONS.TP\fB\-k \fInum\fR, \fB\-\^\-skip \fInumSkip first.I numframes.  By default the decoding starts at the first frame..TP\fB\-n \fInum\fR, \fB\-\^\-frames \fInumDecode only.I numframes.  By default the complete stream is decoded..TP.BR \-y ", " \-\^\-resyncDo NOT try to resync and continuing decoding if an error occurs inthe input file. Normally, .B mpg123tries 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 may either disappearin future or its meaning be revised since it now does the opposite of what itsuggests..TP\fB\-p \fIURL \fR| \fBnone\fR, \fB\-\^\-proxy \fIURL \fR| \fBnoneThe specified.I proxywill be used for HTTP requests.  Itshould be specified as full URL (``http://host.domain:port/''),but the ``http://'' prefix, the port number and the trailingslash are optional (the default port is 80).  Specifying.B nonemeans not to use any proxy, and to retrieve files directlyfrom the respective servers.  See also the``HTTP SUPPORT'' section..TP\fB\-u \fIauth\fR, \fB\-\^\-auth \fIauthHTTP authentication to use when recieving files via HTTP.The format used is user:password..TP\fB\-@ \fIfile\fR, \fB\-\^\-list \fIfileRead filenames and/or URLs of MPEG audio streams from the specified.I filein addition to the ones specified on the command line (if any).Note that.I filecan be either an ordinary file, a dash ``\-'' to indicate thata list of filenames/URLs is to be read from the standard input,or an URL pointing to a an appropriate list file.  Note: onlyone.B \-@option can be used (if more than one is specified, only thelast one will be recognized)..TP\fB\-l \fIn\fR, \fB\-\^\-listentry \fInOf the playlist, play specified entry only. .I nis 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....TP.BR \-z ", " \-\^\-shuffleShuffle play.  Randomly shuffles the order of files specified on the commandline, or in the list file..TP.BR \-Z ", " \-\-randomContinuous random play.  Keeps picking a random file from the command lineor the play list.  Unlike shuffle play above, random play never ends, andplays individual songs more than once..SH OUTPUT and PROCESSING OPTIONS.TP\fB\-a \fIdev\fR, \fB\-\^\-audiodevice \fIdevSpecify the audio device to use.  The default issystem-dependent (usually /dev/audio or /dev/dsp).Use this option if you have multiple audio devices andthe default is not what you want..TP.BR \-s ", " \-\^\-stdoutThe decoded audio samples are written to standard output,instead of playing them through the audio device.  Thisoption must be used if your audio hardware is not supportedby.BR 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)..TP\fB\-w \fIfile\fR, \fB\-\^\-wavWrite output as WAV file. This will cause the MPEG stream to be decoded and saved as file.I file, or standard output if.I -is used as file name. You can also use.I --auand.I --cdrfor AU and CDR format, respectively..TP\fB\-\^\-au \fIfileDoes not play the MPEG file but writes it to.I filein SUN audio format.  If \- is used as the filename, the AU file iswritten to stdout..TP\fB\-\^\-cdr \fIfileDoes not play the MPEG file but writes it to.I fileas a CDR file.  If \- is used as the filename, the CDR file is writtento stdout..TP.BR \-\-reopenForces reopen of the audiodevice after ever song.TP\fB\-g \fIgain\fR, \fB\-\^\-gain \fIgainSet audio hardware output gain (default: don't change)..TP\fB\-f \fIfactor\fR, \fB\-\^\-scale \fIfactorChange scale factor (default: 32768)..TP.BR \-\-rva-mix, \-\-rva-radioEnable 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..TP.BR \-\-rva-album, \-\-rva-audiophileEnable 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..TP.BR \-0 ", " \-\^\-single0 "; " \-1 ", " \-\^\-single1Decode only channel 0 (left) or channel 1 (right),respectively.  These options are available forstereo MPEG streams only..TP.BR \-m ", " \-\^\-mono ", " \-\^\-mix ", " \-\^\-singlemixMix both channels / decode mono. It takes lessCPU time than full stereo decoding..TP.BR \-\-stereoForce stereo output.TP\fB\-r \fIrate\fR, \fB\-\^\-rate \fIrateSet sample rate (default: automatic).  You may want tochange this if you need a constant bitrate independed ofthe mpeg stream rate. mpg123 automagically converts therate. You should then combine this with \-\-stereo or \-\-mono..TP.BR \-2 ", " \-\^\-2to1 "; " \-4 ", " \-\^\-4to1Performs 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..TP.BR \-\-8bitForces 8bit output.TP\fB\-d \fIn\fR, \fB\-\^\-doublespeed \fInOnly play every.IR n 'thframe.  This will cause the MPEG streamto be played.I ntimes faster, which can be used for specialeffects.  Can also be combined with the.B \-\^\-halfspeedoption to play 3 out of 4 frames etc.  Don't expect greatsound quality when using this option..TP\fB\-h \fIn\fR, \fB\-\^\-halfspeed \fInPlay each frame.I ntimes.  This will cause the MPEG streamto be played at.IR 1 / n 'thspeed (n times slower), which can beused for special effects. Can also be combined with the.B \-\^\-doublespeedoption to double every third frame or things like that.Don't expect great sound quality when using this option..TP\fB\-E \fIfile\fR, \fB\-\^\-equalizerEnables equalization, taken from.IR file .The file needs to contain 32 lines of data, additional comment lines maybe prefixed with.IR # .Each data line consists of two floating-point entries, separated bywhitespace.  They specify the multipliers for left and right channel ofa certain frequency band, respectively.  The first line corresponds to thelowest, the 32nd to the highest frequency band.Note that you can control the equalizer interactively with the generic control interface..TP.BR "\-o h" ", " \-\^\-headphonesDirect audio output to the headphone connector (some hardware only; AIX, HP, SUN)..TP.BR "\-o s" ", " \-\^\-speakerDirect audio output to the speaker  (some hardware only; AIX, HP, SUN)..TP.BR "\-o l" ", " \-\^\-lineoutDirect audio output to the line-out connector (some hardware only; AIX, HP, SUN)..TP\fB\-b \fIsize\fR, \fB\-\^\-buffer \fIsizeUse an audio output buffer of.I sizeKbytes.  This is useful to bypass short periods of heavysystem 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..SH MISC OPTIONS.TP.BR \-t ", " \-\^\-testTest mode.  The audio stream is decoded, but no output occurs..TP.BR \-c ", " \-\^\-checkCheck for filter range violations (clipping), and report them for each frameif any occur..TP.BR \-v ", " \-\^\-verboseIncrease the verbosity level.  For example, displays the framenumbers during decoding..TP.BR \-q ", " \-\^\-quietQuiet.  Suppress diagnostic messages..TP.BR \-C ", " \-\^\-controlEnable terminal control keys. By default use 's' to stop, 'p' topause, 'f' to jump forward to the next song, 'b' to jump back to thebeginning of the song, ',' to rewind, '.' to fast forward, and 'q' to quit..TP\fB\-\^\-titleIn an xterm, or rxvt (compatible, TERM environment variable is examined), change the window's title to the name of song currentlyplaying..TP\fB\-\^\-long\-tagDisplay ID3 tag info always in long format with one line per item (artist, title, ...).TP.BR \-R ", " \-\^\-remoteActivate generic control interface..B mpg123will 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..TP.BR \-\^\-remote\-errPrint responses for generic control mode to stderr, not stdout.That is extremely useful when you want to grab the audio via .B -s... (in future, that may be automatically triggered when you specify.B -s).TP\fB\-\^\-aggressiveTries to get higher priority.TP.BR \-T ", " \-\-realtimeTries to gain realtime priority.  This option usually requires rootprivileges to have any effect..TP.BR \-? ", " \-\^\-helpShows short usage instructions..TP.BR \-\^\-longhelpShows long usage instructions..TP.BR \-\^\-versionPrint the version string..SH HTTP SUPPORTIn addition to reading MPEG audio streams from ordinaryfiles and from the standard input,.B mpg123supports retrieval of MPEG audio files or playlists via the HTTP protocol, which is used in the World Wide Web (WWW).  Such files arespecified using a so-called URL, which starts with ``http://''.  When a file withthat prefix is encountered,.B mpg123attempts to open an HTTP connection to the server in order toretrieve that file to decode and play it..PIt is often useful to retrieve files through a WWW cache orso-called proxy.  To accomplish this,.B mpg123examines the environment for variables named.BR MP3_HTTP_PROXY ", " http_proxy " and " HTTP_PROXY ,in this order.  The value of the first one that is set willbe used as proxy specification.  To override this, you canuse the.B \-pcommand line option (see the ``OPTIONS'' section).  Specifying.B "\-p none"will enforce contacting the server directly without usingany proxy, even if one of the above environment variablesis set..PNote that, in order to play MPEG audio files from a WWWserver, it is necessary that the connection to that serveris fast enough.  For example, a 128 kbit/s MPEG filerequires the network connection to be at least 128 kbit/s(16 kbyte/s) plus protocol overhead.  If you suffer fromshort network outages, you should try the.B \-boption (buffer) to bypass such outages.  If your networkconnection is generally not fast enough to retrieve MPEGaudio files in realtime, you can first download the filesto your local harddisk (e.g. using.BR wget (1))and then play them from there..PIf authentication is needed to access the file it can bespecified with the .BR "\-u user:pass"..SH INTERRUPTWhen in terminal control mode, you can quit via pressing the q key, while any time you can abort.B mpg123by pressing Ctrl-C. If not in terminal control mode, this willskip to the next file (if any). If you want to abort playing immediatelyin that case, press Ctrl-C twice in short succession (within about one second)..PNote that the result of quitting.B mpg123pressing Ctrl-C might not be audibleimmediately, due to audio data buffering in the audio device.This delay is system dependent, but it is usually not morethan one or two seconds..SH "SEE ALSO".BR wget (1),.BR sox (1),.SH NOTESMPEG audio decoding requires a good deal of CPU performance,especially layer-3.  To decode it in realtime, you shouldhave at least a Pentium, Alpha, SuperSparc or equivalentprocessor.  You can also use the.B -moption to decode mono only, which reduces the CPU loadsomewhat for layer-3 streams.  See also the.BR \-2 " and " \-4options..PIf everything else fails, use the.B \-soption to decode to standard output, direct it into a fileand then use an appropriate utility to play that file.You might have to use a tool such as.BR sox (1)to convert the output to an audio format suitable foryour audio player..PIf 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 usethe.B \-boption to use a buffer of reasonable size (at least 1000 Kbytes)..SH BUGS.PMostly MPEG-1 layer 2 and 3 are tested in real life.Please report any issues and provide test files to help fixing them..PFree format streams are not supported, but they could be (there is some code)..PNo CRC error checking is performed..PSome platforms lack audio hardware support; you may be able to use the.B -sswitch 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)..SH AUTHORS.TPMaintainers:.brThomas Orgis <maintainer@mpg123.org>, <thomas@orgis.org>.brNicholas J. Humfrey.TPMain author:.brMichael Hipp.TPUses code or ideas from various people, see the AUTHORS file accompanying the source code..SH LICENSEThe majority of.B mpg123is licensed under the GNU Lesser/Library General Public License, LGPL, version 2.1 ..SH WEBSITEhttp://www.mpg123.org.brhttp://sourceforge.net/projects/mpg123