Help/README

   1 MusicBox -
   2 an MP3/OGG Player for the ROX Desktop
   3                 by Ken Hayber (ken@hayber.us)
   4
   5 Brief
   6 ~~~~~
   7 MusicBox plays your mp3, wav, flac and ogg files.  It requires several external
   8 python modules and libraries to support its featurs.  These modules are listed
   9 below.  Typically these modules are detected at runtime and features are
  10 gracefully degraded if things are not found (where possible).
  11
  12 I have attempted to keep the interface simple, yet flexible and featureful.
  13 There are many features that other players have that MusicBox will likely never
  14 have.  Such is life.
  15
  16 The latest version of MusicBox is at:
  17         http://www.hayber.us/rox/MusicBox
  18
  19 Share and Enjoy!
  20
  21 Instructions
  22 ~~~~~~~~~~~~
  23 Extract the MusicBox appdir and copy it to wherever you normally put ROX apps.
  24 Then launch it!  Initially it assumes that you put all your music files
  25 in ~/Music, but this is easily changed.
  26
  27 If these are not correct you must edit the Options to suit your setup. If there
  28 are any errors at startup, you can run the Options dialog without launching the
  29 application using ROX Filer's menu (right click on the AppDir icon).
  30
  31 NOTE: If you have libao/pyao installed, this will be the default output driver,
  32 regardless of whether you have any of the other supported output drivers
  33 installed or not (see below).  It just works better in my experience.  Some of
  34 the output driver choices will not work if you don't have the proper driver
  35 installed; I need to add better feedback to indicate what is working.  The
  36 device setting may have to be changed depending on which driver is selected. For
  37 oss and esd then /dev/dsp or /dev/sound/dsp are probably right.  For alsa
  38 'default' is usually what you want.
  39
  40 For library changes just hit the refresh menu item, unless you used Drag and
  41 Drop in which case the display will update automatically.  If you have a lot of
  42 files it will take considerable time to read them all - see below on how to
  43 speed things up. However, don't let that stop you from hitting the play button -
  44 we got threads!
  45
  46 In place of the ~/Music default library location you may enter:
  47         * one or more directories separated by ':' like a path
  48         * one or more *.pls or *.m3u files
  49         * one or more *.xml files (saved from MusicBox)
  50         * any combination of the above.
  51 You can also leave it blank and just load files dynamically.  This can be done
  52 in the following ways:
  53         * Drag and Drop files or folders on the MusicBox main or Playlist windows
  54         * Pass files or folders or playlists on the MusicBox command line.
  55         * Use remote control functions (see below)
  56
  57 MusicBox currently exports the following commands via rpc
  58  - load_songs  #replace existing and start playing
  59  - add_songs   #append to existing
  60  - play
  61  - pause
  62  - next
  63  - prev
  64  - stop
  65
  66 See the file xsoap.py to learn how to call these functions in python.
  67 Also, see the Extras directory for useful examples of this.
  68 We also support a similar set of command line options. (try: rox MusicBox -h)
  69
  70
  71 Tag Info and Filenames
  72 ~~~~~~~~~~~~~~~~~~~~~~
  73 MusicBox will try to read tag info from your files, but this can take a long
  74 time and many files do not contain this information.  Therefore, MusicBox will
  75 first attempt to 'guess' the artist, album and title from the filename and path
  76 of each song. However this loading process is a background task.  You can start
  77 playing songs or even quit MusicBox while this is happening.
  78
  79 The default assumption is artist/album/title.ext, but you can change this if you
  80 need to.  In the Options dialog there is a Pattern field that provides a place
  81 to edit the default pattern to be used. (Note: this is easy to get wrong and if
  82 you create a pattern that fails to match properly the default will be used)
  83 Currently MusicBox only supports artist, album and title.
  84
  85 The default pattern looks like this:
  86         ^.*/(?P<artist>.*)/(?P<album>.*)/(?P<title>.*)
  87 This pattern throws away any leading path, and separates the rest as
  88 artist/album/title.
  89
  90 The <track> option is also available if you have track numbers as part of your
  91 file naming scheme.
  92
  93 After loading a large list of songs, you can save these in a Library to speed up
  94 reloading the next time.  To do this, right click on either the Main or Playlist
  95 windows and select Save.  A ROX savebox will appear with Library.xml showing
  96 defaulted to the Choices folder for MusicBox.  You may drag this file anywhere
  97 you want to save it and rename it if you wish. Be sure not to change the .xml
  98 extension or MusicBox will not know how to reload it. (FIXME)  This file may now
  99 be dragged into either MusicBox window to reload those songs. MusicBox will not
 100 need to examine each file again to get the tag info - that was saved in the xml
 101 file.  Loading times are much quicker this way.  You can also set one of these
 102 files in the Options dialog as your default library instead of the path to the
 103 actual song files.
 104
 105 MusicBox will also use Extended Attributes for tag info if available.  These
 106 tags are my own creation and only are supported by my CD ripping application
 107 Ripper.  Xattrs are not widely supported yet, but I believe these will be the
 108 future of metadata.  Stay tuned.
 109
 110
 111 Dependencies
 112 ~~~~~~~~~~~~
 113 MusicBox depends on the following external modules/libraries for various
 114 features.  Current versions that I am developing with as of this writing are
 115 listed below.  However older versions probably work fine except as noted.
 116
 117 Basics
 118         ROX-Lib2 2.0.0 (http://rox.sourceforge.net)
 119         GTK+ 2.6.7 [req >= 2.4]
 120         GLib 2.6.3 (http://www.gtk.org)
 121         PyGtk 2.6.1 [req >= 2.4]
 122
 123 Audio output (optional if your python supports ossaudiodev
 124               or linuxaudiodev, but highly recommended)
 125     libao 0.8.5
 126     pyao  0.82 (http://www.vorbis.com)
 127     pyalsaaudio 0.2 (http://www.wilstrup.net/pyalsaaudio/)
 128
 129 MP3 (optional, but you need at least one format supported)
 130     pymad 0.4.1 (http://spacepants.org/src/pymad/)
 131     libmad 0.15.1 (http://www.underbit.com/products/mad/)
 132
 133 ID3 tag support (optional)
 134         pyid3lib 0.5.1,
 135         id3lib 3.8.3 (http://pyid3lib.sourceforge.net)
 136
 137 OGG (optional)
 138     pyogg 1.3,
 139         pyvorbis 1.3,
 140         libvorbis 1.1.0,
 141         libogg 1.1.2 (http://www.vorbis.com)
 142
 143 FLAC (optional)
 144         libflac 1.1.2 (http://flac.sourceforge.net)
 145         pyflac 0.0.1 (included, but must be built, or you can get it from debian)
 146
 147 WAV (standard)
 148         python's built in wave module
 149
 150 Hopefully your distro will provide packages for these, otherwise you will have
 151 to download and build them from sources.
 152
 153 NOTE: I have discovered that pygtk before version 1.99.17 doesn't support
 154 threads all that well, so you must have 1.99.17 or higher.
 155
 156 NOTE: The pyflac module is 0.0.1 and does not seem to be supported by anyone,
 157 although I seem to see support for it in Debian (sarge?).  I included a copy
 158 with a very slightly modified Makefile so that you should just have to type make
 159 in the 'flac' folder.  If you already have a copy installed (e.g. in your normal
 160 python modules directory) just delete or rename this folder.
 161
 162 NOTE: The above has changed a bit.  Debian now has version 0.0.3 and seems to
 163 have a maintainer.  However, my version is now patched to support flac version
 164 1.1.2.  I'll try to push the simple patch to the debian maintainer.
 165
 166
 167 Features:
 168 ~~~~~~~~~
 169 MP3, OGG, Flac, Wav support.
 170 Esd, Alsa, OSS support.
 171 Drag and Drop adding of Songs, Directories of songs, and Playlists (m3u and pls)
 172 Shuffle play (with cache so you don't replay songs too frequently).
 173 Seek control bar to zip to specific parts of any song.
 174 Volume Control (OSS and Alsa mixers)
 175 Compact UI
 176
 177
 178 Conditions
 179 ~~~~~~~~~~
 180 This program is free software; you can redistribute it and/or modify
 181 it under the terms of the GNU General Public License as published by
 182 the Free Software Foundation; either version 2 of the License, or
 183 (at your option) any later version.
 184
 185 This program is distributed in the hope that it will be useful,
 186 but WITHOUT ANY WARRANTY; without even the implied warranty of
 187 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 188 GNU General Public License for more details.
 189
 190 You should have received a copy of the GNU General Public License
 191 along with this program; if not, write to the Free Software
 192 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 193
 194 Please report any bugs to me, <ken@hayber.us>
 195