XMMSd - XMMS Webcontrol plug-in
===============================

Copyright (C) 2002 Fredrik Rambris. All rights reserved
For updates and information please check the homepage at
http://xmmsd.sourceforge.net/

If you need to get in contact with the author send an email to
boost@users.sourceforge.net.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA


ABOUT
-----

XMMSd is a web interface for X Multimedia System (XMMS). It's run both from
within XMMS as a plug-in (general) or from command line as stand alone.

The need for this came up when the author wanted to make a jukebox but didn't
want to implement playlists, decoding and playing. XMMS was so good at that
already. Also if one wanted to interface with XMMS from a CGI or PHP program
XMMS would have to run as the same user as the webserver. It would also be
troublesome for PHP to speak XMMS' native language because it is very machine
bound and PHP isn't too good at that.

What is offered is both a GUI-like interface that could be used right from a
web browser (HTML4 and CSS is used) and a plain-text interface
(ini-file style) (backend) that is ment for other front-ends to use.


INSTALLATION
------------

Either stick with the RPM or unpack the tarball, run "./configure" with the
switches you need, "make", and finally as root "make install" or
"make install-strip" if you don't want the debugsymbols.

Run "./configure --help" for more info about the switches.


USAGE
-----

You have most features when running it as a plug-in so that is probably what
you want to use first. It offers GUI configuration for starters. Simply
start XMMS (after installing the plug-in ofcause), open preferences, in the
general plugin list, select XMMSd and hit the checkbox below.

Then open http://127.0.0.1:8335/ in a webbrowser.

By default it binds to 127.0.0.1 which means that only clients on the local
host can access XMMSd.

There is a second interface accessed through
http://127.0.0.1:8335/text.html which is just plain links and just HTML1.0.

The third and final interface is ment for third party front-ends and is
reached by http://127.0.0.1:8335/backend/

See /backend/help.html for more info about the back end interface.


NOTE!
Think of the security implications before activating the plug-in.
Who can access the port and who should.

If you for some reason prefeer to run the command line version deactivate the
plug-in, open a terminal and run xmmsd --help for a list of options. Just
running xmmsd gives you the same defaults as the plug-in.

After toying around with the web interface it's time to go to the next section.


CONFIGURATION
-------------

In XMMS, select the plug-in in the general plug-in list and click the Configure
button. Here you will find two tabs; Network and Authentication. In the network
tab you set which interface to bind the input port to. What this means is that
if you set 127.0.0.1 (the default) into it only hosts that can reach your
127.0.0.1 can connect to XMMSd... and that is only the same machine that can.
If you, however, change it to the address of another interface, all hosts that
can reach that can connect. If you set it to * in accepts connections on all
available interfaces. So if you have a connection to Internet on the machine
you may want to add firewall rules etc before binding it to * or the interface
that connects to Internet.

You also can change the port that is used to connect to XMMSd with.

On the Authentication tab you may set it to require a username and password
from clients connecting before they can enter. This is stored in plain text
in ~/.xmms/config so anyone that can access that file and connect to XMMSd
can use XMMSd.


SECURITY
--------

As with all network servers. Think before allowing folks in. I doubt that
anyone can DoS it and gain root access as it doesn't run anytning. But nothing
is bug free. If you neglect the security issues and all of a sudden XMMS goes
haywire you may want to check your configuration.


COMPABILITY
-----------

You'll be the judge of that. I've only tested it on GNU/Linux. It should be
just as portable as XMMS but one never knows.


FINAL WORDS
-----------

It would be nice to hear from you users. What you think of it, how you use it,
what features you would like to see and such. Postcards are nice =) so if you
really like it send me one. The user contact is one of the major driving
forces in software development.
