| 1 | DisOrder |
| 2 | ======== |
| 3 | |
| 4 | This program is used to play random and chosen tracks from a collection of |
| 5 | digital audio files (for instance MP3 and OGG files). If you just set it going |
| 6 | it plays random tracks from your collection, but you can also ask for specific |
| 7 | tracks to be played, either via a command line program or a web interface, and |
| 8 | you can 'scratch' the current track. |
| 9 | |
| 10 | See CHANGES for details of recent changes to DisOrder. |
| 11 | |
| 12 | Currently it only runs on Linux. It could probably be ported to other UNIX |
| 13 | variants in some cases without too much effort. Things you will need: |
| 14 | |
| 15 | Build dependencies: |
| 16 | Name Tested Notes |
| 17 | libdb 4.3.21 4.2 and earlier won't work |
| 18 | libgc 6.3 |
| 19 | libvorbisfile 1.0.1 |
| 20 | libpcre 4.5 need UTF-8 support |
| 21 | libmad 0.15.1b |
| 22 | libgcrypt 1.2.0 |
| 23 | libao 0.8.6 |
| 24 | libasound 1.0.8 |
| 25 | Python 2.3 (optional) |
| 26 | GNU C 3.3, 3.4 |
| 27 | |
| 28 | "Tested" means I've built against that version; earlier or later versions will |
| 29 | often work too. |
| 30 | |
| 31 | Runtime dependencies: |
| 32 | * Players: |
| 33 | + ogg123 and mpg321 work for me, but you could potentially use others. |
| 34 | * Web server: |
| 35 | + Apache 1.3.x works for me, but anything that supports CGI and |
| 36 | authentication should be suitable. |
| 37 | |
| 38 | Development dependencies (only developers will need these): |
| 39 | Automake 1.9.4 AM_PATH_PYTHON not good enough in 1.7 |
| 40 | Autoconf 2.59 |
| 41 | Libtool 1.5.6 1.4 not good enough |
| 42 | Bazaar (bzr) |
| 43 | |
| 44 | Mailing lists: |
| 45 | http://www.chiark.greenend.org.uk/mailman/listinfo/sgo-software-discuss |
| 46 | - discussion of DisOrder (and other software), bug reports, etc |
| 47 | http://www.chiark.greenend.org.uk/mailman/listinfo/sgo-software-announce |
| 48 | - announcements of new versions of DisOrder |
| 49 | |
| 50 | |
| 51 | Installation |
| 52 | ============ |
| 53 | |
| 54 | "This place'd be a paradise tomorrow, if every department had a supervisor |
| 55 | with a machine-gun" |
| 56 | |
| 57 | NOTE: If you are upgrading from an earlier version, see README.upgrades. |
| 58 | |
| 59 | 1. Build the software. Do something like this: |
| 60 | |
| 61 | ./configure --sysconfdir=/etc --localstatedir=/var |
| 62 | make |
| 63 | |
| 64 | See INSTALL for more details about driving configure. The precise set of |
| 65 | options you pass to configure is up to you, if you like configuration being |
| 66 | in /usr/local/etc or wherever then that should work. |
| 67 | |
| 68 | If you only want to build a subset of DisOrder, specify one or more of the |
| 69 | following options: |
| 70 | --without-server Don't build server or web interface |
| 71 | --without-gtk Don't build GTK+ client (Disobedience) |
| 72 | --without-python Don't build Python support |
| 73 | |
| 74 | See README.client for setting up a standalone client. |
| 75 | |
| 76 | 2. Install it. Most of the installation is done via the install target: |
| 77 | |
| 78 | make installdirs install |
| 79 | |
| 80 | The CGI interface has to be installed separately, and you must use Libtool |
| 81 | to install it. For instance: |
| 82 | |
| 83 | ./libtool --mode=install install -m 755 progs/disorder.cgi /usr/local/lib/cgi-bin/disorder |
| 84 | |
| 85 | Depending on how your system is configured you may need to link the disorder |
| 86 | libao driver into the right directory: |
| 87 | |
| 88 | ln -s /usr/local/lib/ao/plugins-2/libdisorder.so /usr/lib/ao/plugins-2/. |
| 89 | |
| 90 | 3. Create a 'jukebox' user and group, with the jukebox group being the default |
| 91 | group of the jukebox user. The server will run as this user and group. |
| 92 | Check that this user can read your music files and write to the audio |
| 93 | device, e.g. by playing a track. The exact name doesn't matter, it could be |
| 94 | 'jukebox' or 'disorder' or 'fred' or whatever. |
| 95 | |
| 96 | Do not use a general-purpose user or group, you must create ones |
| 97 | specifically for DisOrder. |
| 98 | |
| 99 | 4. Create /etc/disorder/config. Start from examples/config.sample and adapt it |
| 100 | to your own requirements. In particular, you should: |
| 101 | * edit the 'player' commands to reflect the software you have installed. |
| 102 | * edit the 'collection' command to identify the location(s) of your own |
| 103 | digital audio files. These commands also specify the encoding of |
| 104 | filenames, which you should be sure to get right as recovery from an |
| 105 | error here can be painful (see BUGS). |
| 106 | * edit the 'scratch' commands to supply scratch sounds (or delete them if |
| 107 | you don't want any). |
| 108 | * edit the 'trust' command to reflect the user the web interface will |
| 109 | eventually run as. |
| 110 | * edit the 'url' command to give the URL of the web interface. |
| 111 | * add or remove 'stopword' entries as necessary (these words won't take |
| 112 | part in track name searches from the web interface). |
| 113 | |
| 114 | See disorder_config(5) for more details. |
| 115 | |
| 116 | 5. Create /etc/disorder/config.private. This should be readable only by the |
| 117 | jukebox group: |
| 118 | |
| 119 | touch /etc/disorder/config.private |
| 120 | chown root:jukebox /etc/disorder/config.private |
| 121 | chmod 640 /etc/disorder/config.private |
| 122 | |
| 123 | Set up a username and password for root, for example with line like this: |
| 124 | |
| 125 | allow root somepassword |
| 126 | |
| 127 | Use (for instance) pwgen(1) to create the password. DO NOT use your root |
| 128 | password - this is a password to give root access to the server, not to give |
| 129 | access to the root login. |
| 130 | |
| 131 | See disorderd(8) and disorder_config(5) for more details. |
| 132 | |
| 133 | 6. Make sure the server is started at boot time. On many Linux systems, |
| 134 | examples/disorder.init should be more or less suitable; install it in |
| 135 | /etc/init.d, adapting it as necessary, and make appropriate links from |
| 136 | /etc/rc[0-6].d. If you have a BSD style init then you are on your own. |
| 137 | |
| 138 | 7. Make sure the state directory (/var/disorder or /usr/local/var/disorder or |
| 139 | as determined by configure) exists and is writable by the jukebox user. |
| 140 | |
| 141 | mkdir -m 755 /var/disorder |
| 142 | chown disorder:root /var/disorder |
| 143 | |
| 144 | 8. Start the server, for instance: |
| 145 | |
| 146 | /etc/init.d/disorder start |
| 147 | |
| 148 | By default disorderd logs to daemon.*; check your syslog.conf to see where |
| 149 | this ends up and look for log messages from disorderd there. If it didn't |
| 150 | start up correctly there should be an error message. Correct the problem |
| 151 | and try again. |
| 152 | |
| 153 | 9. After a minute it should start to play something. Try scratching it, as any |
| 154 | of the users you set up in step 5: |
| 155 | |
| 156 | disorder scratch |
| 157 | |
| 158 | The track should stop playing, and (if you set any up) a scratch sound play. |
| 159 | |
| 160 | 10. Add any other users you want to config.private. Each user's password |
| 161 | should be stored in a file in their home directory, ~/.disorder/passwd, |
| 162 | which should be readable only by them, and should take the form of a single |
| 163 | line: |
| 164 | |
| 165 | password MYPASSWORD |
| 166 | |
| 167 | (root doesn't need this as the client can read it out of config.private |
| 168 | when running as root.) |
| 169 | |
| 170 | Note that the server must be reloaded (e.g. by 'disorder reconfigure') |
| 171 | when new users are added. |
| 172 | |
| 173 | Alternatively the administrator can create /etc/disorder/config.USERNAME |
| 174 | containing the same thing as above. It can either be owned by the user and |
| 175 | mode 400, or owned by root and the user's group (if you have per-user |
| 176 | groups) and mode 440. |
| 177 | |
| 178 | You can use 'disorder authorize' to automatically pick passwords and |
| 179 | create these files. |
| 180 | |
| 181 | 11. Optionally source completion.bash from /etc/profile or similar, for |
| 182 | example: |
| 183 | |
| 184 | . /usr/local/share/disorder/completion.bash |
| 185 | |
| 186 | This provides completion over disorder command and option names. |
| 187 | |
| 188 | |
| 189 | Web Interface |
| 190 | ============= |
| 191 | |
| 192 | "Thought I was a gonner baby, but I'm bullet proof" |
| 193 | |
| 194 | These instructions assumes you are using Apache 1.3.x. |
| 195 | |
| 196 | You need to configure a number of things to make this work: |
| 197 | |
| 198 | 1. If you want to have a 'jukebox' virtual host, modify the DNS (or hosts file |
| 199 | if you are somehow reading this in the 1980s) accordingly and use a fragment |
| 200 | such as this one: |
| 201 | |
| 202 | <VirtualHost HOSTNAME> |
| 203 | DocumentRoot /home/jukebox/public_html |
| 204 | ServerName jukebox.DOMAIN |
| 205 | ServerAlias jukebox |
| 206 | ServerAdmin webmaster@DOMAIN |
| 207 | ErrorLog /var/log/apache/jukebox/error.log |
| 208 | TransferLog /var/log/apache/jukebox/access.log |
| 209 | Alias /static/ /usr/local/share/disorder/static/ |
| 210 | </VirtualHost> |
| 211 | |
| 212 | /static/ should point to the 'static' directory installed by DisOrder. If |
| 213 | you don't want to use the name 'static' then you can change the url.static |
| 214 | label in the web interface configuration to your preferred URL; see |
| 215 | disorder_config(5) for details. |
| 216 | |
| 217 | Don't forget to reload Apache after modifying its configuration. |
| 218 | |
| 219 | Separate logging is not required but I find it convenient. Up to you. |
| 220 | |
| 221 | 2. disorder.cgi assumes it is subject to access control (and in particular uses |
| 222 | the username to report who did what). Here's how I configured Apache, given |
| 223 | the above VirtualHost settings: |
| 224 | |
| 225 | <Directory /home/jukebox> |
| 226 | Require valid-user |
| 227 | AuthType basic |
| 228 | AuthName jukebox |
| 229 | AuthUserFile /home/jukebox/http.users |
| 230 | </Directory> |
| 231 | |
| 232 | Adjust this according to wherever you're going to install disorder.cgi and |
| 233 | its expected URL. |
| 234 | |
| 235 | Don't forget to reload apache after modifying its configuration. If you got |
| 236 | it wrong, fix it and restart Apache. |
| 237 | |
| 238 | 3. Create the password file configured above. Something like this: |
| 239 | |
| 240 | # htpasswd -b -c /home/jukebox/http.users myusername mypassword |
| 241 | Adding password for user myusername |
| 242 | # htpasswd -b /home/jukebox/http.users othername otherpass |
| 243 | Adding password for user othername |
| 244 | |
| 245 | 4. The jukebox must be configured to trust the web user. I added the following |
| 246 | line to my /etc/disorder/config: |
| 247 | |
| 248 | trust www-data |
| 249 | |
| 250 | This might not be the same on your system! You have to specify the user |
| 251 | that the CGI script runs as, whatever that is. |
| 252 | |
| 253 | 5. Install disorder.cgi in an appropriate location. Remember to make it |
| 254 | executable. With the above configuration I installed it as |
| 255 | ~jukebox/public_html/index.cgi. |
| 256 | |
| 257 | 6. Give www-data (or whatever user it is) a password and edit |
| 258 | /etc/disorder/config.private accordingly. This file should be mode 640 and |
| 259 | owned by root:jukebox. The line should look something like this: |
| 260 | |
| 261 | allow www-data MYPASSWORD |
| 262 | |
| 263 | After editing the config file, you must make the daemon re-read it: |
| 264 | |
| 265 | disorder reconfigure |
| 266 | |
| 267 | 7. Teach www-data its password, by putting it in /etc/disorder/config.www-data. |
| 268 | This file should be mode 640 and owned by root:www-data. |
| 269 | |
| 270 | password MYPASSWORD |
| 271 | |
| 272 | (You could also use ~www-data/.disorder/passwd for this but on some systems |
| 273 | the web server user's home directory is inside the document root, which |
| 274 | would have rather unfortunate consequences.) |
| 275 | |
| 276 | 8. Try it out. You should be asked for a username and password that you |
| 277 | configured earlier, and be shown details of what is playing and what other |
| 278 | tracks have been configured for future play. |
| 279 | |
| 280 | 9. Some features take time to start working, for instance those involving |
| 281 | reporting the length of tracks. This is because the server starts up as |
| 282 | quickly as possible even if the full track data has not yet been gathered; |
| 283 | the track data is then calculated in the background. |
| 284 | |
| 285 | 10. If you run into problems, always look at the appropriate error log; the |
| 286 | message you see in your web browser will usually not be sufficient to |
| 287 | diagnose the problem all by itself. |
| 288 | |
| 289 | 11. If you have a huge number of top level directories, then you might find |
| 290 | that the 'Choose' page is unreasonably large. If so add the following line |
| 291 | to /etc/disorder/options.user: |
| 292 | label sidebar.choosewhich choosealpha |
| 293 | |
| 294 | This will make 'Choose' be a link for each letter of the 26-letter Roman |
| 295 | alphabet; follow the link and you just get the directories which start with |
| 296 | that letter. The "*" link at the end gives you directories which don't |
| 297 | start with a letter. |
| 298 | |
| 299 | You can copy choosealpha.html to /etc/disorder and edit it to change the |
| 300 | set of initial choices to anything that can be expressed with regexps. The |
| 301 | regexps must be URL-encoded UTF-8 PCRE regexps. |
| 302 | |
| 303 | |
| 304 | Copyright |
| 305 | ========= |
| 306 | |
| 307 | "Nothing but another drug, a licence that you buy and sell" |
| 308 | |
| 309 | DisOrder - select and play digital audio files |
| 310 | Copyright (C) 2003, 2004, 2005, 2006 Richard Kettlewell |
| 311 | Portions extracted from MPG321, http://mpg321.sourceforge.net/ |
| 312 | Copyright (C) 2001 Joe Drew |
| 313 | Copyright (C) 2000-2001 Robert Leslie |
| 314 | Binaries may derive extra copyright owners through linkage (binary distributors |
| 315 | are expected to do their own legwork) |
| 316 | |
| 317 | This program is free software; you can redistribute it and/or modify it under |
| 318 | the terms of the GNU General Public License as published by the Free Software |
| 319 | Foundation; either version 2 of the License, or (at your option) any later |
| 320 | version. |
| 321 | |
| 322 | This program is distributed in the hope that it will be useful, but WITHOUT ANY |
| 323 | WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A |
| 324 | PARTICULAR PURPOSE. See the GNU General Public License for more details. |
| 325 | |
| 326 | You should have received a copy of the GNU General Public License along with |
| 327 | this program; if not, write to the Free Software Foundation, Inc., 59 Temple |
| 328 | Place, Suite 330, Boston, MA 02111-1307 USA |
| 329 | |
| 330 | Local Variables: |
| 331 | mode:text |
| 332 | fill-column:79 |
| 333 | End: |