~ubuntu-branches/ubuntu/lucid/mpg123/lucid

.TH mpg123 1 "12 Aug 2006"

mpg123 \- play audio MPEG 1.0/2.0/2.5 file (layers 1, 2 and 3)

.B options

.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/2 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).

Option arguments (if needed) follow separated by whitespace (not ``='').

.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 \-y ", " \-\^\-resync

Do NOT try to resync and continuing decoding if an error occurs in

the input file. Normally, 

.B mpg123

tries top 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.

.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

.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.

 

.SH OUTPUT and PROCESSING OPTIONS

.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.

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\-\^\-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

\fB\-g \fIgain\fR, \fB\-\^\-gain \fIgain

Set audio hardware output gain (default: don't change).

.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.

.BR \-m ", " \-\^\-mono ", " \-\^\-mix ", " \-\^\-singlemix

Mix both channels / decode mono. It takes less

.BR \-\-stereo

Force stereo output

.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 \-\-8bit

Forces 8bit output

\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

.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.

 

.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' 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.

.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

.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 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\-\^\-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.

specified using a so-called URL, which starts with ``http://''.  When a file with

.BR wget (1))

When in terminal control mode, you can quit via pressing the q key, 

while any time you can abort

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

.B mpg123

pressing Ctrl-C might not be audible

.BR wget (1),

.B -m

option to use a buffer of reasonable size (at least 1000 Kbytes).

.P

MPEG-2.5 could be supported with some work but is highly untested and disabled in the source code (MPEG-2.5 frames are detected and skipped).

.P

Mostly MPEG-1 layer 2 and 3 are tested in real life, other variants may be buggy.

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

.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).

Maintainers:

.br

Thomas Orgis <maintainer@mpg123.org>, <thomas@orgis.org>

.br

Nicholas J. Humfrey

.TP

Michael Hipp

Uses code or ideas from various people, see the AUTHORS file accompanying the source code.

.SH LICENSE

The majority of

.B mpg123

is licensed under the GNU Lesser/Library General Public License, LGPL, version 2.1 . There is in fact only one source code file being exclusivly under GPL version 2, not LGPL: the old alsa output driver that most likely is not even compiled into your binary.

.SH WEBSITE

http://www.mpg123.org

.br

http://sourceforge.net/projects/mpg123