Commit | Line | Data |
---|---|---|
e99d42b1 | 1 | |
460b9539 | 2 | .\" |
405fea4e | 3 | .\" Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell |
460b9539 | 4 | .\" |
5 | .\" This program is free software; you can redistribute it and/or modify | |
6 | .\" it under the terms of the GNU General Public License as published by | |
7 | .\" the Free Software Foundation; either version 2 of the License, or | |
8 | .\" (at your option) any later version. | |
9 | .\" | |
10 | .\" This program is distributed in the hope that it will be useful, but | |
11 | .\" WITHOUT ANY WARRANTY; without even the implied warranty of | |
12 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
13 | .\" General Public License for more details. | |
14 | .\" | |
15 | .\" You should have received a copy of the GNU General Public License | |
16 | .\" along with this program; if not, write to the Free Software | |
17 | .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 | |
18 | .\" USA | |
19 | .\" | |
20 | .TH disorder_config 5 | |
21 | .SH NAME | |
22 | pkgconfdir/config - DisOrder jukebox configuration | |
23 | .SH DESCRIPTION | |
24 | The purpose of DisOrder is to organize and play digital audio files, under the | |
25 | control of multiple users. \fIpkgconfdir/config\fR is the primary | |
26 | configuration file but this man page currently documents all of its various | |
27 | configuration files. | |
28 | .SS Tracks | |
29 | DisOrder can be configured with multiple collections of tracks, indexing them | |
30 | by their filename, and picking players on the basis of filename patterns (for | |
31 | instance, "*.mp3"). | |
32 | .PP | |
33 | Although the model is of filenames, it is not inherent that there are | |
34 | corresponding real files - merely that they can be interpreted by the chosen | |
35 | player. See \fBdisorder\fR(3) for more details about this. | |
36 | .PP | |
37 | Each track can have a set of preferences associated with it. These are simple | |
38 | key-value pairs; they can be used for anything you like, but a number of keys | |
39 | have specific meanings. See \fBdisorder\fR(1) for more details about these. | |
40 | .SS "Track Names" | |
41 | Track names are derived from filenames under the control of regular | |
42 | expressions, rather than attempting to interpret format-specific embedded name | |
43 | information. They can be overridden by setting preferences. | |
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. | |
51 | .SS "Users And Access Control" | |
52 | DisOrder distinguishes between multiple users. This is for access control and | |
53 | reporting, not to provide different views of the world: i.e. preferences and so | |
54 | on are global. | |
55 | .PP | |
56 | It's possible to restrict a small number of operations to a specific subset of | |
57 | users. However, it is assumed that every user is supposed to be able to do | |
58 | most operations - since the users are all sharing the same audio environment | |
59 | they are expected to cooperate with each other. | |
60 | .PP | |
61 | Access control is entirely used-based. If you configure DisOrder to listen for | |
62 | TCP/IP connections then it will accept a connection from anywhere provided the | |
63 | right password is available. Passwords are never transmitted over TCP/IP | |
64 | connections in clear, but everything else is. The expected model is that | |
65 | host-based access control is imposed at the network layer. | |
66 | .SS "Web Interface" | |
67 | The web interface is controlled by a collection of template files, one for each | |
68 | kind of page, and a collection of option files. These are split up and | |
69 | separate from the main configuration file to make it more convenient to | |
70 | override specific bits. | |
71 | .PP | |
72 | The web interface connects to the DisOrder server like any other user, though | |
73 | it is given a special privilege to "become" any other user. (Thus, any process | |
74 | with the same UID as the web interface is very powerful as far as DisOrder | |
25ca855b | 75 | goes. This model will be changed in a future version.) |
460b9539 | 76 | .PP |
77 | Access control to the web interface is (currently) separate from DisOrder's own | |
78 | access control (HTTP authentication is required) but uses the same user | |
79 | namespace. | |
80 | .SH "CONFIGURATION FILE" | |
81 | .SS "General Syntax" | |
82 | Lines are split into fields separated by whitespace (space, tab, line | |
83 | feed, carriage return, form feed). Comments are started by the number | |
84 | sign ("#"). | |
85 | .PP | |
86 | Fields may be unquoted (in which case they may not contain spaces and | |
87 | may not start with a quotation mark or apostrophe) or quoted by either | |
88 | quotation marks or apostrophes. Inside quoted fields every character | |
89 | stands for itself, except that a backslash can only appear as part of | |
90 | one of the following escape sequences: | |
91 | .TP | |
92 | .B \e\e | |
93 | Backslash | |
94 | .TP | |
95 | .B \e" | |
96 | Quotation mark | |
97 | .\" " | |
98 | .TP | |
99 | .B \e' | |
100 | Apostrophe | |
101 | .TP | |
102 | .B \en | |
103 | Line feed | |
104 | .PP | |
105 | No other escape sequences are allowed. | |
106 | .PP | |
107 | Within any line the first field is a configuration command and any | |
108 | further fields are parameters. Lines with no fields are ignored. | |
109 | .PP | |
110 | After editing the config file use \fBdisorder reconfigure\fR to make | |
111 | it re-read it. If there is anything wrong with it the daemon will | |
112 | record a log message and ignore the new config file. (You should fix | |
113 | it before next terminating and restarting the daemon, as it cannot | |
114 | start up without a valid config file.) | |
115 | .SS "Global Configuration" | |
116 | .TP | |
117 | .B home \fIDIRECTORY\fR | |
118 | The home directory for state files. Defaults to | |
119 | .IR pkgstatedir . | |
659d87e8 | 120 | The server will create this directory on startup if it does not exist. |
460b9539 | 121 | .TP |
0c6bcae0 | 122 | .B plugins \fIPATH\fR |
460b9539 | 123 | Adds a directory to the plugin path. (This is also used by the web |
124 | interface.) | |
125 | .IP | |
126 | Plugins are opened the first time they are required and never after, | |
127 | so after changing a plugin you must restart the server before it is | |
128 | guaranteed to take effect. | |
40c30921 RK |
129 | .IP |
130 | If | |
131 | .B plugins | |
132 | is used without arguments the plugin path is cleared. | |
460b9539 | 133 | .SS "Server Configuration" |
134 | .TP | |
135 | .B alias \fIPATTERN\fR | |
136 | Defines the pattern use construct virtual filenames from \fBtrackname_\fR | |
137 | preferences. | |
138 | .IP | |
139 | Most characters stand for themselves, the exception being \fB{\fR which is used | |
140 | to insert a track name part in the form \fB{\fIname\fB}\fR or | |
141 | \fB{/\fIname\fB}\fR. | |
142 | .IP | |
143 | The difference is that the first form just inserts the name part while the | |
144 | second prefixes it with a \fB/\fR if it is nonempty. | |
145 | .IP | |
146 | The pattern should not attempt to include the collection root, which is | |
147 | automatically included, but should include the proper extension. | |
148 | .IP | |
149 | The default is \fB{/artist}{/album}{/title}{ext}\fR. | |
150 | .TP | |
25ca855b | 151 | .B authorization_algorithm \fIALGORITHM\fR |
637fdea3 RK |
152 | Defines the algorithm used to authenticate clients. The valid options |
153 | are sha1 (the default), sha256, sha384 and sha512. See | |
154 | .BR disorder_protocol (5) | |
155 | for more details. | |
156 | .TP | |
30ad4dab | 157 | .B broadcast \fIADDRESS\fR \fIPORT\fR |
158 | Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR. This implies | |
29573477 | 159 | \fBspeaker_backend network\fR. |
61941295 RK |
160 | .IP |
161 | See also \fBmulticast_loop\fR and \fBmulticast_ttl\fR. | |
30ad4dab | 162 | .TP |
163 | .B broadcast_from \fIADDRESS\fR \fIPORT\fR | |
164 | Sets the (local) source address used by \fBbroadcast\fR. | |
165 | .TP | |
460b9539 | 166 | .B channel \fICHANNEL\fR |
167 | The mixer channel that the volume control should use. Valid names depend on | |
168 | your operating system and hardware, but some standard ones that might be useful | |
169 | are: | |
170 | .RS | |
171 | .TP 8 | |
172 | .B pcm | |
25ca855b RK |
173 | Output level for the audio device. This is probably what you want and is the |
174 | default. | |
460b9539 | 175 | .TP |
176 | .B speaker | |
177 | Output level for the PC speaker, if that is connected to the sound card. | |
178 | .TP | |
179 | .B pcm2 | |
180 | Output level for alternative codec device. | |
181 | .TP | |
182 | .B vol | |
183 | Master output level. The OSS documentation recommends against using this, as | |
184 | it affects all output devices. | |
185 | .RE | |
186 | .IP | |
25ca855b RK |
187 | You can also specify channels by number, if you know the right value. NB that |
188 | volume setting only works on OSS systems (including ALSA, via emulation). | |
460b9539 | 189 | .TP |
190 | .B collection \fIMODULE\fR \fIENCODING\fR \fIROOT\fR | |
191 | Define a collection of tracks. | |
192 | .IP | |
193 | \fIMODULE\fR defines which plugin module should be used for this | |
194 | collection. Use the supplied \fBfs\fR module for tracks that exists | |
195 | as ordinary files in the filesystem. | |
196 | .IP | |
197 | \fIENCODING\fR defines the encoding of filenames in this collection. | |
198 | For \fBfs\fR this would be the encoding you use for filenames. | |
199 | Examples might be \fBiso-8859-1\fR or \fButf-8\fR. | |
200 | .IP | |
201 | \fIROOT\fR is the root in the filesystem of the filenames and is | |
202 | passed to the plugin module. | |
203 | .TP | |
204 | .B device \fINAME\fR | |
205 | ALSA device to play raw-format audio. Default is \fBdefault\fR, i.e. to use | |
206 | the whatever the ALSA configured default is. | |
207 | .TP | |
208 | .B gap \fISECONDS\fR | |
209 | Specifies the number of seconds to leave between tracks. The default | |
210 | is 2. | |
211 | .TP | |
212 | .B history \fIINTEGER\fR | |
213 | Specifies the number of recently played tracks to remember (including | |
214 | failed tracks and scratches). | |
215 | .TP | |
216 | .B listen \fR[\fIHOST\fR] \fISERVICE\fR | |
217 | Listen for connections on the address specified by \fIHOST\fR and port | |
218 | specified by \fISERVICE\fR. If \fIHOST\fR is omitted then listens on all | |
219 | local addresses. | |
220 | .IP | |
221 | Normally the server only listens on a UNIX domain socket. | |
222 | .TP | |
223 | .B lock yes\fR|\fBno | |
224 | Determines whether the server locks against concurrent operation. Default is | |
25ca855b RK |
225 | \fByes\fR. There is no good reason to set this to \fBno\fR and the option will |
226 | probably be removed in a future version. | |
460b9539 | 227 | .TP |
228 | .B mixer \fIPATH\fR | |
229 | The path to the mixer device, if you want access to the volume control, | |
25ca855b | 230 | e.g. \fB/dev/mixer\fR (the default). |
460b9539 | 231 | .TP |
61941295 RK |
232 | .B multicast_loop yes\fR|\fBno |
233 | Determines whether multicast packets are loop backed to the sending host. The | |
234 | default is \fByes\fR. This only applies if | |
235 | \fBspeaker_backend\fR is set to \fBnetwork\fR and \fBbroadcast\fR is actually a | |
236 | multicast address. | |
237 | .TP | |
23205f9c | 238 | .B multicast_ttl \fIHOPS\fR |
61941295 | 239 | Set the maximum number of hops to send multicast packets. This only applies if |
23205f9c | 240 | \fBspeaker_backend\fR is set to \fBnetwork\fR and \fBbroadcast\fR is actually a |
25ca855b | 241 | multicast address. The default is 1. |
23205f9c | 242 | .TP |
460b9539 | 243 | .B namepart \fIPART\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]] |
244 | Determines how to extract trackname part \fIPART\fR from a | |
245 | track name (with the collection root part removed). | |
246 | Used in \fB@recent@\fR, \fB@playing@\fR and \fB@search@\fR. | |
247 | .IP | |
248 | Track names can be different in different contexts. For instance the sort | |
249 | string might include an initial track number, but this would be stripped for | |
250 | the display string. \fICONTEXT\fR should be a glob pattern matching the | |
251 | contexts in which this directive will be used. | |
252 | .IP | |
253 | Valid contexts are \fBsort\fR and \fBdisplay\fR. | |
254 | .IP | |
255 | All the \fBnamepart\fR directives are considered in order. The | |
256 | first directive for the right part, that matches the desired context, | |
257 | and with a \fIREGEXP\fR that | |
258 | matches the track is used, and the value chosen is constructed from | |
259 | \fISUBST\fR according to the substitution rules below. | |
260 | .IP | |
261 | Note that searches use the raw track name and \fBtrackname_\fR preferences but | |
262 | not (currently) the results of \fBnamepart\fR, so generating words via this option | |
263 | that aren't in the original track name will lead to confusing results. | |
264 | .IP | |
265 | If you supply no \fBnamepart\fR directives at all then a default set will be | |
266 | supplied automatically. But if you supply even one then you must supply all of | |
25ca855b RK |
267 | them. The defaults are equivalent to: |
268 | .PP | |
269 | .nf | |
270 | namepart title "/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display | |
271 | namepart title "/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort | |
272 | namepart album "/([^/]+)/[^/]+$" $1 * | |
273 | namepart artist "/([^/]+)/[^/]+/[^/]+$" $1 * | |
274 | namepart ext "(\\.[a-zA-Z0-9]+)$" $1 * | |
275 | .fi | |
460b9539 | 276 | .TP |
277 | .B nice_rescan \fIPRIORITY\fR | |
278 | Set the recan subprocess priority. The default is 10. | |
279 | .IP | |
280 | (Note that higher values mean the process gets less CPU time; UNIX priority | |
04e42396 | 281 | values are backwards.) |
460b9539 | 282 | .TP |
283 | .B nice_server \fIPRIORITY\fR | |
284 | Set the server priority. This is applied to the server at startup time (and | |
285 | not when you reload configuration). The server does not use much CPU itself | |
286 | but this value is inherited by programs it executes. If you have limited CPU | |
287 | then it might help to set this to a small negative value. The default is 0. | |
288 | .TP | |
289 | .B nice_speaker \fIPRIORITY\fR | |
290 | Set the speaker process priority. This is applied to the speaker process at | |
291 | startup time (and not when you reload the configuration). The speaker process | |
292 | is not massively CPU intensive by today's standards but depends on reasonably | |
293 | timely scheduling. If you have limited CPU then it might help to set this to a | |
294 | small negative value. The default is 0. | |
295 | .TP | |
2a10b70b RK |
296 | .B noticed_history |
297 | The maximum days that a track can survive in the database of newly added | |
298 | tracks. The default is 31. | |
299 | .TP | |
460b9539 | 300 | .B player \fIPATTERN\fR \fIMODULE\fR [\fIOPTIONS.. [\fB--\fR]] \fIARGS\fR... |
301 | Specifies the player for files matching the glob \fIPATTERN\fR. \fIMODULE\fR | |
302 | specifies which plugin module to use. | |
303 | .IP | |
304 | The following options are supported: | |
305 | .RS | |
306 | .TP | |
307 | .B --wait-for-device\fR[\fB=\fIDEVICE\fR] | |
308 | Waits (for up to a couple of seconds) for the default, or specified, libao | |
309 | device to become openable. | |
310 | .TP | |
311 | .B -- | |
312 | Defines the end of the list of options. Needed if the first argument to the | |
313 | plugin starts with a "-". | |
314 | .RE | |
315 | .IP | |
316 | The following are the standard modules: | |
317 | .RS | |
318 | .TP | |
319 | .B exec \fICOMMAND\fR \fIARGS\fR... | |
320 | The command is executed via \fBexecvp\fR(3), not via the shell. | |
321 | The \fBPATH\fR environment variable is searched for the executable if it is not | |
322 | an absolute path. | |
323 | The command is expected to know how to open its own sound device. | |
324 | .TP | |
325 | .B execraw \fICOMMAND\fR \fIARGS\fR... | |
326 | Identical to the \fBexec\fR except that the player is expected to use the | |
ce6c36be | 327 | DisOrder raw player protocol. |
328 | .BR disorder-decode (8) | |
329 | can decode several common audio file formats to this format. If your favourite | |
330 | format is not supported, but you have a player which uses libao, there is also | |
331 | a libao driver which supports this format; see below for more information about | |
332 | this. | |
460b9539 | 333 | .TP |
334 | .B shell \fR[\fISHELL\fR] \fICOMMAND\fR | |
335 | The command is executed using the shell. If \fISHELL\fR is specified then that | |
336 | is used, otherwise \fBsh\fR will be used. In either case the \fBPATH\fR | |
337 | environment variable is searched for the shell executable if it is not an | |
338 | absolute path. The track name is stored in the environment variable | |
339 | \fBTRACK\fR. | |
340 | .IP | |
341 | Be careful of the interaction between the configuration file quoting rules and | |
342 | the shell quoting rules. | |
343 | .RE | |
344 | .IP | |
345 | If multiple player commands match a track then the first match is used. | |
62dc3748 RK |
346 | .IP |
347 | For the server to be able to calculate track lengths, there should be a | |
348 | .B tracklength | |
349 | command corresponding to each | |
350 | .B player | |
351 | command. | |
40c30921 RK |
352 | .IP |
353 | If | |
354 | .B player | |
355 | is used without arguments, the list of players is cleared. | |
460b9539 | 356 | .TP |
357 | .B prefsync \fISECONDS\fR | |
358 | The interval at which the preferences log file will be synchronised. Defaults | |
359 | to 3600, i.e. one hour. | |
360 | .TP | |
459d4402 | 361 | .B queue_pad \fICOUNT\fR |
362 | The target size of the queue. If random play is enabled then randomly picked | |
25ca855b | 363 | tracks will be added until the queue is at least this big. The default is 10. |
459d4402 | 364 | .TP |
62dc3748 RK |
365 | .B restrict \fR[\fBscratch\fR] [\fBremove\fR] [\fBmove\fR] |
366 | Determine which operations are restricted to the submitter of a | |
367 | track. By default, no operations are restricted, i.e. anyone can | |
368 | scratch or remove anything. | |
369 | .IP | |
370 | If \fBrestrict scratch\fR or \fBrestrict remove\fR are set then only the user | |
371 | that submitted a track can scratch or remove it, respectively. | |
372 | .IP | |
373 | If \fBrestrict move\fR is set then only trusted users can move tracks around in | |
374 | the queue. | |
375 | .IP | |
376 | If \fBrestrict\fR is used more than once then only the final use has any | |
377 | effect. | |
378 | .TP | |
405fea4e | 379 | .B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS |
380 | Describes the sample format expected by the \fBspeaker_command\fR (below). The | |
381 | components of the format specification are as follows: | |
382 | .RS | |
383 | .TP 10 | |
384 | .I BITS | |
385 | The number of bits per sample. Optionally, may be suffixed by \fBb\fR or | |
386 | \fBl\fR for big-endian and little-endian words. If neither is used the native | |
387 | byte order is assumed. | |
388 | .TP | |
389 | .I RATE | |
390 | The number of samples per second. | |
391 | .TP | |
392 | .I CHANNELS | |
393 | The number of channels. | |
394 | .PP | |
395 | The default is | |
396 | .BR 16/44100/2 . | |
937be4c0 RK |
397 | .PP |
398 | With the | |
399 | .B network | |
400 | backend the sample format is forced to | |
e99d42b1 | 401 | .B 16b/44100/2 |
937be4c0 RK |
402 | and with the |
403 | .B coreaudio | |
404 | backend it is forced to | |
405 | .BR 16/44100/2 , | |
406 | in both cases regardless of what is specified in the configuration file. | |
405fea4e | 407 | .RE |
408 | .TP | |
460b9539 | 409 | .B signal \fINAME\fR |
410 | Defines the signal to be sent to track player process groups when tracks are | |
411 | scratched. The default is \fBSIGKILL\fR. | |
412 | .IP | |
413 | Signals are specified by their full C name, i.e. \fBSIGINT\fR and not \fBINT\fR | |
414 | or \fBInterrupted\fR or whatever. | |
415 | .TP | |
29573477 | 416 | .B speaker_backend \fINAME\fR |
417 | Selects the backend use by the speaker process. The following options are | |
418 | available: | |
419 | .RS | |
420 | .TP | |
421 | .B alsa | |
422 | Use the ALSA API. This is only available on Linux systems, on which it is the | |
423 | default. | |
424 | .TP | |
937be4c0 RK |
425 | .B coreaudio |
426 | Use Apple Core Audio. This only available on OS X systems, on which it is the | |
427 | default. | |
428 | .TP | |
e99d42b1 | 429 | .B oss |
25ca855b | 430 | Use the OSS (/dev/dsp) API. Not available on all platforms. |
e99d42b1 | 431 | .TP |
29573477 | 432 | .B command |
433 | Execute a command. This is the default if | |
434 | .B speaker_command | |
937be4c0 | 435 | is specified, or if no native is available. |
29573477 | 436 | .TP |
437 | .B network | |
438 | Transmit audio over the network. This is the default if | |
803f6e52 | 439 | \fBbroadcast\fR is specified. You can use |
440 | .BR disorder-playrtp (1) | |
441 | to receive and play the resulting stream on Linux and OS X. | |
29573477 | 442 | .RE |
443 | .TP | |
5330d674 | 444 | .B sox_generation \fB0\fR|\fB1 |
445 | Determines whether calls to \fBsox\fR(1) should use \fB-b\fR, \fB-x\fR, etc (if | |
25ca855b RK |
446 | the generation is 0) or \fB-\fIbits\fR, \fB-L\fR etc (if it is 1). See the |
447 | documentation for your installed copy of \fBsox\fR to determine which you need. | |
448 | The default is 0. | |
5330d674 | 449 | .TP |
405fea4e | 450 | .B speaker_command \fICOMMAND |
451 | Causes the speaker subprocess to pipe audio data into shell command | |
452 | \fICOMMAND\fR, rather than writing to a local sound card. The sample format is | |
453 | determine by | |
454 | .B sample_format | |
455 | above. | |
77cfc7a2 | 456 | .IP |
457 | Note that if the sample format is wrong then | |
458 | .BR sox (1) | |
459 | is invoked to translate it. If | |
460 | .B sox | |
461 | is not installed then this will not work. | |
405fea4e | 462 | .TP |
460b9539 | 463 | .B scratch \fIPATH\fR |
464 | Specifies a scratch. When a track is scratched, a scratch track is | |
465 | played at random. | |
466 | Scratches are played using the same logic as other tracks. | |
467 | .IP | |
468 | At least for the time being, path names of scratches must be encoded using | |
469 | UTF-8 (which means that ASCII will do). | |
40c30921 RK |
470 | .IP |
471 | If \fBscratch\fR is used without arguments then the list of scratches is | |
472 | cleared. | |
460b9539 | 473 | .TP |
474 | .B stopword \fIWORD\fR ... | |
475 | Specifies one or more stopwords that should not take part in searches | |
476 | over track names. | |
40c30921 RK |
477 | .IP |
478 | If \fBstopword\fR is used without arguments then the list of stopwords is | |
479 | cleared. | |
62dc3748 RK |
480 | .TP |
481 | .B tracklength \fIPATTERN\fR \fIMODULE\fR | |
482 | Specifies the module used to calculate the length of files matching | |
483 | \fIPATTERN\fR. \fIMODULE\fR specifies which plugin module to use. | |
40c30921 RK |
484 | .IP |
485 | If \fBtracklength\fR is used without arguments then the list of modules is | |
486 | cleared. | |
460b9539 | 487 | .SS "Client Configuration" |
488 | .TP | |
ccf0aafa | 489 | .B connect \fIHOST SERVICE\fR |
460b9539 | 490 | Connect to the address specified by \fIHOST\fR and port specified by |
ccf0aafa | 491 | \fISERVICE\fR. |
460b9539 | 492 | .SS "Web Interface Configuration" |
493 | .TP | |
494 | .B refresh \fISECONDS\fR | |
495 | Specifies the maximum refresh period in seconds. Default 15. | |
496 | .TP | |
61507e3c RK |
497 | .B short_display \fICHARACTERS\fR |
498 | Defines the maximum number of characters to include in a \fBshort\fR name | |
499 | part. Default 30. | |
500 | .TP | |
460b9539 | 501 | .B templates \fIPATH\fR ... |
502 | Specifies the directory containing templates used by the web | |
503 | interface. If a template appears in more than one template directory | |
504 | then the one in the earliest directory specified is chosen. | |
505 | .IP | |
506 | See below for further details. | |
40c30921 RK |
507 | .IP |
508 | If \fBtemplates\fR is used without arguments then the template path is cleared. | |
460b9539 | 509 | .TP |
510 | .B transform \fITYPE\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]] | |
511 | Determines how names are sorted and displayed in track choice displays. | |
512 | .IP | |
513 | \fITYPE\fR is the type of transformation; usually \fBtrack\fR or | |
514 | \fBdir\fR but you can define your own. | |
515 | .IP | |
516 | \fICONTEXT\fR is a glob pattern matching the context. Standard contexts are | |
517 | \fBsort\fR (which determines how directory names are sorted) and \fBdisplay\fR | |
518 | (which determines how they are displayed). Again, you can define your | |
519 | own. | |
520 | .IP | |
521 | All the \fBtransform\fR directives are considered in order. If | |
522 | the \fITYPE\fR, \fIREGEXP\fR and the \fICONTEXT\fR match | |
523 | then a new track name is constructed from | |
524 | \fISUBST\fR according to the substitution rules below. If several | |
525 | match then each is executed in order. | |
526 | .IP | |
527 | If you supply no \fBtransform\fR directives at all then a default set will be | |
528 | supplied automatically. But if you supply even one then you must supply all of | |
25ca855b RK |
529 | them. The defaults are: |
530 | .PP | |
531 | .nf | |
532 | transform track "^.*/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display | |
533 | transform track "^.*/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort | |
534 | transform dir "^.*/([^/]+)$" $1 * | |
535 | transform dir "^(the) ([^/]*)" "$2 $1" sort i | |
536 | transform dir "[[:punct:]]" "" sort g | |
537 | .fi | |
460b9539 | 538 | .TP |
539 | .B url \fIURL\fR | |
540 | Specifies the URL of the web interface. This URL will be used in | |
541 | generated web pages. | |
542 | .IP | |
543 | This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not | |
544 | \fB/cgi-bin/jukebox\fR. | |
545 | .SS "Authentication Configuration" | |
546 | .TP | |
547 | .B allow \fIUSERNAME\fR \fIPASSWORD\fR | |
548 | Specify a username/password pair. | |
40c30921 RK |
549 | .IP |
550 | If | |
551 | .B allow | |
552 | is used without arguments, the list of allowed users is cleared. | |
460b9539 | 553 | .TP |
554 | .B password \fIPASSWORD\fR | |
555 | Specify password. | |
556 | .TP | |
557 | .B trust \fIUSERNAME\fR | |
558 | Allow \fIUSERNAME\fR to perform privileged operations such as shutting | |
559 | down or reconfiguring the daemon, or becoming another user. | |
40c30921 RK |
560 | .IP |
561 | If \fBtrust\fR is used without arguments then the list of trusted users is | |
562 | cleared. | |
460b9539 | 563 | .TP |
564 | .B user \fIUSER\fR | |
565 | Specifies the user to run as. Only makes sense if invoked as root (or | |
566 | the target user). | |
567 | .TP | |
568 | .B username \fIUSERNAME\fR | |
569 | Specify username. The default is taken from the environment variable | |
570 | \fBLOGNAME\fR. | |
571 | .PP | |
572 | Configuration files are read in the following order: | |
573 | .TP | |
574 | .I pkgconfdir/config | |
575 | .TP | |
576 | .I pkgconfdir/config.private | |
577 | Should be readable only by the jukebox group, and contain \fBallow\fR | |
578 | commands for authorised users. | |
36be7e6a RK |
579 | .IP |
580 | If this file does not exist at startup then the server will create it with a | |
581 | randomly chosen password for the root user. | |
460b9539 | 582 | .TP |
583 | .I pkgconfdir/config.\fRUSER | |
584 | Per-user system-controlled client configuration. Optional but if it | |
585 | exists must be readable only by the relevant user. Would normally | |
586 | contain a \fBpassword\fR directive. | |
587 | .TP | |
588 | .I ~\fRUSER\fI/.disorder/passwd | |
589 | Per-user client configuration. Optional but if it exists must be | |
590 | readable only by the relevant user. Would normally contain a | |
591 | \fBpassword\fR directive. | |
592 | .SH "GLOBAL PREFERENCES" | |
593 | These are the values set with \fBset-global\fR. | |
594 | .TP | |
595 | .B required-tags | |
596 | If this is set an nonempty then randomly played tracks will always have at | |
597 | least one of the listed tags. | |
598 | .IP | |
599 | Tags can contain any printing character except comma. Leading and trailing | |
600 | spaces are not significant but internal spaces are. Tags in a list are | |
601 | separated by commas. | |
602 | .TP | |
603 | .B prohibited-tags | |
604 | If this is set an nonempty then randomly played tracks will never have any of | |
605 | the listed tags. | |
606 | .TP | |
607 | .B playing | |
608 | If unset or \fByes\fR then play is enabled. Otherwise it is disabled. Use | |
609 | \fBdisable\fR rather than setting it directly. | |
610 | .TP | |
611 | .B random-play | |
612 | If unset or \fByes\fR then random play is enabled. Otherwise it is disabled. | |
613 | Use \fBdisable\fR rather than setting it directly. | |
f9635e06 RK |
614 | .PP |
615 | Global preferences starting '_' are read-only (in the sense that you cannot | |
616 | modify them; the server may modify them as part of its normal operation). They | |
617 | are: | |
618 | .TP | |
619 | .B _dbversion | |
620 | The database version string. This is used by DisOrder to detect when it must | |
621 | modify the database after an upgrade. | |
460b9539 | 622 | .SH "LIBAO DRIVER" |
623 | .SS "Raw Protocol Players" | |
624 | Raw protocol players are expected to use the \fBdisorder\fR libao driver. | |
625 | Programs that use libao generally have command line options to select the | |
626 | driver and pass options to it. | |
627 | .SS "Driver Options" | |
628 | The known driver options are: | |
629 | .TP | |
630 | .B fd | |
631 | The file descriptor to write to. If this is not specified then the driver | |
632 | looks like the environment variable \fBDISORDER_RAW_FD\fR. If that is not set | |
633 | then the default is 1 (i.e. standard output). | |
634 | .TP | |
635 | .B fragile | |
636 | If this is set to a nonzero value then the driver will call \fB_exit\fR(2) if a | |
637 | write to the output file descriptor fails. This is a workaround for buggy | |
638 | players such as \fBogg123\fR that ignore write errors. | |
639 | .SH "WEB TEMPLATES" | |
640 | When \fBdisorder.cgi\fR wants to generate a page for an action it searches the | |
641 | directories specified with \fBtemplates\fR for a matching file. It is | |
642 | suggested that you leave the distributed templates unchanged and put | |
643 | any customisations in an earlier entry in the template path. | |
644 | .PP | |
645 | The supplied templates are: | |
646 | .TP | |
647 | .B about.html | |
648 | Display information about DisOrder. | |
649 | .TP | |
650 | .B choose.html | |
651 | Navigates through the track database to choose a track to play. The | |
652 | \fBdir\fR argument gives the directory to look in; if it is missing | |
653 | then the root directory is used. | |
654 | .TP | |
655 | .B choosealpha.html | |
656 | Provides a front end to \fBchoose.html\fR which allows subsets of the top level | |
657 | directories to be selected by initial letter. | |
658 | .TP | |
d5b6ffd7 RK |
659 | .B new.html |
660 | Lists newly added tracks. | |
661 | .TP | |
460b9539 | 662 | .B playing.html |
663 | The "front page", which usually shows the currently playing tracks and | |
664 | the queue. | |
665 | Gets an HTTP \fBRefresh\fR header. | |
666 | .IP | |
667 | If the \fBmgmt\fR CGI argument is set to \fBtrue\fR then we include extra | |
668 | buttons for moving tracks up and down in the queue. There is some logic in | |
669 | \fBdisorder.cgi\fR to ensure that \fBmgmt=true\fR is preserved across refreshes | |
670 | and redirects back into itself, but URLs embedded in web pages must include it | |
671 | explicitly. | |
672 | .TP | |
673 | .B prefs.html | |
674 | Views preferences. If the \fBfile\fR, \fBname\fR and \fBvalue\fR arguments are | |
675 | all set then that preference is modified; if \fBfile\fR and \fBname\fR are set | |
676 | but not \fBvalue\fR then the preference is deleted. | |
677 | .TP | |
678 | .B recent.html | |
679 | Lists recently played tracks. | |
680 | .TP | |
681 | .B search.html | |
682 | Presents search results. | |
683 | .TP | |
684 | .B volume.html | |
685 | Primitive volume control. | |
686 | .PP | |
687 | Additionally, other standard files are included by these: | |
688 | .TP | |
689 | .B credits.html | |
690 | Included at the end of the main content \fB<DIV>\fR element. | |
691 | .TP | |
d5b6ffd7 RK |
692 | .B topbar.html |
693 | Included at the start of the \fB<BODY>\fR element. (This supplants | |
694 | \fBsidebar.html\fR, though the latter is still available; override label | |
695 | \fBmenu\fR to choose between them.) | |
460b9539 | 696 | .TP |
697 | .B stdhead.html | |
698 | Included in the \fB<HEAD>\fR element. | |
699 | .TP | |
700 | .B stylesheet.html | |
701 | Contains the default DisOrder stylesheet. You can override this by editing the | |
702 | CSS or by replacing it all with a \fB<LINK>\fR to an external stylesheet. | |
703 | .PP | |
704 | Templates are ASCII files containing HTML documents, with an expansion | |
705 | syntax to enable data supplied by the implementation to be inserted. | |
706 | .PP | |
707 | If you want to use characters outside the ASCII range, use either the | |
708 | appropriate HTML entity, e.g. \fBé\fR, or an SGML numeric | |
709 | character reference, e.g. \fBý\fR. Use \fB@\fR to insert a | |
710 | literal \fB@\fR without falling foul of the expansion syntax. | |
711 | .SS "Expansion Syntax" | |
712 | Expansions are surrounded by at ("@") symbols take the form of a keyword | |
713 | followed by zero or more arguments. Arguments may either be quoted by curly | |
714 | brackets ("{" and "}") or separated by colons (":"). Both kinds may be mixed | |
715 | in a single expansion, though doing so seems likely to cause confusion. | |
716 | The descriptions below contain suggested forms for each | |
717 | expansion. | |
718 | .PP | |
719 | Leading and trailing whitespace in unquoted arguments is ignored, as is | |
720 | whitespace (including newlines) following a close bracket ("}"). | |
721 | .PP | |
722 | Arguments are recursively expanded before being interpreted, except for | |
723 | \fITEMPLATE\fR arguments. These are expanded (possibly more than once) to | |
724 | produce the final expansion. | |
725 | (More than once means the same argument being expanded more than once | |
726 | for different tracks or whatever, not the result of the first | |
727 | expansion itself being re-expanded.) | |
728 | .PP | |
729 | Strings constructed by expansions (i.e. not literally copied from the template | |
730 | text) are SGML-quoted: any character which does not stand for itself in #PCDATA | |
731 | or a quoted attribute value is replaced by the appropriate numeric character | |
732 | reference. | |
733 | .PP | |
734 | The exception to this is that such strings are \fInot\fR quoted when they are | |
735 | generated in the expansion of a parameter. | |
736 | .PP | |
737 | In the descriptions below, the current track means the one set by | |
738 | \fB@playing@\fR, \fB@recent@\fR or \fB@queue@\fR, not the one that is playing. | |
739 | If none of these expansions are in force then there is no current track. | |
740 | \fIBOOL\fR should always be either \fBtrue\fR or \fBfalse\fR. | |
741 | .SS "Expansions" | |
742 | The following expansion keywords are defined: | |
743 | .TP | |
744 | .B @#{\fICOMMENT\fB}@ | |
745 | Ignored. | |
746 | .TP | |
747 | .B @action@ | |
748 | The current action. This reports | |
749 | .B manage | |
750 | if the action is really | |
751 | .B playing | |
752 | but | |
753 | .B mgmt=true | |
754 | was set. | |
755 | .TP | |
756 | .B @and{\fIBOOL\fB}{\fIBOOL\fB}\fR...\fB@ | |
757 | If there are no arguments, or all the arguments are \fBtrue\fB, then expands to | |
758 | \fBtrue\fR, otherwise to \fBfalse\fR. | |
759 | .TP | |
760 | .B @arg:\fINAME\fB@ | |
25ca855b | 761 | Expands to the value of CGI argument \fINAME\fR. |
460b9539 | 762 | .TP |
763 | .B @basename@ | |
764 | The basename of the current directory component, in \fB@navigate@\fR. | |
765 | .TP | |
766 | .B @basename{\fIPATH\fB}@ | |
767 | The base name part of \fIPATH\fR. | |
768 | .TP | |
769 | .B @choose{\fIWHAT\fB}{\fITEMPLATE\fB}@ | |
770 | Expands \fITEMPLATE\fR repeatedly for each file or directory under | |
771 | \fB@arg:directory@\fR. | |
772 | \fIWHAT\fR should be either \fBfile\fR or \fBdirectory\fR. | |
773 | Use \fB@file@\fR to get the display name or filename of the file or | |
774 | directory. | |
775 | Usually used in \fBchoose.html\fR. | |
776 | .TP | |
777 | .B @dirname@ | |
778 | The directory of the current directory component, in \fB@navigate@\fR. | |
779 | .TP | |
780 | .B @dirname{\fIPATH\fB}@ | |
781 | The directory part of \fIPATH\fR. | |
782 | .TP | |
783 | .B @enabled@ | |
784 | Expands to \fBtrue\fR if play is currently enabled, otherwise to \fBfalse\fR. | |
785 | .TP | |
786 | .B @eq{\fIA\fB}{\fIB\fB} | |
787 | Expands to \fBtrue\fR if \fIA\fR and \fIB\fR are identical, otherwise to | |
788 | \fBfalse\fR. | |
789 | .TP | |
790 | .B @file@ | |
791 | Expands to the filename of the current file or directory, inside the template | |
792 | argument to \fBchoose\fR. | |
793 | .TP | |
794 | .B @files{\fITEMPLATE\fB} | |
40c30921 | 795 | Expands \fITEMPLATE\fR once for each file indicated by the \fBdirectory\fR CGI |
460b9539 | 796 | arg if it is present, or otherwise for the list of files counted by \fBfiles\fR |
797 | with names \fB0_file\fR, \fB1_file\fR etc. | |
798 | .TP | |
799 | .B @fullname@ | |
800 | The full path of the current directory component, in \fB@navigate@\fR. | |
801 | .TP | |
802 | .B @id@ | |
803 | The ID of the current track. | |
804 | .TP | |
805 | .B @if{\fIBOOL\fB}{\fITRUEPART\fB}{\fIFALSEPART\fB}@ | |
806 | If \fIBOOL\fR expands to \fBtrue\fR then expands to \fITRUEPART\fR, otherwise | |
807 | to \fIFALSEPART\fR (which may be omitted). | |
808 | .TP | |
809 | .B @include:\fIPATH\fR@ | |
810 | Include the named file as if it were a template file. If \fIPATH\fR | |
811 | starts with a \fB/\fR then it is used as-is; otherwise, ".html" is | |
812 | appended and the template path is searched. | |
813 | .TP | |
814 | .B @index@ | |
815 | Expands to the index of the current file in \fB@queue@\fR, \fB@recent@\fR or | |
816 | \fB@files@\fR. | |
817 | .TP | |
818 | .B @isdirectories@ | |
819 | Expands to \fBtrue\fR if there are any directories in \fB@arg:directory@\fR, | |
820 | otherwise to \fBfalse\fR. | |
821 | .TP | |
822 | .B @isfiles@ | |
823 | Expands to \fBtrue\fR if there are any files in \fB@arg:directory@\fR, | |
824 | otherwise to \fBfalse\fR. | |
825 | .TP | |
826 | .B @isfirst@ | |
827 | Expands to \fBtrue\fR if this is the first repetition of a \fITEMPLATE\fR | |
828 | argument in a loop (\fB@queue\fR or similar), otherwise to \fBfalse\fR. | |
829 | .TP | |
830 | .B @islast@ | |
831 | Expands to \fBtrue\fR if this is the last repetition of a \fITEMPLATE\fR in a | |
832 | loop, otherwise to \fBfalse\fR. | |
833 | .TP | |
d5b6ffd7 RK |
834 | .B @isnew@ |
835 | Expands to \fBtrue\fR if the newly added tracks list has any tracks in it, | |
836 | otherwise to \fBfalse\fR. | |
837 | .TP | |
460b9539 | 838 | .B @isplaying@ |
839 | Expands to \fBtrue\fR if a track is playing, otherwise to \fBfalse\fR. | |
840 | .TP | |
841 | .B @isqueue@ | |
842 | Expands to \fBtrue\fR if there are any tracks in the queue, otherwise to | |
843 | \fBfalse\fR. | |
844 | .TP | |
845 | .B @isrecent@ | |
846 | Expands to \fBtrue\fR if the recently played list has any tracks in it, | |
847 | otherwise to \fBfalse\fR. | |
848 | .TP | |
849 | .B @label:\fINAME\fR\fB@ | |
850 | Expands to the value of label \fINAME\fR. See the shipped \fIoptions.labels\fR | |
851 | file for full documentation of the labels used by the standard templates. | |
852 | .TP | |
853 | .B @length@ | |
854 | Expands to the length of the current track. | |
855 | .TP | |
856 | .B @navigate{\fIDIRECTORY\fB}{\fITEMPLATE\fB} | |
857 | Expands \fITEMPLATE\fR for each component of \fIDIRECTORY\fR in turn. | |
858 | Use \fB@dirname\fR and \fB@basename@\fR to get the components of the path to | |
859 | each component. | |
860 | Usually used in \fBchoose.html\fR. | |
861 | .TP | |
862 | .B @ne{\fIA\fB}{\fIB\fB} | |
863 | Expands to \fBtrue\fR if \fIA\fR and \fIB\fR differ, otherwise to \fBfalse\fR. | |
864 | .TP | |
d5b6ffd7 RK |
865 | .B @new{\fITEMPLATE\fB} |
866 | Expands \fITEMPLATE\fR for each track in the newly added tracks list, starting | |
867 | with the most recent. Used in \fBnew.html\fR. | |
868 | .TP | |
460b9539 | 869 | .B @nfiles@ |
870 | Expands to the number of files from \fB@files\fR (above). | |
871 | .TP | |
872 | .B @nonce@ | |
873 | Expands to a string including the time and process ID, intended to be | |
874 | unique across invocations. | |
875 | .TP | |
876 | .B @not{\fIBOOL\fB}@ | |
877 | Expands to \fBfalse\fR if \fIBOOL\fR is \fBtrue\fR, otherwise to | |
878 | \fBfalse\fR. | |
879 | .TP | |
880 | .B @or{\fIBOOL\fB}{\fIBOOL\fB}\fR...\fB@ | |
881 | If at least one argument is \fBtrue\fB, then expands to \fBtrue\fR, otherwise | |
882 | to \fBfalse\fR. | |
883 | .TP | |
884 | .B @parity@ | |
885 | Expands to \fBeven\fR or \fBodd\fR depending on whether the current track is at | |
886 | an even or odd position in \fB@queue@\fR, \fB@recent@\fR or \fB@files@\fR. | |
887 | .TP | |
888 | .B @part{\fICONTEXT\fB}{\fIPART\fB}@ | |
889 | Expands to track name part \fIPART\fR using context \fICONTEXT\fR for the | |
61507e3c | 890 | current track. The context may be omitted and defaults |
460b9539 | 891 | to \fBdisplay\fR. |
61507e3c RK |
892 | .IP |
893 | The special context \fBshort\fR is equivalent to \fBdisplay\fR but limited to | |
894 | the \fBshort_display\fR limit. | |
460b9539 | 895 | .TP |
896 | .B @part{\fICONTEXT\fB}{\fIPART\fB}{\fITRACK\fB}@ | |
897 | Expands to track name part \fIPART\fR using context \fICONTEXT\fR for | |
898 | \fITRACK\fR. In this usage the context may not be omitted. | |
61507e3c RK |
899 | .IP |
900 | The special context \fBshort\fR is equivalent to \fBdisplay\fR but limited to | |
901 | the \fBshort_display\fR limit. | |
460b9539 | 902 | .TP |
903 | .B @paused@ | |
904 | Expands to \fBtrue\fR if the current track is paused, else \fBfalse\fR. | |
905 | .TP | |
906 | .B @playing{\fITEMPLATE\fB}@ | |
907 | Expands \fITEMPLATE\fR using the playing track as the current track. | |
908 | .TP | |
909 | .B @pref{\fITRACK\fB}{\fIKEY\fB}@ | |
910 | Expand to the track preference, or the empty string if it is not set. | |
911 | .TP | |
912 | .B @prefname@ | |
913 | Expands to the name of the current preference, in the template | |
914 | argument of \fB@prefs@\fR. | |
915 | .TP | |
916 | .B @prefs{\fIFILE\fB}{\fITEMPLATE\fB}@ | |
917 | Expands \fITEMPLATE\fR repeatedly, for each preference of track | |
918 | \fIFILE\fR. | |
919 | Use \fB@prefname@\fR and \fB@prefvalue@\fR to get the name and value. | |
920 | .TP | |
921 | .B @prefvalue@ | |
922 | Expands to the value of the current preference, in the template | |
923 | argument of \fB@prefs@\fR. | |
924 | .TP | |
925 | .B @queue{\fITEMPLATE\fB}@ | |
926 | Expands \fITEMPLATE\fR repeatedly using the each track on the queue in turn as | |
927 | the current track. The track at the head of the queue comes first. | |
928 | .TP | |
929 | .B @random-enabled@ | |
930 | Expands to \fBtrue\fR if random play is currently enabled, otherwise to | |
931 | \fBfalse\fR. | |
932 | .TP | |
933 | .B @recent{\fITEMPLATE\fB}@ | |
934 | Expands \fITEMPLATE\fR repeatedly using the each recently played track in turn | |
935 | as the current track. The most recently played track comes first. | |
936 | .TP | |
937 | .B @resolve{\fITRACK\fB}@ | |
938 | Resolve aliases for \fITRACK\fR and expands to the result. | |
939 | .TP | |
940 | .B @search{\fIPART\fB}\fR[\fB{\fICONTEXT\fB}\fR]\fB{\fITEMPLATE\fB}@ | |
941 | Expands \fITEMPLATE\fR once for each group of search results that have | |
942 | a common value of track part \fIPART\fR. | |
943 | The groups are sorted by the value of the part. | |
944 | .IP | |
945 | .B @part@ | |
946 | and | |
947 | .B @file@ | |
948 | within the template will apply to one of the tracks in the group. | |
949 | .IP | |
950 | If \fICONTEXT\fR is specified it should be either \fBsort\fR or \fBdisplay\fR, | |
951 | and determines the context for \fIPART\fR. The default is \fBsort\fR. Usually | |
952 | you want \fBdisplay\fR for everything except the title and \fBsort\fR for the | |
953 | title. If you use \fBsort\fR for artist and album then you are likely to get | |
954 | strange effects. | |
955 | .TP | |
956 | .B @server-version@ | |
957 | Expands to the server's version string. | |
958 | .TP | |
959 | .B @shell{\fICOMMAND\fB}@ | |
960 | Expands to the output of \fICOMMAND\fR executed via the shell. \fBsh\fR is | |
961 | searched for using \fBPATH\fR. If the command fails then this is logged but | |
962 | otherwise ignored. | |
963 | .TP | |
964 | .B @state@ | |
965 | In \fB@queue@\fR and \fB@recent@\fR, expands to the state of the current | |
966 | track. Otherwise the empty string. Known states are: | |
967 | .RS | |
968 | .TP 12 | |
969 | .B failed | |
970 | The player terminated with nonzero status, but not because the track was | |
971 | scratched. | |
972 | .TP | |
973 | .B isscratch | |
974 | A scratch, in the queue. | |
975 | .TP | |
976 | .B no_player | |
977 | No player could be found. | |
978 | .TP | |
979 | .B ok | |
980 | Played successfully. | |
981 | .TP | |
982 | .B random | |
983 | A randomly chosen track, in the queue. | |
984 | .TP | |
985 | .B scratched | |
986 | This track was scratched. | |
987 | .TP | |
988 | .B unplayed | |
989 | An explicitly queued track, in the queue. | |
990 | .RE | |
991 | .IP | |
992 | Some additional states only apply to playing tracks, so will never be seen in | |
993 | the queue or recently-played list: | |
994 | .RS | |
995 | .TP 12 | |
996 | .B paused | |
997 | The track has been paused. | |
998 | .TP | |
999 | .B quitting | |
1000 | Interrupted because the server is shutting down. | |
1001 | .TP | |
1002 | .B started | |
1003 | This track is currently playing. | |
1004 | .RE | |
1005 | .TP | |
1006 | .B @stats@ | |
1007 | Expands to the server statistics. | |
1008 | .TP | |
1009 | .B @thisurl@ | |
1010 | Expands to the URL of the current page. Typically used in | |
1011 | .B back | |
1012 | arguments. If there is a | |
1013 | .B nonce | |
1014 | argument then it is changed to a fresh value. | |
1015 | .TP | |
1016 | .B @track@ | |
1017 | The current track. | |
1018 | .TP | |
1019 | .B @trackstate{\fIPATH\fB}@ | |
1020 | Expands to the current track state: \fBplaying\fR if the track is actually | |
1021 | playing now, \fBqueued\fR if it is queued or the empty string otherwise. | |
1022 | .TP | |
1023 | .B @transform{\fIPATH\fB}{\fITYPE\fB}{\fICONTEXT\fB}@ | |
1024 | Transform a path according to \fBtransform\fR (see above). | |
1025 | \fIPATH\fR should be a raw filename (of a track or directory). | |
1026 | \fITYPE\fR should be the transform type (e.g. \fItrack\fR or \fIdir\fR). | |
1027 | \fICONTEXT\fR should be the context, and can be omitted (the default | |
1028 | is \fBdisplay\fR). | |
1029 | .TP | |
1030 | .B @url@ | |
1031 | Expands to the canonical URL as defined in \fIpkgconfdir/config\fR. | |
1032 | .TP | |
1033 | .B @urlquote{\fISTRING\fB}@ | |
1034 | URL-quote \fISTRING\fR. | |
1035 | .TP | |
1036 | .B @version@ | |
1037 | Expands to \fBdisorder.cgi\fR's version string. | |
1038 | .TP | |
1039 | .B @volume:\fISPEAKER\fB@ | |
40c30921 | 1040 | The volume on the left or right speaker. \fISPEAKER\fR must be \fBleft\fR or |
460b9539 | 1041 | \fBright\fR. |
1042 | .TP | |
1043 | .B @when@ | |
1044 | When the current track was played (or when it is expected to be played, if it | |
1045 | has not been played yet) | |
1046 | .TP | |
1047 | .B @who@ | |
1048 | Who submitted the current track. | |
1049 | .SH "WEB OPTIONS" | |
1050 | This is a file called \fIoptions\fR, searched for in the same manner | |
1051 | as templates. It includes numerous options for the control of the web | |
1052 | interface. The general syntax is the same as the main configuration | |
1053 | file, except that it should be encoded using UTF-8 (though this might | |
1054 | change to the current locale's character encoding; stick to ASCII to | |
1055 | be safe). | |
1056 | .PP | |
1057 | The shipped \fIoptions\fR file includes four standard options files. | |
1058 | In order, they are: | |
1059 | .TP | |
1060 | .I options.labels | |
1061 | The default labels file. You wouldn't normally edit this directly - instead | |
1062 | supply your own commands in \fIoptions.user\fR. Have a look at the shipped | |
1063 | version of the file for documentation of labels used by the standard templates. | |
1064 | .TP | |
1065 | .I options.user | |
1066 | A user options file. Here you should put any overrides for the default | |
1067 | labels and any extra labels required by your modified templates. | |
1068 | .PP | |
1069 | Valid directives are: | |
1070 | .TP | |
1071 | .B columns \fINAME\fR \fIHEADING\fR... | |
1072 | Defines the columns used in \fB@playing@\fR and \fB@recent@\fB. \fINAME\fR | |
1073 | must be either \fBplaying\fR, \fBrecent\fR or \fBsearch\fR. | |
1074 | \fIHEADING\fR... is a list of | |
1075 | heading names. If a column is defined more than once then the last definitions | |
1076 | is used. | |
1077 | .IP | |
1078 | The heading names \fBbutton\fR, \fBlength\fR, \fBwhen\fR and \fBwho\fR | |
1079 | are built in. | |
1080 | .TP | |
1081 | .B include \fIPATH\fR | |
1082 | Includes another file. If \fIPATH\fR starts with a \fB/\fR then it is | |
1083 | taken as is, otherwise it is searched for in the template path. | |
1084 | .TP | |
1085 | .B label \fINAME\fR \fIVALUE\fR | |
1086 | Define a label. If a label is defined more than once then the last definition | |
1087 | is used. | |
1088 | .SS Labels | |
1089 | Some labels are defined inside \fBdisorder.cgi\fR and others by the | |
1090 | default templates. You can define your own labels and use them inside | |
1091 | a template. | |
1092 | .PP | |
1093 | When an undefined label is expanded, if it has a dot in its name then | |
1094 | the part after the final dot is used as its value. Otherwise the | |
1095 | whole name is used as the value. | |
1096 | .PP | |
1097 | Labels are no longer documented here, see the shipped \fIoptions.labels\fR file | |
1098 | instead. | |
1099 | .SH "REGEXP SUBSTITUTION RULES" | |
1100 | Regexps are PCRE regexps, as defined in \fBpcrepattern\fR(3). The | |
1101 | only option used is \fBPCRE_UTF8\fR. Remember that the configuration | |
1102 | file syntax means you have to escape backslashes and quotes inside | |
1103 | quoted strings. | |
1104 | .PP | |
1105 | In a \fISUBST\fR string the following sequences are interpreted | |
1106 | specially: | |
1107 | .TP | |
1108 | .B $1 \fR... \fB$9 | |
1109 | These expand to the first to ninth bracketed subexpression. | |
1110 | .TP | |
1111 | .B $& | |
1112 | This expands to the matched part of the subject string. | |
1113 | .TP | |
1114 | .B $$ | |
1115 | This expands to a single \fB$\fR symbol. | |
1116 | .PP | |
1117 | All other pairs starting with \fB$\fR are undefined (and might be used | |
1118 | for something else in the future, so don't rely on the current | |
1119 | behaviour.) | |
1120 | .PP | |
1121 | If \fBi\fR is present in \fIREFLAGS\fR then the match is case-independent. If | |
1122 | \fBg\fR is present then all matches are replaced, otherwise only the first | |
1123 | match is replaced. | |
1124 | .SH "ACTIONS" | |
1125 | What the web interface actually does is terminated by the \fBaction\fR CGI | |
1126 | argument. The values listed below are supported. | |
1127 | .PP | |
1128 | Except as specified, all actions redirect back to the \fBplaying.html\fR | |
1129 | template unless the \fBback\fR argument is present, in which case the URL it | |
1130 | gives is used instead. | |
1131 | .PP | |
1132 | Redirection to \fBplaying.html\fR preserves \fBmgmt=true\fR if it is present. | |
1133 | .TP 8 | |
1134 | .B "move" | |
1135 | Move track \fBid\fR by offset \fBdelta\fR. | |
1136 | .TP | |
1137 | .B "play" | |
1138 | Play track \fBfile\fR, or if that is missing then play all the tracks in | |
1139 | \fBdirectory\fR. | |
1140 | .TP | |
1141 | .B "playing" | |
1142 | Don't change any state, but instead compute a suitable refresh time and include | |
1143 | that in an HTTP header. Expands the \fBplaying.html\fR template rather than | |
1144 | redirecting. | |
1145 | .IP | |
1146 | This is the default if \fBaction\fR is missing. | |
1147 | .TP | |
1148 | .B "random-disable" | |
1149 | Disables random play. | |
1150 | .TP | |
1151 | .B "random-enable" | |
1152 | Enables random play. | |
1153 | .TP | |
1154 | .B "disable" | |
1155 | Disables play completely. | |
1156 | .TP | |
1157 | .B "enable" | |
1158 | Enables play. | |
1159 | .TP | |
1160 | .B "pause" | |
1161 | Pauses the current track. | |
1162 | .TP | |
1163 | .B "remove" | |
1164 | Remove track \fBid\fR. | |
1165 | .TP | |
1166 | .B "resume" | |
1167 | Resumes play after a pause. | |
1168 | .TP | |
1169 | .B "scratch" | |
1170 | Scratch the playing track. If \fBid\fR is present it must match the playing | |
1171 | track. | |
1172 | .TP | |
1173 | .B "volume" | |
1174 | Change the volume by \fBdelta\fR, or if that is missing then set it to the | |
1175 | values of \fBleft\fR and \fBright\fR. Expands to the \fBvolume.html\fR template | |
1176 | rather than redirecting. | |
1177 | .TP | |
1178 | .B "prefs" | |
1179 | Adjust preferences from the \fBprefs.html\fR template (which it then expands | |
1180 | rather than redirecting). | |
1181 | .IP | |
1182 | If | |
1183 | .B parts | |
1184 | is set then the cooked interface is assumed. The value of | |
1185 | .B parts | |
1186 | is used to determine which trackname preferences are set. By default the | |
1187 | .B display | |
1188 | context is adjusted but this can be overridden with the | |
1189 | .B context | |
1190 | argument. Also the | |
1191 | .B random | |
1192 | argument is checked; if it is set then random play is enabled for that track, | |
1193 | otherwise it is disabled. | |
1194 | .IP | |
1195 | Otherwise if the | |
1196 | .B name | |
1197 | and | |
1198 | .B value | |
1199 | arguments are set then they are used to set a single preference. | |
1200 | .IP | |
1201 | Otherwise if just the | |
1202 | .B name | |
1203 | argument is set then that preference is deleted. | |
1204 | .IP | |
1205 | It is recommended that links to the \fBprefs\fR action use \fB@resolve@\fR to | |
1206 | enure that the real track name is always used. Otherwise if the preferences | |
1207 | page is used to adjust a trackname_ preference, the alias may change, leading | |
1208 | to the URL going stale. | |
1209 | .TP | |
1210 | .B "error" | |
1211 | This action is generated automatically when an error occurs connecting to the | |
1212 | server. The \fBerror\fR label is set to an indication of what the error is. | |
1213 | .SH "TRACK NAME PARTS" | |
1214 | The traditional track name parts are \fBartist\fR, \fBalbum\fR and \fBtitle\fR, | |
1215 | with the obvious intended meaning. These are controlled by configuration and | |
1216 | by \fBtrackname_\fR preferences. | |
1217 | .PP | |
1218 | In addition there are two built-in parts, \fBpath\fR which is the whole path | |
1219 | name and \fBext\fR which is the filename extension, including the initial dot | |
1220 | (or the empty string if there is not extension). | |
1221 | .SH "SEE ALSO" | |
77cfc7a2 | 1222 | \fBdisorder\fR(1), \fBsox\fR(1), \fBdisorderd\fR(8), \fBdisorder-dump\fR(8), |
460b9539 | 1223 | \fBpcrepattern\fR(3) |
1224 | .\" Local Variables: | |
1225 | .\" mode:nroff | |
1226 | .\" fill-column:79 | |
1227 | .\" End: |