| 1 | DisOrder |
| 2 | ======== |
| 3 | |
| 4 | DisOrder is a multi-user software jukebox. |
| 5 | * It can play either selected tracks or pick tracks at random. |
| 6 | * It supports OGG, MP3, FLAC and WAV files, and can be configured to support |
| 7 | anything you can supply a player for (up to a point). |
| 8 | * It supports both ALSA and OSS and can also broadcast an RTP stream over a |
| 9 | LAN; a player for the latter is included. |
| 10 | * Tracks may be selected either via a hierarchical interface or by a fast |
| 11 | word search. |
| 12 | * It has a web interface (allowing access from graphical web browsers) and a |
| 13 | GTK+ interface that runs on Linux and Mac systems. |
| 14 | * Playing tracks can be paused or cancelled ("scratched"). |
| 15 | |
| 16 | See CHANGES for details of recent changes to DisOrder. |
| 17 | |
| 18 | The server supports Linux and can be made to work on a Mac (see README.mac). |
| 19 | The clients work on both Linux and the Mac. It could probably be ported to |
| 20 | some other UNIX variants without too much effort. Things you will need: |
| 21 | |
| 22 | Build dependencies: |
| 23 | Name Tested Notes |
| 24 | libdb 4.3.29 4.2 and earlier won't work |
| 25 | libgc 6.8 |
| 26 | libvorbisfile 1.1.2 |
| 27 | libpcre 6.7 need UTF-8 support |
| 28 | libmad 0.15.1b |
| 29 | libgcrypt 1.2.3 |
| 30 | libao 0.8.6 |
| 31 | libasound 1.0.13 |
| 32 | libFLAC 1.1.2 |
| 33 | GNU C 4.1.2 |
| 34 | GNU Make 3.81 |
| 35 | GNU Sed 4.1.5 |
| 36 | Python 2.4.4 (optional) |
| 37 | GTK+ 2.8.20 (if you want the GTK+ client) |
| 38 | GLIB 2.12.4 (if you want the GTK+ client) |
| 39 | |
| 40 | "Tested" means I've built against that version; earlier or later versions will |
| 41 | often work too. |
| 42 | |
| 43 | Runtime dependencies: |
| 44 | * Web server: |
| 45 | + Apache 1.3.x works for me, but anything that supports CGI and |
| 46 | authentication should be suitable. |
| 47 | * Separate player programs are no longer required (but may still be used) |
| 48 | |
| 49 | Development dependencies (only developers will need these): |
| 50 | Automake 1.10 AM_PATH_PYTHON not good enough in 1.7 |
| 51 | Autoconf 2.61 |
| 52 | Libtool 1.5.22 1.4 not good enough |
| 53 | Bazaar (bzr) |
| 54 | |
| 55 | On Debian you might ensure you have the required packages as follows: |
| 56 | apt-get install gcc libc-dev automake autoconf libtool libgtk2.0-dev \ |
| 57 | libgc-dev libgcrypt-dev libpcre3-dev libvorbis-dev \ |
| 58 | libao-dev libmad0-dev libasound2-dev libdb4.3-dev \ |
| 59 | libflac-dev |
| 60 | |
| 61 | Mailing lists: |
| 62 | http://www.chiark.greenend.org.uk/mailman/listinfo/sgo-software-discuss |
| 63 | - discussion of DisOrder (and other software), bug reports, etc |
| 64 | http://www.chiark.greenend.org.uk/mailman/listinfo/sgo-software-announce |
| 65 | - announcements of new versions of DisOrder |
| 66 | |
| 67 | |
| 68 | Installation |
| 69 | ============ |
| 70 | |
| 71 | "This place'd be a paradise tomorrow, if every department had a supervisor |
| 72 | with a machine-gun" |
| 73 | |
| 74 | NOTE: If you are upgrading from an earlier version, see README.upgrades. |
| 75 | |
| 76 | On a Debian system, if you install from .deb files then you should be able to |
| 77 | skip steps 1 to 6 and configure it via debconf. This is strongly recommended! |
| 78 | |
| 79 | 1. Build the software. Do something like this: |
| 80 | |
| 81 | ./configure --sysconfdir=/etc --localstatedir=/var |
| 82 | make |
| 83 | |
| 84 | See INSTALL for more details about driving configure. The precise set of |
| 85 | options you pass to configure is up to you, if you like configuration being |
| 86 | in /usr/local/etc or wherever then that should work. |
| 87 | |
| 88 | If you only want to build a subset of DisOrder, specify one or more of the |
| 89 | following options: |
| 90 | --without-server Don't build server or web interface |
| 91 | --without-gtk Don't build GTK+ client (Disobedience) |
| 92 | --without-python Don't build Python support |
| 93 | |
| 94 | See README.client for setting up a standalone client (or read the |
| 95 | disobedience man page). |
| 96 | |
| 97 | 2. Install it. Most of the installation is done via the install target: |
| 98 | |
| 99 | make installdirs install |
| 100 | |
| 101 | The CGI interface has to be installed separately; see under 'Web Interface' |
| 102 | below. |
| 103 | |
| 104 | 3. Create a 'jukebox' user and group, with the jukebox group being the default |
| 105 | group of the jukebox user. The server will run as this user and group. |
| 106 | Check that this user can read your music files and write to the audio |
| 107 | device, e.g. by playing a track. The exact name doesn't matter, it could be |
| 108 | 'jukebox' or 'disorder' or 'fred' or whatever. |
| 109 | |
| 110 | Do not use a general-purpose user or group, you must create ones |
| 111 | specifically for DisOrder. |
| 112 | |
| 113 | 4. Create /etc/disorder/config. Start from examples/config.sample and adapt it |
| 114 | to your own requirements. The things you MUST do are: |
| 115 | * edit the 'collection' command to identify the location(s) of your own |
| 116 | digital audio files. These commands also specify the encoding of |
| 117 | filenames, which you should be sure to get right as recovery from an |
| 118 | error here can be painful (see BUGS). |
| 119 | Optionally you may also want to do the following: |
| 120 | * add 'player' commands for any file formats not supported natively |
| 121 | * edit the 'scratch' commands to supply scratch sounds (or delete them if |
| 122 | you don't want any). |
| 123 | * add or remove 'stopword' entries as necessary (these words won't take |
| 124 | part in track name searches from the web interface). |
| 125 | |
| 126 | See disorder_config(5) for more details. |
| 127 | |
| 128 | See README.streams for how to set up network play. |
| 129 | |
| 130 | If adding new 'player' commands, see README.raw for details on setting up |
| 131 | "raw format" players. Non-raw players are still supported but not in all |
| 132 | configurations and they cannot support pausing and gapless play. |
| 133 | |
| 134 | 5. Make sure the server is started at boot time. |
| 135 | |
| 136 | On many Linux systems, examples/disorder.init should be more or less |
| 137 | suitable; install it in /etc/init.d, adapting it as necessary, and make |
| 138 | appropriate links from /etc/rc[0-6].d. |
| 139 | |
| 140 | 6. Start the server. |
| 141 | |
| 142 | On Linux systems with sysv-style init: |
| 143 | |
| 144 | /etc/init.d/disorder start |
| 145 | |
| 146 | By default disorderd logs to daemon.*; check your syslog.conf to see where |
| 147 | this ends up and look for log messages from disorderd there. If it didn't |
| 148 | start up correctly there should be an error message. Correct the problem |
| 149 | and try again. |
| 150 | |
| 151 | 7. After a minute it should start to play something. Try scratching it (as |
| 152 | root): |
| 153 | |
| 154 | disorder scratch |
| 155 | |
| 156 | The track should stop playing, and (if you set any up) a scratch sound play. |
| 157 | |
| 158 | 8. Add any other users you want. These easiest way to do this is (still as |
| 159 | root): |
| 160 | |
| 161 | disorder authorize USERNAME |
| 162 | |
| 163 | This will automatically choose a random password and create |
| 164 | /etc/disorder/config.USERNAME. |
| 165 | |
| 166 | Those users should now be able to access the server from the same host as it |
| 167 | runs on, either via the disorder command or Disobedience. To run |
| 168 | Disobedience from some other host, File->Login allows hostnames, passwords |
| 169 | etc to be configured. |
| 170 | |
| 171 | 9. Optionally source completion.bash from /etc/profile or similar, for |
| 172 | example: |
| 173 | |
| 174 | . /usr/local/share/disorder/completion.bash |
| 175 | |
| 176 | This provides completion over disorder command and option names. |
| 177 | |
| 178 | |
| 179 | Web Interface |
| 180 | ============= |
| 181 | |
| 182 | "Thought I was a gonner baby, but I'm bullet proof" |
| 183 | |
| 184 | As above, if you install from a .deb, much of the work will be done |
| 185 | automatically. |
| 186 | |
| 187 | You need to configure a number of things to make this work: |
| 188 | |
| 189 | 1. If you want online registration to work then you set mail_sender in |
| 190 | /etc/disorder/config to the email address that communications from the web |
| 191 | interface will appear to be sent. If this is not a valid, deliverable email |
| 192 | address then the results are not likely to reliable. |
| 193 | |
| 194 | mail_sender webmaster@example.com |
| 195 | |
| 196 | By default the web interface sends mail by connecting to the SMTP port of |
| 197 | 127.0.0.1. You can override this with the smtp_server directive, for |
| 198 | exampler: |
| 199 | |
| 200 | smtp_server mail.example.com |
| 201 | |
| 202 | 2. The web interface depends on a 'guest' user existing. You can create this |
| 203 | with the following command: |
| 204 | |
| 205 | disorder setup-guest |
| 206 | |
| 207 | If you don't want to allow online registration instead use: |
| 208 | |
| 209 | disorder setup-guest --no-online-registration |
| 210 | |
| 211 | 3. Make sure that DisOrder can find its icons and stylesheet. For example in |
| 212 | your web server configuration: |
| 213 | |
| 214 | Alias /disorder/ /usr/local/share/disorder/static/ |
| 215 | |
| 216 | Alternatively you could use a symlink from the right location in your |
| 217 | document root, provided your web server is configured to follow them. |
| 218 | |
| 219 | cd /var/www |
| 220 | ln -s /usr/local/share/disorder/static disorder |
| 221 | |
| 222 | 4. Install disorder.cgi in an appropriate location. Remember to make it |
| 223 | executable. Example: |
| 224 | |
| 225 | install -m 755 clients/disorder.cgi /usr/lib/cgi-bin/disorder |
| 226 | |
| 227 | 5. Try it out. You should be able to perform read-only operations straight |
| 228 | away, and after visiting the 'Login' page to authenticate, perform other |
| 229 | operations like adding a track to the queue. |
| 230 | |
| 231 | 6. If you run into problems, always look at the appropriate error log; the |
| 232 | message you see in your web browser will usually not be sufficient to |
| 233 | diagnose the problem all by itself. |
| 234 | |
| 235 | 7. If you have a huge number of top level directories, then you might find |
| 236 | that the 'Choose' page is unreasonably large. If so add the following line |
| 237 | to /etc/disorder/options.user: |
| 238 | label sidebar.choosewhich choosealpha |
| 239 | |
| 240 | This will make 'Choose' be a link for each letter of the 26-letter Roman |
| 241 | alphabet; follow the link and you just get the directories which start with |
| 242 | that letter. The "*" link at the end gives you directories which don't |
| 243 | start with a letter. |
| 244 | |
| 245 | You can copy choosealpha.html to /etc/disorder and edit it to change the |
| 246 | set of initial choices to anything that can be expressed with regexps. The |
| 247 | regexps must be URL-encoded UTF-8 PCRE regexps. |
| 248 | |
| 249 | If you want to give DisOrder its own virtual host, see README.vhost. |
| 250 | |
| 251 | Copyright |
| 252 | ========= |
| 253 | |
| 254 | "Nothing but another drug, a licence that you buy and sell" |
| 255 | |
| 256 | DisOrder - select and play digital audio files |
| 257 | Copyright (C) 2003-2007 Richard Kettlewell |
| 258 | Portions copyright (C) 2007 Ross Younger |
| 259 | Portions copyright (C) 2007 Mark Wooding |
| 260 | Portions extracted from MPG321, http://mpg321.sourceforge.net/ |
| 261 | Copyright (C) 2001 Joe Drew |
| 262 | Copyright (C) 2000-2001 Robert Leslie |
| 263 | Binaries may derive extra copyright owners through linkage (binary distributors |
| 264 | are expected to do their own legwork) |
| 265 | |
| 266 | This program is free software; you can redistribute it and/or modify it under |
| 267 | the terms of the GNU General Public License as published by the Free Software |
| 268 | Foundation; either version 2 of the License, or (at your option) any later |
| 269 | version. |
| 270 | |
| 271 | This program is distributed in the hope that it will be useful, but WITHOUT ANY |
| 272 | WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A |
| 273 | PARTICULAR PURPOSE. See the GNU General Public License for more details. |
| 274 | |
| 275 | You should have received a copy of the GNU General Public License along with |
| 276 | this program; if not, write to the Free Software Foundation, Inc., 59 Temple |
| 277 | Place, Suite 330, Boston, MA 02111-1307 USA |
| 278 | |
| 279 | Local Variables: |
| 280 | mode:text |
| 281 | fill-column:79 |
| 282 | End: |