| .TH mpg123 1 "31 Jan 2008" |
| .SH NAME |
| mpg123 \- 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 mpg123 |
| reads one or more |
| .IR file\^ s |
| (or standard input if ``\-'' is specified) or |
| .IR URL\^ s |
| and plays them on the audio device (default) or |
| outputs them to stdout. |
| .IR file\^ / URL |
| is assumed to be an MPEG audio bit stream. |
| .SH OPERANDS |
| The following operands are supported: |
| .TP 8 |
| .IR 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 |
| .I URL |
| (see next section). |
| .SH OPTIONS |
| .B 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. |
| .SH INPUT OPTIONS |
| .TP |
| \fB\-k \fInum\fR, \fB\-\^\-skip \fInum |
| Skip first |
| .I num |
| frames. By default the decoding starts at the first frame. |
| .TP |
| \fB\-n \fInum\fR, \fB\-\^\-frames \fInum |
| Decode only |
| .I num |
| frames. By default the complete stream is decoded. |
| .TP |
| .BR \-\-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. |
| .TP |
| .BR \-y ", " \-\^\-no\-resync |
| Do NOT try to resync and continue decoding if an error occurs in |
| the input file. Normally, |
| .B 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). |
| .TP |
| \fB\-\^-resync\-limit \fIbytes\fR |
| Set number of bytes to search for valid MPEG data; <0 means search whole stream. |
| If you know there are huge chunks of invalid data in your files... here is your hammer. |
| .TP |
| \fB\-p \fIURL \fR| \fBnone\fR, \fB\-\^\-proxy \fIURL \fR| \fBnone |
| The specified |
| .I 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 |
| .B none |
| means not to use any proxy, and to retrieve files directly |
| from the respective servers. See also the |
| ``HTTP SUPPORT'' section. |
| .TP |
| \fB\-u \fIauth\fR, \fB\-\^\-auth \fIauth |
| HTTP authentication to use when recieving files via HTTP. |
| The format used is user:password. |
| .TP |
| \fB\-@ \fIfile\fR, \fB\-\^\-list \fIfile |
| Read filenames and/or URLs of MPEG audio streams from the specified |
| .I file |
| in addition to the ones specified on the command line (if any). |
| Note that |
| .I 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 |
| .B \-@ |
| option can be used (if more than one is specified, only the |
| last one will be recognized). |
| .TP |
| \fB\-l \fIn\fR, \fB\-\^\-listentry \fIn |
| Of the playlist, play specified entry only. |
| .I 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... |
| .TP |
| \fB\-\-loop \fItimes\fR |
| for looping track(s) a certain number of times, < 0 means infinite loop (not with --random!). |
| .TP |
| .BR \-\-keep\-open |
| For remote control mode: Keep loaded file open after reaching end. |
| .TP |
| \fB\-\-timeout \fIseconds\fR |
| Timeout in (integer) seconds before declaring a stream dead (if <= 0, wait forever). |
| .TP |
| .BR \-z ", " \-\^\-shuffle |
| Shuffle play. Randomly shuffles the order of files specified on the command |
| line, or in the list file. |
| .TP |
| .BR \-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. |
| .TP |
| \fB\-\^\-no\-icy\-meta |
| Do not accept ICY meta data. |
| .TP |
| \fB\-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. |
| .TP |
| \fB\-\-index\-size \fIsize\fR |
| Set the number of entries in the seek frame index table. |
| .TP |
| \fB\-\-preframes \fInum\fR |
| 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). |
| |
| .SH OUTPUT and PROCESSING OPTIONS |
| .TP |
| \fB\-o \fImodule\fR, \-\^\-output \fImodule\fR |
| Select audio output module. You can provide a comma-separated list to use the first one that works. |
| .TP |
| \fB\-\^\-list\-modules |
| List the available modules. |
| .TP |
| \fB\-a \fIdev\fR, \fB\-\^\-audiodevice \fIdev |
| 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. |
| .TP |
| .BR \-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 |
| .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\-O \fIfile\fR, \fB\-\^\-outfile |
| Write raw output into a file (instead of simply redirecting standard output to a file with the shell). |
| .TP |
| \fB\-w \fIfile\fR, \fB\-\^\-wav |
| Write 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 --au |
| and |
| .I --cdr |
| for AU and CDR format, respectively. |
| .TP |
| \fB\-\^\-au \fIfile |
| Does not play the MPEG file but writes it to |
| .I file |
| in SUN audio format. If \- is used as the filename, the AU file is |
| written to stdout. |
| .TP |
| \fB\-\^\-cdr \fIfile |
| Does not play the MPEG file but writes it to |
| .I file |
| as a CDR file. If \- is used as the filename, the CDR file is written |
| to stdout. |
| .TP |
| .BR \-\-reopen |
| Forces reopen of the audiodevice after ever song |
| .TP |
| .BR \-\-cpu\ \fIdecoder\-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. |
| .TP |
| .BR \-\-test\-cpu |
| Tests your CPU and prints a list of possible choices for \-\-cpu. |
| .TP |
| .BR \-\-list\-cpu |
| Lists all available decoder choices, regardless of support by your CPU. |
| .TP |
| \fB\-g \fIgain\fR, \fB\-\^\-gain \fIgain |
| [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!) |
| .TP |
| \fB\-f \fIfactor\fR, \fB\-\^\-scale \fIfactor |
| Change scale factor (default: 32768). |
| .TP |
| .BR \-\-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. |
| .TP |
| .BR \-\-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. |
| .TP |
| .BR \-0 ", " \-\^\-single0 "; " \-1 ", " \-\^\-single1 |
| Decode only channel 0 (left) or channel 1 (right), |
| respectively. These options are available for |
| stereo MPEG streams only. |
| .TP |
| .BR \-m ", " \-\^\-mono ", " \-\^\-mix ", " \-\^\-singlemix |
| Mix both channels / decode mono. It takes less |
| CPU time than full stereo decoding. |
| .TP |
| .BR \-\-stereo |
| Force stereo output |
| .TP |
| \fB\-r \fIrate\fR, \fB\-\^\-rate \fIrate |
| Set sample rate (default: automatic). You may want to |
| change this if you need a constant bitrate independed of |
| the mpeg stream rate. mpg123 automagically converts the |
| rate. You should then combine this with \-\-stereo or \-\-mono. |
| .TP |
| .BR \-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. |
| .TP |
| .BR \-\-pitch\ \fIvalue |
| 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. |
| .TP |
| .BR \-\-8bit |
| Forces 8bit output |
| .TP |
| \fB\-d \fIn\fR, \fB\-\^\-doublespeed \fIn |
| Only play every |
| .IR n 'th |
| frame. This will cause the MPEG stream |
| to be played |
| .I n |
| times faster, which can be used for special |
| effects. Can also be combined with the |
| .B \-\^\-halfspeed |
| option to play 3 out of 4 frames etc. Don't expect great |
| sound quality when using this option. |
| .TP |
| \fB\-h \fIn\fR, \fB\-\^\-halfspeed \fIn |
| Play each frame |
| .I n |
| times. This will cause the MPEG stream |
| to be played at |
| .IR 1 / n 'th |
| speed (n times slower), which can be |
| used for special effects. Can also be combined with the |
| .B \-\^\-doublespeed |
| option 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\-\^\-equalizer |
| Enables equalization, taken from |
| .IR file . |
| The file needs to contain 32 lines of data, additional comment lines may |
| be prefixed with |
| .IR # . |
| 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. |
| .TP |
| \fB\-\^\-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 . |
| .TP |
| \fB\-\^\-no\-gapless |
| Disable the gapless code. That gives you MP3 decodings that include encoder delay and padding plus mpg123's decoder delay. |
| .TP |
| \fB\-D \fIn\fR, \fB\-\-delay \fIn |
| Insert a delay of \fIn\fR seconds before each track. |
| .TP |
| .BR "\-o h" ", " \-\^\-headphones |
| Direct audio output to the headphone connector (some hardware only; AIX, HP, SUN). |
| .TP |
| .BR "\-o s" ", " \-\^\-speaker |
| Direct audio output to the speaker (some hardware only; AIX, HP, SUN). |
| .TP |
| .BR "\-o l" ", " \-\^\-lineout |
| Direct audio output to the line-out connector (some hardware only; AIX, HP, SUN). |
| .TP |
| \fB\-b \fIsize\fR, \fB\-\^\-buffer \fIsize |
| Use an audio output buffer of |
| .I 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. |
| .TP |
| \fB\-\^\-preload \fIfraction |
| Wait for the buffer to be filled to |
| .I 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). |
| .TP |
| \fB\-\^\-smooth |
| Keep buffer over track boundaries -- meaning, do not empty the buffer between tracks for possibly some added smoothness. |
| |
| .SH MISC OPTIONS |
| |
| .TP |
| .BR \-t ", " \-\^\-test |
| Test mode. The audio stream is decoded, but no output occurs. |
| .TP |
| .BR \-c ", " \-\^\-check |
| Check for filter range violations (clipping), and report them for each frame |
| if any occur. |
| .TP |
| .BR \-v ", " \-\^\-verbose |
| Increase the verbosity level. For example, displays the frame |
| numbers during decoding. |
| .TP |
| .BR \-q ", " \-\^\-quiet |
| Quiet. Suppress diagnostic messages. |
| .TP |
| .BR \-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. |
| .TP |
| \fB\-\^\-title |
| In an xterm, or rxvt (compatible, TERM environment variable is examined), change the window's title to the name of song currently |
| playing. |
| .TP |
| \fB\-\^\-long\-tag |
| Display ID3 tag info always in long format with one line per item (artist, title, ...) |
| .TP |
| .BR \-\-utf8 |
| Regardless of environment, print metadata in UTF-8 (otherwise, when not using UTF-8 locale, you'll get ASCII stripdown). |
| .TP |
| .BR \-R ", " \-\^\-remote |
| Activate generic control interface. |
| .B 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. |
| .TP |
| .BR \-\^\-remote\-err |
| Print responses for generic control mode to standard error, not standard out. |
| This is automatically triggered when using |
| .B -s |
| \fN. |
| .TP |
| \fB\-\-fifo \fIpath |
| Create a fifo / named pipe on the given path and use that for reading commands instead of standard input. |
| .TP |
| \fB\-\^\-aggressive |
| Tries to get higher priority |
| .TP |
| .BR \-T ", " \-\-realtime |
| Tries to gain realtime priority. This option usually requires root |
| privileges to have any effect. |
| .TP |
| .BR \-? ", " \-\^\-help |
| Shows short usage instructions. |
| .TP |
| .BR \-\^\-longhelp |
| Shows long usage instructions. |
| .TP |
| .BR \-\^\-version |
| Print the version string. |
| .SH HTTP SUPPORT |
| In addition to reading MPEG audio streams from ordinary |
| files and from the standard input, |
| .B 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, |
| .B mpg123 |
| attempts to open an HTTP connection to the server in order to |
| retrieve that file to decode and play it. |
| .P |
| It is often useful to retrieve files through a WWW cache or |
| so-called proxy. To accomplish this, |
| .B mpg123 |
| examines 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 will |
| be used as proxy specification. To override this, you can |
| use the |
| .B \-p |
| command line option (see the ``OPTIONS'' section). Specifying |
| .B "\-p none" |
| will enforce contacting the server directly without using |
| any proxy, even if one of the above environment variables |
| is set. |
| .P |
| 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 \-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 |
| .BR wget (1)) |
| and then play them from there. |
| .P |
| If authentication is needed to access the file it can be |
| specified with the |
| .BR "\-u user:pass". |
| .SH INTERRUPT |
| When in terminal control mode, you can quit via pressing the q key, |
| while any time you can abort |
| .B 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). |
| .P |
| Note that the result of quitting |
| .B 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. |
| .SH "SEE ALSO" |
| .BR wget (1), |
| .BR sox (1), |
| .SH 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 |
| .B -m |
| option to decode mono only, which reduces the CPU load |
| somewhat for layer-3 streams. See also the |
| .BR \-2 " and " \-4 |
| options. |
| .P |
| If everything else fails, use the |
| .B \-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 |
| .BR sox (1) |
| to convert the output to an audio format suitable for |
| your audio player. |
| .P |
| 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 \-b |
| option to use a buffer of reasonable size (at least 1000 Kbytes). |
| .SH BUGS |
| .P |
| Mostly MPEG-1 layer 2 and 3 are tested in real life. |
| Please report any issues and provide test files to help fixing them. |
| .P |
| Free format streams are not supported, but they could be (there is some code). |
| .P |
| No CRC error checking is performed. |
| .P |
| Some platforms lack audio hardware support; you may be able to use the |
| .B -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). |
| .SH AUTHORS |
| .TP |
| Maintainers: |
| .br |
| Thomas Orgis <maintainer@mpg123.org>, <thomas@orgis.org> |
| .br |
| Nicholas J. Humfrey |
| .TP |
| Creator: |
| .br |
| Michael Hipp |
| .TP |
| Uses code or ideas from various people, see the AUTHORS file accompanying the source code. |
| .SH LICENSE |
| .B mpg123 |
| is licensed under the GNU Lesser/Library General Public License, LGPL, version 2.1 . |
| .SH WEBSITE |
| http://www.mpg123.org |
| .br |
| http://sourceforge.net/projects/mpg123 |