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