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