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 | |
2ea2b361 RK |
16 | See CHANGES.html for details of recent changes to DisOrder and |
17 | README.upgrades.html for upgrade instructions. | |
460b9539 | 18 | |
7a4c02b0 RK |
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. | |
460b9539 | 25 | |
26 | Build dependencies: | |
23d0e963 | 27 | Name Tested Notes |
06f35ddc | 28 | libdb 4.5.20 not 4.6; 4.[78] seem to be ok |
1a0d3568 | 29 | libgc 6.8 |
06f35ddc RK |
30 | libvorbisfile 1.2.0 |
31 | libpcre 7.6 need UTF-8 support | |
460b9539 | 32 | libmad 0.15.1b |
06f35ddc | 33 | libgcrypt 1.4.1 |
06f35ddc RK |
34 | libasound 1.0.16 |
35 | libFLAC 1.2.1 | |
81410abb | 36 | libsamplerate 0.1.4 currently optional but strongly recommended |
c076146f | 37 | GStreamer 1.10.4 or 0.10.36 currently optional |
06f35ddc | 38 | GNU C 4.2.1 } |
23d0e963 RK |
39 | GNU Make 3.81 } Non-GNU versions will NOT work |
40 | GNU Sed 4.1.5 } | |
41 | Python 2.5.2 (optional; 2.4 won't work) | |
93c8c20f RK |
42 | GTK+ 2.12.12 (for the GTK+ client; 2.10 & older will NOT work) |
43 | GLIB 2.16.6 (for the GTK+ client) | |
460b9539 | 44 | |
45 | "Tested" means I've built against that version; earlier or later versions will | |
46 | often work too. | |
47 | ||
81410abb MW |
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 | ||
91d9a42d | 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. | |
e9194ec6 | 60 | |
802cbf55 | 61 | Bug tracker, etc: |
847e2b27 | 62 | https://github.com/ewxrjk/disorder |
802cbf55 | 63 | |
460b9539 | 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 | ||
91d9a42d | 70 | Developers should read README.developers. |
71 | ||
460b9539 | 72 | |
7a4c02b0 RK |
73 | Installation |
74 | ============ | |
460b9539 | 75 | |
76 | "This place'd be a paradise tomorrow, if every department had a supervisor | |
77 | with a machine-gun" | |
78 | ||
2ea2b361 RK |
79 | IMPORTANT: If you are upgrading from an earlier version, see |
80 | README.upgrades.html. | |
460b9539 | 81 | |
7a4c02b0 RK |
82 | Debian/Ubuntu: steps 1 to 6 are dealt with automatically if you use the .deb |
83 | files. | |
84 | ||
f3e157f7 RK |
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. | |
7a4c02b0 | 88 | |
460b9539 | 89 | 1. Build the software. Do something like this: |
90 | ||
7a4c02b0 RK |
91 | ./configure |
92 | make # on FreeBSD use gmake | |
460b9539 | 93 | |
7a4c02b0 | 94 | See INSTALL or ./configure --help for more details about driving configure. |
460b9539 | 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 | ||
64ac73bb RK |
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: | |
4cbafe13 | 104 | |
f03d4184 | 105 | ./configure cgiexecdir=/whatever/cgi-bin httpdir=/whatever/htdocs |
4cbafe13 | 106 | |
655cae67 RK |
107 | See README.client for setting up a standalone client (or read the |
108 | disobedience man page). | |
109 | ||
7a4c02b0 RK |
110 | To build .debs on Debian/Ubuntu, use: |
111 | fakeroot debian/rules binary | |
112 | ||
460b9539 | 113 | 2. Install it. Most of the installation is done via the install target: |
114 | ||
115 | make installdirs install | |
116 | ||
7a4c02b0 RK |
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 | ||
460b9539 | 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 | |
be2d9f37 | 130 | to your own requirements. The things you MUST do are: |
460b9539 | 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). | |
be2d9f37 | 135 | Optionally you may also want to do the following: |
e6a35d1c RK |
136 | * add 'player' and 'tracklength' commands for any file formats not |
137 | supported natively | |
460b9539 | 138 | * edit the 'scratch' commands to supply scratch sounds (or delete them if |
139 | you don't want any). | |
e6a35d1c RK |
140 | * add extra 'stopword' entries as necessary (these words won't take part in |
141 | track name searches from the web interface). | |
460b9539 | 142 | |
143 | See disorder_config(5) for more details. | |
144 | ||
da6f7693 RK |
145 | See README.streams for how to set up network play. |
146 | ||
bf38ab1a | 147 | If adding new 'player' commands, see disorder(3) for details on setting up |
da6f7693 | 148 | "raw format" players. Non-raw players are still supported but not in all |
662886f6 | 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. | |
6e2c9f5f | 152 | |
36be7e6a | 153 | 5. Make sure the server is started at boot time. |
e83d0967 RK |
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 | ||
36be7e6a | 159 | 6. Start the server. |
e83d0967 RK |
160 | |
161 | On Linux systems with sysv-style init: | |
460b9539 | 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 | ||
01f400ed RK |
170 | 7. After a short while it should start to play something. Try scratching it |
171 | (as root): | |
460b9539 | 172 | |
173 | disorder scratch | |
174 | ||
175 | The track should stop playing, and (if you set any up) a scratch sound play. | |
176 | ||
5f5fc693 RK |
177 | 8. Add any other users you want. These easiest way to do this is (still as |
178 | root): | |
460b9539 | 179 | |
8ae47ac8 | 180 | disorder authorize USERNAME |
460b9539 | 181 | |
f0feb22e | 182 | This will automatically choose a random password and create |
5b14453f | 183 | ~USERNAME/.disorder/passwd. |
460b9539 | 184 | |
9025afab RK |
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 | ||
7a4c02b0 RK |
190 | Alternatively, after setting up the web interface (below), it's possible to |
191 | allow users to register themselves without operator involvement. | |
192 | ||
36be7e6a RK |
193 | 9. Optionally source completion.bash from /etc/profile or similar, for |
194 | example: | |
460b9539 | 195 | |
36be7e6a | 196 | . /usr/local/share/disorder/completion.bash |
460b9539 | 197 | |
36be7e6a | 198 | This provides completion over disorder command and option names. |
460b9539 | 199 | |
200 | ||
201 | Web Interface | |
202 | ============= | |
203 | ||
204 | "Thought I was a gonner baby, but I'm bullet proof" | |
205 | ||
7a4c02b0 RK |
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. | |
460b9539 | 210 | |
211 | You need to configure a number of things to make this work: | |
212 | ||
662886f6 | 213 | 1. If you want online registration to work then set mail_sender in |
e70701e7 | 214 | /etc/disorder/config to the email address that communications from the web |
563071c2 | 215 | interface will appear to be sent. If this is not a valid, deliverable email |
662886f6 | 216 | address then the results are not likely to be reliable. |
e70701e7 | 217 | |
218 | mail_sender webmaster@example.com | |
219 | ||
2eee4b0c RK |
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: | |
e70701e7 | 229 | |
230 | smtp_server mail.example.com | |
231 | ||
ad884aa5 | 232 | Use 'disorder reconfigure' to make sure the server knows these settings. |
233 | ||
e70701e7 | 234 | 2. The web interface depends on a 'guest' user existing. You can create this |
5e34540b | 235 | with the following command: |
236 | ||
237 | disorder setup-guest | |
238 | ||
239 | If you don't want to allow online registration instead use: | |
240 | ||
a767291c | 241 | disorder setup-guest --no-online-registration |
5e34540b | 242 | |
d576d190 RK |
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. | |
460b9539 | 250 | |
64ac73bb | 251 | 4. If you run into problems, always look at the appropriate error log; the |
5e34540b | 252 | message you see in your web browser will usually not be sufficient to |
253 | diagnose the problem all by itself. | |
460b9539 | 254 | |
64ac73bb | 255 | 5. If you have a huge number of top level directories, then you might find |
5e34540b | 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. | |
460b9539 | 268 | |
a767291c | 269 | If you want to give DisOrder its own virtual host, see README.vhost. |
460b9539 | 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 | |
3697ed99 | 277 | Copyright (C) 2003-2013 Richard Kettlewell |
313acc77 | 278 | Portions copyright (C) 2007 Ross Younger |
0e5e68c3 | 279 | Portions copyright (C) 2007, 2013, 2015-2016 Mark Wooding |
460b9539 | 280 | Portions extracted from MPG321, http://mpg321.sourceforge.net/ |
281 | Copyright (C) 2001 Joe Drew | |
282 | Copyright (C) 2000-2001 Robert Leslie | |
d436bd52 | 283 | Portions Copyright (C) 1997-2006 Free Software Foundation, Inc. |
56293dc8 | 284 | Portions Copyright (C) 2000 Red Hat, Inc., Jonathan Blandford <jrb@redhat.com> |
460b9539 | 285 | Binaries may derive extra copyright owners through linkage (binary distributors |
286 | are expected to do their own legwork) | |
287 | ||
e7eb3a27 RK |
288 | This program is free software: you can redistribute it and/or modify |
289 | it under the terms of the GNU General Public License as published by | |
290 | the Free Software Foundation, either version 3 of the License, or | |
291 | (at your option) any later version. | |
292 | ||
293 | This program is distributed in the hope that it will be useful, | |
294 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
295 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
296 | GNU General Public License for more details. | |
297 | ||
298 | You should have received a copy of the GNU General Public License | |
299 | along with this program. If not, see <http://www.gnu.org/licenses/>. | |
460b9539 | 300 | |
301 | Local Variables: | |
302 | mode:text | |
303 | fill-column:79 | |
304 | End: |