MusicBox -
an MP3/OGG Player for the ROX Desktop
		by Ken Hayber

Brief
~~~~~
MusicBox plays your mp3 and ogg files.  It supports ogg via pyogg/libvorbis and
mp3 via pymad/libmad.

The latest version of MusicBox is at:

	http://khayber.dyndns.org/rox/musicbox


Instructions
~~~~~~~~~~~~
Extract the MusicBox appdir and copy it to wherever you normally put ROX apps.
Then launch it!  Initially it assumes that you put all your mp3 and/or ogg files
in ~/Music.

If these are not correct you must edit the Options to suit your setup.  For
library changes just hit the refresh menu item, unless you used Drag and Drop in which
case the display will update automatically.  If you have a lot of files it will
take considerable time to read them all - see below on how to speed things up.
However, don't let that stop you from hitting the play button!  We got threads!

In place of the ~/Music default library location you may enter:
	* one or more directories separated by ':' like a path
	* one or more *.pls or *.m3u files
	* one or more *.xml files (saved from MusicBox)
	* any combination of the above.
You can also leave it blank and just load files dynamically.  This can be done in the
following ways:
	* Drag and Drop files or folders on the MusicBox main or Playlist windows
	* Pass files or folders or playlists on the MusicBox command line.
	* Use XMLrpc (see below)

MusicBox currently exports the following commands via XMLrpc:
	* load_args('song1.mp3 ~/LotsOfMusicHere anothersong.ogg')
	* play(), pause(), next(), prev(), stop()

Here is how to call these functions in python.
	import xmlrpclib
	client = xmlrpclib.Server("http://localhost:8989", None, False)
	client.load_args('~/Music/somesong.ogg')
	client.play()


Tag Info and Filenames
~~~~~~~~~~~~~~~~~~~~~~
MusicBox will try to read tag info from your files, but this can take a long time
and many files do not contain this information.  Therefore, MusicBox will first attempt
to 'guess' the artist, album and title from the filename and path of each song.
However this loading process is a background task.  You can start playing songs or
even quit MusicBox while this is happening.

The default assumption is artist/album/title.ext, but you can change this if you
need to.  In the Options dialog there is a Pattern field that provides a place to
edit the default pattern to be used. (Note: this is easy to get wrong and if you
create a pattern that fails to match properly the default will be used)  Currently
MusicBox only supports artist, album and title.

The default pattern looks like this:
	^.*/(?P<artist>.*)/(?P<album>.*)/(?P<title>.*)
This pattern throws away any leading path, and separates the rest as artist/album/title.
The <track> option is also available if you have track numbers as part of your file
naming scheme.

After loading a large list of songs, you can save these in a Library to speed up
reloading the next time.  To do this, right click on either the Main or Playlist windows
and select Save.  A ROX savebox will appear with Library.xml showing defaulted to the
Choices folder for MusicBox.  You may drag this file anywhere you want to save it and
rename it if you wish. Be sure not to change the .xml extension or MusicBox will not
know how to reload it. (FIXME)  This file may now be dragged into either MusicBox window
to reload those songs. MusicBox will not need to examine each file again to get the tag
info - that was saved in the xml file.  Loading times are much quicker this way.  You
can also set one of these files in the Options dialog as your default library instead of
the path to the actual song files.

MusicBox will also use Extended Attributes for tag info if available.  These tags are
my own creation and only are supported by my CD ripping application Ripper.  Xattrs are
not widely supported yet, but I believe these will be the future of metadata.  Stay tuned.


Dependencies
~~~~~~~~~~~~
MusicBox depends on pyao/libao for sound output, pymad/libmad for mp3 processing
and pyogg/libvorbis and friends for ogg support.

Current versions as of this writing are:
    pymad 0.4.1 (http://spacepants.org/src/pymad/)
    libmad 0.14.2 (http://www.underbit.com/products/mad/)
    pyogg, pyvorbis, libvorbis, libogg 1.0 (http://www.vorbis.com/download.psp)
    libao 0.8.3 (http://www.vorbis.com/download.psp)
    pyao  0.8 (http://www.vorbis.com/download.psp)
Optional:
	pyid3lib, id3lib (for ID3v2 tags!)

Hopefully your distro will provide packages for these, otherwise you will have to
download and build them from sources.

NOTE: I have discovered that pygtk before version 1.99.17 doesn't support threads all
that well, so you must have 1.99.17 or higher.  Sorry.


Features:
~~~~~~~~~
MP3 and OGG support.
Esd, Alsa, OSS support.
Drag and Drop adding of Songs, Directories of songs, and Playlists (m3u and pls)
Shuffle play (with cache so you don't replay songs too frequently).
Seek control bar to zip to specific parts of any song.
Volume Control
Compact UI


Conditions
~~~~~~~~~~
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

Please report any bugs to me, <khayber at socal dot rr dot com>

