| 1 | .\" |
| 2 | .\" Copyright (C) 2004-2009 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 3 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, |
| 10 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 11 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 12 | .\" GNU General Public License for more details. |
| 13 | .\" |
| 14 | .\" You should have received a copy of the GNU General Public License |
| 15 | .\" along with this program. If not, see <http://www.gnu.org/licenses/>. |
| 16 | .\" |
| 17 | .TH disorder_config 5 |
| 18 | .SH NAME |
| 19 | pkgconfdir/config - DisOrder jukebox configuration |
| 20 | .SH DESCRIPTION |
| 21 | The purpose of DisOrder is to organize and play digital audio files, under the |
| 22 | control of multiple users. |
| 23 | \fIpkgconfdir/config\fR is the primary configuration file; the web interface |
| 24 | uses a number of others (see \fBdisorder.cgi\fR(8)). |
| 25 | .SS Tracks |
| 26 | DisOrder can be configured with multiple collections of tracks, indexing them |
| 27 | by their filename, and picking players on the basis of filename patterns (for |
| 28 | instance, "*.mp3"). |
| 29 | .PP |
| 30 | Although the model is of filenames, it is not inherent that there are |
| 31 | corresponding real files - merely that they can be interpreted by the chosen |
| 32 | player. |
| 33 | See \fBdisorder\fR(3) for more details about this. |
| 34 | .PP |
| 35 | Each track can have a set of preferences associated with it. |
| 36 | These are simple key-value pairs; they can be used for anything you |
| 37 | like, but a number of keys have specific meanings. |
| 38 | See \fBdisorder_preferences\fR(5) 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. |
| 43 | They can be overridden by setting preferences. |
| 44 | .PP |
| 45 | Names for display are distinguished from names for sorting, so with the right |
| 46 | underlying filenames an album can be displayed in its original order even if |
| 47 | the displayed track titles are not lexically sorted. |
| 48 | .SS "Server State" |
| 49 | A collection of global preferences define various bits of server state: whether |
| 50 | random play is enabled, what tags to check for when picking at random, etc. |
| 51 | See \fBdisorder_preferences\fR(5) for more information. |
| 52 | .SS "Users And Access Control" |
| 53 | DisOrder distinguishes between multiple users. |
| 54 | This is for access control and reporting, not to provide different |
| 55 | views of the world: i.e. preferences and so on are global. |
| 56 | .PP |
| 57 | Each user has an associated set of rights which contorl which commands they may |
| 58 | execute. |
| 59 | Normally you would give all users most rights, and expect them to |
| 60 | cooperate (they are after all presumed to be in a shared sound environment). |
| 61 | .PP |
| 62 | The full set of rights are: |
| 63 | .TP |
| 64 | .B read |
| 65 | User can perform read-only operations |
| 66 | .TP |
| 67 | .B play |
| 68 | User can add tracks to the queue |
| 69 | .TP |
| 70 | .B "move any" |
| 71 | User can move any track |
| 72 | .TP |
| 73 | .B "move mine" |
| 74 | User can move their own tracks |
| 75 | .TP |
| 76 | .B "move random" |
| 77 | User can move randomly chosen tracks |
| 78 | .TP |
| 79 | .B "remove any" |
| 80 | User can remove any track |
| 81 | .TP |
| 82 | .B "remove mine" |
| 83 | User can remove their own tracks |
| 84 | .TP |
| 85 | .B "remove random" |
| 86 | User can remove randomly chosen tracks |
| 87 | .TP |
| 88 | .B "scratch any" |
| 89 | User can scratch any track |
| 90 | .TP |
| 91 | .B "scratch mine" |
| 92 | User can scratch their own tracks |
| 93 | .TP |
| 94 | .B "scratch random" |
| 95 | User can scratch randomly chosen tracks |
| 96 | .TP |
| 97 | .B volume |
| 98 | User can change the volume |
| 99 | .TP |
| 100 | .B admin |
| 101 | User can perform admin operations |
| 102 | .TP |
| 103 | .B rescan |
| 104 | User can initiate a rescan |
| 105 | .TP |
| 106 | .B register |
| 107 | User can register new users. |
| 108 | Normally only the |
| 109 | .B guest |
| 110 | user would have this right. |
| 111 | .TP |
| 112 | .B userinfo |
| 113 | User can edit their own userinfo |
| 114 | .TP |
| 115 | .B prefs |
| 116 | User can modify track preferences |
| 117 | .TP |
| 118 | .B "global prefs" |
| 119 | User can modify global preferences |
| 120 | .TP |
| 121 | .B pause |
| 122 | User can pause/resume |
| 123 | .PP |
| 124 | Access control is entirely used-based. |
| 125 | If you configure DisOrder to listen for TCP/IP connections then it will |
| 126 | accept a connection from anywhere provided the right password is |
| 127 | available. |
| 128 | Passwords are never transmitted over TCP/IP connections in clear, |
| 129 | but everything else is. |
| 130 | The expected model is that host-based access control is imposed at |
| 131 | the network layer. |
| 132 | .SS "Web Interface" |
| 133 | The web interface is controlled by a collection of template files, one for each |
| 134 | kind of page, and a collection of option files. |
| 135 | These are split up and separate from the main configuration file to |
| 136 | .PP |
| 137 | See \fBdisorder.cgi\fR(8) for more information. |
| 138 | .SS "Searching And Tags" |
| 139 | Search strings contain a list of search terms separated by spaces. |
| 140 | A search term can either be a single word or a tag, prefixed with "tag:". |
| 141 | .PP |
| 142 | Search words are compared without regard to letter case or accents; thus, all |
| 143 | of the following will be considered to be equal to one another: |
| 144 | .PP |
| 145 | .nf |
| 146 | LATIN CAPITAL LETTER E |
| 147 | LATIN SMALL LETTER E |
| 148 | LATIN CAPITAL LETTER E WITH GRAVE |
| 149 | LATIN SMALL LETTER E WITH GRAVE |
| 150 | LATIN CAPITAL LETTER E plus COMBINING GRAVE ACCENT |
| 151 | LATIN SMALL LETTER E plus COMBINING GRAVE ACCENT |
| 152 | .fi |
| 153 | .PP |
| 154 | The same rules apply to tags but in addition leading and trailing whitespace is |
| 155 | disregarded and all whitespace sequences are treated as equal when they appear |
| 156 | as internal whitespace. |
| 157 | .PP |
| 158 | Where several tags are listed, for instance the tags preference for a track, |
| 159 | the tags are separated by commas. |
| 160 | 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). |
| 165 | Comments are started by the number 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. |
| 170 | Inside quoted fields every character stands for itself, except that |
| 171 | a backslash can only appear as part of one of the following escape sequences: |
| 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. |
| 190 | Lines with no fields are ignored. |
| 191 | .PP |
| 192 | After editing the config file use \fBdisorder reconfigure\fR to make |
| 193 | it re-read it. |
| 194 | If there is anything wrong with it the daemon will record a log |
| 195 | message and ignore the new config file. |
| 196 | (You should fix it before next terminating and restarting the daemon, |
| 197 | as it cannot start up without a valid config file.) |
| 198 | .SS "Configuration Files" |
| 199 | Configuration files are read in the following order: |
| 200 | .TP |
| 201 | .I pkgconfdir/config |
| 202 | .TP |
| 203 | .I pkgconfdir/config.private |
| 204 | Should be readable only by the jukebox group. |
| 205 | Not really useful any more and will be abolished in future. |
| 206 | .TP |
| 207 | .I ~\fRUSERNAME\fI/.disorder/passwd |
| 208 | Per-user client configuration. |
| 209 | Optional but if it exists must be readable only by the relevant user. |
| 210 | Would normally contain a \fBpassword\fR directive. |
| 211 | .TP |
| 212 | .I pkgconfdir/config.\fRUSERNAME |
| 213 | Per-user system-controlled client configuration. |
| 214 | Optional but if it exists must be readable only by the relevant user. |
| 215 | Would normally contain a \fBpassword\fR directive. |
| 216 | .IP |
| 217 | The prefererred location for per-user passwords is \fI~/.disorder/passwd\fR and |
| 218 | \fBdisorder authorize\fR writes there now. |
| 219 | .SS "Global Configuration" |
| 220 | .TP |
| 221 | .B home \fIDIRECTORY\fR |
| 222 | The home directory for state files. |
| 223 | Defaults to |
| 224 | .IR pkgstatedir . |
| 225 | The server will create this directory on startup if it does not exist. |
| 226 | .TP |
| 227 | .B plugins \fIPATH\fR |
| 228 | Adds a directory to the plugin path. |
| 229 | (This is also used by the web interface.) |
| 230 | .IP |
| 231 | Plugins are opened the first time they are required and never after, |
| 232 | so after changing a plugin you must restart the server before it is |
| 233 | guaranteed to take effect. |
| 234 | .IP |
| 235 | If |
| 236 | .B plugins |
| 237 | is used without arguments the plugin path is cleared. |
| 238 | .SS "Server Configuration" |
| 239 | .TP |
| 240 | .B alias \fIPATTERN\fR |
| 241 | Defines the pattern use construct virtual filenames from \fBtrackname_\fR |
| 242 | preferences. |
| 243 | .IP |
| 244 | Most characters stand for themselves, the exception being \fB{\fR which is used |
| 245 | to insert a track name part in the form \fB{\fIname\fB}\fR or |
| 246 | \fB{/\fIname\fB}\fR. |
| 247 | .IP |
| 248 | The difference is that the first form just inserts the name part while the |
| 249 | second prefixes it with a \fB/\fR if it is nonempty. |
| 250 | .IP |
| 251 | The pattern should not attempt to include the collection root, which is |
| 252 | automatically included, but should include the proper extension. |
| 253 | .IP |
| 254 | The default is \fB{/artist}{/album}{/title}{ext}\fR. |
| 255 | .TP |
| 256 | .B api \fINAME\fR |
| 257 | Selects the backend used to play sound and to set the volume. |
| 258 | The following options are available: |
| 259 | .RS |
| 260 | .TP |
| 261 | .B alsa |
| 262 | Use the ALSA API. |
| 263 | This is only available on Linux systems, on which it is the default. |
| 264 | .TP |
| 265 | .B coreaudio |
| 266 | Use Apple Core Audio. |
| 267 | This only available on OS X systems, on which it is the default. |
| 268 | .TP |
| 269 | .B oss |
| 270 | Use the OSS (/dev/dsp) API. |
| 271 | Not available on all platforms. |
| 272 | .TP |
| 273 | .B command |
| 274 | Execute a command. |
| 275 | This is the default if |
| 276 | .B speaker_command |
| 277 | is specified, or if no native is available. |
| 278 | .IP |
| 279 | You might want to set |
| 280 | .B pause_mode |
| 281 | with this backend. |
| 282 | .TP |
| 283 | .B rtp |
| 284 | Transmit audio over the network. |
| 285 | This is the default if \fBbroadcast\fR is specified. |
| 286 | You can use |
| 287 | .BR disorder-playrtp (1) |
| 288 | to receive and play the resulting stream on Linux and OS X. |
| 289 | .B network |
| 290 | is a deprecated synonym for this API. |
| 291 | .RE |
| 292 | .TP |
| 293 | .B authorization_algorithm \fIALGORITHM\fR |
| 294 | Defines the algorithm used to authenticate clients. |
| 295 | The valid options are sha1 (the default), sha256, sha384 and sha512. |
| 296 | See |
| 297 | .BR disorder_protocol (5) |
| 298 | for more details. |
| 299 | .TP |
| 300 | .B broadcast \fR[\fIFAMILY\fR] \fIADDRESS\fR \fIPORT\fR |
| 301 | Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR. |
| 302 | This implies \fBapi rtp\fR. |
| 303 | .IP |
| 304 | \fIFAMILY\fR can be \fB-4\fR or \fB-6\fR to force IPv4 or IPv6, if this is not |
| 305 | implied by \fIADDRESS\fR. |
| 306 | Note that IPv6 is not currently well tested. |
| 307 | .IP |
| 308 | See also \fBmulticast_loop\fR and \fBmulticast_ttl\fR. |
| 309 | .TP |
| 310 | .B broadcast_from \fR[\fIFAMILY\fR] \fIADDRESS\fR \fIPORT\fR |
| 311 | Sets the (local) source address used by \fBbroadcast\fR. |
| 312 | .IP |
| 313 | \fIFAMILY\fR can be \fB-4\fR or \fB-6\fR to force IPv4 or IPv6, if this is not |
| 314 | implied by \fIADDRESS\fR. |
| 315 | Note that IPv6 is not currently well tested. |
| 316 | .TP |
| 317 | .B channel \fICHANNEL\fR |
| 318 | The mixer channel that the volume control should use. |
| 319 | .IP |
| 320 | For \fBapi oss\fR the possible values are: |
| 321 | .RS |
| 322 | .TP 8 |
| 323 | .B pcm |
| 324 | |
| 325 | Output level for the audio device. |
| 326 | This is probably what you want and is the default. |
| 327 | .TP |
| 328 | .B speaker |
| 329 | Output level for the PC speaker, if that is connected to the sound card. |
| 330 | .TP |
| 331 | .B pcm2 |
| 332 | Output level for alternative codec device. |
| 333 | .TP |
| 334 | .B vol |
| 335 | Master output level. |
| 336 | The OSS documentation recommends against using this, as it affects all |
| 337 | output devices. |
| 338 | .RE |
| 339 | .IP |
| 340 | You can also specify channels by number, if you know the right value. |
| 341 | .IP |
| 342 | For \fBapi alsa\fR, this is the name of the mixer control to use. |
| 343 | The default is \fBPCM\fR. |
| 344 | Use \fBamixer scontrols\fR or similar to get a full list. |
| 345 | .IP |
| 346 | For \fBapi coreaudio\fR, volume setting is not currently supported. |
| 347 | .TP |
| 348 | .B collection \fIMODULE\fR \fIENCODING\fR \fIROOT\fR |
| 349 | .TP |
| 350 | .B collection \fIMODULE\fR \fIROOT\fR |
| 351 | .TP |
| 352 | .B collection \fIROOT\fR |
| 353 | Define a collection of tracks. |
| 354 | .IP |
| 355 | \fIMODULE\fR defines which plugin module should be used for this |
| 356 | collection. |
| 357 | Use the supplied \fBfs\fR module for tracks that exist as ordinary |
| 358 | files in the filesystem. |
| 359 | If no \fIMODULE\fR is specified then \fBfs\fR is assumed. |
| 360 | .IP |
| 361 | \fIENCODING\fR defines the encoding of filenames in this collection. |
| 362 | For \fBfs\fR this would be the encoding you use for filenames. |
| 363 | Examples might be \fBiso\-8859\-1\fR or \fButf\-8\fR. |
| 364 | If no encoding is specified then the current locale's character encoding |
| 365 | is used. |
| 366 | .IP |
| 367 | NB that this default depends on the locale the server runs in, which is not |
| 368 | necessarily the same as that of ordinary users, depending how the system is |
| 369 | configured. |
| 370 | It's best to explicitly specify it to be certain. |
| 371 | .IP |
| 372 | \fIROOT\fR is the root in the filesystem of the filenames and is |
| 373 | passed to the plugin module. |
| 374 | It must be an absolute path and should not end with a "/". |
| 375 | .TP |
| 376 | .B cookie_key_lifetime \fISECONDS\fR |
| 377 | Lifetime of the signing key used in constructing cookies. The default is one |
| 378 | week. |
| 379 | .TP |
| 380 | .B cookie_login_lifetime \fISECONDS\fR |
| 381 | Lifetime of a cookie enforced by the server. When the cookie expires the user |
| 382 | will have to log in again even if their browser has remembered the cookie that |
| 383 | long. The default is one day. |
| 384 | .TP |
| 385 | .B default_rights \fIRIGHTS\fR |
| 386 | Defines the set of rights given to new users. |
| 387 | The argument is a comma-separated list of rights. |
| 388 | For the possible values see |
| 389 | .B "Users And Access Control" |
| 390 | above. |
| 391 | .IP |
| 392 | The default is to allow everything except \fBadmin\fR and \fBregister\fR |
| 393 | (modified in legacy configurations by the obsolete \fBrestrict\fR directive). |
| 394 | .TP |
| 395 | .B device \fINAME\fR |
| 396 | Sound output device. |
| 397 | .IP |
| 398 | For \fBapi oss\fR this is the path to the device to use. |
| 399 | If it is set to \fBdefault\fR then \fI/dev/dsp\fR and \fI/dev/audio\fR |
| 400 | will be tried. |
| 401 | .IP |
| 402 | For \fBapi alsa\fR this is the device name to use. |
| 403 | .IP |
| 404 | For \fBapi coreaudio\fR this can be either the UID or the human-readable |
| 405 | name of the desired device. |
| 406 | For a list of names, visit System Preferences -> Sound and look at the Type column. |
| 407 | For example, you might use "Built-in Output" for the built-in speaker |
| 408 | or "Built-in Line Output" if you have connected external speakers. |
| 409 | Remember to quote the name. |
| 410 | .IP |
| 411 | The default is \fBdefault\fR, which is intended to map to whatever the system's |
| 412 | default is. |
| 413 | .TP |
| 414 | .B gap \fISECONDS\fR |
| 415 | Specifies the number of seconds to leave between tracks. |
| 416 | The default is 0. |
| 417 | .IP |
| 418 | NB this option currently DOES NOT WORK. If there is genuine demand it might be |
| 419 | reinstated. |
| 420 | .TP |
| 421 | .B history \fIINTEGER\fR |
| 422 | Specifies the number of recently played tracks to remember (including |
| 423 | failed tracks and scratches). |
| 424 | .TP |
| 425 | .B listen \fR[\fIFAMILY\fR] \fR[\fIHOST\fR] \fISERVICE\fR |
| 426 | Listen for connections on the address specified by \fIHOST\fR and port |
| 427 | specified by \fISERVICE\fR. |
| 428 | If \fIHOST\fR is omitted, or is \fB*\fR, then listens on all local addresses. |
| 429 | .IP |
| 430 | \fIFAMILY\fR can be \fB-4\fR or \fB-6\fR to force IPv4 or IPv6, if this is not |
| 431 | implied by \fIHOST\fR. |
| 432 | Note that IPv6 is not currently well tested. |
| 433 | .IP |
| 434 | Normally the server only listens on a UNIX domain socket. |
| 435 | .TP |
| 436 | .B lock yes\fR|\fBno |
| 437 | Determines whether the server locks against concurrent operation. |
| 438 | Default is \fByes\fR. |
| 439 | There is no good reason to set this to \fBno\fR and the option will |
| 440 | probably be removed in a future version. |
| 441 | .TP |
| 442 | .B mixer \fIDEVICE\fR |
| 443 | The mixer device name, if it needs to be specified separately from |
| 444 | \fBdevice\fR. |
| 445 | .IP |
| 446 | For \fBapi oss\fR this should be the path to the mixer device and the default |
| 447 | is \fI/dev/mixer\fR. |
| 448 | .IP |
| 449 | For \fBapi alsa\fR, this is the index of the mixer control to use. |
| 450 | The default is 0. |
| 451 | .IP |
| 452 | For \fBapi coreaudio\fR, volume setting is not currently supported. |
| 453 | .TP |
| 454 | .B multicast_loop yes\fR|\fBno |
| 455 | Determines whether multicast packets are loop backed to the sending host. |
| 456 | The default is \fByes\fR. |
| 457 | This only applies if \fBapi\fR is set to \fBrtp\fR and \fBbroadcast\fR |
| 458 | is actually a multicast address. |
| 459 | .TP |
| 460 | .B multicast_ttl \fIHOPS\fR |
| 461 | Set the maximum number of hops to send multicast packets. |
| 462 | This only applies if \fBapi\fR is set to \fBrtp\fR and |
| 463 | \fBbroadcast\fR is actually a multicast address. |
| 464 | The default is 1. |
| 465 | .TP |
| 466 | .B namepart \fIPART\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]] |
| 467 | Determines how to extract trackname part \fIPART\fR from a |
| 468 | track name (with the collection root part removed). |
| 469 | Used in \fB@recent@\fR, \fB@playing@\fR and \fB@search@\fR. |
| 470 | .IP |
| 471 | Track names can be different in different contexts. |
| 472 | For instance the sort string might include an initial track number, |
| 473 | but this would be stripped for the display string. |
| 474 | \fICONTEXT\fR should be a glob pattern matching the |
| 475 | contexts in which this directive will be used. |
| 476 | .IP |
| 477 | Valid contexts are \fBsort\fR and \fBdisplay\fR. |
| 478 | .IP |
| 479 | All the \fBnamepart\fR directives are considered in order. |
| 480 | The first directive for the right part, that matches the desired context, |
| 481 | and with a \fIREGEXP\fR that |
| 482 | matches the track is used, and the value chosen is constructed from |
| 483 | \fISUBST\fR according to the substitution rules below. |
| 484 | .IP |
| 485 | Note that searches use the raw track name and \fBtrackname_\fR preferences but |
| 486 | not (currently) the results of \fBnamepart\fR, so generating words via this option |
| 487 | that aren't in the original track name will lead to confusing results. |
| 488 | .IP |
| 489 | If you supply no \fBnamepart\fR directives at all then a default set will be |
| 490 | supplied automatically. |
| 491 | But if you supply even one then you must supply all of them. |
| 492 | The defaults are equivalent to: |
| 493 | .PP |
| 494 | .nf |
| 495 | namepart title "/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display |
| 496 | namepart title "/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort |
| 497 | namepart album "/([^/]+)/[^/]+$" $1 * |
| 498 | namepart artist "/([^/]+)/[^/]+/[^/]+$" $1 * |
| 499 | namepart ext "(\\.[a-zA-Z0-9]+)$" $1 * |
| 500 | .fi |
| 501 | .TP |
| 502 | .B new_bias \fIWEIGHT\fR |
| 503 | The weight for new tracks. |
| 504 | The default is 450000, i.e. recently added tracks are a fifty times as likely |
| 505 | to be picked as normal. |
| 506 | .TP |
| 507 | .B new_bias_age \fISECONDS\fR |
| 508 | The maximum age of tracks that \fBnew_bias\fR applies to, in seconds. |
| 509 | The default is one week. |
| 510 | .TP |
| 511 | .B new_max \fIMAX\fR |
| 512 | The maximum number of tracks to list when reporting newly noticed tracks. |
| 513 | The default is 100. |
| 514 | .TP |
| 515 | .B nice_rescan \fIPRIORITY\fR |
| 516 | Set the recan subprocess priority. |
| 517 | The default is 10. |
| 518 | .IP |
| 519 | (Note that higher values mean the process gets less CPU time; UNIX priority |
| 520 | values are backwards.) |
| 521 | .TP |
| 522 | .B nice_server \fIPRIORITY\fR |
| 523 | Set the server priority. |
| 524 | This is applied to the server at startup time (and not when you reload |
| 525 | configuration). |
| 526 | The server does not use much CPU itself but this value is inherited |
| 527 | by programs it executes. |
| 528 | If you have limited CPU then it might help to set this to a small |
| 529 | negative value. |
| 530 | The default is 0. |
| 531 | .TP |
| 532 | .B nice_speaker \fIPRIORITY\fR |
| 533 | Set the speaker process priority. |
| 534 | This is applied to the speaker process at startup time (and not when |
| 535 | you reload the configuration). |
| 536 | The speaker process is not massively CPU intensive by today's |
| 537 | standards but depends on reasonably timely scheduling. |
| 538 | If you have limited CPU then it might help to set this to a small |
| 539 | negative value. |
| 540 | The default is 0. |
| 541 | .TP |
| 542 | .B noticed_history |
| 543 | The maximum days that a track can survive in the database of newly added |
| 544 | tracks. |
| 545 | The default is 31. |
| 546 | .TP |
| 547 | .B pause_mode \fIMODE |
| 548 | Sets the pause mode for the \fBcommand\fR backend. |
| 549 | The possible values are: |
| 550 | .RS |
| 551 | .TP |
| 552 | .B silence |
| 553 | Send silent (0-value) samples when paused. |
| 554 | This is the default. |
| 555 | .TP |
| 556 | .B suspend |
| 557 | Stop writing when paused. |
| 558 | .RE |
| 559 | .TP |
| 560 | .B player \fIPATTERN\fR \fIMODULE\fR [\fIOPTIONS.. [\fB\-\-\fR]] \fIARGS\fR... |
| 561 | Specifies the player for files matching the glob \fIPATTERN\fR. |
| 562 | \fIMODULE\fR specifies which plugin module to use. |
| 563 | .IP |
| 564 | The following options are supported: |
| 565 | .RS |
| 566 | .TP |
| 567 | .B \-\-wait\-for\-device\fR[\fB=\fIDEVICE\fR] |
| 568 | Waits (for up to a couple of seconds) for the default, or specified, libao |
| 569 | device to become openable. |
| 570 | .TP |
| 571 | .B \-\- |
| 572 | Defines the end of the list of options. |
| 573 | Needed if the first argument to the plugin starts with a "\-". |
| 574 | .RE |
| 575 | .IP |
| 576 | The following are the standard modules: |
| 577 | .RS |
| 578 | .TP |
| 579 | .B exec \fICOMMAND\fR \fIARGS\fR... |
| 580 | The command is executed via \fBexecvp\fR(3), not via the shell. |
| 581 | The \fBPATH\fR environment variable is searched for the executable if it is not |
| 582 | an absolute path. |
| 583 | The command is expected to know how to open its own sound device. |
| 584 | .TP |
| 585 | .B execraw \fICOMMAND\fR \fIARGS\fR... |
| 586 | Identical to the \fBexec\fR except that the player is expected to use the |
| 587 | DisOrder raw player protocol. |
| 588 | .BR disorder-decode (8) |
| 589 | can decode several common audio file formats to this format. |
| 590 | If your favourite format is not supported, but you have a player |
| 591 | which uses libao, there is also a libao driver which supports this format; |
| 592 | see below for more information about this. |
| 593 | .TP |
| 594 | .B shell \fR[\fISHELL\fR] \fICOMMAND\fR |
| 595 | The command is executed using the shell. |
| 596 | If \fISHELL\fR is specified then that is used, otherwise \fBsh\fR will be used. |
| 597 | In either case the \fBPATH\fR environment variable is searched for the shell |
| 598 | executable if it is not an absolute path. |
| 599 | The track name is stored in the environment variable |
| 600 | \fBTRACK\fR. |
| 601 | .IP |
| 602 | Be careful of the interaction between the configuration file quoting rules and |
| 603 | the shell quoting rules. |
| 604 | .RE |
| 605 | .IP |
| 606 | If multiple player commands match a track then the first match is used. |
| 607 | .IP |
| 608 | For the server to be able to calculate track lengths, there should be a |
| 609 | .B tracklength |
| 610 | command corresponding to each |
| 611 | .B player |
| 612 | command. |
| 613 | .IP |
| 614 | If |
| 615 | .B player |
| 616 | is used without arguments, the list of players is cleared. |
| 617 | .TP |
| 618 | .B prefsync \fISECONDS\fR |
| 619 | The interval at which the preferences log file will be synchronised. |
| 620 | Defaults to 3600, i.e. one hour. |
| 621 | .TP |
| 622 | .B queue_pad \fICOUNT\fR |
| 623 | The target size of the queue. |
| 624 | If random play is enabled then randomly picked tracks will be added until |
| 625 | the queue is at least this big. |
| 626 | The default is 10. |
| 627 | .TP |
| 628 | .B reminder_interval \fISECONDS\fR |
| 629 | The minimum number of seconds that must elapse between password reminders. |
| 630 | The default is 600, i.e. 10 minutes. |
| 631 | .TP |
| 632 | .B remote_userman yes\fR|\fBno |
| 633 | User management over TCP connection is only allowed if this is set to |
| 634 | \fByes\fR. By default it is set to \fBno\fR. |
| 635 | .TP |
| 636 | .B replay_min \fISECONDS\fR |
| 637 | The minimum number of seconds that must elapse after a track has been played |
| 638 | before it can be picked at random. The default is 8 hours. If this is set to |
| 639 | 0 then there is no limit, though current \fBdisorder-choose\fR will not pick |
| 640 | anything currently listed in the recently-played list. |
| 641 | .TP |
| 642 | .B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS |
| 643 | Describes the sample format expected by the \fBspeaker_command\fR (below). |
| 644 | The components of the format specification are as follows: |
| 645 | .RS |
| 646 | .TP 10 |
| 647 | .I BITS |
| 648 | The number of bits per sample. |
| 649 | Optionally, may be suffixed by \fBb\fR or \fBl\fR for big-endian and |
| 650 | little-endian words. |
| 651 | If neither is used the native byte order is assumed. |
| 652 | .TP |
| 653 | .I RATE |
| 654 | The number of samples per second. |
| 655 | .TP |
| 656 | .I CHANNELS |
| 657 | The number of channels. |
| 658 | .PP |
| 659 | The default is |
| 660 | .BR 16/44100/2 . |
| 661 | .PP |
| 662 | With the |
| 663 | .B rtp |
| 664 | backend the sample format is forced to |
| 665 | .B 16b/44100/2 |
| 666 | and with the |
| 667 | .B coreaudio |
| 668 | backend it is forced to |
| 669 | .BR 16/44100/2 , |
| 670 | in both cases regardless of what is specified in the configuration file. |
| 671 | .RE |
| 672 | .TP |
| 673 | .B signal \fINAME\fR |
| 674 | Defines the signal to be sent to track player process groups when tracks are |
| 675 | scratched. |
| 676 | The default is \fBSIGKILL\fR. |
| 677 | .IP |
| 678 | Signals are specified by their full C name, i.e. \fBSIGINT\fR and not \fBINT\fR |
| 679 | or \fBInterrupted\fR or whatever. |
| 680 | .TP |
| 681 | .B sox_generation \fB0\fR|\fB1 |
| 682 | Determines whether calls to \fBsox\fR(1) should use \fB\-b\fR, \fB\-x\fR, etc (if |
| 683 | the generation is 0) or \fB\-\fIbits\fR, \fB\-L\fR etc (if it is 1). |
| 684 | See the documentation for your installed copy of \fBsox\fR to determine |
| 685 | which you need. |
| 686 | The default is set according to the version of sox found when DisOrder was |
| 687 | built. |
| 688 | If you run on a system with a different version of sox, you will need to |
| 689 | set this option. |
| 690 | .TP |
| 691 | .B speaker_backend \fINAME |
| 692 | This is an alias for \fBapi\fR; see above. |
| 693 | .TP |
| 694 | .B speaker_command \fICOMMAND |
| 695 | Causes the speaker subprocess to pipe audio data into shell command |
| 696 | \fICOMMAND\fR, rather than writing to a local sound card. |
| 697 | The sample format is determine by |
| 698 | .B sample_format |
| 699 | above. |
| 700 | .IP |
| 701 | Note that if the sample format is wrong then |
| 702 | .BR sox (1) |
| 703 | is invoked to translate it. |
| 704 | If |
| 705 | .B sox |
| 706 | is not installed then this will not work. |
| 707 | .TP |
| 708 | .B scratch \fIPATH\fR |
| 709 | Specifies a scratch. |
| 710 | When a track is scratched, a scratch track is played at random. |
| 711 | Scratches are played using the same logic as other tracks. |
| 712 | .IP |
| 713 | At least for the time being, path names of scratches must be encoded using |
| 714 | UTF-8 (which means that ASCII will do). |
| 715 | .IP |
| 716 | If \fBscratch\fR is used without arguments then the list of scratches is |
| 717 | cleared. |
| 718 | .TP |
| 719 | .B stopword \fIWORD\fR ... |
| 720 | Specifies one or more stopwords that should not take part in searches |
| 721 | over track names. |
| 722 | .IP |
| 723 | If \fBstopword\fR is used without arguments then the list of stopwords is |
| 724 | cleared. |
| 725 | .IP |
| 726 | There is a default set of stopwords built in, but this option can be used to |
| 727 | augment or replace that list. |
| 728 | .TP |
| 729 | .B tracklength \fIPATTERN\fR \fIMODULE\fR |
| 730 | Specifies the module used to calculate the length of files matching |
| 731 | \fIPATTERN\fR. |
| 732 | \fIMODULE\fR specifies which plugin module to use. |
| 733 | .IP |
| 734 | If \fBtracklength\fR is used without arguments then the list of modules is |
| 735 | cleared. |
| 736 | .TP |
| 737 | .B user \fIUSERNAME\fR |
| 738 | Specifies the user to run as. |
| 739 | Only makes sense if invoked as root (or the target user). |
| 740 | .SS "Client Configuration" |
| 741 | These options would normally be used in \fI~\fRUSERNAME\fI/.disorder/passwd\fR |
| 742 | or |
| 743 | \fIpkgconfdir/config.\fRUSERNAME. |
| 744 | .TP |
| 745 | .B connect \fR[\fIFAMILY\fR] \fIHOST SERVICE\fR |
| 746 | Connect to the address specified by \fIHOST\fR and port specified by |
| 747 | \fISERVICE\fR. |
| 748 | .IP |
| 749 | \fIFAMILY\fR can be \fB-4\fR or \fB-6\fR to force IPv4 or IPv6, if this is not |
| 750 | implied by \fIHOST\fR. |
| 751 | Note that IPv6 is not currently well tested. |
| 752 | .TP |
| 753 | .B password \fIPASSWORD\fR |
| 754 | Specify password. |
| 755 | .TP |
| 756 | .B username \fIUSERNAME\fR |
| 757 | Specify username. |
| 758 | The default is inferred from the current UID. |
| 759 | .SS "Web Interface Configuration" |
| 760 | .\" TODO this section is misnamed really... |
| 761 | .TP |
| 762 | .B mail_sender \fIADDRESS\fR |
| 763 | The email address that appears in the From: field of any mail messages sent by |
| 764 | the web interface. |
| 765 | This must be set if you have online registration enabled. |
| 766 | .TP |
| 767 | .B refresh \fISECONDS\fR |
| 768 | Specifies the maximum refresh period in seconds. |
| 769 | Default 15. |
| 770 | .TP |
| 771 | .B sendmail \fIPATH\fR |
| 772 | The path to the Sendmail executable. |
| 773 | This must support the \fB-bs\fR option (Postfix, Exim and Sendmail should all |
| 774 | work). |
| 775 | The default is the sendmail executable found at compile time. |
| 776 | .TP |
| 777 | .B short_display \fICHARACTERS\fR |
| 778 | Defines the maximum number of characters to include in a \fBshort\fR name |
| 779 | part. |
| 780 | Default 30. |
| 781 | .TP |
| 782 | .B smtp_server \fIHOSTNAME\fR |
| 783 | The hostname (or address) of the SMTP server to use for sending mail. |
| 784 | The default is 127.0.0.1. |
| 785 | If \fBsendmail\fR is set then that is used instead. |
| 786 | .TP |
| 787 | .B transform \fITYPE\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]] |
| 788 | Determines how names are sorted and displayed in track choice displays. |
| 789 | .IP |
| 790 | \fITYPE\fR is the type of transformation; usually \fBtrack\fR or |
| 791 | \fBdir\fR but you can define your own. |
| 792 | .IP |
| 793 | \fICONTEXT\fR is a glob pattern matching the context. |
| 794 | Standard contexts are \fBsort\fR (which determines how directory names |
| 795 | are sorted) and \fBdisplay\fR (which determines how they are displayed). |
| 796 | Again, you can define your own. |
| 797 | .IP |
| 798 | All the \fBtransform\fR directives are considered in order. |
| 799 | If the \fITYPE\fR, \fIREGEXP\fR and the \fICONTEXT\fR match |
| 800 | then a new track name is constructed from |
| 801 | \fISUBST\fR according to the substitution rules below. |
| 802 | If several match then each is executed in order. |
| 803 | .IP |
| 804 | If you supply no \fBtransform\fR directives at all then a default set will be |
| 805 | supplied automatically. |
| 806 | But if you supply even one then you must supply all of them. |
| 807 | The defaults are: |
| 808 | .PP |
| 809 | .nf |
| 810 | transform track "^.*/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display |
| 811 | transform track "^.*/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort |
| 812 | transform dir "^.*/([^/]+)$" $1 * |
| 813 | transform dir "^(the) ([^/]*)" "$2 $1" sort i |
| 814 | transform dir "[[:punct:]]" "" sort g |
| 815 | .fi |
| 816 | .TP |
| 817 | .B url \fIURL\fR |
| 818 | Specifies the URL of the web interface. |
| 819 | This URL will be used in generated web pages. |
| 820 | The default is inferred at runtime, so this option no |
| 821 | longer needs to be specified. |
| 822 | .IP |
| 823 | This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not |
| 824 | \fB/cgi-bin/jukebox\fR. |
| 825 | .SH "GLOBAL PREFERENCES" |
| 826 | .SH "LIBAO DRIVER" |
| 827 | .SS "Raw Protocol Players" |
| 828 | Raw protocol players are expected to use the \fBdisorder\fR libao driver. |
| 829 | Programs that use libao generally have command line options to select the |
| 830 | driver and pass options to it. |
| 831 | .SS "Driver Options" |
| 832 | The known driver options are: |
| 833 | .TP |
| 834 | .B fd |
| 835 | The file descriptor to write to. |
| 836 | If this is not specified then the driver looks like the environment |
| 837 | variable \fBDISORDER_RAW_FD\fR. |
| 838 | If that is not set then the default is 1 (i.e. standard output). |
| 839 | .TP |
| 840 | .B fragile |
| 841 | If this is set to a nonzero value then the driver will call \fB_exit\fR(2) if a |
| 842 | write to the output file descriptor fails. |
| 843 | This is a workaround for buggy players such as \fBogg123\fR that ignore |
| 844 | write errors. |
| 845 | .SH "REGEXP SUBSTITUTION RULES" |
| 846 | Regexps are PCRE regexps, as defined in \fBpcrepattern\fR(3). |
| 847 | The only option used is \fBPCRE_UTF8\fR. |
| 848 | Remember that the configuration file syntax means you have to |
| 849 | escape backslashes and quotes inside quoted strings. |
| 850 | .PP |
| 851 | In a \fISUBST\fR string the following sequences are interpreted |
| 852 | specially: |
| 853 | .TP |
| 854 | .B $1 \fR... \fB$9 |
| 855 | These expand to the first to ninth bracketed subexpression. |
| 856 | .TP |
| 857 | .B $& |
| 858 | This expands to the matched part of the subject string. |
| 859 | .TP |
| 860 | .B $$ |
| 861 | This expands to a single \fB$\fR symbol. |
| 862 | .PP |
| 863 | All other pairs starting with \fB$\fR are undefined (and might be used |
| 864 | for something else in the future, so don't rely on the current |
| 865 | behaviour.) |
| 866 | .PP |
| 867 | If \fBi\fR is present in \fIREFLAGS\fR then the match is case-independent. |
| 868 | If \fBg\fR is present then all matches are replaced, otherwise only the first |
| 869 | match is replaced. |
| 870 | .SH "TRACK NAME PARTS" |
| 871 | The traditional track name parts are \fBartist\fR, \fBalbum\fR and \fBtitle\fR, |
| 872 | with the obvious intended meaning. |
| 873 | These are controlled by configuration and by \fBtrackname_\fR preferences. |
| 874 | .PP |
| 875 | In addition there are two built-in parts, \fBpath\fR which is the whole path |
| 876 | name and \fBext\fR which is the filename extension, including the initial dot |
| 877 | (or the empty string if there is not extension). |
| 878 | .SH "SEE ALSO" |
| 879 | \fBdisorder\fR(1), \fBsox\fR(1), \fBdisorderd\fR(8), \fBdisorder\-dump\fR(8), |
| 880 | \fBpcrepattern\fR(3), \fBdisorder_templates\fR(5), \fBdisorder_actions\fR(5), |
| 881 | \fBdisorder.cgi\fR(8), \fBdisorder_preferences\fR(5) |
| 882 | .\" Local Variables: |
| 883 | .\" mode:nroff |
| 884 | .\" fill-column:79 |
| 885 | .\" End: |