513 lines
19 KiB
Groff
513 lines
19 KiB
Groff
.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 once lost in stream; <0 means search whole stream.
|
|
If you know there are huge chunks of invalid data in your files... here is your hammer.
|
|
Note: Only since version 1.14 this also increases the amount of junk skipped on beginning.
|
|
.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 independent 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\-\^\-float
|
|
Forces f32 encoding
|
|
.TP
|
|
\fp\-e \fIenc\fR, \fB\-\^\-encoding \fIenc
|
|
Choose output sample encoding. Possible values look like f32 (32-bit floating point), s32 (32-bit signed integer), u32 (32-bit unsigned integer) and the variants with different numbers of bits (s24, u24, s16, u16, s8, u8) and also special variants like ulaw and alaw 8-bit.
|
|
See the output of mpg123's longhelp for actually available encodings.
|
|
.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
|