| 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 or tag 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.html for details of recent changes to DisOrder and |
| 17 | README.upgrades.html for upgrade instructions. |
| 18 | |
| 19 | Platform support: |
| 20 | Linux Well tested on Debian |
| 21 | Mac OS X Disobedience well tested, server somewhat tested; use fink |
| 22 | FreeBSD Scantily tested; use ports for dependencies |
| 23 | It could probably be ported to some other UNIX variants without too much |
| 24 | effort. |
| 25 | |
| 26 | Build dependencies: |
| 27 | Name Tested Notes |
| 28 | libdb 5.3.20 also 5.1; not 4.6; 4.[578] seem to be ok |
| 29 | libgc 7.4.2 |
| 30 | libvorbisfile 1.3.5 |
| 31 | libpcre 10.22 or 7.6 need UTF-8 support |
| 32 | libmad 0.15.1b |
| 33 | libgcrypt 1.7.6 |
| 34 | libasound 1.1.3 |
| 35 | libFLAC 1.3.2 |
| 36 | libsamplerate 0.1.8 currently optional but strongly recommended |
| 37 | GStreamer 1.10.4 or 0.10.36 currently optional |
| 38 | GNU C 6.4.0 } |
| 39 | GNU Make 4.1 } Non-GNU versions will NOT work |
| 40 | GNU Sed 4.4 } |
| 41 | Python 2.7.13 (optional, 2.5.2 onwards OK; 2.4 won't work) |
| 42 | GTK+ 2.12.12 (for the GTK+ client; 2.10 & older will NOT work) |
| 43 | GLIB 2.16.6 (for the GTK+ client) |
| 44 | |
| 45 | "Tested" means I've built against that version; earlier or later versions will |
| 46 | often work too. |
| 47 | |
| 48 | If you don't have libsamplerate then DisOrder will try to run sox(1) to do |
| 49 | sample-rate and channel conversion. Unfortunately, sox has a tendency to |
| 50 | change its command-line options incompatibly every few years. Rather than |
| 51 | chase this moving target by supporting the new options introduced in 14.2, |
| 52 | I'm declaring DisOrder's sox support to be deprecated -- though (unlike |
| 53 | sox's policy) it won't actually go away until the next major version. |
| 54 | Alternatives include building against libsamplerate, or using GStreamer's |
| 55 | audio decoding instead of DisOrder's built-in decoders. |
| 56 | |
| 57 | For the web interface to work you will additionally need a web server. I've |
| 58 | had both Apache 1.3.x and 2.x working. Anything that supports CGI should be |
| 59 | OK. |
| 60 | |
| 61 | Bug tracker, etc: |
| 62 | https://github.com/ewxrjk/disorder |
| 63 | |
| 64 | Mailing lists: |
| 65 | http://www.chiark.greenend.org.uk/mailman/listinfo/sgo-software-discuss |
| 66 | - discussion of DisOrder (and other software), bug reports, etc |
| 67 | http://www.chiark.greenend.org.uk/mailman/listinfo/sgo-software-announce |
| 68 | - announcements of new versions of DisOrder |
| 69 | |
| 70 | Developers should read README.developers. |
| 71 | |
| 72 | |
| 73 | Installation |
| 74 | ============ |
| 75 | |
| 76 | "This place'd be a paradise tomorrow, if every department had a supervisor |
| 77 | with a machine-gun" |
| 78 | |
| 79 | IMPORTANT: If you are upgrading from an earlier version, see |
| 80 | README.upgrades.html. |
| 81 | |
| 82 | Debian/Ubuntu: steps 1 to 6 are dealt with automatically if you use the .deb |
| 83 | files. |
| 84 | |
| 85 | OX X/FreeBSD/other Linux: after installation (step 1 and 2), running |
| 86 | 'sudo bash scripts/setup' will cover steps 3 to 6. If it doesn't work on your |
| 87 | platform, please get in touch. |
| 88 | |
| 89 | 1. Build the software. Do something like this: |
| 90 | |
| 91 | ./configure |
| 92 | make # on FreeBSD use gmake |
| 93 | |
| 94 | See INSTALL or ./configure --help for more details about driving configure. |
| 95 | |
| 96 | If you only want to build a subset of DisOrder, specify one or more of the |
| 97 | following options: |
| 98 | --without-server Don't build server or web interface |
| 99 | --without-gtk Don't build GTK+ client (Disobedience) |
| 100 | --without-python Don't build Python support |
| 101 | |
| 102 | If configure cannot guess where your web server keeps its HTML documents and |
| 103 | CGI programs, you may have to tell it, for instance: |
| 104 | |
| 105 | ./configure cgiexecdir=/whatever/cgi-bin httpdir=/whatever/htdocs |
| 106 | |
| 107 | See README.client for setting up a standalone client (or read the |
| 108 | disobedience man page). |
| 109 | |
| 110 | To build .debs on Debian/Ubuntu, use: |
| 111 | fakeroot debian/rules binary |
| 112 | |
| 113 | 2. Install it. Most of the installation is done via the install target: |
| 114 | |
| 115 | make installdirs install |
| 116 | |
| 117 | NB steps 3 to 6 are covered by scripts/setup. It should work on FreeBSD, OS |
| 118 | X and Linux and could be adapted to other platforms. |
| 119 | |
| 120 | 3. Create a 'jukebox' user and group, with the jukebox group being the default |
| 121 | group of the jukebox user. The server will run as this user and group. |
| 122 | Check that this user can read your music files and write to the audio |
| 123 | device, e.g. by playing a track. The exact name doesn't matter, it could be |
| 124 | 'jukebox' or 'disorder' or 'fred' or whatever. |
| 125 | |
| 126 | Do not use a general-purpose user or group, you must create ones |
| 127 | specifically for DisOrder. |
| 128 | |
| 129 | 4. Create /etc/disorder/config. Start from examples/config.sample and adapt it |
| 130 | to your own requirements. The things you MUST do are: |
| 131 | * edit the 'collection' command to identify the location(s) of your own |
| 132 | digital audio files. These commands also specify the encoding of |
| 133 | filenames, which you should be sure to get right as recovery from an |
| 134 | error here can be painful (see BUGS). |
| 135 | Optionally you may also want to do the following: |
| 136 | * add 'player' and 'tracklength' commands for any file formats not |
| 137 | supported natively |
| 138 | * edit the 'scratch' commands to supply scratch sounds (or delete them if |
| 139 | you don't want any). |
| 140 | * add extra 'stopword' entries as necessary (these words won't take part in |
| 141 | track name searches from the web interface). |
| 142 | |
| 143 | See disorder_config(5) for more details. |
| 144 | |
| 145 | See README.streams for how to set up network play. |
| 146 | |
| 147 | If adding new 'player' commands, see disorder(3) for details on setting up |
| 148 | "raw format" players. Non-raw players are still supported but not in all |
| 149 | configurations and they cannot support pausing and gapless play. If you |
| 150 | want additional formats to be supported natively please point the author at |
| 151 | a GPL-compatible library that can decode them. |
| 152 | |
| 153 | 5. Make sure the server is started at boot time. |
| 154 | |
| 155 | On many Linux systems, examples/disorder.init should be more or less |
| 156 | suitable; install it in /etc/init.d, adapting it as necessary, and make |
| 157 | appropriate links from /etc/rc[0-6].d. |
| 158 | |
| 159 | 6. Start the server. |
| 160 | |
| 161 | On Linux systems with sysv-style init: |
| 162 | |
| 163 | /etc/init.d/disorder start |
| 164 | |
| 165 | By default disorderd logs to daemon.*; check your syslog.conf to see where |
| 166 | this ends up and look for log messages from disorderd there. If it didn't |
| 167 | start up correctly there should be an error message. Correct the problem |
| 168 | and try again. |
| 169 | |
| 170 | 7. After a short while it should start to play something. Try scratching it |
| 171 | (as root): |
| 172 | |
| 173 | disorder scratch |
| 174 | |
| 175 | The track should stop playing, and (if you set any up) a scratch sound play. |
| 176 | |
| 177 | 8. Add any other users you want. These easiest way to do this is (still as |
| 178 | root): |
| 179 | |
| 180 | disorder authorize USERNAME |
| 181 | |
| 182 | This will automatically choose a random password and create |
| 183 | ~USERNAME/.disorder/passwd. |
| 184 | |
| 185 | Those users should now be able to access the server from the same host as it |
| 186 | runs on, either via the disorder command or Disobedience. To run |
| 187 | Disobedience from some other host, File->Login allows hostnames, passwords |
| 188 | etc to be configured. |
| 189 | |
| 190 | Alternatively, after setting up the web interface (below), it's possible to |
| 191 | allow users to register themselves without operator involvement. |
| 192 | |
| 193 | 9. Optionally source completion.bash from /etc/profile or similar, for |
| 194 | example: |
| 195 | |
| 196 | . /usr/local/share/disorder/completion.bash |
| 197 | |
| 198 | This provides completion over disorder command and option names. |
| 199 | |
| 200 | |
| 201 | Web Interface |
| 202 | ============= |
| 203 | |
| 204 | "Thought I was a gonner baby, but I'm bullet proof" |
| 205 | |
| 206 | Debian/Ubuntu: the .deb files will do the setup here automatically. |
| 207 | |
| 208 | OS X/FreeBSD/other Linux: scripts/setup as referred to above will do the setup |
| 209 | here automatically. |
| 210 | |
| 211 | You need to configure a number of things to make this work: |
| 212 | |
| 213 | 1. If you want online registration to work then set mail_sender in |
| 214 | /etc/disorder/config to the email address that communications from the web |
| 215 | interface will appear to be sent. If this is not a valid, deliverable email |
| 216 | address then the results are not likely to be reliable. |
| 217 | |
| 218 | mail_sender webmaster@example.com |
| 219 | |
| 220 | By default the web interface sends mail via the system sendmail executable |
| 221 | (typically /usr/sbin/sendmail or /usr/lib/sendmail). You can override this |
| 222 | with the sendmail directive, for example: |
| 223 | |
| 224 | sendmail /usr/sbin/my-sendmail |
| 225 | |
| 226 | The executable you choose must support the -bs option. Alternatively you |
| 227 | can tell it to connect to an SMTP server via TCP, with the smtp_server |
| 228 | directive. For example: |
| 229 | |
| 230 | smtp_server mail.example.com |
| 231 | |
| 232 | Use 'disorder reconfigure' to make sure the server knows these settings. |
| 233 | |
| 234 | 2. The web interface depends on a 'guest' user existing. You can create this |
| 235 | with the following command: |
| 236 | |
| 237 | disorder setup-guest |
| 238 | |
| 239 | If you don't want to allow online registration instead use: |
| 240 | |
| 241 | disorder setup-guest --no-online-registration |
| 242 | |
| 243 | 3. Try it out. The url will be (something like): |
| 244 | |
| 245 | http://localhost/cgi-bin/disorder |
| 246 | |
| 247 | You should be able to perform read-only operations straight away, and after |
| 248 | visiting the 'Login' page to authenticate, perform other operations like |
| 249 | adding a track to the queue. |
| 250 | |
| 251 | 4. If you run into problems, always look at the appropriate error log; the |
| 252 | message you see in your web browser will usually not be sufficient to |
| 253 | diagnose the problem all by itself. |
| 254 | |
| 255 | 5. If you have a huge number of top level directories, then you might find |
| 256 | that the 'Choose' page is unreasonably large. If so add the following line |
| 257 | to /etc/disorder/options.user: |
| 258 | label sidebar.choosewhich choosealpha |
| 259 | |
| 260 | This will make 'Choose' be a link for each letter of the 26-letter Roman |
| 261 | alphabet; follow the link and you just get the directories which start with |
| 262 | that letter. The "*" link at the end gives you directories which don't |
| 263 | start with a letter. |
| 264 | |
| 265 | You can copy choosealpha.html to /etc/disorder and edit it to change the |
| 266 | set of initial choices to anything that can be expressed with regexps. The |
| 267 | regexps must be URL-encoded UTF-8 PCRE regexps. |
| 268 | |
| 269 | If you want to give DisOrder its own virtual host, see README.vhost. |
| 270 | |
| 271 | Copyright |
| 272 | ========= |
| 273 | |
| 274 | "Nothing but another drug, a licence that you buy and sell" |
| 275 | |
| 276 | DisOrder - select and play digital audio files |
| 277 | Copyright (C) 2003-2013 Richard Kettlewell |
| 278 | Portions copyright (C) 2007 Ross Younger |
| 279 | Portions copyright (C) 2007, 2013, 2015-2017 Mark Wooding |
| 280 | Portions extracted from MPG321, http://mpg321.sourceforge.net/ |
| 281 | Copyright (C) 2001 Joe Drew |
| 282 | Copyright (C) 2000-2001 Robert Leslie |
| 283 | Portions Copyright (C) 1997-2006 Free Software Foundation, Inc. |
| 284 | Portions Copyright (C) 2000 Red Hat, Inc., Jonathan Blandford <jrb@redhat.com> |
| 285 | Unicode test files Copyright (C) 1991-2017 Unicode Inc.; see |
| 286 | libtests/COPYING.unicode-tests for details. |
| 287 | Binaries may derive extra copyright owners through linkage (binary distributors |
| 288 | are expected to do their own legwork) |
| 289 | |
| 290 | This program is free software: you can redistribute it and/or modify |
| 291 | it under the terms of the GNU General Public License as published by |
| 292 | the Free Software Foundation, either version 3 of the License, or |
| 293 | (at your option) any later version. |
| 294 | |
| 295 | This program is distributed in the hope that it will be useful, |
| 296 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 297 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 298 | GNU General Public License for more details. |
| 299 | |
| 300 | You should have received a copy of the GNU General Public License |
| 301 | along with this program. If not, see <http://www.gnu.org/licenses/>. |
| 302 | |
| 303 | Local Variables: |
| 304 | mode:text |
| 305 | fill-column:79 |
| 306 | End: |