Commit | Line | Data |
---|---|---|
460b9539 | 1 | .\" |
8f9616f1 | 2 | .\" Copyright (C) 2004-2008 Richard Kettlewell |
460b9539 | 3 | .\" |
4 | .\" This program is free software; you can redistribute it and/or modify | |
5 | .\" it under the terms of the GNU General Public License as published by | |
6 | .\" the Free Software Foundation; either version 2 of the License, or | |
7 | .\" (at your option) any later version. | |
8 | .\" | |
9 | .\" This program is distributed in the hope that it will be useful, but | |
10 | .\" WITHOUT ANY WARRANTY; without even the implied warranty of | |
11 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
12 | .\" General Public License for more details. | |
13 | .\" | |
14 | .\" You should have received a copy of the GNU General Public License | |
15 | .\" along with this program; if not, write to the Free Software | |
16 | .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 | |
17 | .\" USA | |
18 | .\" | |
19 | .TH disorder_config 5 | |
20 | .SH NAME | |
21 | pkgconfdir/config - DisOrder jukebox configuration | |
22 | .SH DESCRIPTION | |
23 | The purpose of DisOrder is to organize and play digital audio files, under the | |
c0c23a60 RK |
24 | control of multiple users. |
25 | \fIpkgconfdir/config\fR is the primary configuration file but this | |
26 | man page currently documents all of its various configuration files. | |
460b9539 | 27 | .SS Tracks |
28 | DisOrder can be configured with multiple collections of tracks, indexing them | |
29 | by their filename, and picking players on the basis of filename patterns (for | |
30 | instance, "*.mp3"). | |
31 | .PP | |
32 | Although the model is of filenames, it is not inherent that there are | |
33 | corresponding real files - merely that they can be interpreted by the chosen | |
c0c23a60 RK |
34 | player. |
35 | See \fBdisorder\fR(3) for more details about this. | |
460b9539 | 36 | .PP |
c0c23a60 RK |
37 | Each track can have a set of preferences associated with it. |
38 | These are simple key-value pairs; they can be used for anything you | |
39 | like, but a number of keys have specific meanings. | |
40 | See \fBdisorder\fR(1) for more details about these. | |
460b9539 | 41 | .SS "Track Names" |
42 | Track names are derived from filenames under the control of regular | |
43 | expressions, rather than attempting to interpret format-specific embedded name | |
c0c23a60 RK |
44 | information. |
45 | They can be overridden by setting preferences. | |
460b9539 | 46 | .PP |
47 | Names for display are distinguished from names for sorting, so with the right | |
48 | underlying filenames an album can be displayed in its original order even if | |
49 | the displayed track titles are not lexically sorted. | |
50 | .SS "Server State" | |
51 | A collection of global preferences define various bits of server state: whether | |
52 | random play is enabled, what tags to check for when picking at random, etc. | |
53 | .SS "Users And Access Control" | |
c0c23a60 RK |
54 | DisOrder distinguishes between multiple users. |
55 | This is for access control and reporting, not to provide different | |
56 | views of the world: i.e. preferences and so on are global. | |
460b9539 | 57 | .PP |
eb5dc014 | 58 | Each user has an associated set of rights which contorl which commands they may |
c0c23a60 RK |
59 | execute. |
60 | Normally you would give all users most rights, and expect them to | |
eb5dc014 RK |
61 | cooperate (they are after all presumed to be in a shared sound environment). |
62 | .PP | |
63 | The full set of rights are: | |
64 | .TP | |
65 | .B read | |
66 | User can perform read-only operations | |
67 | .TP | |
68 | .B play | |
69 | User can add tracks to the queue | |
70 | .TP | |
71 | .B "move any" | |
72 | User can move any track | |
73 | .TP | |
74 | .B "move mine" | |
75 | User can move their own tracks | |
76 | .TP | |
77 | .B "move random" | |
78 | User can move randomly chosen tracks | |
79 | .TP | |
80 | .B "remove any" | |
81 | User can remove any track | |
82 | .TP | |
83 | .B "remove mine" | |
84 | User can remove their own tracks | |
85 | .TP | |
86 | .B "remove random" | |
87 | User can remove randomly chosen tracks | |
88 | .TP | |
89 | .B "scratch any" | |
90 | User can scratch any track | |
91 | .TP | |
92 | .B "scratch mine" | |
93 | User can scratch their own tracks | |
94 | .TP | |
95 | .B "scratch random" | |
96 | User can scratch randomly chosen tracks | |
97 | .TP | |
98 | .B volume | |
99 | User can change the volume | |
100 | .TP | |
101 | .B admin | |
102 | User can perform admin operations | |
103 | .TP | |
104 | .B rescan | |
105 | User can initiate a rescan | |
106 | .TP | |
107 | .B register | |
c0c23a60 RK |
108 | User can register new users. |
109 | Normally only the | |
eb5dc014 RK |
110 | .B guest |
111 | user would have this right. | |
112 | .TP | |
113 | .B userinfo | |
114 | User can edit their own userinfo | |
115 | .TP | |
116 | .B prefs | |
117 | User can modify track preferences | |
118 | .TP | |
119 | .B "global prefs" | |
120 | User can modify global preferences | |
121 | .TP | |
122 | .B pause | |
123 | User can pause/resume | |
460b9539 | 124 | .PP |
c0c23a60 RK |
125 | Access control is entirely used-based. |
126 | If you configure DisOrder to listen for TCP/IP connections then it will | |
127 | accept a connection from anywhere provided the right password is | |
128 | available. | |
129 | Passwords are never transmitted over TCP/IP connections in clear, | |
130 | but everything else is. | |
131 | The expected model is that host-based access control is imposed at | |
132 | the network layer. | |
460b9539 | 133 | .SS "Web Interface" |
134 | The web interface is controlled by a collection of template files, one for each | |
c0c23a60 RK |
135 | kind of page, and a collection of option files. |
136 | These are split up and separate from the main configuration file to | |
137 | make it more convenient to override specific bits. | |
460b9539 | 138 | .PP |
139 | The web interface connects to the DisOrder server like any other user, though | |
c0c23a60 RK |
140 | it is given a special privilege to "become" any other user. |
141 | (Thus, any process with the same UID as the web interface is very | |
142 | powerful as far as DisOrder goes. | |
143 | This model will be changed in a future version.) | |
460b9539 | 144 | .PP |
145 | Access control to the web interface is (currently) separate from DisOrder's own | |
146 | access control (HTTP authentication is required) but uses the same user | |
147 | namespace. | |
5c1ae3bc RK |
148 | .PP |
149 | See \fBdisorder.cgi\fR(8) for more information. | |
180dcdb0 | 150 | .SS "Searching And Tags" |
c0c23a60 RK |
151 | Search strings contain a list of search terms separated by spaces. |
152 | A search term can either be a single word or a tag, prefixed with "tag:". | |
180dcdb0 RK |
153 | .PP |
154 | Search words are compared without regard to letter case or accents; thus, all | |
155 | of the following will be considered to be equal to one another: | |
156 | .PP | |
157 | .nf | |
158 | LATIN CAPITAL LETTER E | |
159 | LATIN SMALL LETTER E | |
160 | LATIN CAPITAL LETTER E WITH GRAVE | |
161 | LATIN SMALL LETTER E WITH GRAVE | |
162 | LATIN CAPITAL LETTER E plus COMBINING GRAVE ACCENT | |
163 | LATIN SMALL LETTER E plus COMBINING GRAVE ACCENT | |
164 | .fi | |
165 | .PP | |
166 | The same rules apply to tags but in addition leading and trailing whitespace is | |
167 | disregarded and all whitespace sequences are treated as equal when they appear | |
168 | as internal whitespace. | |
169 | .PP | |
170 | Where several tags are listed, for instance the tags preference for a track, | |
c0c23a60 RK |
171 | the tags are separated by commas. |
172 | Therefore tags may not contain commas. | |
460b9539 | 173 | .SH "CONFIGURATION FILE" |
174 | .SS "General Syntax" | |
175 | Lines are split into fields separated by whitespace (space, tab, line | |
c0c23a60 RK |
176 | feed, carriage return, form feed). |
177 | Comments are started by the number sign ("#"). | |
460b9539 | 178 | .PP |
179 | Fields may be unquoted (in which case they may not contain spaces and | |
180 | may not start with a quotation mark or apostrophe) or quoted by either | |
c0c23a60 RK |
181 | quotation marks or apostrophes. |
182 | Inside quoted fields every character stands for itself, except that | |
183 | a backslash can only appear as part of one of the following escape sequences: | |
460b9539 | 184 | .TP |
185 | .B \e\e | |
186 | Backslash | |
187 | .TP | |
188 | .B \e" | |
189 | Quotation mark | |
190 | .\" " | |
191 | .TP | |
192 | .B \e' | |
193 | Apostrophe | |
194 | .TP | |
195 | .B \en | |
196 | Line feed | |
197 | .PP | |
198 | No other escape sequences are allowed. | |
199 | .PP | |
200 | Within any line the first field is a configuration command and any | |
c0c23a60 RK |
201 | further fields are parameters. |
202 | Lines with no fields are ignored. | |
460b9539 | 203 | .PP |
204 | After editing the config file use \fBdisorder reconfigure\fR to make | |
c0c23a60 RK |
205 | it re-read it. |
206 | If there is anything wrong with it the daemon will record a log | |
207 | message and ignore the new config file. | |
208 | (You should fix it before next terminating and restarting the daemon, | |
209 | as it cannot start up without a valid config file.) | |
eb5dc014 RK |
210 | .SS "Configuration Files" |
211 | Configuration files are read in the following order: | |
212 | .TP | |
213 | .I pkgconfdir/config | |
214 | .TP | |
215 | .I pkgconfdir/config.private | |
c0c23a60 RK |
216 | Should be readable only by the jukebox group. |
217 | Not really useful any more and will be abolished in future. | |
eb5dc014 | 218 | .TP |
90ad6c6e | 219 | .I ~\fRUSERNAME\fI/.disorder/passwd |
c0c23a60 RK |
220 | Per-user client configuration. |
221 | Optional but if it exists must be readable only by the relevant user. | |
222 | Would normally contain a \fBpassword\fR directive. | |
5b14453f | 223 | .TP |
90ad6c6e | 224 | .I pkgconfdir/config.\fRUSERNAME |
c0c23a60 RK |
225 | Per-user system-controlled client configuration. |
226 | Optional but if it exists must be readable only by the relevant user. | |
227 | Would normally contain a \fBpassword\fR directive. | |
5b14453f RK |
228 | .IP |
229 | The prefererred location for per-user passwords is \fI~/.disorder/passwd\fR and | |
c0c23a60 | 230 | \fBdisorder authorize\fR writes there now. |
460b9539 | 231 | .SS "Global Configuration" |
232 | .TP | |
233 | .B home \fIDIRECTORY\fR | |
c0c23a60 RK |
234 | The home directory for state files. |
235 | Defaults to | |
460b9539 | 236 | .IR pkgstatedir . |
659d87e8 | 237 | The server will create this directory on startup if it does not exist. |
460b9539 | 238 | .TP |
0c6bcae0 | 239 | .B plugins \fIPATH\fR |
c0c23a60 RK |
240 | Adds a directory to the plugin path. |
241 | (This is also used by the web interface.) | |
460b9539 | 242 | .IP |
243 | Plugins are opened the first time they are required and never after, | |
244 | so after changing a plugin you must restart the server before it is | |
245 | guaranteed to take effect. | |
40c30921 RK |
246 | .IP |
247 | If | |
248 | .B plugins | |
249 | is used without arguments the plugin path is cleared. | |
460b9539 | 250 | .SS "Server Configuration" |
251 | .TP | |
252 | .B alias \fIPATTERN\fR | |
253 | Defines the pattern use construct virtual filenames from \fBtrackname_\fR | |
254 | preferences. | |
255 | .IP | |
256 | Most characters stand for themselves, the exception being \fB{\fR which is used | |
257 | to insert a track name part in the form \fB{\fIname\fB}\fR or | |
258 | \fB{/\fIname\fB}\fR. | |
259 | .IP | |
260 | The difference is that the first form just inserts the name part while the | |
261 | second prefixes it with a \fB/\fR if it is nonempty. | |
262 | .IP | |
263 | The pattern should not attempt to include the collection root, which is | |
264 | automatically included, but should include the proper extension. | |
265 | .IP | |
266 | The default is \fB{/artist}{/album}{/title}{ext}\fR. | |
267 | .TP | |
bd8895a8 | 268 | .B api \fINAME\fR |
c0c23a60 RK |
269 | Selects the backend used to play sound and to set the volume. |
270 | The following options are available: | |
bd8895a8 | 271 | .RS |
272 | .TP | |
273 | .B alsa | |
c0c23a60 RK |
274 | Use the ALSA API. |
275 | This is only available on Linux systems, on which it is the default. | |
bd8895a8 | 276 | .TP |
277 | .B coreaudio | |
c0c23a60 RK |
278 | Use Apple Core Audio. |
279 | This only available on OS X systems, on which it is the default. | |
bd8895a8 | 280 | .TP |
281 | .B oss | |
c0c23a60 RK |
282 | Use the OSS (/dev/dsp) API. |
283 | Not available on all platforms. | |
bd8895a8 | 284 | .TP |
285 | .B command | |
c0c23a60 RK |
286 | Execute a command. |
287 | This is the default if | |
bd8895a8 | 288 | .B speaker_command |
289 | is specified, or if no native is available. | |
290 | .TP | |
291 | .B network | |
c0c23a60 RK |
292 | Transmit audio over the network. |
293 | This is the default if \fBbroadcast\fR is specified. | |
294 | You can use | |
bd8895a8 | 295 | .BR disorder-playrtp (1) |
296 | to receive and play the resulting stream on Linux and OS X. | |
297 | .RE | |
298 | .TP | |
25ca855b | 299 | .B authorization_algorithm \fIALGORITHM\fR |
c0c23a60 RK |
300 | Defines the algorithm used to authenticate clients. |
301 | The valid options are sha1 (the default), sha256, sha384 and sha512. | |
302 | See | |
637fdea3 RK |
303 | .BR disorder_protocol (5) |
304 | for more details. | |
305 | .TP | |
30ad4dab | 306 | .B broadcast \fIADDRESS\fR \fIPORT\fR |
c0c23a60 RK |
307 | Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR. |
308 | This implies \fBapi network\fR. | |
61941295 RK |
309 | .IP |
310 | See also \fBmulticast_loop\fR and \fBmulticast_ttl\fR. | |
30ad4dab | 311 | .TP |
312 | .B broadcast_from \fIADDRESS\fR \fIPORT\fR | |
313 | Sets the (local) source address used by \fBbroadcast\fR. | |
314 | .TP | |
460b9539 | 315 | .B channel \fICHANNEL\fR |
bd8895a8 | 316 | The mixer channel that the volume control should use. |
317 | .IP | |
318 | For \fBapi oss\fR the possible values are: | |
460b9539 | 319 | .RS |
320 | .TP 8 | |
321 | .B pcm | |
c0c23a60 RK |
322 | Output level for the audio device. |
323 | This is probably what you want and is the default. | |
460b9539 | 324 | .TP |
325 | .B speaker | |
326 | Output level for the PC speaker, if that is connected to the sound card. | |
327 | .TP | |
328 | .B pcm2 | |
329 | Output level for alternative codec device. | |
330 | .TP | |
331 | .B vol | |
c0c23a60 RK |
332 | Master output level. |
333 | The OSS documentation recommends against using this, as it affects all | |
334 | output devices. | |
460b9539 | 335 | .RE |
336 | .IP | |
bd8895a8 | 337 | You can also specify channels by number, if you know the right value. |
338 | .IP | |
c0c23a60 RK |
339 | For \fBapi alsa\fR, this is the name of the mixer control to use. |
340 | The default is \fBPCM\fR. | |
341 | Use \fBamixer scontrols\fR or similar to get a full list. | |
bd8895a8 | 342 | .IP |
343 | For \fBapi coreaudio\fR, volume setting is not currently supported. | |
460b9539 | 344 | .TP |
345 | .B collection \fIMODULE\fR \fIENCODING\fR \fIROOT\fR | |
01cef138 RK |
346 | .TP |
347 | .B collection \fIMODULE\fR \fIROOT\fR | |
348 | .TP | |
349 | .B collection \fIROOT\fR | |
460b9539 | 350 | Define a collection of tracks. |
351 | .IP | |
352 | \fIMODULE\fR defines which plugin module should be used for this | |
c0c23a60 RK |
353 | collection. |
354 | Use the supplied \fBfs\fR module for tracks that exist as ordinary | |
355 | files in the filesystem. | |
356 | If no \fIMODULE\fR is specified then \fBfs\fR is assumed. | |
357 | .IP | |
358 | \fIENCODING\fR defines the encoding of filenames in this collection. | |
359 | For \fBfs\fR this would be the encoding you use for filenames. | |
0d350ff0 | 360 | Examples might be \fBiso\-8859\-1\fR or \fButf\-8\fR. |
c0c23a60 RK |
361 | If no encoding is specified then the current locale's character encoding |
362 | is used. | |
460b9539 | 363 | .IP |
01cef138 RK |
364 | NB that this default depends on the locale the server runs in, which is not |
365 | necessarily the same as that of ordinary users, depending how the system is | |
c0c23a60 RK |
366 | configured. |
367 | It's best to explicitly specify it to be certain. | |
460b9539 | 368 | .IP |
369 | \fIROOT\fR is the root in the filesystem of the filenames and is | |
c0c23a60 RK |
370 | passed to the plugin module. |
371 | It must be an absolute path and should not end with a "/". | |
460b9539 | 372 | .TP |
dafbdc04 RK |
373 | .B cookie_key_lifetime \fISECONDS\fR |
374 | Lifetime of the signing key used in constructing cookies. The default is one | |
375 | week. | |
376 | .TP | |
377 | .B cookie_login_lifetime \fISECONDS\fR | |
378 | Lifetime of a cookie enforced by the server. When the cookie expires the user | |
379 | will have to log in again even if their browser has remembered the cookie that | |
380 | long. The default is one day. | |
381 | .TP | |
04e1fa7c | 382 | .B default_rights \fIRIGHTS\fR |
c0c23a60 RK |
383 | Defines the set of rights given to new users. |
384 | The argument is a comma-separated list of rights. | |
385 | For the possible values see | |
04e1fa7c RK |
386 | .B "Users And Access Control" |
387 | above. | |
388 | .IP | |
389 | The default is to allow everything except \fBadmin\fR and \fBregister\fR | |
390 | (modified in legacy configurations by the obsolete \fBrestrict\fR directive). | |
391 | .TP | |
460b9539 | 392 | .B device \fINAME\fR |
bd8895a8 | 393 | Sound output device. |
394 | .IP | |
c0c23a60 RK |
395 | For \fBapi oss\fR this is the path to the device to use. |
396 | If it is set to \fBdefault\fR then \fI/dev/dsp\fR and \fI/dev/audio\fR | |
397 | will be tried. | |
bd8895a8 | 398 | .IP |
399 | For \fBapi alsa\fR this is the device name to use. | |
400 | .IP | |
401 | For \fBapi coreaudio\fR this is currently ignored. | |
402 | .IP | |
b25aac59 | 403 | The default is \fBdefault\fR, which is intended to map to whatever the system's |
404 | default is. | |
460b9539 | 405 | .TP |
406 | .B gap \fISECONDS\fR | |
c0c23a60 RK |
407 | Specifies the number of seconds to leave between tracks. |
408 | The default is 0. | |
49a773eb RK |
409 | .IP |
410 | NB this option currently DOES NOT WORK. If there is genuine demand it might be | |
411 | reinstated. | |
460b9539 | 412 | .TP |
413 | .B history \fIINTEGER\fR | |
414 | Specifies the number of recently played tracks to remember (including | |
415 | failed tracks and scratches). | |
416 | .TP | |
417 | .B listen \fR[\fIHOST\fR] \fISERVICE\fR | |
418 | Listen for connections on the address specified by \fIHOST\fR and port | |
c0c23a60 RK |
419 | specified by \fISERVICE\fR. |
420 | If \fIHOST\fR is omitted then listens on all local addresses. | |
460b9539 | 421 | .IP |
422 | Normally the server only listens on a UNIX domain socket. | |
423 | .TP | |
424 | .B lock yes\fR|\fBno | |
c0c23a60 RK |
425 | Determines whether the server locks against concurrent operation. |
426 | Default is \fByes\fR. | |
427 | There is no good reason to set this to \fBno\fR and the option will | |
25ca855b | 428 | probably be removed in a future version. |
460b9539 | 429 | .TP |
bd8895a8 | 430 | .B mixer \fIDEVICE\fR |
431 | The mixer device name, if it needs to be specified separately from | |
432 | \fBdevice\fR. | |
433 | .IP | |
434 | For \fBapi oss\fR this should be the path to the mixer device and the default | |
435 | is \fI/dev/mixer\fR. | |
436 | .IP | |
c0c23a60 RK |
437 | For \fBapi alsa\fR, this is the index of the mixer control to use. |
438 | The default is 0. | |
bd8895a8 | 439 | .IP |
440 | For \fBapi coreaudio\fR, volume setting is not currently supported. | |
460b9539 | 441 | .TP |
61941295 | 442 | .B multicast_loop yes\fR|\fBno |
c0c23a60 RK |
443 | Determines whether multicast packets are loop backed to the sending host. |
444 | The default is \fByes\fR. | |
445 | This only applies if \fBapi\fR is set to \fBnetwork\fR and \fBbroadcast\fR | |
446 | is actually a multicast address. | |
61941295 | 447 | .TP |
23205f9c | 448 | .B multicast_ttl \fIHOPS\fR |
c0c23a60 RK |
449 | Set the maximum number of hops to send multicast packets. |
450 | This only applies if \fBapi\fR is set to \fBnetwork\fR and | |
451 | \fBbroadcast\fR is actually a multicast address. | |
452 | The default is 1. | |
23205f9c | 453 | .TP |
460b9539 | 454 | .B namepart \fIPART\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]] |
455 | Determines how to extract trackname part \fIPART\fR from a | |
456 | track name (with the collection root part removed). | |
457 | Used in \fB@recent@\fR, \fB@playing@\fR and \fB@search@\fR. | |
458 | .IP | |
c0c23a60 RK |
459 | Track names can be different in different contexts. |
460 | For instance the sort string might include an initial track number, | |
461 | but this would be stripped for the display string. | |
462 | \fICONTEXT\fR should be a glob pattern matching the | |
460b9539 | 463 | contexts in which this directive will be used. |
464 | .IP | |
465 | Valid contexts are \fBsort\fR and \fBdisplay\fR. | |
466 | .IP | |
c0c23a60 RK |
467 | All the \fBnamepart\fR directives are considered in order. |
468 | The first directive for the right part, that matches the desired context, | |
460b9539 | 469 | and with a \fIREGEXP\fR that |
470 | matches the track is used, and the value chosen is constructed from | |
471 | \fISUBST\fR according to the substitution rules below. | |
472 | .IP | |
473 | Note that searches use the raw track name and \fBtrackname_\fR preferences but | |
474 | not (currently) the results of \fBnamepart\fR, so generating words via this option | |
475 | that aren't in the original track name will lead to confusing results. | |
476 | .IP | |
477 | If you supply no \fBnamepart\fR directives at all then a default set will be | |
c0c23a60 RK |
478 | supplied automatically. |
479 | But if you supply even one then you must supply all of them. | |
480 | The defaults are equivalent to: | |
25ca855b RK |
481 | .PP |
482 | .nf | |
483 | namepart title "/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display | |
484 | namepart title "/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort | |
485 | namepart album "/([^/]+)/[^/]+$" $1 * | |
486 | namepart artist "/([^/]+)/[^/]+/[^/]+$" $1 * | |
487 | namepart ext "(\\.[a-zA-Z0-9]+)$" $1 * | |
488 | .fi | |
460b9539 | 489 | .TP |
05dcfac6 RK |
490 | .B new_bias \fIWEIGHT\fR |
491 | The weight for new tracks. | |
492 | The default is 900000, i.e. recently added tracks are a hundred times as likely | |
493 | to be picked as normal. | |
494 | .TP | |
495 | .B new_bias_age \fISECONDS\fR | |
496 | The maximum age of tracks that \fBnew_bias\fR applies to, in seconds. | |
497 | The default is one week. | |
498 | .TP | |
d742bb47 | 499 | .B new_max \fIMAX\fR |
c0c23a60 RK |
500 | The maximum number of tracks to list when reporting newly noticed tracks. |
501 | The default is 100. | |
d742bb47 | 502 | .TP |
460b9539 | 503 | .B nice_rescan \fIPRIORITY\fR |
c0c23a60 RK |
504 | Set the recan subprocess priority. |
505 | The default is 10. | |
460b9539 | 506 | .IP |
507 | (Note that higher values mean the process gets less CPU time; UNIX priority | |
04e42396 | 508 | values are backwards.) |
460b9539 | 509 | .TP |
510 | .B nice_server \fIPRIORITY\fR | |
c0c23a60 RK |
511 | Set the server priority. |
512 | This is applied to the server at startup time (and not when you reload | |
513 | configuration). | |
514 | The server does not use much CPU itself but this value is inherited | |
515 | by programs it executes. | |
516 | If you have limited CPU then it might help to set this to a small | |
517 | negative value. | |
518 | The default is 0. | |
460b9539 | 519 | .TP |
520 | .B nice_speaker \fIPRIORITY\fR | |
c0c23a60 RK |
521 | Set the speaker process priority. |
522 | This is applied to the speaker process at startup time (and not when | |
523 | you reload the configuration). | |
524 | The speaker process is not massively CPU intensive by today's | |
525 | standards but depends on reasonably timely scheduling. | |
526 | If you have limited CPU then it might help to set this to a small | |
527 | negative value. | |
528 | The default is 0. | |
460b9539 | 529 | .TP |
2a10b70b RK |
530 | .B noticed_history |
531 | The maximum days that a track can survive in the database of newly added | |
c0c23a60 RK |
532 | tracks. |
533 | The default is 31. | |
2a10b70b | 534 | .TP |
0d350ff0 | 535 | .B player \fIPATTERN\fR \fIMODULE\fR [\fIOPTIONS.. [\fB\-\-\fR]] \fIARGS\fR... |
c0c23a60 RK |
536 | Specifies the player for files matching the glob \fIPATTERN\fR. |
537 | \fIMODULE\fR specifies which plugin module to use. | |
460b9539 | 538 | .IP |
539 | The following options are supported: | |
540 | .RS | |
541 | .TP | |
0d350ff0 | 542 | .B \-\-wait\-for\-device\fR[\fB=\fIDEVICE\fR] |
460b9539 | 543 | Waits (for up to a couple of seconds) for the default, or specified, libao |
544 | device to become openable. | |
545 | .TP | |
0d350ff0 | 546 | .B \-\- |
c0c23a60 | 547 | Defines the end of the list of options. |
0d350ff0 | 548 | Needed if the first argument to the plugin starts with a "\-". |
460b9539 | 549 | .RE |
550 | .IP | |
551 | The following are the standard modules: | |
552 | .RS | |
553 | .TP | |
554 | .B exec \fICOMMAND\fR \fIARGS\fR... | |
555 | The command is executed via \fBexecvp\fR(3), not via the shell. | |
556 | The \fBPATH\fR environment variable is searched for the executable if it is not | |
557 | an absolute path. | |
558 | The command is expected to know how to open its own sound device. | |
559 | .TP | |
560 | .B execraw \fICOMMAND\fR \fIARGS\fR... | |
561 | Identical to the \fBexec\fR except that the player is expected to use the | |
ce6c36be | 562 | DisOrder raw player protocol. |
563 | .BR disorder-decode (8) | |
c0c23a60 RK |
564 | can decode several common audio file formats to this format. |
565 | If your favourite format is not supported, but you have a player | |
566 | which uses libao, there is also a libao driver which supports this format; | |
567 | see below for more information about this. | |
460b9539 | 568 | .TP |
569 | .B shell \fR[\fISHELL\fR] \fICOMMAND\fR | |
c0c23a60 RK |
570 | The command is executed using the shell. |
571 | If \fISHELL\fR is specified then that is used, otherwise \fBsh\fR will be used. | |
572 | In either case the \fBPATH\fR environment variable is searched for the shell | |
573 | executable if it is not an absolute path. | |
574 | The track name is stored in the environment variable | |
460b9539 | 575 | \fBTRACK\fR. |
576 | .IP | |
577 | Be careful of the interaction between the configuration file quoting rules and | |
578 | the shell quoting rules. | |
579 | .RE | |
580 | .IP | |
581 | If multiple player commands match a track then the first match is used. | |
62dc3748 RK |
582 | .IP |
583 | For the server to be able to calculate track lengths, there should be a | |
584 | .B tracklength | |
585 | command corresponding to each | |
586 | .B player | |
587 | command. | |
40c30921 RK |
588 | .IP |
589 | If | |
590 | .B player | |
591 | is used without arguments, the list of players is cleared. | |
460b9539 | 592 | .TP |
593 | .B prefsync \fISECONDS\fR | |
c0c23a60 RK |
594 | The interval at which the preferences log file will be synchronised. |
595 | Defaults to 3600, i.e. one hour. | |
460b9539 | 596 | .TP |
459d4402 | 597 | .B queue_pad \fICOUNT\fR |
c0c23a60 RK |
598 | The target size of the queue. |
599 | If random play is enabled then randomly picked tracks will be added until | |
600 | the queue is at least this big. | |
601 | The default is 10. | |
459d4402 | 602 | .TP |
6207d2f3 | 603 | .B reminder_interval \fISECONDS\fR |
c0c23a60 RK |
604 | The minimum number of seconds that must elapse between password reminders. |
605 | The default is 600, i.e. 10 minutes. | |
6207d2f3 | 606 | .TP |
810b8083 RK |
607 | .B remote_userman yes\fR|\fBno |
608 | User management over TCP connection is only allowed if this is set to | |
609 | \fByes\fR. By default it is set to \fBno\fR. | |
610 | .TP | |
cebe3127 RK |
611 | .B replay_min \fISECONDS\fR |
612 | The minimum number of seconds that must elapse after a track has been played | |
613 | before it can be picked at random. The default is 8 hours. If this is set to | |
614 | 0 then there is no limit, though current \fBdisorder-choose\fR will not pick | |
615 | anything currently listed in the recently-played list. | |
616 | .TP | |
405fea4e | 617 | .B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS |
c0c23a60 RK |
618 | Describes the sample format expected by the \fBspeaker_command\fR (below). |
619 | The components of the format specification are as follows: | |
405fea4e | 620 | .RS |
621 | .TP 10 | |
622 | .I BITS | |
c0c23a60 RK |
623 | The number of bits per sample. |
624 | Optionally, may be suffixed by \fBb\fR or \fBl\fR for big-endian and | |
625 | little-endian words. | |
626 | If neither is used the native byte order is assumed. | |
405fea4e | 627 | .TP |
628 | .I RATE | |
629 | The number of samples per second. | |
630 | .TP | |
631 | .I CHANNELS | |
632 | The number of channels. | |
633 | .PP | |
634 | The default is | |
635 | .BR 16/44100/2 . | |
937be4c0 RK |
636 | .PP |
637 | With the | |
638 | .B network | |
639 | backend the sample format is forced to | |
e99d42b1 | 640 | .B 16b/44100/2 |
937be4c0 RK |
641 | and with the |
642 | .B coreaudio | |
643 | backend it is forced to | |
644 | .BR 16/44100/2 , | |
645 | in both cases regardless of what is specified in the configuration file. | |
405fea4e | 646 | .RE |
647 | .TP | |
460b9539 | 648 | .B signal \fINAME\fR |
649 | Defines the signal to be sent to track player process groups when tracks are | |
c0c23a60 RK |
650 | scratched. |
651 | The default is \fBSIGKILL\fR. | |
460b9539 | 652 | .IP |
653 | Signals are specified by their full C name, i.e. \fBSIGINT\fR and not \fBINT\fR | |
654 | or \fBInterrupted\fR or whatever. | |
655 | .TP | |
5330d674 | 656 | .B sox_generation \fB0\fR|\fB1 |
0d350ff0 RK |
657 | Determines whether calls to \fBsox\fR(1) should use \fB\-b\fR, \fB\-x\fR, etc (if |
658 | the generation is 0) or \fB\-\fIbits\fR, \fB\-L\fR etc (if it is 1). | |
c0c23a60 RK |
659 | See the documentation for your installed copy of \fBsox\fR to determine |
660 | which you need. | |
25ca855b | 661 | The default is 0. |
5330d674 | 662 | .TP |
bd8895a8 | 663 | .B speaker_backend \fINAME |
664 | This is an alias for \fBapi\fR; see above. | |
665 | .TP | |
405fea4e | 666 | .B speaker_command \fICOMMAND |
667 | Causes the speaker subprocess to pipe audio data into shell command | |
c0c23a60 RK |
668 | \fICOMMAND\fR, rather than writing to a local sound card. |
669 | The sample format is determine by | |
405fea4e | 670 | .B sample_format |
671 | above. | |
77cfc7a2 | 672 | .IP |
673 | Note that if the sample format is wrong then | |
674 | .BR sox (1) | |
c0c23a60 RK |
675 | is invoked to translate it. |
676 | If | |
77cfc7a2 | 677 | .B sox |
678 | is not installed then this will not work. | |
405fea4e | 679 | .TP |
460b9539 | 680 | .B scratch \fIPATH\fR |
c0c23a60 RK |
681 | Specifies a scratch. |
682 | When a track is scratched, a scratch track is played at random. | |
460b9539 | 683 | Scratches are played using the same logic as other tracks. |
684 | .IP | |
685 | At least for the time being, path names of scratches must be encoded using | |
686 | UTF-8 (which means that ASCII will do). | |
40c30921 RK |
687 | .IP |
688 | If \fBscratch\fR is used without arguments then the list of scratches is | |
689 | cleared. | |
460b9539 | 690 | .TP |
691 | .B stopword \fIWORD\fR ... | |
692 | Specifies one or more stopwords that should not take part in searches | |
693 | over track names. | |
40c30921 RK |
694 | .IP |
695 | If \fBstopword\fR is used without arguments then the list of stopwords is | |
696 | cleared. | |
86be0c30 | 697 | .IP |
698 | There is a default set of stopwords built in, but this option can be used to | |
699 | augment or replace that list. | |
62dc3748 RK |
700 | .TP |
701 | .B tracklength \fIPATTERN\fR \fIMODULE\fR | |
702 | Specifies the module used to calculate the length of files matching | |
c0c23a60 RK |
703 | \fIPATTERN\fR. |
704 | \fIMODULE\fR specifies which plugin module to use. | |
40c30921 RK |
705 | .IP |
706 | If \fBtracklength\fR is used without arguments then the list of modules is | |
707 | cleared. | |
eb5dc014 | 708 | .TP |
90ad6c6e | 709 | .B user \fIUSERNAME\fR |
c0c23a60 RK |
710 | Specifies the user to run as. |
711 | Only makes sense if invoked as root (or the target user). | |
460b9539 | 712 | .SS "Client Configuration" |
713 | .TP | |
ccf0aafa | 714 | .B connect \fIHOST SERVICE\fR |
460b9539 | 715 | Connect to the address specified by \fIHOST\fR and port specified by |
ccf0aafa | 716 | \fISERVICE\fR. |
460b9539 | 717 | .SS "Web Interface Configuration" |
718 | .TP | |
e70701e7 | 719 | .B mail_sender \fIADDRESS\fR |
720 | The email address that appears in the From: field of any mail messages sent by | |
c0c23a60 RK |
721 | the web interface. |
722 | This must be set if you have online registration enabled. | |
e70701e7 | 723 | .TP |
460b9539 | 724 | .B refresh \fISECONDS\fR |
c0c23a60 RK |
725 | Specifies the maximum refresh period in seconds. |
726 | Default 15. | |
460b9539 | 727 | .TP |
61507e3c RK |
728 | .B short_display \fICHARACTERS\fR |
729 | Defines the maximum number of characters to include in a \fBshort\fR name | |
c0c23a60 RK |
730 | part. |
731 | Default 30. | |
61507e3c | 732 | .TP |
e70701e7 | 733 | .B smtp_server \fIHOSTNAME\fR |
c0c23a60 RK |
734 | The hostname (or address) of the SMTP server to use for sending mail. |
735 | The default is 127.0.0.1. | |
e70701e7 | 736 | .TP |
460b9539 | 737 | .B templates \fIPATH\fR ... |
738 | Specifies the directory containing templates used by the web | |
c0c23a60 RK |
739 | interface. |
740 | If a template appears in more than one template directory | |
460b9539 | 741 | then the one in the earliest directory specified is chosen. |
742 | .IP | |
743 | See below for further details. | |
40c30921 RK |
744 | .IP |
745 | If \fBtemplates\fR is used without arguments then the template path is cleared. | |
460b9539 | 746 | .TP |
747 | .B transform \fITYPE\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]] | |
748 | Determines how names are sorted and displayed in track choice displays. | |
749 | .IP | |
750 | \fITYPE\fR is the type of transformation; usually \fBtrack\fR or | |
751 | \fBdir\fR but you can define your own. | |
752 | .IP | |
c0c23a60 RK |
753 | \fICONTEXT\fR is a glob pattern matching the context. |
754 | Standard contexts are \fBsort\fR (which determines how directory names | |
755 | are sorted) and \fBdisplay\fR (which determines how they are displayed). | |
756 | Again, you can define your own. | |
460b9539 | 757 | .IP |
c0c23a60 RK |
758 | All the \fBtransform\fR directives are considered in order. |
759 | If the \fITYPE\fR, \fIREGEXP\fR and the \fICONTEXT\fR match | |
460b9539 | 760 | then a new track name is constructed from |
c0c23a60 RK |
761 | \fISUBST\fR according to the substitution rules below. |
762 | If several match then each is executed in order. | |
460b9539 | 763 | .IP |
764 | If you supply no \fBtransform\fR directives at all then a default set will be | |
c0c23a60 RK |
765 | supplied automatically. |
766 | But if you supply even one then you must supply all of them. | |
767 | The defaults are: | |
25ca855b RK |
768 | .PP |
769 | .nf | |
770 | transform track "^.*/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display | |
771 | transform track "^.*/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort | |
772 | transform dir "^.*/([^/]+)$" $1 * | |
773 | transform dir "^(the) ([^/]*)" "$2 $1" sort i | |
774 | transform dir "[[:punct:]]" "" sort g | |
775 | .fi | |
460b9539 | 776 | .TP |
777 | .B url \fIURL\fR | |
c0c23a60 RK |
778 | Specifies the URL of the web interface. |
779 | This URL will be used in generated web pages. | |
780 | The default is inferred at runtime, so this option no | |
b64c2805 | 781 | longer needs to be specified. |
460b9539 | 782 | .IP |
783 | This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not | |
784 | \fB/cgi-bin/jukebox\fR. | |
785 | .SS "Authentication Configuration" | |
90ad6c6e RK |
786 | These options would normally be used in \fI~\fRUSERNAME\fI/.disorder/passwd\fR |
787 | or | |
788 | \fIpkgconfdir/config.\fRUSERNAME. | |
460b9539 | 789 | .TP |
460b9539 | 790 | .B password \fIPASSWORD\fR |
791 | Specify password. | |
792 | .TP | |
460b9539 | 793 | .B username \fIUSERNAME\fR |
c0c23a60 RK |
794 | Specify username. |
795 | The default is taken from the environment variable \fBLOGNAME\fR. | |
460b9539 | 796 | .SH "GLOBAL PREFERENCES" |
0d350ff0 | 797 | These are the values set with \fBset\-global\fR. |
460b9539 | 798 | .TP |
0d350ff0 | 799 | .B required\-tags |
460b9539 | 800 | If this is set an nonempty then randomly played tracks will always have at |
801 | least one of the listed tags. | |
460b9539 | 802 | .TP |
0d350ff0 | 803 | .B prohibited\-tags |
460b9539 | 804 | If this is set an nonempty then randomly played tracks will never have any of |
805 | the listed tags. | |
806 | .TP | |
807 | .B playing | |
c0c23a60 RK |
808 | If unset or \fByes\fR then play is enabled. |
809 | Otherwise it is disabled. | |
810 | Use \fBdisable\fR rather than setting it directly. | |
460b9539 | 811 | .TP |
0d350ff0 | 812 | .B random\-play |
c0c23a60 RK |
813 | If unset or \fByes\fR then random play is enabled. |
814 | Otherwise it is disabled. | |
460b9539 | 815 | Use \fBdisable\fR rather than setting it directly. |
f9635e06 RK |
816 | .PP |
817 | Global preferences starting '_' are read-only (in the sense that you cannot | |
c0c23a60 RK |
818 | modify them; the server may modify them as part of its normal operation). |
819 | They are: | |
f9635e06 RK |
820 | .TP |
821 | .B _dbversion | |
c0c23a60 RK |
822 | The database version string. |
823 | This is used by DisOrder to detect when it must | |
f9635e06 | 824 | modify the database after an upgrade. |
460b9539 | 825 | .SH "LIBAO DRIVER" |
826 | .SS "Raw Protocol Players" | |
827 | Raw protocol players are expected to use the \fBdisorder\fR libao driver. | |
828 | Programs that use libao generally have command line options to select the | |
829 | driver and pass options to it. | |
830 | .SS "Driver Options" | |
831 | The known driver options are: | |
832 | .TP | |
833 | .B fd | |
c0c23a60 RK |
834 | The file descriptor to write to. |
835 | If this is not specified then the driver looks like the environment | |
836 | variable \fBDISORDER_RAW_FD\fR. | |
837 | If that is not set then the default is 1 (i.e. standard output). | |
460b9539 | 838 | .TP |
839 | .B fragile | |
840 | If this is set to a nonzero value then the driver will call \fB_exit\fR(2) if a | |
c0c23a60 RK |
841 | write to the output file descriptor fails. |
842 | This is a workaround for buggy players such as \fBogg123\fR that ignore | |
843 | write errors. | |
3e1616b6 RK |
844 | .SH "REGEXP SUBSTITUTION RULES" |
845 | Regexps are PCRE regexps, as defined in \fBpcrepattern\fR(3). | |
846 | The only option used is \fBPCRE_UTF8\fR. | |
847 | Remember that the configuration file syntax means you have to | |
848 | escape backslashes and quotes inside quoted strings. | |
849 | .PP | |
850 | In a \fISUBST\fR string the following sequences are interpreted | |
851 | specially: | |
852 | .TP | |
853 | .B $1 \fR... \fB$9 | |
854 | These expand to the first to ninth bracketed subexpression. | |
855 | .TP | |
856 | .B $& | |
857 | This expands to the matched part of the subject string. | |
858 | .TP | |
859 | .B $$ | |
860 | This expands to a single \fB$\fR symbol. | |
861 | .PP | |
862 | All other pairs starting with \fB$\fR are undefined (and might be used | |
863 | for something else in the future, so don't rely on the current | |
864 | behaviour.) | |
865 | .PP | |
866 | If \fBi\fR is present in \fIREFLAGS\fR then the match is case-independent. | |
867 | If \fBg\fR is present then all matches are replaced, otherwise only the first | |
868 | match is replaced. | |
460b9539 | 869 | .SH "TRACK NAME PARTS" |
870 | The traditional track name parts are \fBartist\fR, \fBalbum\fR and \fBtitle\fR, | |
c0c23a60 RK |
871 | with the obvious intended meaning. |
872 | These are controlled by configuration and by \fBtrackname_\fR preferences. | |
460b9539 | 873 | .PP |
874 | In addition there are two built-in parts, \fBpath\fR which is the whole path | |
875 | name and \fBext\fR which is the filename extension, including the initial dot | |
876 | (or the empty string if there is not extension). | |
877 | .SH "SEE ALSO" | |
0d350ff0 | 878 | \fBdisorder\fR(1), \fBsox\fR(1), \fBdisorderd\fR(8), \fBdisorder\-dump\fR(8), |
5c1ae3bc RK |
879 | \fBpcrepattern\fR(3), \fBdisorder_templates\fR(5), \fBdisorder_actions\fR(5), |
880 | \fBdisorder.cgi\fR(8) | |
460b9539 | 881 | .\" Local Variables: |
882 | .\" mode:nroff | |
883 | .\" fill-column:79 | |
884 | .\" End: |