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