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