X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/36be7e6a505753eb31ed165084c729c7efa40534..180dcdb017156143feb02c98959b31020645640d:/doc/disorder_config.5.in diff --git a/doc/disorder_config.5.in b/doc/disorder_config.5.in index 744bf13..6cb4a78 100644 --- a/doc/disorder_config.5.in +++ b/doc/disorder_config.5.in @@ -72,11 +72,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 @@ -119,13 +141,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 +170,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 +179,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 +192,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 +206,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 +244,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 +286,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. @@ -320,6 +365,16 @@ the shell quoting rules. .RE .IP If multiple player commands match a track then the first match is used. +.IP +For the server to be able to calculate track lengths, there should be a +.B tracklength +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 @@ -327,7 +382,21 @@ 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 +track. By default, no operations are restricted, i.e. anyone can +scratch or remove anything. +.IP +If \fBrestrict scratch\fR or \fBrestrict remove\fR are set then only the user +that submitted a track can scratch or remove it, respectively. +.IP +If \fBrestrict move\fR is set then only trusted users can move tracks around in +the queue. +.IP +If \fBrestrict\fR is used more than once then only the final use has any +effect. .TP .B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS Describes the sample format expected by the \fBspeaker_command\fR (below). The @@ -380,8 +449,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 @@ -397,8 +465,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 @@ -413,20 +482,6 @@ is invoked to translate it. If .B sox is not installed then this will not work. .TP -.B restrict \fR[\fBscratch\fR] [\fBremove\fR] [\fBmove\fR] -Determine which operations are restricted to the submitter of a -track. By default, no operations are restricted, i.e. anyone can -scratch or remove anything. -.IP -If \fBrestrict scratch\fR or \fBrestrict remove\fR are set then only the user -that submitted a track can scratch or remove it, respectively. -.IP -If \fBrestrict move\fR is set then only trusted users can move tracks around in -the queue. -.IP -If \fBrestrict\fR is used more than once then only the final use has any -effect. -.TP .B scratch \fIPATH\fR Specifies a scratch. When a track is scratched, a scratch track is played at random. @@ -434,10 +489,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 @@ -448,12 +516,18 @@ Connect to the address specified by \fIHOST\fR and port specified by .B refresh \fISECONDS\fR Specifies the maximum refresh period in seconds. Default 15. .TP +.B short_display \fICHARACTERS\fR +Defines the maximum number of characters to include in a \fBshort\fR name +part. Default 30. +.TP .B templates \fIPATH\fR ... Specifies the directory containing templates used by the web 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. @@ -474,7 +548,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 @@ -486,6 +568,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. @@ -493,6 +579,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 @@ -528,10 +617,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 @@ -544,6 +629,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. @@ -683,7 +776,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. @@ -717,7 +810,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 @@ -812,12 +905,18 @@ an even or odd position in \fB@queue@\fR, \fB@recent@\fR or \fB@files@\fR. .TP .B @part{\fICONTEXT\fB}{\fIPART\fB}@ Expands to track name part \fIPART\fR using context \fICONTEXT\fR for the -current track. The context may be omitted (and normally would be) and defaults +current track. The context may be omitted and defaults to \fBdisplay\fR. +.IP +The special context \fBshort\fR is equivalent to \fBdisplay\fR but limited to +the \fBshort_display\fR limit. .TP .B @part{\fICONTEXT\fB}{\fIPART\fB}{\fITRACK\fB}@ Expands to track name part \fIPART\fR using context \fICONTEXT\fR for \fITRACK\fR. In this usage the context may not be omitted. +.IP +The special context \fBshort\fR is equivalent to \fBdisplay\fR but limited to +the \fBshort_display\fR limit. .TP .B @paused@ Expands to \fBtrue\fR if the current track is paused, else \fBfalse\fR. @@ -956,7 +1055,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@