--- name: "mpg123-esd" section: "1" platform: "linux" package: "mpg123" version: "1.12.1-3" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/mpg123.bin" --- # mpg123-esd(1) play audio MPEG 1.0/2.0/2.5 stream (layers 1, 2 and 3) Part of [mpg123.bin(1)](/mpg123.bin/1.md). ## 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 \`\`=''). Note that some options can be absent from your installation when disabled in the build process. ## 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.* - **--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.* - **-y**, **--no-resync** *Do NOT try to resync and continue 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 has been renamed from --resync.* *The old name still works, but is not advertised or recommened to use (subject to removal in future).* - **--resync-limit** *bytes* 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. - **-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...* - **--loop** *times* for looping track(s) a certain number of times, \< 0 means infinite loop (not with --random!). - **--keep-open** For remote control mode: Keep loaded file open after reaching end. - **--timeout** *seconds* Timeout in (integer) seconds before declaring a stream dead (if \<= 0, wait forever). - **-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. - **--no-icy-meta** **Do not accept ICY meta data.** - **-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.** - **--index-size** *size* Set the number of entries in the seek frame index table. - **--preframes** *num* 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). ## OUTPUT and PROCESSING OPTIONS - **-o** *module*, --output *module* Select audio output module. You can provide a comma-separated list to use the first one that works. - **--list-modules** **List the available modules.** - **-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).* - **-O** *file*, **--outfile** **Write raw output into a file (instead of simply redirecting standard output to a file with the shell).** - **-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* - **--cpu *decoder-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.* - **--test-cpu** *Tests your CPU and prints a list of possible choices for --cpu.* - **--list-cpu** *Lists all available decoder choices, regardless of support by your CPU.* - **-g** *gain*, **--gain** *gain* *\[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!)* - **-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.* - **--pitch *value*** *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.* - **--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.** - **--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 .** - **--no-gapless** **Disable the gapless code. That gives you MP3 decodings that include encoder delay and padding plus mpg123's decoder delay.** - **-D** *n*, **--delay** *n* *Insert a delay of n* seconds before each track. - **-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.* - **--preload** *fraction* *Wait for the buffer to be filled to* *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).* - **--smooth** **Keep buffer over track boundaries -- meaning, do not empty the buffer between tracks for possibly some added smoothness.** ## 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' 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.** - **--title** **In an xterm, or rxvt (compatible, TERM environment variable is examined), change the window's title to the name of song currently** **playing.** - **--long-tag** **Display ID3 tag info always in long format with one line per item (artist, title, ...)** - **--utf8** **Regardless of environment, print metadata in UTF-8 (otherwise, when not using UTF-8 locale, you'll get ASCII stripdown).** - **-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 standard error, not standard out.** **This is automatically triggered when using** **-s** . - **--fifo** *path* *Create a fifo / named pipe on the given path and use that for reading commands instead of standard input.* - **--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 an i486DX4, 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** - **Creator:** **Michael Hipp** - **Uses code or ideas from various people, see the AUTHORS file accompanying the source code.** ## LICENSE **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**