--- name: "mpg123-oss-i486" section: "1" platform: "linux" package: "mpg123-oss-i486" version: "0.61-5" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/mpg123-oss-i486" --- # mpg123-oss-i486(1) play audio MPEG 1.0/2.0/2.5 stream (layers 1, 2 and 3) ## 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 *file*s (or standard input if \`\`-'' is specified) or *URL*s 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 \`\`=''). ## 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.* - **-y**, **--resync** *Do NOT try to resync and continuing 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 may either disappear* *in future or its meaning be revised since it now does the opposite of what it* *suggests.* - **-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.* - **-@** *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...* - **-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.* ## OUTPUT and PROCESSING OPTIONS - **-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).* - **-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.** - **--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.* - **--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* - **-g** *gain*, **--gain** *gain* *Set audio hardware output gain (default: don't change).* - **-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 independed 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.* - **--8bit** *Forces 8bit output* - **-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.** - **-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.* ## 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' to stop, 'p' to* *pause, '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.* - **--title** **In an xterm, or rxvt (compatible, TERM environment variable is examined), change the window's title to the name of song currently** **playing.** - **-R**, **--remote** **Activate generic control interface.** **mpg123** **will then read and execute commands from stdin. Basic usage is \`\`load \ '' to play some file and the obvious \`\`pause'', \`\`command.** **\`\`jump \'' 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 stderr, not stdout.** **That is extremely useful when you want to grab the audio via** **-s** **-s** **)** - **--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)](/wget/1.md)) **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)](/wget/1.md), [**sox**(1)](/sox/1.md), ## NOTES **MPEG audio decoding requires a good deal of CPU performance,** **especially layer-3. To decode it in realtime, you should** **have at least a 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)](/sox/1.md) **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 - **Maintainers:** **Thomas Orgis \, \**\ **Nicholas J. Humfrey** - **Main author:** **Michael Hipp** - **Uses code or ideas from various people, see the AUTHORS file accompanying the source code.** ## LICENSE **The majority of** **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**