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 | |
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"). | |
460b9539 | 15 | |
16 | See CHANGES for details of recent changes to DisOrder. | |
17 | ||
5f5fc693 RK |
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: | |
460b9539 | 21 | |
22 | Build dependencies: | |
23 | Name Tested Notes | |
1a0d3568 | 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 | |
460b9539 | 28 | libmad 0.15.1b |
1a0d3568 | 29 | libgcrypt 1.2.3 |
460b9539 | 30 | libao 0.8.6 |
1a0d3568 | 31 | libasound 1.0.13 |
32 | libFLAC 1.1.2 | |
33 | GNU C 4.1.2 | |
34 | GNU Make 3.81 | |
ddf922de | 35 | GNU Sed 4.1.5 |
1a0d3568 | 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) | |
460b9539 | 39 | |
40 | "Tested" means I've built against that version; earlier or later versions will | |
41 | often work too. | |
42 | ||
43 | Runtime dependencies: | |
460b9539 | 44 | * Web server: |
45 | + Apache 1.3.x works for me, but anything that supports CGI and | |
46 | authentication should be suitable. | |
1a0d3568 | 47 | * Separate player programs are no longer required (but may still be used) |
460b9539 | 48 | |
49 | Development dependencies (only developers will need these): | |
1a0d3568 | 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 | |
39068fb4 | 53 | Bazaar (bzr) |
460b9539 | 54 | |
e9194ec6 | 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 \ | |
1a0d3568 | 58 | libao-dev libmad0-dev libasound2-dev libdb4.3-dev \ |
59 | libflac-dev | |
e9194ec6 | 60 | |
460b9539 | 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 | ||
5f5fc693 RK |
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 | ||
460b9539 | 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 | ||
655cae67 RK |
94 | See README.client for setting up a standalone client (or read the |
95 | disobedience man page). | |
96 | ||
460b9539 | 97 | 2. Install it. Most of the installation is done via the install target: |
98 | ||
99 | make installdirs install | |
100 | ||
813070ec RK |
101 | The CGI interface has to be installed separately; see under 'Web Interface' |
102 | below. | |
460b9539 | 103 | |
460b9539 | 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 | |
be2d9f37 | 114 | to your own requirements. The things you MUST do are: |
460b9539 | 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). | |
be2d9f37 RK |
119 | Optionally you may also want to do the following: |
120 | * add 'player' commands for any file formats not supported natively | |
460b9539 | 121 | * edit the 'scratch' commands to supply scratch sounds (or delete them if |
122 | you don't want any). | |
460b9539 | 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 | ||
da6f7693 RK |
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. | |
6e2c9f5f | 133 | |
36be7e6a | 134 | 5. Make sure the server is started at boot time. |
e83d0967 RK |
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 | ||
36be7e6a | 140 | 6. Start the server. |
e83d0967 RK |
141 | |
142 | On Linux systems with sysv-style init: | |
460b9539 | 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 | ||
5f5fc693 RK |
151 | 7. After a minute it should start to play something. Try scratching it (as |
152 | root): | |
460b9539 | 153 | |
154 | disorder scratch | |
155 | ||
156 | The track should stop playing, and (if you set any up) a scratch sound play. | |
157 | ||
5f5fc693 RK |
158 | 8. Add any other users you want. These easiest way to do this is (still as |
159 | root): | |
460b9539 | 160 | |
8ae47ac8 | 161 | disorder authorize USERNAME |
460b9539 | 162 | |
f0feb22e RK |
163 | This will automatically choose a random password and create |
164 | /etc/disorder/config.USERNAME. | |
460b9539 | 165 | |
9025afab RK |
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 | ||
36be7e6a RK |
171 | 9. Optionally source completion.bash from /etc/profile or similar, for |
172 | example: | |
460b9539 | 173 | |
36be7e6a | 174 | . /usr/local/share/disorder/completion.bash |
460b9539 | 175 | |
36be7e6a | 176 | This provides completion over disorder command and option names. |
460b9539 | 177 | |
178 | ||
179 | Web Interface | |
180 | ============= | |
181 | ||
182 | "Thought I was a gonner baby, but I'm bullet proof" | |
183 | ||
184 | These instructions assumes you are using Apache 1.3.x. | |
185 | ||
186 | You need to configure a number of things to make this work: | |
187 | ||
be2d9f37 RK |
188 | 1. If you want to have a 'jukebox' virtual host, modify the DNS accordingly and |
189 | use a fragment such as this one: | |
460b9539 | 190 | |
191 | <VirtualHost HOSTNAME> | |
192 | DocumentRoot /home/jukebox/public_html | |
193 | ServerName jukebox.DOMAIN | |
194 | ServerAlias jukebox | |
195 | ServerAdmin webmaster@DOMAIN | |
196 | ErrorLog /var/log/apache/jukebox/error.log | |
197 | TransferLog /var/log/apache/jukebox/access.log | |
198 | Alias /static/ /usr/local/share/disorder/static/ | |
199 | </VirtualHost> | |
200 | ||
201 | /static/ should point to the 'static' directory installed by DisOrder. If | |
202 | you don't want to use the name 'static' then you can change the url.static | |
203 | label in the web interface configuration to your preferred URL; see | |
204 | disorder_config(5) for details. | |
205 | ||
206 | Don't forget to reload Apache after modifying its configuration. | |
207 | ||
208 | Separate logging is not required but I find it convenient. Up to you. | |
209 | ||
210 | 2. disorder.cgi assumes it is subject to access control (and in particular uses | |
211 | the username to report who did what). Here's how I configured Apache, given | |
212 | the above VirtualHost settings: | |
213 | ||
214 | <Directory /home/jukebox> | |
215 | Require valid-user | |
216 | AuthType basic | |
217 | AuthName jukebox | |
218 | AuthUserFile /home/jukebox/http.users | |
219 | </Directory> | |
220 | ||
221 | Adjust this according to wherever you're going to install disorder.cgi and | |
222 | its expected URL. | |
223 | ||
224 | Don't forget to reload apache after modifying its configuration. If you got | |
225 | it wrong, fix it and restart Apache. | |
226 | ||
227 | 3. Create the password file configured above. Something like this: | |
228 | ||
229 | # htpasswd -b -c /home/jukebox/http.users myusername mypassword | |
230 | Adding password for user myusername | |
231 | # htpasswd -b /home/jukebox/http.users othername otherpass | |
232 | Adding password for user othername | |
233 | ||
813070ec RK |
234 | 4. The jukebox must be configured to trust the web user. The example |
235 | configuration assumes that this is www-data, but it might be something else | |
236 | on your system. Edit the 'trust' line if necessary. | |
460b9539 | 237 | |
238 | 5. Install disorder.cgi in an appropriate location. Remember to make it | |
813070ec RK |
239 | executable. For example: |
240 | ||
241 | install -m 755 clients/disorder.cgi ~jukebox/public_html/index.cgi | |
460b9539 | 242 | |
be2d9f37 RK |
243 | 6. The config file must also allow the web interface to be any user, and it |
244 | must list the URL of the web interface explicitly: | |
245 | ||
246 | trust www-data | |
247 | url http://jukebox.DOMAIN/ | |
248 | ||
249 | 7. Give www-data (or whatever user it is) a password and edit | |
460b9539 | 250 | /etc/disorder/config.private accordingly. This file should be mode 640 and |
251 | owned by root:jukebox. The line should look something like this: | |
252 | ||
253 | allow www-data MYPASSWORD | |
254 | ||
255 | After editing the config file, you must make the daemon re-read it: | |
256 | ||
257 | disorder reconfigure | |
258 | ||
be2d9f37 | 259 | 8. Teach www-data its password, by putting it in /etc/disorder/config.www-data. |
460b9539 | 260 | This file should be mode 640 and owned by root:www-data. |
261 | ||
262 | password MYPASSWORD | |
263 | ||
264 | (You could also use ~www-data/.disorder/passwd for this but on some systems | |
265 | the web server user's home directory is inside the document root, which | |
be2d9f37 | 266 | would have rather unfortunate consequences!) |
460b9539 | 267 | |
be2d9f37 | 268 | 9. Try it out. You should be asked for a username and password that you |
460b9539 | 269 | configured earlier, and be shown details of what is playing and what other |
270 | tracks have been configured for future play. | |
271 | ||
be2d9f37 RK |
272 | 10. If you run into problems, always look at the appropriate error log; the |
273 | message you see in your web browser will usually not be sufficient to | |
274 | diagnose the problem all by itself. | |
460b9539 | 275 | |
be2d9f37 | 276 | 11. If you have a huge number of top level directories, then you might find |
460b9539 | 277 | that the 'Choose' page is unreasonably large. If so add the following line |
278 | to /etc/disorder/options.user: | |
279 | label sidebar.choosewhich choosealpha | |
280 | ||
281 | This will make 'Choose' be a link for each letter of the 26-letter Roman | |
282 | alphabet; follow the link and you just get the directories which start with | |
283 | that letter. The "*" link at the end gives you directories which don't | |
284 | start with a letter. | |
285 | ||
286 | You can copy choosealpha.html to /etc/disorder and edit it to change the | |
287 | set of initial choices to anything that can be expressed with regexps. The | |
288 | regexps must be URL-encoded UTF-8 PCRE regexps. | |
289 | ||
290 | ||
291 | Copyright | |
292 | ========= | |
293 | ||
294 | "Nothing but another drug, a licence that you buy and sell" | |
295 | ||
296 | DisOrder - select and play digital audio files | |
eb525fcd | 297 | Copyright (C) 2003-2007 Richard Kettlewell |
313acc77 RK |
298 | Portions copyright (C) 2007 Ross Younger |
299 | Portions copyright (C) 2007 Mark Wooding | |
460b9539 | 300 | Portions extracted from MPG321, http://mpg321.sourceforge.net/ |
301 | Copyright (C) 2001 Joe Drew | |
302 | Copyright (C) 2000-2001 Robert Leslie | |
303 | Binaries may derive extra copyright owners through linkage (binary distributors | |
304 | are expected to do their own legwork) | |
305 | ||
306 | This program is free software; you can redistribute it and/or modify it under | |
307 | the terms of the GNU General Public License as published by the Free Software | |
308 | Foundation; either version 2 of the License, or (at your option) any later | |
309 | version. | |
310 | ||
311 | This program is distributed in the hope that it will be useful, but WITHOUT ANY | |
312 | WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A | |
313 | PARTICULAR PURPOSE. See the GNU General Public License for more details. | |
314 | ||
315 | You should have received a copy of the GNU General Public License along with | |
316 | this program; if not, write to the Free Software Foundation, Inc., 59 Temple | |
317 | Place, Suite 330, Boston, MA 02111-1307 USA | |
318 | ||
319 | Local Variables: | |
320 | mode:text | |
321 | fill-column:79 | |
322 | End: |