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. | |
180dcdb0 | 148 | .SS "Searching And Tags" |
c0c23a60 RK |
149 | Search strings contain a list of search terms separated by spaces. |
150 | A search term can either be a single word or a tag, prefixed with "tag:". | |
180dcdb0 RK |
151 | .PP |
152 | Search words are compared without regard to letter case or accents; thus, all | |
153 | of the following will be considered to be equal to one another: | |
154 | .PP | |
155 | .nf | |
156 | LATIN CAPITAL LETTER E | |
157 | LATIN SMALL LETTER E | |
158 | LATIN CAPITAL LETTER E WITH GRAVE | |
159 | LATIN SMALL LETTER E WITH GRAVE | |
160 | LATIN CAPITAL LETTER E plus COMBINING GRAVE ACCENT | |
161 | LATIN SMALL LETTER E plus COMBINING GRAVE ACCENT | |
162 | .fi | |
163 | .PP | |
164 | The same rules apply to tags but in addition leading and trailing whitespace is | |
165 | disregarded and all whitespace sequences are treated as equal when they appear | |
166 | as internal whitespace. | |
167 | .PP | |
168 | Where several tags are listed, for instance the tags preference for a track, | |
c0c23a60 RK |
169 | the tags are separated by commas. |
170 | Therefore tags may not contain commas. | |
460b9539 | 171 | .SH "CONFIGURATION FILE" |
172 | .SS "General Syntax" | |
173 | Lines are split into fields separated by whitespace (space, tab, line | |
c0c23a60 RK |
174 | feed, carriage return, form feed). |
175 | Comments are started by the number sign ("#"). | |
460b9539 | 176 | .PP |
177 | Fields may be unquoted (in which case they may not contain spaces and | |
178 | may not start with a quotation mark or apostrophe) or quoted by either | |
c0c23a60 RK |
179 | quotation marks or apostrophes. |
180 | Inside quoted fields every character stands for itself, except that | |
181 | a backslash can only appear as part of one of the following escape sequences: | |
460b9539 | 182 | .TP |
183 | .B \e\e | |
184 | Backslash | |
185 | .TP | |
186 | .B \e" | |
187 | Quotation mark | |
188 | .\" " | |
189 | .TP | |
190 | .B \e' | |
191 | Apostrophe | |
192 | .TP | |
193 | .B \en | |
194 | Line feed | |
195 | .PP | |
196 | No other escape sequences are allowed. | |
197 | .PP | |
198 | Within any line the first field is a configuration command and any | |
c0c23a60 RK |
199 | further fields are parameters. |
200 | Lines with no fields are ignored. | |
460b9539 | 201 | .PP |
202 | After editing the config file use \fBdisorder reconfigure\fR to make | |
c0c23a60 RK |
203 | it re-read it. |
204 | If there is anything wrong with it the daemon will record a log | |
205 | message and ignore the new config file. | |
206 | (You should fix it before next terminating and restarting the daemon, | |
207 | as it cannot start up without a valid config file.) | |
eb5dc014 RK |
208 | .SS "Configuration Files" |
209 | Configuration files are read in the following order: | |
210 | .TP | |
211 | .I pkgconfdir/config | |
212 | .TP | |
213 | .I pkgconfdir/config.private | |
c0c23a60 RK |
214 | Should be readable only by the jukebox group. |
215 | Not really useful any more and will be abolished in future. | |
eb5dc014 | 216 | .TP |
90ad6c6e | 217 | .I ~\fRUSERNAME\fI/.disorder/passwd |
c0c23a60 RK |
218 | Per-user client configuration. |
219 | Optional but if it exists must be readable only by the relevant user. | |
220 | Would normally contain a \fBpassword\fR directive. | |
5b14453f | 221 | .TP |
90ad6c6e | 222 | .I pkgconfdir/config.\fRUSERNAME |
c0c23a60 RK |
223 | Per-user system-controlled client configuration. |
224 | Optional but if it exists must be readable only by the relevant user. | |
225 | Would normally contain a \fBpassword\fR directive. | |
5b14453f RK |
226 | .IP |
227 | The prefererred location for per-user passwords is \fI~/.disorder/passwd\fR and | |
c0c23a60 | 228 | \fBdisorder authorize\fR writes there now. |
460b9539 | 229 | .SS "Global Configuration" |
230 | .TP | |
231 | .B home \fIDIRECTORY\fR | |
c0c23a60 RK |
232 | The home directory for state files. |
233 | Defaults to | |
460b9539 | 234 | .IR pkgstatedir . |
659d87e8 | 235 | The server will create this directory on startup if it does not exist. |
460b9539 | 236 | .TP |
0c6bcae0 | 237 | .B plugins \fIPATH\fR |
c0c23a60 RK |
238 | Adds a directory to the plugin path. |
239 | (This is also used by the web interface.) | |
460b9539 | 240 | .IP |
241 | Plugins are opened the first time they are required and never after, | |
242 | so after changing a plugin you must restart the server before it is | |
243 | guaranteed to take effect. | |
40c30921 RK |
244 | .IP |
245 | If | |
246 | .B plugins | |
247 | is used without arguments the plugin path is cleared. | |
460b9539 | 248 | .SS "Server Configuration" |
249 | .TP | |
250 | .B alias \fIPATTERN\fR | |
251 | Defines the pattern use construct virtual filenames from \fBtrackname_\fR | |
252 | preferences. | |
253 | .IP | |
254 | Most characters stand for themselves, the exception being \fB{\fR which is used | |
255 | to insert a track name part in the form \fB{\fIname\fB}\fR or | |
256 | \fB{/\fIname\fB}\fR. | |
257 | .IP | |
258 | The difference is that the first form just inserts the name part while the | |
259 | second prefixes it with a \fB/\fR if it is nonempty. | |
260 | .IP | |
261 | The pattern should not attempt to include the collection root, which is | |
262 | automatically included, but should include the proper extension. | |
263 | .IP | |
264 | The default is \fB{/artist}{/album}{/title}{ext}\fR. | |
265 | .TP | |
bd8895a8 | 266 | .B api \fINAME\fR |
c0c23a60 RK |
267 | Selects the backend used to play sound and to set the volume. |
268 | The following options are available: | |
bd8895a8 | 269 | .RS |
270 | .TP | |
271 | .B alsa | |
c0c23a60 RK |
272 | Use the ALSA API. |
273 | This is only available on Linux systems, on which it is the default. | |
bd8895a8 | 274 | .TP |
275 | .B coreaudio | |
c0c23a60 RK |
276 | Use Apple Core Audio. |
277 | This only available on OS X systems, on which it is the default. | |
bd8895a8 | 278 | .TP |
279 | .B oss | |
c0c23a60 RK |
280 | Use the OSS (/dev/dsp) API. |
281 | Not available on all platforms. | |
bd8895a8 | 282 | .TP |
283 | .B command | |
c0c23a60 RK |
284 | Execute a command. |
285 | This is the default if | |
bd8895a8 | 286 | .B speaker_command |
287 | is specified, or if no native is available. | |
288 | .TP | |
289 | .B network | |
c0c23a60 RK |
290 | Transmit audio over the network. |
291 | This is the default if \fBbroadcast\fR is specified. | |
292 | You can use | |
bd8895a8 | 293 | .BR disorder-playrtp (1) |
294 | to receive and play the resulting stream on Linux and OS X. | |
295 | .RE | |
296 | .TP | |
25ca855b | 297 | .B authorization_algorithm \fIALGORITHM\fR |
c0c23a60 RK |
298 | Defines the algorithm used to authenticate clients. |
299 | The valid options are sha1 (the default), sha256, sha384 and sha512. | |
300 | See | |
637fdea3 RK |
301 | .BR disorder_protocol (5) |
302 | for more details. | |
303 | .TP | |
30ad4dab | 304 | .B broadcast \fIADDRESS\fR \fIPORT\fR |
c0c23a60 RK |
305 | Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR. |
306 | This implies \fBapi network\fR. | |
61941295 RK |
307 | .IP |
308 | See also \fBmulticast_loop\fR and \fBmulticast_ttl\fR. | |
30ad4dab | 309 | .TP |
310 | .B broadcast_from \fIADDRESS\fR \fIPORT\fR | |
311 | Sets the (local) source address used by \fBbroadcast\fR. | |
312 | .TP | |
460b9539 | 313 | .B channel \fICHANNEL\fR |
bd8895a8 | 314 | The mixer channel that the volume control should use. |
315 | .IP | |
316 | For \fBapi oss\fR the possible values are: | |
460b9539 | 317 | .RS |
318 | .TP 8 | |
319 | .B pcm | |
c0c23a60 RK |
320 | Output level for the audio device. |
321 | This is probably what you want and is the default. | |
460b9539 | 322 | .TP |
323 | .B speaker | |
324 | Output level for the PC speaker, if that is connected to the sound card. | |
325 | .TP | |
326 | .B pcm2 | |
327 | Output level for alternative codec device. | |
328 | .TP | |
329 | .B vol | |
c0c23a60 RK |
330 | Master output level. |
331 | The OSS documentation recommends against using this, as it affects all | |
332 | output devices. | |
460b9539 | 333 | .RE |
334 | .IP | |
bd8895a8 | 335 | You can also specify channels by number, if you know the right value. |
336 | .IP | |
c0c23a60 RK |
337 | For \fBapi alsa\fR, this is the name of the mixer control to use. |
338 | The default is \fBPCM\fR. | |
339 | Use \fBamixer scontrols\fR or similar to get a full list. | |
bd8895a8 | 340 | .IP |
341 | For \fBapi coreaudio\fR, volume setting is not currently supported. | |
460b9539 | 342 | .TP |
343 | .B collection \fIMODULE\fR \fIENCODING\fR \fIROOT\fR | |
01cef138 RK |
344 | .TP |
345 | .B collection \fIMODULE\fR \fIROOT\fR | |
346 | .TP | |
347 | .B collection \fIROOT\fR | |
460b9539 | 348 | Define a collection of tracks. |
349 | .IP | |
350 | \fIMODULE\fR defines which plugin module should be used for this | |
c0c23a60 RK |
351 | collection. |
352 | Use the supplied \fBfs\fR module for tracks that exist as ordinary | |
353 | files in the filesystem. | |
354 | If no \fIMODULE\fR is specified then \fBfs\fR is assumed. | |
355 | .IP | |
356 | \fIENCODING\fR defines the encoding of filenames in this collection. | |
357 | For \fBfs\fR this would be the encoding you use for filenames. | |
0d350ff0 | 358 | Examples might be \fBiso\-8859\-1\fR or \fButf\-8\fR. |
c0c23a60 RK |
359 | If no encoding is specified then the current locale's character encoding |
360 | is used. | |
460b9539 | 361 | .IP |
01cef138 RK |
362 | NB that this default depends on the locale the server runs in, which is not |
363 | necessarily the same as that of ordinary users, depending how the system is | |
c0c23a60 RK |
364 | configured. |
365 | It's best to explicitly specify it to be certain. | |
460b9539 | 366 | .IP |
367 | \fIROOT\fR is the root in the filesystem of the filenames and is | |
c0c23a60 RK |
368 | passed to the plugin module. |
369 | It must be an absolute path and should not end with a "/". | |
460b9539 | 370 | .TP |
dafbdc04 RK |
371 | .B cookie_key_lifetime \fISECONDS\fR |
372 | Lifetime of the signing key used in constructing cookies. The default is one | |
373 | week. | |
374 | .TP | |
375 | .B cookie_login_lifetime \fISECONDS\fR | |
376 | Lifetime of a cookie enforced by the server. When the cookie expires the user | |
377 | will have to log in again even if their browser has remembered the cookie that | |
378 | long. The default is one day. | |
379 | .TP | |
04e1fa7c | 380 | .B default_rights \fIRIGHTS\fR |
c0c23a60 RK |
381 | Defines the set of rights given to new users. |
382 | The argument is a comma-separated list of rights. | |
383 | For the possible values see | |
04e1fa7c RK |
384 | .B "Users And Access Control" |
385 | above. | |
386 | .IP | |
387 | The default is to allow everything except \fBadmin\fR and \fBregister\fR | |
388 | (modified in legacy configurations by the obsolete \fBrestrict\fR directive). | |
389 | .TP | |
460b9539 | 390 | .B device \fINAME\fR |
bd8895a8 | 391 | Sound output device. |
392 | .IP | |
c0c23a60 RK |
393 | For \fBapi oss\fR this is the path to the device to use. |
394 | If it is set to \fBdefault\fR then \fI/dev/dsp\fR and \fI/dev/audio\fR | |
395 | will be tried. | |
bd8895a8 | 396 | .IP |
397 | For \fBapi alsa\fR this is the device name to use. | |
398 | .IP | |
399 | For \fBapi coreaudio\fR this is currently ignored. | |
400 | .IP | |
b25aac59 | 401 | The default is \fBdefault\fR, which is intended to map to whatever the system's |
402 | default is. | |
460b9539 | 403 | .TP |
404 | .B gap \fISECONDS\fR | |
c0c23a60 RK |
405 | Specifies the number of seconds to leave between tracks. |
406 | The default is 0. | |
49a773eb RK |
407 | .IP |
408 | NB this option currently DOES NOT WORK. If there is genuine demand it might be | |
409 | reinstated. | |
460b9539 | 410 | .TP |
411 | .B history \fIINTEGER\fR | |
412 | Specifies the number of recently played tracks to remember (including | |
413 | failed tracks and scratches). | |
414 | .TP | |
415 | .B listen \fR[\fIHOST\fR] \fISERVICE\fR | |
416 | Listen for connections on the address specified by \fIHOST\fR and port | |
c0c23a60 RK |
417 | specified by \fISERVICE\fR. |
418 | If \fIHOST\fR is omitted then listens on all local addresses. | |
460b9539 | 419 | .IP |
420 | Normally the server only listens on a UNIX domain socket. | |
421 | .TP | |
422 | .B lock yes\fR|\fBno | |
c0c23a60 RK |
423 | Determines whether the server locks against concurrent operation. |
424 | Default is \fByes\fR. | |
425 | There is no good reason to set this to \fBno\fR and the option will | |
25ca855b | 426 | probably be removed in a future version. |
460b9539 | 427 | .TP |
bd8895a8 | 428 | .B mixer \fIDEVICE\fR |
429 | The mixer device name, if it needs to be specified separately from | |
430 | \fBdevice\fR. | |
431 | .IP | |
432 | For \fBapi oss\fR this should be the path to the mixer device and the default | |
433 | is \fI/dev/mixer\fR. | |
434 | .IP | |
c0c23a60 RK |
435 | For \fBapi alsa\fR, this is the index of the mixer control to use. |
436 | The default is 0. | |
bd8895a8 | 437 | .IP |
438 | For \fBapi coreaudio\fR, volume setting is not currently supported. | |
460b9539 | 439 | .TP |
61941295 | 440 | .B multicast_loop yes\fR|\fBno |
c0c23a60 RK |
441 | Determines whether multicast packets are loop backed to the sending host. |
442 | The default is \fByes\fR. | |
443 | This only applies if \fBapi\fR is set to \fBnetwork\fR and \fBbroadcast\fR | |
444 | is actually a multicast address. | |
61941295 | 445 | .TP |
23205f9c | 446 | .B multicast_ttl \fIHOPS\fR |
c0c23a60 RK |
447 | Set the maximum number of hops to send multicast packets. |
448 | This only applies if \fBapi\fR is set to \fBnetwork\fR and | |
449 | \fBbroadcast\fR is actually a multicast address. | |
450 | The default is 1. | |
23205f9c | 451 | .TP |
460b9539 | 452 | .B namepart \fIPART\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]] |
453 | Determines how to extract trackname part \fIPART\fR from a | |
454 | track name (with the collection root part removed). | |
455 | Used in \fB@recent@\fR, \fB@playing@\fR and \fB@search@\fR. | |
456 | .IP | |
c0c23a60 RK |
457 | Track names can be different in different contexts. |
458 | For instance the sort string might include an initial track number, | |
459 | but this would be stripped for the display string. | |
460 | \fICONTEXT\fR should be a glob pattern matching the | |
460b9539 | 461 | contexts in which this directive will be used. |
462 | .IP | |
463 | Valid contexts are \fBsort\fR and \fBdisplay\fR. | |
464 | .IP | |
c0c23a60 RK |
465 | All the \fBnamepart\fR directives are considered in order. |
466 | The first directive for the right part, that matches the desired context, | |
460b9539 | 467 | and with a \fIREGEXP\fR that |
468 | matches the track is used, and the value chosen is constructed from | |
469 | \fISUBST\fR according to the substitution rules below. | |
470 | .IP | |
471 | Note that searches use the raw track name and \fBtrackname_\fR preferences but | |
472 | not (currently) the results of \fBnamepart\fR, so generating words via this option | |
473 | that aren't in the original track name will lead to confusing results. | |
474 | .IP | |
475 | If you supply no \fBnamepart\fR directives at all then a default set will be | |
c0c23a60 RK |
476 | supplied automatically. |
477 | But if you supply even one then you must supply all of them. | |
478 | The defaults are equivalent to: | |
25ca855b RK |
479 | .PP |
480 | .nf | |
481 | namepart title "/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display | |
482 | namepart title "/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort | |
483 | namepart album "/([^/]+)/[^/]+$" $1 * | |
484 | namepart artist "/([^/]+)/[^/]+/[^/]+$" $1 * | |
485 | namepart ext "(\\.[a-zA-Z0-9]+)$" $1 * | |
486 | .fi | |
460b9539 | 487 | .TP |
d742bb47 | 488 | .B new_max \fIMAX\fR |
c0c23a60 RK |
489 | The maximum number of tracks to list when reporting newly noticed tracks. |
490 | The default is 100. | |
d742bb47 | 491 | .TP |
460b9539 | 492 | .B nice_rescan \fIPRIORITY\fR |
c0c23a60 RK |
493 | Set the recan subprocess priority. |
494 | The default is 10. | |
460b9539 | 495 | .IP |
496 | (Note that higher values mean the process gets less CPU time; UNIX priority | |
04e42396 | 497 | values are backwards.) |
460b9539 | 498 | .TP |
499 | .B nice_server \fIPRIORITY\fR | |
c0c23a60 RK |
500 | Set the server priority. |
501 | This is applied to the server at startup time (and not when you reload | |
502 | configuration). | |
503 | The server does not use much CPU itself but this value is inherited | |
504 | by programs it executes. | |
505 | If you have limited CPU then it might help to set this to a small | |
506 | negative value. | |
507 | The default is 0. | |
460b9539 | 508 | .TP |
509 | .B nice_speaker \fIPRIORITY\fR | |
c0c23a60 RK |
510 | Set the speaker process priority. |
511 | This is applied to the speaker process at startup time (and not when | |
512 | you reload the configuration). | |
513 | The speaker process is not massively CPU intensive by today's | |
514 | standards but depends on reasonably timely scheduling. | |
515 | If you have limited CPU then it might help to set this to a small | |
516 | negative value. | |
517 | The default is 0. | |
460b9539 | 518 | .TP |
2a10b70b RK |
519 | .B noticed_history |
520 | The maximum days that a track can survive in the database of newly added | |
c0c23a60 RK |
521 | tracks. |
522 | The default is 31. | |
2a10b70b | 523 | .TP |
0d350ff0 | 524 | .B player \fIPATTERN\fR \fIMODULE\fR [\fIOPTIONS.. [\fB\-\-\fR]] \fIARGS\fR... |
c0c23a60 RK |
525 | Specifies the player for files matching the glob \fIPATTERN\fR. |
526 | \fIMODULE\fR specifies which plugin module to use. | |
460b9539 | 527 | .IP |
528 | The following options are supported: | |
529 | .RS | |
530 | .TP | |
0d350ff0 | 531 | .B \-\-wait\-for\-device\fR[\fB=\fIDEVICE\fR] |
460b9539 | 532 | Waits (for up to a couple of seconds) for the default, or specified, libao |
533 | device to become openable. | |
534 | .TP | |
0d350ff0 | 535 | .B \-\- |
c0c23a60 | 536 | Defines the end of the list of options. |
0d350ff0 | 537 | Needed if the first argument to the plugin starts with a "\-". |
460b9539 | 538 | .RE |
539 | .IP | |
540 | The following are the standard modules: | |
541 | .RS | |
542 | .TP | |
543 | .B exec \fICOMMAND\fR \fIARGS\fR... | |
544 | The command is executed via \fBexecvp\fR(3), not via the shell. | |
545 | The \fBPATH\fR environment variable is searched for the executable if it is not | |
546 | an absolute path. | |
547 | The command is expected to know how to open its own sound device. | |
548 | .TP | |
549 | .B execraw \fICOMMAND\fR \fIARGS\fR... | |
550 | Identical to the \fBexec\fR except that the player is expected to use the | |
ce6c36be | 551 | DisOrder raw player protocol. |
552 | .BR disorder-decode (8) | |
c0c23a60 RK |
553 | can decode several common audio file formats to this format. |
554 | If your favourite format is not supported, but you have a player | |
555 | which uses libao, there is also a libao driver which supports this format; | |
556 | see below for more information about this. | |
460b9539 | 557 | .TP |
558 | .B shell \fR[\fISHELL\fR] \fICOMMAND\fR | |
c0c23a60 RK |
559 | The command is executed using the shell. |
560 | If \fISHELL\fR is specified then that is used, otherwise \fBsh\fR will be used. | |
561 | In either case the \fBPATH\fR environment variable is searched for the shell | |
562 | executable if it is not an absolute path. | |
563 | The track name is stored in the environment variable | |
460b9539 | 564 | \fBTRACK\fR. |
565 | .IP | |
566 | Be careful of the interaction between the configuration file quoting rules and | |
567 | the shell quoting rules. | |
568 | .RE | |
569 | .IP | |
570 | If multiple player commands match a track then the first match is used. | |
62dc3748 RK |
571 | .IP |
572 | For the server to be able to calculate track lengths, there should be a | |
573 | .B tracklength | |
574 | command corresponding to each | |
575 | .B player | |
576 | command. | |
40c30921 RK |
577 | .IP |
578 | If | |
579 | .B player | |
580 | is used without arguments, the list of players is cleared. | |
460b9539 | 581 | .TP |
582 | .B prefsync \fISECONDS\fR | |
c0c23a60 RK |
583 | The interval at which the preferences log file will be synchronised. |
584 | Defaults to 3600, i.e. one hour. | |
460b9539 | 585 | .TP |
459d4402 | 586 | .B queue_pad \fICOUNT\fR |
c0c23a60 RK |
587 | The target size of the queue. |
588 | If random play is enabled then randomly picked tracks will be added until | |
589 | the queue is at least this big. | |
590 | The default is 10. | |
459d4402 | 591 | .TP |
6207d2f3 | 592 | .B reminder_interval \fISECONDS\fR |
c0c23a60 RK |
593 | The minimum number of seconds that must elapse between password reminders. |
594 | The default is 600, i.e. 10 minutes. | |
6207d2f3 | 595 | .TP |
810b8083 RK |
596 | .B remote_userman yes\fR|\fBno |
597 | User management over TCP connection is only allowed if this is set to | |
598 | \fByes\fR. By default it is set to \fBno\fR. | |
599 | .TP | |
cebe3127 RK |
600 | .B replay_min \fISECONDS\fR |
601 | The minimum number of seconds that must elapse after a track has been played | |
602 | before it can be picked at random. The default is 8 hours. If this is set to | |
603 | 0 then there is no limit, though current \fBdisorder-choose\fR will not pick | |
604 | anything currently listed in the recently-played list. | |
605 | .TP | |
405fea4e | 606 | .B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS |
c0c23a60 RK |
607 | Describes the sample format expected by the \fBspeaker_command\fR (below). |
608 | The components of the format specification are as follows: | |
405fea4e | 609 | .RS |
610 | .TP 10 | |
611 | .I BITS | |
c0c23a60 RK |
612 | The number of bits per sample. |
613 | Optionally, may be suffixed by \fBb\fR or \fBl\fR for big-endian and | |
614 | little-endian words. | |
615 | If neither is used the native byte order is assumed. | |
405fea4e | 616 | .TP |
617 | .I RATE | |
618 | The number of samples per second. | |
619 | .TP | |
620 | .I CHANNELS | |
621 | The number of channels. | |
622 | .PP | |
623 | The default is | |
624 | .BR 16/44100/2 . | |
937be4c0 RK |
625 | .PP |
626 | With the | |
627 | .B network | |
628 | backend the sample format is forced to | |
e99d42b1 | 629 | .B 16b/44100/2 |
937be4c0 RK |
630 | and with the |
631 | .B coreaudio | |
632 | backend it is forced to | |
633 | .BR 16/44100/2 , | |
634 | in both cases regardless of what is specified in the configuration file. | |
405fea4e | 635 | .RE |
636 | .TP | |
460b9539 | 637 | .B signal \fINAME\fR |
638 | Defines the signal to be sent to track player process groups when tracks are | |
c0c23a60 RK |
639 | scratched. |
640 | The default is \fBSIGKILL\fR. | |
460b9539 | 641 | .IP |
642 | Signals are specified by their full C name, i.e. \fBSIGINT\fR and not \fBINT\fR | |
643 | or \fBInterrupted\fR or whatever. | |
644 | .TP | |
5330d674 | 645 | .B sox_generation \fB0\fR|\fB1 |
0d350ff0 RK |
646 | Determines whether calls to \fBsox\fR(1) should use \fB\-b\fR, \fB\-x\fR, etc (if |
647 | the generation is 0) or \fB\-\fIbits\fR, \fB\-L\fR etc (if it is 1). | |
c0c23a60 RK |
648 | See the documentation for your installed copy of \fBsox\fR to determine |
649 | which you need. | |
25ca855b | 650 | The default is 0. |
5330d674 | 651 | .TP |
bd8895a8 | 652 | .B speaker_backend \fINAME |
653 | This is an alias for \fBapi\fR; see above. | |
654 | .TP | |
405fea4e | 655 | .B speaker_command \fICOMMAND |
656 | Causes the speaker subprocess to pipe audio data into shell command | |
c0c23a60 RK |
657 | \fICOMMAND\fR, rather than writing to a local sound card. |
658 | The sample format is determine by | |
405fea4e | 659 | .B sample_format |
660 | above. | |
77cfc7a2 | 661 | .IP |
662 | Note that if the sample format is wrong then | |
663 | .BR sox (1) | |
c0c23a60 RK |
664 | is invoked to translate it. |
665 | If | |
77cfc7a2 | 666 | .B sox |
667 | is not installed then this will not work. | |
405fea4e | 668 | .TP |
460b9539 | 669 | .B scratch \fIPATH\fR |
c0c23a60 RK |
670 | Specifies a scratch. |
671 | When a track is scratched, a scratch track is played at random. | |
460b9539 | 672 | Scratches are played using the same logic as other tracks. |
673 | .IP | |
674 | At least for the time being, path names of scratches must be encoded using | |
675 | UTF-8 (which means that ASCII will do). | |
40c30921 RK |
676 | .IP |
677 | If \fBscratch\fR is used without arguments then the list of scratches is | |
678 | cleared. | |
460b9539 | 679 | .TP |
680 | .B stopword \fIWORD\fR ... | |
681 | Specifies one or more stopwords that should not take part in searches | |
682 | over track names. | |
40c30921 RK |
683 | .IP |
684 | If \fBstopword\fR is used without arguments then the list of stopwords is | |
685 | cleared. | |
86be0c30 | 686 | .IP |
687 | There is a default set of stopwords built in, but this option can be used to | |
688 | augment or replace that list. | |
62dc3748 RK |
689 | .TP |
690 | .B tracklength \fIPATTERN\fR \fIMODULE\fR | |
691 | Specifies the module used to calculate the length of files matching | |
c0c23a60 RK |
692 | \fIPATTERN\fR. |
693 | \fIMODULE\fR specifies which plugin module to use. | |
40c30921 RK |
694 | .IP |
695 | If \fBtracklength\fR is used without arguments then the list of modules is | |
696 | cleared. | |
eb5dc014 | 697 | .TP |
90ad6c6e | 698 | .B user \fIUSERNAME\fR |
c0c23a60 RK |
699 | Specifies the user to run as. |
700 | Only makes sense if invoked as root (or the target user). | |
460b9539 | 701 | .SS "Client Configuration" |
702 | .TP | |
ccf0aafa | 703 | .B connect \fIHOST SERVICE\fR |
460b9539 | 704 | Connect to the address specified by \fIHOST\fR and port specified by |
ccf0aafa | 705 | \fISERVICE\fR. |
460b9539 | 706 | .SS "Web Interface Configuration" |
707 | .TP | |
e70701e7 | 708 | .B mail_sender \fIADDRESS\fR |
709 | The email address that appears in the From: field of any mail messages sent by | |
c0c23a60 RK |
710 | the web interface. |
711 | This must be set if you have online registration enabled. | |
e70701e7 | 712 | .TP |
460b9539 | 713 | .B refresh \fISECONDS\fR |
c0c23a60 RK |
714 | Specifies the maximum refresh period in seconds. |
715 | Default 15. | |
460b9539 | 716 | .TP |
61507e3c RK |
717 | .B short_display \fICHARACTERS\fR |
718 | Defines the maximum number of characters to include in a \fBshort\fR name | |
c0c23a60 RK |
719 | part. |
720 | Default 30. | |
61507e3c | 721 | .TP |
e70701e7 | 722 | .B smtp_server \fIHOSTNAME\fR |
c0c23a60 RK |
723 | The hostname (or address) of the SMTP server to use for sending mail. |
724 | The default is 127.0.0.1. | |
e70701e7 | 725 | .TP |
460b9539 | 726 | .B templates \fIPATH\fR ... |
727 | Specifies the directory containing templates used by the web | |
c0c23a60 RK |
728 | interface. |
729 | If a template appears in more than one template directory | |
460b9539 | 730 | then the one in the earliest directory specified is chosen. |
731 | .IP | |
732 | See below for further details. | |
40c30921 RK |
733 | .IP |
734 | If \fBtemplates\fR is used without arguments then the template path is cleared. | |
460b9539 | 735 | .TP |
736 | .B transform \fITYPE\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]] | |
737 | Determines how names are sorted and displayed in track choice displays. | |
738 | .IP | |
739 | \fITYPE\fR is the type of transformation; usually \fBtrack\fR or | |
740 | \fBdir\fR but you can define your own. | |
741 | .IP | |
c0c23a60 RK |
742 | \fICONTEXT\fR is a glob pattern matching the context. |
743 | Standard contexts are \fBsort\fR (which determines how directory names | |
744 | are sorted) and \fBdisplay\fR (which determines how they are displayed). | |
745 | Again, you can define your own. | |
460b9539 | 746 | .IP |
c0c23a60 RK |
747 | All the \fBtransform\fR directives are considered in order. |
748 | If the \fITYPE\fR, \fIREGEXP\fR and the \fICONTEXT\fR match | |
460b9539 | 749 | then a new track name is constructed from |
c0c23a60 RK |
750 | \fISUBST\fR according to the substitution rules below. |
751 | If several match then each is executed in order. | |
460b9539 | 752 | .IP |
753 | If you supply no \fBtransform\fR directives at all then a default set will be | |
c0c23a60 RK |
754 | supplied automatically. |
755 | But if you supply even one then you must supply all of them. | |
756 | The defaults are: | |
25ca855b RK |
757 | .PP |
758 | .nf | |
759 | transform track "^.*/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display | |
760 | transform track "^.*/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort | |
761 | transform dir "^.*/([^/]+)$" $1 * | |
762 | transform dir "^(the) ([^/]*)" "$2 $1" sort i | |
763 | transform dir "[[:punct:]]" "" sort g | |
764 | .fi | |
460b9539 | 765 | .TP |
766 | .B url \fIURL\fR | |
c0c23a60 RK |
767 | Specifies the URL of the web interface. |
768 | This URL will be used in generated web pages. | |
769 | The default is inferred at runtime, so this option no | |
b64c2805 | 770 | longer needs to be specified. |
460b9539 | 771 | .IP |
772 | This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not | |
773 | \fB/cgi-bin/jukebox\fR. | |
774 | .SS "Authentication Configuration" | |
90ad6c6e RK |
775 | These options would normally be used in \fI~\fRUSERNAME\fI/.disorder/passwd\fR |
776 | or | |
777 | \fIpkgconfdir/config.\fRUSERNAME. | |
460b9539 | 778 | .TP |
460b9539 | 779 | .B password \fIPASSWORD\fR |
780 | Specify password. | |
781 | .TP | |
460b9539 | 782 | .B username \fIUSERNAME\fR |
c0c23a60 RK |
783 | Specify username. |
784 | The default is taken from the environment variable \fBLOGNAME\fR. | |
460b9539 | 785 | .SH "GLOBAL PREFERENCES" |
0d350ff0 | 786 | These are the values set with \fBset\-global\fR. |
460b9539 | 787 | .TP |
0d350ff0 | 788 | .B required\-tags |
460b9539 | 789 | If this is set an nonempty then randomly played tracks will always have at |
790 | least one of the listed tags. | |
460b9539 | 791 | .TP |
0d350ff0 | 792 | .B prohibited\-tags |
460b9539 | 793 | If this is set an nonempty then randomly played tracks will never have any of |
794 | the listed tags. | |
795 | .TP | |
796 | .B playing | |
c0c23a60 RK |
797 | If unset or \fByes\fR then play is enabled. |
798 | Otherwise it is disabled. | |
799 | Use \fBdisable\fR rather than setting it directly. | |
460b9539 | 800 | .TP |
0d350ff0 | 801 | .B random\-play |
c0c23a60 RK |
802 | If unset or \fByes\fR then random play is enabled. |
803 | Otherwise it is disabled. | |
460b9539 | 804 | Use \fBdisable\fR rather than setting it directly. |
f9635e06 RK |
805 | .PP |
806 | Global preferences starting '_' are read-only (in the sense that you cannot | |
c0c23a60 RK |
807 | modify them; the server may modify them as part of its normal operation). |
808 | They are: | |
f9635e06 RK |
809 | .TP |
810 | .B _dbversion | |
c0c23a60 RK |
811 | The database version string. |
812 | This is used by DisOrder to detect when it must | |
f9635e06 | 813 | modify the database after an upgrade. |
460b9539 | 814 | .SH "LIBAO DRIVER" |
815 | .SS "Raw Protocol Players" | |
816 | Raw protocol players are expected to use the \fBdisorder\fR libao driver. | |
817 | Programs that use libao generally have command line options to select the | |
818 | driver and pass options to it. | |
819 | .SS "Driver Options" | |
820 | The known driver options are: | |
821 | .TP | |
822 | .B fd | |
c0c23a60 RK |
823 | The file descriptor to write to. |
824 | If this is not specified then the driver looks like the environment | |
825 | variable \fBDISORDER_RAW_FD\fR. | |
826 | If that is not set then the default is 1 (i.e. standard output). | |
460b9539 | 827 | .TP |
828 | .B fragile | |
829 | If this is set to a nonzero value then the driver will call \fB_exit\fR(2) if a | |
c0c23a60 RK |
830 | write to the output file descriptor fails. |
831 | This is a workaround for buggy players such as \fBogg123\fR that ignore | |
832 | write errors. | |
460b9539 | 833 | .SH "WEB TEMPLATES" |
834 | When \fBdisorder.cgi\fR wants to generate a page for an action it searches the | |
c0c23a60 RK |
835 | directories specified with \fBtemplates\fR for a matching file. |
836 | It is suggested that you leave the distributed templates unchanged and put | |
460b9539 | 837 | any customisations in an earlier entry in the template path. |
838 | .PP | |
839 | The supplied templates are: | |
840 | .TP | |
841 | .B about.html | |
842 | Display information about DisOrder. | |
843 | .TP | |
844 | .B choose.html | |
c0c23a60 RK |
845 | Navigates through the track database to choose a track to play. |
846 | The \fBdir\fR argument gives the directory to look in; if it is missing | |
460b9539 | 847 | then the root directory is used. |
848 | .TP | |
849 | .B choosealpha.html | |
850 | Provides a front end to \fBchoose.html\fR which allows subsets of the top level | |
851 | directories to be selected by initial letter. | |
852 | .TP | |
d5b6ffd7 RK |
853 | .B new.html |
854 | Lists newly added tracks. | |
855 | .TP | |
460b9539 | 856 | .B playing.html |
857 | The "front page", which usually shows the currently playing tracks and | |
858 | the queue. | |
859 | Gets an HTTP \fBRefresh\fR header. | |
860 | .IP | |
861 | If the \fBmgmt\fR CGI argument is set to \fBtrue\fR then we include extra | |
c0c23a60 RK |
862 | buttons for moving tracks up and down in the queue. |
863 | There is some logic in \fBdisorder.cgi\fR to ensure that \fBmgmt=true\fR | |
864 | is preserved across refreshes and redirects back into itself, but | |
865 | URLs embedded in web pages must include it explicitly. | |
460b9539 | 866 | .TP |
867 | .B prefs.html | |
c0c23a60 RK |
868 | Views preferences. |
869 | If the \fBfile\fR, \fBname\fR and \fBvalue\fR arguments are | |
460b9539 | 870 | all set then that preference is modified; if \fBfile\fR and \fBname\fR are set |
871 | but not \fBvalue\fR then the preference is deleted. | |
872 | .TP | |
873 | .B recent.html | |
874 | Lists recently played tracks. | |
875 | .TP | |
876 | .B search.html | |
877 | Presents search results. | |
878 | .TP | |
879 | .B volume.html | |
880 | Primitive volume control. | |
881 | .PP | |
882 | Additionally, other standard files are included by these: | |
883 | .TP | |
884 | .B credits.html | |
885 | Included at the end of the main content \fB<DIV>\fR element. | |
886 | .TP | |
d5b6ffd7 | 887 | .B topbar.html |
e12da4d9 | 888 | Included at the start of the \fB<BODY>\fR element. |
889 | .TP | |
890 | .B topbarend.html | |
891 | Included at the end of the \fB<BODY>\fR element. | |
460b9539 | 892 | .TP |
893 | .B stdhead.html | |
894 | Included in the \fB<HEAD>\fR element. | |
895 | .TP | |
896 | .B stylesheet.html | |
c0c23a60 RK |
897 | Contains the default DisOrder stylesheet. |
898 | You can override this by editing the CSS or by replacing it all with | |
899 | a \fB<LINK>\fR to an external stylesheet. | |
460b9539 | 900 | .PP |
901 | Templates are ASCII files containing HTML documents, with an expansion | |
902 | syntax to enable data supplied by the implementation to be inserted. | |
903 | .PP | |
904 | If you want to use characters outside the ASCII range, use either the | |
905 | appropriate HTML entity, e.g. \fBé\fR, or an SGML numeric | |
c0c23a60 RK |
906 | character reference, e.g. \fBý\fR. |
907 | Use \fB@\fR to insert a literal \fB@\fR without falling foul of | |
908 | the expansion syntax. | |
460b9539 | 909 | .SS "Expansion Syntax" |
910 | Expansions are surrounded by at ("@") symbols take the form of a keyword | |
c0c23a60 RK |
911 | followed by zero or more arguments. |
912 | Arguments may either be quoted by curly brackets ("{" and "}") or separated | |
913 | by colons (":"). | |
914 | Both kinds may be mixed in a single expansion, though doing so seems | |
915 | likely to cause confusion. | |
916 | The descriptions below contain suggested forms for each expansion. | |
460b9539 | 917 | .PP |
918 | Leading and trailing whitespace in unquoted arguments is ignored, as is | |
919 | whitespace (including newlines) following a close bracket ("}"). | |
920 | .PP | |
921 | Arguments are recursively expanded before being interpreted, except for | |
c0c23a60 RK |
922 | \fITEMPLATE\fR arguments. |
923 | These are expanded (possibly more than once) to produce the final expansion. | |
460b9539 | 924 | (More than once means the same argument being expanded more than once |
925 | for different tracks or whatever, not the result of the first | |
926 | expansion itself being re-expanded.) | |
927 | .PP | |
928 | Strings constructed by expansions (i.e. not literally copied from the template | |
929 | text) are SGML-quoted: any character which does not stand for itself in #PCDATA | |
930 | or a quoted attribute value is replaced by the appropriate numeric character | |
931 | reference. | |
932 | .PP | |
933 | The exception to this is that such strings are \fInot\fR quoted when they are | |
934 | generated in the expansion of a parameter. | |
935 | .PP | |
936 | In the descriptions below, the current track means the one set by | |
937 | \fB@playing@\fR, \fB@recent@\fR or \fB@queue@\fR, not the one that is playing. | |
938 | If none of these expansions are in force then there is no current track. | |
939 | \fIBOOL\fR should always be either \fBtrue\fR or \fBfalse\fR. | |
940 | .SS "Expansions" | |
941 | The following expansion keywords are defined: | |
942 | .TP | |
943 | .B @#{\fICOMMENT\fB}@ | |
944 | Ignored. | |
945 | .TP | |
946 | .B @action@ | |
c0c23a60 RK |
947 | The current action. |
948 | This reports | |
460b9539 | 949 | .B manage |
950 | if the action is really | |
951 | .B playing | |
952 | but | |
953 | .B mgmt=true | |
954 | was set. | |
955 | .TP | |
956 | .B @and{\fIBOOL\fB}{\fIBOOL\fB}\fR...\fB@ | |
957 | If there are no arguments, or all the arguments are \fBtrue\fB, then expands to | |
958 | \fBtrue\fR, otherwise to \fBfalse\fR. | |
959 | .TP | |
960 | .B @arg:\fINAME\fB@ | |
25ca855b | 961 | Expands to the value of CGI argument \fINAME\fR. |
460b9539 | 962 | .TP |
963 | .B @basename@ | |
964 | The basename of the current directory component, in \fB@navigate@\fR. | |
965 | .TP | |
966 | .B @basename{\fIPATH\fB}@ | |
967 | The base name part of \fIPATH\fR. | |
968 | .TP | |
969 | .B @choose{\fIWHAT\fB}{\fITEMPLATE\fB}@ | |
970 | Expands \fITEMPLATE\fR repeatedly for each file or directory under | |
971 | \fB@arg:directory@\fR. | |
972 | \fIWHAT\fR should be either \fBfile\fR or \fBdirectory\fR. | |
973 | Use \fB@file@\fR to get the display name or filename of the file or | |
974 | directory. | |
975 | Usually used in \fBchoose.html\fR. | |
976 | .TP | |
977 | .B @dirname@ | |
978 | The directory of the current directory component, in \fB@navigate@\fR. | |
979 | .TP | |
980 | .B @dirname{\fIPATH\fB}@ | |
981 | The directory part of \fIPATH\fR. | |
982 | .TP | |
983 | .B @enabled@ | |
984 | Expands to \fBtrue\fR if play is currently enabled, otherwise to \fBfalse\fR. | |
985 | .TP | |
986 | .B @eq{\fIA\fB}{\fIB\fB} | |
987 | Expands to \fBtrue\fR if \fIA\fR and \fIB\fR are identical, otherwise to | |
988 | \fBfalse\fR. | |
989 | .TP | |
990 | .B @file@ | |
991 | Expands to the filename of the current file or directory, inside the template | |
992 | argument to \fBchoose\fR. | |
993 | .TP | |
994 | .B @files{\fITEMPLATE\fB} | |
40c30921 | 995 | Expands \fITEMPLATE\fR once for each file indicated by the \fBdirectory\fR CGI |
460b9539 | 996 | arg if it is present, or otherwise for the list of files counted by \fBfiles\fR |
997 | with names \fB0_file\fR, \fB1_file\fR etc. | |
998 | .TP | |
999 | .B @fullname@ | |
1000 | The full path of the current directory component, in \fB@navigate@\fR. | |
1001 | .TP | |
1002 | .B @id@ | |
1003 | The ID of the current track. | |
1004 | .TP | |
1005 | .B @if{\fIBOOL\fB}{\fITRUEPART\fB}{\fIFALSEPART\fB}@ | |
1006 | If \fIBOOL\fR expands to \fBtrue\fR then expands to \fITRUEPART\fR, otherwise | |
1007 | to \fIFALSEPART\fR (which may be omitted). | |
1008 | .TP | |
8f9616f1 RK |
1009 | .B @image:\fINAME\fB@ |
1010 | Expands to the (possibly relative) URL for image \fINAME\fR. | |
1011 | .IP | |
1012 | If there is a label \fBimages.\fINAME\fR then that will be the image base name. | |
1013 | Otherwise the image base name is \fINAME\fB.png\fR or just \fINAME\fR if it | |
c0c23a60 RK |
1014 | alraedy has an extension. |
1015 | Thus labels may be defined to give images role names. | |
8f9616f1 | 1016 | .IP |
c0c23a60 RK |
1017 | If there is a label \fBurl.static\fR then that is the base URL for images. |
1018 | If it is not defined then \fB/disorder\fR is used as a default. | |
8f9616f1 RK |
1019 | .TP |
1020 | .B @include:\fIPATH\fB@ | |
c0c23a60 RK |
1021 | Include the named file as if it were a template file. |
1022 | If \fIPATH\fR starts with a \fB/\fR then it is used as-is; | |
1023 | otherwise, ".html" is appended and the template path is searched. | |
460b9539 | 1024 | .TP |
1025 | .B @index@ | |
1026 | Expands to the index of the current file in \fB@queue@\fR, \fB@recent@\fR or | |
1027 | \fB@files@\fR. | |
1028 | .TP | |
1029 | .B @isdirectories@ | |
1030 | Expands to \fBtrue\fR if there are any directories in \fB@arg:directory@\fR, | |
1031 | otherwise to \fBfalse\fR. | |
1032 | .TP | |
1033 | .B @isfiles@ | |
1034 | Expands to \fBtrue\fR if there are any files in \fB@arg:directory@\fR, | |
1035 | otherwise to \fBfalse\fR. | |
1036 | .TP | |
1037 | .B @isfirst@ | |
1038 | Expands to \fBtrue\fR if this is the first repetition of a \fITEMPLATE\fR | |
1039 | argument in a loop (\fB@queue\fR or similar), otherwise to \fBfalse\fR. | |
1040 | .TP | |
1041 | .B @islast@ | |
1042 | Expands to \fBtrue\fR if this is the last repetition of a \fITEMPLATE\fR in a | |
1043 | loop, otherwise to \fBfalse\fR. | |
1044 | .TP | |
d5b6ffd7 RK |
1045 | .B @isnew@ |
1046 | Expands to \fBtrue\fR if the newly added tracks list has any tracks in it, | |
1047 | otherwise to \fBfalse\fR. | |
1048 | .TP | |
460b9539 | 1049 | .B @isplaying@ |
1050 | Expands to \fBtrue\fR if a track is playing, otherwise to \fBfalse\fR. | |
1051 | .TP | |
1052 | .B @isqueue@ | |
1053 | Expands to \fBtrue\fR if there are any tracks in the queue, otherwise to | |
1054 | \fBfalse\fR. | |
1055 | .TP | |
1056 | .B @isrecent@ | |
1057 | Expands to \fBtrue\fR if the recently played list has any tracks in it, | |
1058 | otherwise to \fBfalse\fR. | |
1059 | .TP | |
1060 | .B @label:\fINAME\fR\fB@ | |
c0c23a60 RK |
1061 | Expands to the value of label \fINAME\fR. |
1062 | See the shipped \fIoptions.labels\fR file for full documentation of the | |
1063 | labels used by the standard templates. | |
460b9539 | 1064 | .TP |
1065 | .B @length@ | |
1066 | Expands to the length of the current track. | |
1067 | .TP | |
938d8157 | 1068 | .B @movable@ |
1069 | Expands to \fBtrue\fR if the current track is movable, otherwise to | |
1070 | \fBfalse\fR. | |
1071 | .TP | |
460b9539 | 1072 | .B @navigate{\fIDIRECTORY\fB}{\fITEMPLATE\fB} |
1073 | Expands \fITEMPLATE\fR for each component of \fIDIRECTORY\fR in turn. | |
1074 | Use \fB@dirname\fR and \fB@basename@\fR to get the components of the path to | |
1075 | each component. | |
1076 | Usually used in \fBchoose.html\fR. | |
1077 | .TP | |
1078 | .B @ne{\fIA\fB}{\fIB\fB} | |
1079 | Expands to \fBtrue\fR if \fIA\fR and \fIB\fR differ, otherwise to \fBfalse\fR. | |
1080 | .TP | |
d5b6ffd7 RK |
1081 | .B @new{\fITEMPLATE\fB} |
1082 | Expands \fITEMPLATE\fR for each track in the newly added tracks list, starting | |
c0c23a60 RK |
1083 | with the most recent. |
1084 | Used in \fBnew.html\fR. | |
d5b6ffd7 | 1085 | .TP |
460b9539 | 1086 | .B @nfiles@ |
1087 | Expands to the number of files from \fB@files\fR (above). | |
1088 | .TP | |
1089 | .B @nonce@ | |
1090 | Expands to a string including the time and process ID, intended to be | |
1091 | unique across invocations. | |
1092 | .TP | |
1093 | .B @not{\fIBOOL\fB}@ | |
1094 | Expands to \fBfalse\fR if \fIBOOL\fR is \fBtrue\fR, otherwise to | |
1095 | \fBfalse\fR. | |
1096 | .TP | |
1097 | .B @or{\fIBOOL\fB}{\fIBOOL\fB}\fR...\fB@ | |
1098 | If at least one argument is \fBtrue\fB, then expands to \fBtrue\fR, otherwise | |
1099 | to \fBfalse\fR. | |
1100 | .TP | |
1101 | .B @parity@ | |
1102 | Expands to \fBeven\fR or \fBodd\fR depending on whether the current track is at | |
1103 | an even or odd position in \fB@queue@\fR, \fB@recent@\fR or \fB@files@\fR. | |
1104 | .TP | |
1105 | .B @part{\fICONTEXT\fB}{\fIPART\fB}@ | |
1106 | Expands to track name part \fIPART\fR using context \fICONTEXT\fR for the | |
c0c23a60 RK |
1107 | current track. |
1108 | The context may be omitted and defaults to \fBdisplay\fR. | |
61507e3c RK |
1109 | .IP |
1110 | The special context \fBshort\fR is equivalent to \fBdisplay\fR but limited to | |
1111 | the \fBshort_display\fR limit. | |
460b9539 | 1112 | .TP |
1113 | .B @part{\fICONTEXT\fB}{\fIPART\fB}{\fITRACK\fB}@ | |
1114 | Expands to track name part \fIPART\fR using context \fICONTEXT\fR for | |
c0c23a60 RK |
1115 | \fITRACK\fR. |
1116 | In this usage the context may not be omitted. | |
61507e3c RK |
1117 | .IP |
1118 | The special context \fBshort\fR is equivalent to \fBdisplay\fR but limited to | |
1119 | the \fBshort_display\fR limit. | |
460b9539 | 1120 | .TP |
1121 | .B @paused@ | |
1122 | Expands to \fBtrue\fR if the current track is paused, else \fBfalse\fR. | |
1123 | .TP | |
1124 | .B @playing{\fITEMPLATE\fB}@ | |
1125 | Expands \fITEMPLATE\fR using the playing track as the current track. | |
1126 | .TP | |
1127 | .B @pref{\fITRACK\fB}{\fIKEY\fB}@ | |
1128 | Expand to the track preference, or the empty string if it is not set. | |
1129 | .TP | |
1130 | .B @prefname@ | |
1131 | Expands to the name of the current preference, in the template | |
1132 | argument of \fB@prefs@\fR. | |
1133 | .TP | |
1134 | .B @prefs{\fIFILE\fB}{\fITEMPLATE\fB}@ | |
1135 | Expands \fITEMPLATE\fR repeatedly, for each preference of track | |
1136 | \fIFILE\fR. | |
1137 | Use \fB@prefname@\fR and \fB@prefvalue@\fR to get the name and value. | |
1138 | .TP | |
1139 | .B @prefvalue@ | |
1140 | Expands to the value of the current preference, in the template | |
1141 | argument of \fB@prefs@\fR. | |
1142 | .TP | |
1143 | .B @queue{\fITEMPLATE\fB}@ | |
1144 | Expands \fITEMPLATE\fR repeatedly using the each track on the queue in turn as | |
c0c23a60 RK |
1145 | the current track. |
1146 | The track at the head of the queue comes first. | |
460b9539 | 1147 | .TP |
0d350ff0 | 1148 | .B @random\-enabled@ |
460b9539 | 1149 | Expands to \fBtrue\fR if random play is currently enabled, otherwise to |
1150 | \fBfalse\fR. | |
1151 | .TP | |
1152 | .B @recent{\fITEMPLATE\fB}@ | |
1153 | Expands \fITEMPLATE\fR repeatedly using the each recently played track in turn | |
c0c23a60 RK |
1154 | as the current track. |
1155 | The most recently played track comes first. | |
460b9539 | 1156 | .TP |
938d8157 | 1157 | .B @removable@ |
1158 | Expands to \fBtrue\fR if the current track is removable, otherwise to | |
1159 | \fBfalse\fR. | |
1160 | .TP | |
460b9539 | 1161 | .B @resolve{\fITRACK\fB}@ |
1162 | Resolve aliases for \fITRACK\fR and expands to the result. | |
1163 | .TP | |
938d8157 | 1164 | .B @right{\fIRIGHT\fB}@ |
1165 | Exapnds to \fBtrue\fR if the user has right \fIRIGHT\fR, otherwise to | |
1166 | \fBfalse\fR. | |
1167 | .TP | |
1168 | .B @right{\fIRIGHT\fB}{\fITRUEPART\fB}{\fIFALSEPART\fB}@ | |
1169 | Expands to \fITRUEPART\fR if the user right \fIRIGHT\fR, otherwise to | |
1170 | \fIFALSEPART\fR (which may be omitted). | |
1171 | .TP | |
1172 | .B @scratchable@ | |
1173 | Expands to \fBtrue\fR if the currently playing track is scratchable, otherwise | |
1174 | to \fBfalse\fR. | |
1175 | .TP | |
460b9539 | 1176 | .B @search{\fIPART\fB}\fR[\fB{\fICONTEXT\fB}\fR]\fB{\fITEMPLATE\fB}@ |
1177 | Expands \fITEMPLATE\fR once for each group of search results that have | |
1178 | a common value of track part \fIPART\fR. | |
1179 | The groups are sorted by the value of the part. | |
1180 | .IP | |
1181 | .B @part@ | |
1182 | and | |
1183 | .B @file@ | |
1184 | within the template will apply to one of the tracks in the group. | |
1185 | .IP | |
1186 | If \fICONTEXT\fR is specified it should be either \fBsort\fR or \fBdisplay\fR, | |
c0c23a60 RK |
1187 | and determines the context for \fIPART\fR. |
1188 | The default is \fBsort\fR. | |
1189 | Usually you want \fBdisplay\fR for everything except the title and | |
1190 | \fBsort\fR for the title. | |
1191 | If you use \fBsort\fR for artist and album then you are likely to get | |
460b9539 | 1192 | strange effects. |
1193 | .TP | |
0d350ff0 | 1194 | .B @server\-version@ |
460b9539 | 1195 | Expands to the server's version string. |
1196 | .TP | |
1197 | .B @shell{\fICOMMAND\fB}@ | |
c0c23a60 RK |
1198 | Expands to the output of \fICOMMAND\fR executed via the shell. |
1199 | \fBsh\fR is searched for using \fBPATH\fR. | |
1200 | If the command fails then this is logged but otherwise ignored. | |
460b9539 | 1201 | .TP |
1202 | .B @state@ | |
1203 | In \fB@queue@\fR and \fB@recent@\fR, expands to the state of the current | |
c0c23a60 RK |
1204 | track. |
1205 | Otherwise the empty string. | |
1206 | Known states are: | |
460b9539 | 1207 | .RS |
1208 | .TP 12 | |
1209 | .B failed | |
1210 | The player terminated with nonzero status, but not because the track was | |
1211 | scratched. | |
1212 | .TP | |
1213 | .B isscratch | |
1214 | A scratch, in the queue. | |
1215 | .TP | |
1216 | .B no_player | |
1217 | No player could be found. | |
1218 | .TP | |
1219 | .B ok | |
1220 | Played successfully. | |
1221 | .TP | |
1222 | .B random | |
1223 | A randomly chosen track, in the queue. | |
1224 | .TP | |
1225 | .B scratched | |
1226 | This track was scratched. | |
1227 | .TP | |
1228 | .B unplayed | |
1229 | An explicitly queued track, in the queue. | |
1230 | .RE | |
1231 | .IP | |
1232 | Some additional states only apply to playing tracks, so will never be seen in | |
1233 | the queue or recently-played list: | |
1234 | .RS | |
1235 | .TP 12 | |
1236 | .B paused | |
1237 | The track has been paused. | |
1238 | .TP | |
1239 | .B quitting | |
1240 | Interrupted because the server is shutting down. | |
1241 | .TP | |
1242 | .B started | |
1243 | This track is currently playing. | |
1244 | .RE | |
1245 | .TP | |
1246 | .B @stats@ | |
1247 | Expands to the server statistics. | |
1248 | .TP | |
1249 | .B @thisurl@ | |
c0c23a60 RK |
1250 | Expands to the URL of the current page. |
1251 | Typically used in | |
460b9539 | 1252 | .B back |
c0c23a60 RK |
1253 | arguments. |
1254 | If there is a | |
460b9539 | 1255 | .B nonce |
1256 | argument then it is changed to a fresh value. | |
1257 | .TP | |
1258 | .B @track@ | |
1259 | The current track. | |
1260 | .TP | |
1261 | .B @trackstate{\fIPATH\fB}@ | |
1262 | Expands to the current track state: \fBplaying\fR if the track is actually | |
1263 | playing now, \fBqueued\fR if it is queued or the empty string otherwise. | |
1264 | .TP | |
1265 | .B @transform{\fIPATH\fB}{\fITYPE\fB}{\fICONTEXT\fB}@ | |
1266 | Transform a path according to \fBtransform\fR (see above). | |
1267 | \fIPATH\fR should be a raw filename (of a track or directory). | |
1268 | \fITYPE\fR should be the transform type (e.g. \fItrack\fR or \fIdir\fR). | |
1269 | \fICONTEXT\fR should be the context, and can be omitted (the default | |
1270 | is \fBdisplay\fR). | |
1271 | .TP | |
1272 | .B @url@ | |
1273 | Expands to the canonical URL as defined in \fIpkgconfdir/config\fR. | |
1274 | .TP | |
1275 | .B @urlquote{\fISTRING\fB}@ | |
1276 | URL-quote \fISTRING\fR. | |
1277 | .TP | |
fdf98378 | 1278 | .B @user@ |
c0c23a60 RK |
1279 | The current username. |
1280 | This will be "guest" if nobody is logged in. | |
fdf98378 | 1281 | .TP |
968f044a | 1282 | .B @userinfo{\fIPROPERTY\fB}@ |
1283 | Look up a property of the logged-in user. | |
1284 | .TP | |
460b9539 | 1285 | .B @version@ |
1286 | Expands to \fBdisorder.cgi\fR's version string. | |
1287 | .TP | |
1288 | .B @volume:\fISPEAKER\fB@ | |
c0c23a60 RK |
1289 | The volume on the left or right speaker. |
1290 | \fISPEAKER\fR must be \fBleft\fR or \fBright\fR. | |
460b9539 | 1291 | .TP |
1292 | .B @when@ | |
1293 | When the current track was played (or when it is expected to be played, if it | |
1294 | has not been played yet) | |
1295 | .TP | |
1296 | .B @who@ | |
1297 | Who submitted the current track. | |
1298 | .SH "WEB OPTIONS" | |
1299 | This is a file called \fIoptions\fR, searched for in the same manner | |
c0c23a60 RK |
1300 | as templates. |
1301 | It includes numerous options for the control of the web interface. | |
1302 | The general syntax is the same as the main configuration | |
460b9539 | 1303 | file, except that it should be encoded using UTF-8 (though this might |
1304 | change to the current locale's character encoding; stick to ASCII to | |
1305 | be safe). | |
1306 | .PP | |
1307 | The shipped \fIoptions\fR file includes four standard options files. | |
1308 | In order, they are: | |
1309 | .TP | |
1310 | .I options.labels | |
c0c23a60 RK |
1311 | The default labels file. |
1312 | You wouldn't normally edit this directly - instead supply your own commands | |
1313 | in \fIoptions.user\fR. | |
1314 | Have a look at the shipped version of the file for documentation of | |
1315 | labels used by the standard templates. | |
460b9539 | 1316 | .TP |
1317 | .I options.user | |
c0c23a60 RK |
1318 | A user options file. |
1319 | Here you should put any overrides for the default labels and any | |
1320 | extra labels required by your modified templates. | |
460b9539 | 1321 | .PP |
1322 | Valid directives are: | |
1323 | .TP | |
1324 | .B columns \fINAME\fR \fIHEADING\fR... | |
c0c23a60 RK |
1325 | Defines the columns used in \fB@playing@\fR and \fB@recent@\fB. |
1326 | \fINAME\fR must be either \fBplaying\fR, \fBrecent\fR or \fBsearch\fR. | |
1327 | \fIHEADING\fR... is a list of heading names. | |
1328 | If a column is defined more than once then the last definitions is used. | |
460b9539 | 1329 | .IP |
1330 | The heading names \fBbutton\fR, \fBlength\fR, \fBwhen\fR and \fBwho\fR | |
1331 | are built in. | |
1332 | .TP | |
1333 | .B include \fIPATH\fR | |
c0c23a60 RK |
1334 | Includes another file. |
1335 | If \fIPATH\fR starts with a \fB/\fR then it is taken as is, otherwise | |
1336 | it is searched for in the template path. | |
460b9539 | 1337 | .TP |
1338 | .B label \fINAME\fR \fIVALUE\fR | |
c0c23a60 RK |
1339 | Define a label. |
1340 | If a label is defined more than once then the last definition is used. | |
460b9539 | 1341 | .SS Labels |
1342 | Some labels are defined inside \fBdisorder.cgi\fR and others by the | |
c0c23a60 RK |
1343 | default templates. |
1344 | You can define your own labels and use them inside a template. | |
460b9539 | 1345 | .PP |
1346 | When an undefined label is expanded, if it has a dot in its name then | |
c0c23a60 RK |
1347 | the part after the final dot is used as its value. |
1348 | Otherwise the whole name is used as the value. | |
460b9539 | 1349 | .PP |
1350 | Labels are no longer documented here, see the shipped \fIoptions.labels\fR file | |
1351 | instead. | |
1352 | .SH "REGEXP SUBSTITUTION RULES" | |
c0c23a60 RK |
1353 | Regexps are PCRE regexps, as defined in \fBpcrepattern\fR(3). |
1354 | The only option used is \fBPCRE_UTF8\fR. | |
1355 | Remember that the configuration file syntax means you have to | |
1356 | escape backslashes and quotes inside quoted strings. | |
460b9539 | 1357 | .PP |
1358 | In a \fISUBST\fR string the following sequences are interpreted | |
1359 | specially: | |
1360 | .TP | |
1361 | .B $1 \fR... \fB$9 | |
1362 | These expand to the first to ninth bracketed subexpression. | |
1363 | .TP | |
1364 | .B $& | |
1365 | This expands to the matched part of the subject string. | |
1366 | .TP | |
1367 | .B $$ | |
1368 | This expands to a single \fB$\fR symbol. | |
1369 | .PP | |
1370 | All other pairs starting with \fB$\fR are undefined (and might be used | |
1371 | for something else in the future, so don't rely on the current | |
1372 | behaviour.) | |
1373 | .PP | |
c0c23a60 RK |
1374 | If \fBi\fR is present in \fIREFLAGS\fR then the match is case-independent. |
1375 | If \fBg\fR is present then all matches are replaced, otherwise only the first | |
460b9539 | 1376 | match is replaced. |
1377 | .SH "ACTIONS" | |
1378 | What the web interface actually does is terminated by the \fBaction\fR CGI | |
c0c23a60 RK |
1379 | argument. |
1380 | The values listed below are supported. | |
460b9539 | 1381 | .PP |
1382 | Except as specified, all actions redirect back to the \fBplaying.html\fR | |
1383 | template unless the \fBback\fR argument is present, in which case the URL it | |
1384 | gives is used instead. | |
1385 | .PP | |
1386 | Redirection to \fBplaying.html\fR preserves \fBmgmt=true\fR if it is present. | |
1387 | .TP 8 | |
1388 | .B "move" | |
1389 | Move track \fBid\fR by offset \fBdelta\fR. | |
1390 | .TP | |
1391 | .B "play" | |
1392 | Play track \fBfile\fR, or if that is missing then play all the tracks in | |
1393 | \fBdirectory\fR. | |
1394 | .TP | |
1395 | .B "playing" | |
1396 | Don't change any state, but instead compute a suitable refresh time and include | |
c0c23a60 RK |
1397 | that in an HTTP header. |
1398 | Expands the \fBplaying.html\fR template rather than redirecting. | |
460b9539 | 1399 | .IP |
1400 | This is the default if \fBaction\fR is missing. | |
1401 | .TP | |
0d350ff0 | 1402 | .B "random\-disable" |
460b9539 | 1403 | Disables random play. |
1404 | .TP | |
0d350ff0 | 1405 | .B "random\-enable" |
460b9539 | 1406 | Enables random play. |
1407 | .TP | |
1408 | .B "disable" | |
1409 | Disables play completely. | |
1410 | .TP | |
1411 | .B "enable" | |
1412 | Enables play. | |
1413 | .TP | |
1414 | .B "pause" | |
1415 | Pauses the current track. | |
1416 | .TP | |
1417 | .B "remove" | |
1418 | Remove track \fBid\fR. | |
1419 | .TP | |
1420 | .B "resume" | |
1421 | Resumes play after a pause. | |
1422 | .TP | |
1423 | .B "scratch" | |
c0c23a60 RK |
1424 | Scratch the playing track. |
1425 | If \fBid\fR is present it must match the playing track. | |
460b9539 | 1426 | .TP |
1427 | .B "volume" | |
1428 | Change the volume by \fBdelta\fR, or if that is missing then set it to the | |
c0c23a60 RK |
1429 | values of \fBleft\fR and \fBright\fR. |
1430 | Expands to the \fBvolume.html\fR template rather than redirecting. | |
460b9539 | 1431 | .TP |
1432 | .B "prefs" | |
1433 | Adjust preferences from the \fBprefs.html\fR template (which it then expands | |
1434 | rather than redirecting). | |
1435 | .IP | |
1436 | If | |
1437 | .B parts | |
c0c23a60 RK |
1438 | is set then the cooked interface is assumed. |
1439 | The value of | |
460b9539 | 1440 | .B parts |
c0c23a60 RK |
1441 | is used to determine which trackname preferences are set. |
1442 | By default the | |
460b9539 | 1443 | .B display |
1444 | context is adjusted but this can be overridden with the | |
1445 | .B context | |
c0c23a60 RK |
1446 | argument. |
1447 | Also the | |
460b9539 | 1448 | .B random |
1449 | argument is checked; if it is set then random play is enabled for that track, | |
1450 | otherwise it is disabled. | |
1451 | .IP | |
1452 | Otherwise if the | |
1453 | .B name | |
1454 | and | |
1455 | .B value | |
1456 | arguments are set then they are used to set a single preference. | |
1457 | .IP | |
1458 | Otherwise if just the | |
1459 | .B name | |
1460 | argument is set then that preference is deleted. | |
1461 | .IP | |
1462 | It is recommended that links to the \fBprefs\fR action use \fB@resolve@\fR to | |
c0c23a60 RK |
1463 | enure that the real track name is always used. |
1464 | Otherwise if the preferences page is used to adjust a trackname_ preference, | |
1465 | the alias may change, leading to the URL going stale. | |
460b9539 | 1466 | .TP |
1467 | .B "error" | |
1468 | This action is generated automatically when an error occurs connecting to the | |
c0c23a60 RK |
1469 | server. |
1470 | The \fBerror\fR label is set to an indication of what the error is. | |
460b9539 | 1471 | .SH "TRACK NAME PARTS" |
1472 | The traditional track name parts are \fBartist\fR, \fBalbum\fR and \fBtitle\fR, | |
c0c23a60 RK |
1473 | with the obvious intended meaning. |
1474 | These are controlled by configuration and by \fBtrackname_\fR preferences. | |
460b9539 | 1475 | .PP |
1476 | In addition there are two built-in parts, \fBpath\fR which is the whole path | |
1477 | name and \fBext\fR which is the filename extension, including the initial dot | |
1478 | (or the empty string if there is not extension). | |
1479 | .SH "SEE ALSO" | |
0d350ff0 | 1480 | \fBdisorder\fR(1), \fBsox\fR(1), \fBdisorderd\fR(8), \fBdisorder\-dump\fR(8), |
460b9539 | 1481 | \fBpcrepattern\fR(3) |
1482 | .\" Local Variables: | |
1483 | .\" mode:nroff | |
1484 | .\" fill-column:79 | |
1485 | .\" End: |