MP3CGI V1.0 release notes
=========================

What is this?
=============

MP3CGI is a Web interface to the `xaudio' MP3 player, for Linux. It may work on other
Unix versions with a bit of tweaking, but i haven't tried. 
MP3CGI runs on the same computer as xaudio, and allows MP3 playback to be
controlled remotely by a Web browser. 

To use MP3CGI you will need the xaudio package, and a Web server that supports
CGI (e.g., Apache).

Please note the MP3CGI is _extremely_ basic. In particular it gives no 
feedback on what is being played, and can only cope with MP3 files in
a single directory (but see below for suggestions on how to get around this).
It does not support playlists, shuffle, or any of the nice features that a
stand-alone player can provide.

MP3CGI works well with the MIXCGI mixer interface, available wherever you
got this.

Overview of operation
=====================

MP3CGI consists of two parts: a small daemon (mp3d) and a CGI interface. The
daemon must run continuously, and should usually be started at boot time.
The daemon is very small, and it is a shame that it has to exist
at all; however, the Web server will tend to wait until the CGI program (and
all its child processes) are complete before returning a page to the browser,
and I guess people don't want their browsers to hang up while playing MP3s. The
CGI process tells the daemon what to play, and when to stop. mp3d should run
as a user that has sufficient rights to invoke the xaudio player and read
files in the MP3 directory, but no more. In particular it won't allow itself
to be run as root, for security reasons.


Installation
============

Basic procedure (this is what will happen if you do `make install'):

1. Copy the mp3d executable to any convenient location and (optionally) have
it started at boot time.

2. Copy mp3cgi.cgi to your Web server's cgi-bin directory (e.g., on a default
Linux Apache installation this will be /home/httpd/cgi-bin).

This installs the software; to use it you will also need to
create, or modify, a web page to link to MP3CGI. The link should
specifiy the port number which mp3d is listening, and the directory
which contains the MP3 files. Here is a suitable piece of HTML:

<a href=/cgi-bin/mp3cgi?port=21221&dir=/mp3>Play MP3</a>

You will probably need to change the directory from `/mp3' to wherever your
system keeps MP3 files.
Note that although MP3CGI only supports a single directory of MP3 files, 
you can provide multiple links to it with different directories.


Compilation
===========

You should just be able to type `make' on a Linux system; with anything
else, you're on your own, I'm afraid. 


Notes
=====

1. If nothing happens when you try to play, check the Web server error log.
Error messages encountered while executing the MP3 player are written there.
They cannot be written to the Web page for technical reasons that I can't be
bothered to explain.

2. MP3CGI does not display or use MP3 `genre' codes, because on the whole
no-one fills them in correctly, and they are meaningless. It also does not
display the `comment' tag, for the same reason.

3. MP3CGI does not play any MP3 files itself, it simply calls on `xaudio' to
do this. At the time of writing, xaudio was the best free MP3 player
available, which is why it was selected. Therefore, to use MP3CGI you will
need xaudio, and it must be in your system's PATH. If you want to use
something other than xaudio, you will need to edit mp3cgi.cpp and recompile.

4. mp3d listens on port 21221 by default. If this isn't suitable, you will
need to modify mp3d.cpp and re-compile. Note that the interface to mp3d is
text based, so you can test it separately by doing `telnet localhost 21221' or
whatever. It only understands two commands: `play [filename]' and `stop'.