X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/f0c20432f8c9dffd049c785f21cc85d98ff628fd..f0feb22e80bfe438c16d212a7cc8be6d2282b6ac:/doc/disorder_config.5.in diff --git a/doc/disorder_config.5.in b/doc/disorder_config.5.in index f73f0bf..6eb57b8 100644 --- a/doc/disorder_config.5.in +++ b/doc/disorder_config.5.in @@ -1,4 +1,3 @@ - .\" .\" Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell .\" @@ -72,11 +71,33 @@ 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 namespace. +.SS "Searching And Tags" +Search strings contain a list of search terms separated by spaces. A search +term can either be a single word or a tag, prefixed with "tag:". +.PP +Search words are compared without regard to letter case or accents; thus, all +of the following will be considered to be equal to one another: +.PP +.nf + LATIN CAPITAL LETTER E + LATIN SMALL LETTER E + LATIN CAPITAL LETTER E WITH GRAVE + LATIN SMALL LETTER E WITH GRAVE + LATIN CAPITAL LETTER E plus COMBINING GRAVE ACCENT + LATIN SMALL LETTER E plus COMBINING GRAVE ACCENT +.fi +.PP +The same rules apply to tags but in addition leading and trailing whitespace is +disregarded and all whitespace sequences are treated as equal when they appear +as internal whitespace. +.PP +Where several tags are listed, for instance the tags preference for a track, +the tags are separated by commas. Therefore tags may not contain commas. .SH "CONFIGURATION FILE" .SS "General Syntax" Lines are split into fields separated by whitespace (space, tab, line @@ -126,6 +147,10 @@ interface.) 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 +169,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 +178,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 +191,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 +205,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 +243,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 +285,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 +370,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 +381,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 +448,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 +464,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 +488,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 +525,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 +547,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 @@ -498,15 +565,15 @@ This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not \fB/cgi-bin/jukebox\fR. .SS "Authentication Configuration" .TP -.B allow \fIUSERNAME\fR \fIPASSWORD\fR -Specify a username/password pair. -.TP .B password \fIPASSWORD\fR Specify password. .TP .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 @@ -542,10 +609,6 @@ These are the values set with \fBset-global\fR. .B required-tags If this is set an nonempty then randomly played tracks will always have at least one of the listed tags. -.IP -Tags can contain any printing character except comma. Leading and trailing -spaces are not significant but internal spaces are. Tags in a list are -separated by commas. .TP .B prohibited-tags If this is set an nonempty then randomly played tracks will never have any of @@ -705,7 +768,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. @@ -739,7 +802,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 @@ -984,7 +1047,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@