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