$Id: README,v 1.5 2005/03/07 13:30:36 xi Exp $

What is MusicControl
====================

MusicControl is designed to put YOU in control of the music that gets played
from your computer.

It supports MP3, OGG and various module formats.

For MP3 support, you need to have mpg123 installed.
For OGG support, you need to have ogg123 installed.
For module support, you need to have simplemod installed.
(http://borderworlds.dk/projects/#sm)

The basic operation involves the two queues. In the random queue MusicControl
automatically add a random song whenever there are less than 5 songs left.
In the manual queue you have to add songs yourself.

Whenever MusicControl is done playing a song it looks for a new one. It starts
by looking in the manual queue and takes one from there if there are any.
Otherwise it will take one from the random queue.


Installing MusicControl
=======================
If you are not a developer then fetch the binary distribution
(MusicControl-0.1.jar). To run MusicControl just run the command

java -jar MusicControl-0.3.jar


If you are a developer, fetch the tarball instead. The script in the
root directory of the archive called 'musiccontrol' will build and run
MusicControl for you. Take a look at build.xml to see the various ant rules.

Using MusicControl for streaming
================================
MusicControl has the ability to output raw PCM sound on standard output
suitable for piping into ices which will then send it off to an icecast
streaming server.

To do this either specifiy -s on the command line or open the configuration
window and select STDOUT as audio device. You need to run MusicControl like
this:

java -jar MusicControl-0.3.jar -s | ices stream.xml

stream.xml is an ices configuration file and needs to contain something like
the following to accept the pcm data on its standard input:

<input>
  <module>stdinpcm</module>
  <param name="rate">44100</param>
  <param name="channels">2</param>
  <param name="metadata">0</param>
  <param name="metadatafilename">none</param>
</input>

MusicControl does not support feeding metadata to ices at this point. (Feel
free to send patches)
