X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/62dc37489c39c8d20046b4d5e323707239491df6..79cbb91d611df73fbb24ccae5f858f2dae7d7d18:/doc/disorder_config.5.in diff --git a/doc/disorder_config.5.in b/doc/disorder_config.5.in index 743bb51..787b61a 100644 --- a/doc/disorder_config.5.in +++ b/doc/disorder_config.5.in @@ -72,7 +72,7 @@ override specific bits. The web interface connects to the DisOrder server like any other user, though it is given a special privilege to "become" any other user. (Thus, any process with the same UID as the web interface is very powerful as far as DisOrder -goes.) +goes. This model will be changed in a future version.) .PP Access control to the web interface is (currently) separate from DisOrder's own access control (HTTP authentication is required) but uses the same user @@ -119,13 +119,17 @@ The home directory for state files. Defaults to .IR pkgstatedir . The server will create this directory on startup if it does not exist. .TP -.B plugin \fIPATH\fR +.B plugins \fIPATH\fR Adds a directory to the plugin path. (This is also used by the web interface.) .IP Plugins are opened the first time they are required and never after, so after changing a plugin you must restart the server before it is guaranteed to take effect. +.IP +If +.B plugins +is used without arguments the plugin path is cleared. .SS "Server Configuration" .TP .B alias \fIPATTERN\fR @@ -144,7 +148,7 @@ automatically included, but should include the proper extension. .IP The default is \fB{/artist}{/album}{/title}{ext}\fR. .TP -.B authorization_algorthm \fIALGORITHM\fR +.B authorization_algorithm \fIALGORITHM\fR Defines the algorithm used to authenticate clients. The valid options are sha1 (the default), sha256, sha384 and sha512. See .BR disorder_protocol (5) @@ -153,6 +157,8 @@ for more details. .B broadcast \fIADDRESS\fR \fIPORT\fR Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR. This implies \fBspeaker_backend network\fR. +.IP +See also \fBmulticast_loop\fR and \fBmulticast_ttl\fR. .TP .B broadcast_from \fIADDRESS\fR \fIPORT\fR Sets the (local) source address used by \fBbroadcast\fR. @@ -164,7 +170,8 @@ are: .RS .TP 8 .B pcm -Output level for the audio device. This is probably what you want. +Output level for the audio device. This is probably what you want and is the +default. .TP .B speaker Output level for the PC speaker, if that is connected to the sound card. @@ -177,7 +184,8 @@ Master output level. The OSS documentation recommends against using this, as it affects all output devices. .RE .IP -You can also specify channels by number, if you know the right value. +You can also specify channels by number, if you know the right value. NB that +volume setting only works on OSS systems (including ALSA, via emulation). .TP .B collection \fIMODULE\fR \fIENCODING\fR \fIROOT\fR Define a collection of tracks. @@ -214,17 +222,24 @@ Normally the server only listens on a UNIX domain socket. .TP .B lock yes\fR|\fBno Determines whether the server locks against concurrent operation. Default is -\fByes\fR. +\fByes\fR. There is no good reason to set this to \fBno\fR and the option will +probably be removed in a future version. .TP .B mixer \fIPATH\fR The path to the mixer device, if you want access to the volume control, -e.g. \fB/dev/mixer\fR. +e.g. \fB/dev/mixer\fR (the default). .TP -.B multicast_ttl \fIHOPS\fR -Set the maximum number of hops to send multicast packets. This only applies is +.B multicast_loop yes\fR|\fBno +Determines whether multicast packets are loop backed to the sending host. The +default is \fByes\fR. This only applies if \fBspeaker_backend\fR is set to \fBnetwork\fR and \fBbroadcast\fR is actually a multicast address. .TP +.B multicast_ttl \fIHOPS\fR +Set the maximum number of hops to send multicast packets. This only applies if +\fBspeaker_backend\fR is set to \fBnetwork\fR and \fBbroadcast\fR is actually a +multicast address. The default is 1. +.TP .B namepart \fIPART\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]] Determines how to extract trackname part \fIPART\fR from a track name (with the collection root part removed). @@ -249,7 +264,15 @@ that aren't in the original track name will lead to confusing results. .IP If you supply no \fBnamepart\fR directives at all then a default set will be supplied automatically. But if you supply even one then you must supply all of -them. See the example config file for the defaults. +them. The defaults are equivalent to: +.PP +.nf +namepart title "/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display +namepart title "/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort +namepart album "/([^/]+)/[^/]+$" $1 * +namepart artist "/([^/]+)/[^/]+/[^/]+$" $1 * +namepart ext "(\\.[a-zA-Z0-9]+)$" $1 * +.fi .TP .B nice_rescan \fIPRIORITY\fR Set the recan subprocess priority. The default is 10. @@ -326,6 +349,10 @@ For the server to be able to calculate track lengths, there should be a command corresponding to each .B player command. +.IP +If +.B player +is used without arguments, the list of players is cleared. .TP .B prefsync \fISECONDS\fR The interval at which the preferences log file will be synchronised. Defaults @@ -333,7 +360,7 @@ to 3600, i.e. one hour. .TP .B queue_pad \fICOUNT\fR The target size of the queue. If random play is enabled then randomly picked -tracks will be added until the queue is at least this big. +tracks will be added until the queue is at least this big. The default is 10. .TP .B restrict \fR[\fBscratch\fR] [\fBremove\fR] [\fBmove\fR] Determine which operations are restricted to the submitter of a @@ -400,8 +427,7 @@ Use Apple Core Audio. This only available on OS X systems, on which it is the default. .TP .B oss -Use the OSS (/dev/dsp) API. Not available on all platforms. Not well -maintained at the moment. +Use the OSS (/dev/dsp) API. Not available on all platforms. .TP .B command Execute a command. This is the default if @@ -417,8 +443,9 @@ to receive and play the resulting stream on Linux and OS X. .TP .B sox_generation \fB0\fR|\fB1 Determines whether calls to \fBsox\fR(1) should use \fB-b\fR, \fB-x\fR, etc (if -the generation is 0) or \fB-\fIbits\fR, \fB-L\fR etc (if it is 1). The default -is 0. +the generation is 0) or \fB-\fIbits\fR, \fB-L\fR etc (if it is 1). See the +documentation for your installed copy of \fBsox\fR to determine which you need. +The default is 0. .TP .B speaker_command \fICOMMAND Causes the speaker subprocess to pipe audio data into shell command @@ -440,14 +467,23 @@ Scratches are played using the same logic as other tracks. .IP At least for the time being, path names of scratches must be encoded using UTF-8 (which means that ASCII will do). +.IP +If \fBscratch\fR is used without arguments then the list of scratches is +cleared. .TP .B stopword \fIWORD\fR ... Specifies one or more stopwords that should not take part in searches over track names. +.IP +If \fBstopword\fR is used without arguments then the list of stopwords is +cleared. .TP .B tracklength \fIPATTERN\fR \fIMODULE\fR Specifies the module used to calculate the length of files matching \fIPATTERN\fR. \fIMODULE\fR specifies which plugin module to use. +.IP +If \fBtracklength\fR is used without arguments then the list of modules is +cleared. .SS "Client Configuration" .TP .B connect \fIHOST SERVICE\fR @@ -468,6 +504,8 @@ interface. If a template appears in more than one template directory then the one in the earliest directory specified is chosen. .IP See below for further details. +.IP +If \fBtemplates\fR is used without arguments then the template path is cleared. .TP .B transform \fITYPE\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]] Determines how names are sorted and displayed in track choice displays. @@ -488,7 +526,15 @@ match then each is executed in order. .IP If you supply no \fBtransform\fR directives at all then a default set will be supplied automatically. But if you supply even one then you must supply all of -them. See the example config file for the defaults. +them. The defaults are: +.PP +.nf +transform track "^.*/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display +transform track "^.*/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort +transform dir "^.*/([^/]+)$" $1 * +transform dir "^(the) ([^/]*)" "$2 $1" sort i +transform dir "[[:punct:]]" "" sort g +.fi .TP .B url \fIURL\fR Specifies the URL of the web interface. This URL will be used in @@ -500,6 +546,10 @@ This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not .TP .B allow \fIUSERNAME\fR \fIPASSWORD\fR Specify a username/password pair. +.IP +If +.B allow +is used without arguments, the list of allowed users is cleared. .TP .B password \fIPASSWORD\fR Specify password. @@ -507,6 +557,9 @@ Specify password. .B trust \fIUSERNAME\fR Allow \fIUSERNAME\fR to perform privileged operations such as shutting down or reconfiguring the daemon, or becoming another user. +.IP +If \fBtrust\fR is used without arguments then the list of trusted users is +cleared. .TP .B user \fIUSER\fR Specifies the user to run as. Only makes sense if invoked as root (or @@ -558,6 +611,14 @@ If unset or \fByes\fR then play is enabled. Otherwise it is disabled. Use .B random-play If unset or \fByes\fR then random play is enabled. Otherwise it is disabled. Use \fBdisable\fR rather than setting it directly. +.PP +Global preferences starting '_' are read-only (in the sense that you cannot +modify them; the server may modify them as part of its normal operation). They +are: +.TP +.B _dbversion +The database version string. This is used by DisOrder to detect when it must +modify the database after an upgrade. .SH "LIBAO DRIVER" .SS "Raw Protocol Players" Raw protocol players are expected to use the \fBdisorder\fR libao driver. @@ -697,7 +758,7 @@ If there are no arguments, or all the arguments are \fBtrue\fB, then expands to \fBtrue\fR, otherwise to \fBfalse\fR. .TP .B @arg:\fINAME\fB@ -Expands to the value of CGI script argument \fINAME\fR. +Expands to the value of CGI argument \fINAME\fR. .TP .B @basename@ The basename of the current directory component, in \fB@navigate@\fR. @@ -731,7 +792,7 @@ Expands to the filename of the current file or directory, inside the template argument to \fBchoose\fR. .TP .B @files{\fITEMPLATE\fB} -Expands \fITEMPLATE\fB once for each file indicated by the \fBdirectory\fR CGI +Expands \fITEMPLATE\fR once for each file indicated by the \fBdirectory\fR CGI arg if it is present, or otherwise for the list of files counted by \fBfiles\fR with names \fB0_file\fR, \fB1_file\fR etc. .TP @@ -976,7 +1037,7 @@ URL-quote \fISTRING\fR. Expands to \fBdisorder.cgi\fR's version string. .TP .B @volume:\fISPEAKER\fB@ -The volume on the left or right speaker. \fISPEAKER\fR must be \fBleft\fB or +The volume on the left or right speaker. \fISPEAKER\fR must be \fBleft\fR or \fBright\fR. .TP .B @when@