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