ABOUT MPG321
------------

mpg321 is a Free replacement for mpg123, a very popular command-line mp3
player. mpg123 is used for frontends, as an mp3 player and as an mp3 to
wave file decoder (primarily for use with CD-recording software.) In all
of these capacities, mpg321 can be used as a drop-in replacement for
mpg123.

mpg321 is a project conceived and written by Joe Drew <hoserhead@woot.net>.
It uses code from the MAD distribution by Rob Leslie; XMMS; and plaympeg
from the SMPEG distribution. mpg321 is licensed under the GNU General
Public License version 2, as documented in the 'COPYING' file.

WHY MPG321?
-----------

mpg123 is very popular because of its relative simplicity and its general
facility. It is very good at what it does. It is, however, under a non-free
license: you can't incorporate its code into your own without getting
special permission, and commercial entities also need special permission
just to use it.

Being a Free Software advocate, I saw a deficiency in the dependency many
people had on mpg123. Therefore, I created mpg321, and as more features
of mpg123 are implemented, it becomes less and less likely that anyone
will need mpg123 for anything any more.

INSTALLING MPG321
-----------------

Please read the document 'INSTALL' to find mpg321's dependencies and
configuration, compilation and installation instructions.

mpg321 has been tested on Debian GNU/Linux (x86), as well as Sun Solaris
(UltraSparc). It is also available from several BSD vendors, and may be
included in other Linux distributions. Any problems encountered on any
system, though, should be reported to the author.

GETTING INVOLVED/INFORMED
-------------------------

If you like mpg321, please donate to the Electronic Freedom Foundation (EFF).
They help ensure that software for any purpose can continue to be written
legally. Find out more information at http://www.eff.org .

To be informed of any new releases of mpg321, please subscribe to the
mpg321-announce mailing list: send an email with 'subscribe' in the body or
subject to mpg321-announce-request@lists.sourceforge.net, or visit
http://lists.sourceforge.net/lists/listinfo/mpg321-announce .

There are a number of tasks that are still on-going with the develompent
of mpg321. If you're interested, please read the TODO and HACKING files.
Also, always feel free to e-mail me, Joe Drew <hoserhead@woot.net>.

There is also a sourceforge project for mpg321:
http://sourceforge.net/projects/mpg321

HISTORY OF MPG321
-----------------

`mpg321' started long ago (sometime in 1999) as a wrapper script for
the mpg123 frontend of the media player FreeAmp. It was contributed
to the Debian package of FreeAmp, and for several revisions was
included as 'mpg123.freeamp.' (This script has since been removed.)

mpg123.freeamp didn't work very well, and was limited by FreeAmp's
implementation of the mpg123 frontend, but it worked for what I needed
it to do: play music from the command-line without needing mpg123
installed.

Early in 2001, I decided that a real alternative to mpg123 was needed,
and started looking around for a good mp3 decoding library. I came
across SMPEG, which was written by Loki Software, and based on SDL.
It was very simple programatically and handled most everything that
was needed. mpg321 was born, and it did all the simple things that
were required of it.

SMPEG, however, required SDL for output, which in turn required many
other libraries. This was a very sub-optimal arrangement. So, in 2001,
I performed what amounted to almost a full rewrite of mpg321, porting
it to Rob Leslie's MAD MPEG audio decoder library. I chose MAD because
it provides very high-quality output, and also because it operates entirely
with fixed point (integer) instructions.

At the same time, I also switched to the Ogg Vorbis (Xiphophorous) project
libao for all audio output.

That's pretty much where mpg321 stands right now. There are still
unimplemented features, and undoubtedly still bugs. But it works well
for many people, and it liberates one more dependency people had on
non-Free software. That's worth it, to me.

mpg321 now implements mpg123's 'Remote Control' interface, via option
-R. This is useful if, for example, you're writing a frontend to mpg321
which needs a consitent, reliable interface to control playback.

The Remote Control Interface has a small quirk, consistent with that of
mpg123: you must specify a dummy argument on the command-line. That
is to say, running `mpg321 -R' will bring up the usage message; running
`mpg321 -R abcd' (or anything else in place of 'abcd') will start the
Remote Control Interface.

Once you're running with the Remote Control Interface, there are
several commands you can use:

COMMANDS:
--------
(All commands can be shortened to first character only)

LOAD <file>

Loads and starts playing <file>.

JUMP [+-]<frames>
If '+' or '-' is specified, jumps <frames> frames forward, or backwards,
respectively, in the the mp3 file.  If neither is specifies, jumps to
absolute frame <frames> in the mp3 file.

PAUSE
Pauses the playback of the mp3 file; if already paused, restarts playback.

QUIT
Quits mpg321.

There are also several outputs possible:

OUTPUT:
------

@R MPG123
mpg123 tagline. Output at startup.

@I mp3-filename
Prints out the filename of the mp3 file, minus the extension. Happens after
an mp3 file has been loaded.

@S <a> <b> <c> <d> <e> <f> <g> <h> <i> <j> <k> <l>
Outputs information about the mp3 file after loading.
<a>: version of the mp3 file. Currently always 1.0 with madlib, but don't
     depend on it, particularly if you intend portability to mpg123 as well.
     Float/string.
<b>: layer: 1, 2, or 3. Integer.
<c>: Samplerate. Integer.
<d>: Mode string. String.
<e>: Mode extension. Integer.
<f>: Bytes per frame (estimate, particularly if the stream is VBR). Integer.
<g>: Number of channels (1 or 2, usually). Integer.
<h>: Is stream copyrighted? (1 or 0). Integer.
<i>: Is stream CRC protected? (1 or 0). Integer.
<j>: Emphasis. Integer.
<k>: Bitrate, in kbps. (i.e., 128.) Integer.
<l>: Extension. Integer.

@F <current-frame> <frames-remaining> <current-time> <time-remaining>
Frame decoding status updates (once per frame).
Current-frame and frames-remaining are integers; current-time and
time-remaining floating point numbers with two decimal places.

@S {0, 1, 2}
Stop/pause status.
0 - playing has stopped. When 'STOP' is entered, or the mp3 file is finished.
1 - Playing is paused. Enter 'PAUSE' or 'P' to continue.
2 - Playing has begun again.