Moosic - A musical jukebox program.
Version 1.5.1
By Daniel Pearson

Moosic is a music player that focuses on convenient and powerful playlist
management.  It consists of a server process that maintains a queue of music
files to play and a client program which sends commands to the server.  The
server continually runs through its playlist, popping items off the top of the
list and playing each with an external program.  The standard client is a simple
command-line utility which allows you to perform powerful operations upon the
server's queue, including the addition of whole directory trees, automatic
shuffling, and item removal according to regular expressions.  The server comes
configured to play MP3, Ogg, MIDI, MOD, and WAV files.

REQUIREMENTS:
The primary requirement is a Python interpreter that supports version 2.2 of the
language (or later) and also includes support for threads.  It also relies on
the Unix "find" utility.  It relies upon external programs for actually playing
the music files.  The default setup uses mpg123 for MP3, timidity for MIDI,
ogg123 for Ogg/Vorbis, mikmod for the whole range of MOD formats, TakCD for
audio CDs, and SOX for a wide variety of sound other (mostly uncompressed) sound
file formats.  Moosic will only work on Unix systems, since it uses a wide
variety of Unix-only features.  All of these portability issues are noted within
the source code.

INSTALLATION:
After extracting the archive file (tarball) used to distribute Moosic, change to
the directory that contains Moosic, and run "python setup.py install" with the
privileges of root (the system administration account).  If you cannot or do not
want to install Moosic with root privileges, you can install it into your own
home directory by running "python setup.py install --home=~" instead.  If you
install Moosic into your home directory, make sure that the PYTHONPATH
environment variable is set and includes the directory "~/lib/python/".

USAGE:
"moosic" is the command-line program that provides the main interface to the
Moosic jukebox.  It works by sending a command to the Moosic server and
returning the response, if any.  The first non-option argument given to moosic
is the name of the command to be performed.  Use "moosic --showcommands" to get
a list of all the different possible commands, or read moosic's manual page.
There are very many commands, so you should start by just learning a few
commonly used commands, and only learning others as you feel the need.  I
recommend starting with the following short command vocabulary: add, list, stop,
play, and shuffle.

For example, "moosic add foo.mp3" adds the file foo.mp3 (in the current
directory) to the end of the song queue and returns you immediately back to your
shell prompt without printing any output (unless an error occurs).  Compare with
"moosic list", which will list the contents of the song queue.  Note that if the
song queue is empty, "moosic list" will not display anything.

Any command which takes a list of files as an argument will also accept
directories, and doing so will cause every file below that directory to be
included in the file-list.  Note that the default behavior of moosic is to
shuffle everything in a file-list before sending the list to the server, but
only after recursively expanding named directories.  You can disable shuffling
by using the -o option.  Use "moosic --help" to learn about all the options for
changing the shuffling behavior, as well as the other command options.

When the Moosic server isn't already running, moosic will automatically start it
for you (unless you specifically request otherwise with a command-line option).
For backwards compatibility, the "moosicd" program can be run to explicitly
start the server.  However, this usage is obsolete because you can run "moosic
startserver" to achieve the same effect.  This means that you can delete the
"moosicd" program from your system if you want.


Copyright (C) 2001-2004 Daniel Pearson <daniel@nanoo.org>

This program is free software, and can be redistributed and/or modified under
the terms of the GNU General Public License (GPL).  See the file named
"License.txt" for more details.
