X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/937be4c02816d026de3063f32d82fafda1f3c512..79cbb91d611df73fbb24ccae5f858f2dae7d7d18:/doc/disorder_config.5.in diff --git a/doc/disorder_config.5.in b/doc/disorder_config.5.in index 1f0b266..787b61a 100644 --- a/doc/disorder_config.5.in +++ b/doc/disorder_config.5.in @@ -1,3 +1,4 @@ + .\" .\" Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell .\" @@ -71,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 @@ -116,14 +117,19 @@ start up without a valid config file.) .B home \fIDIRECTORY\fR 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 @@ -142,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) @@ -151,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. @@ -162,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. @@ -175,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. @@ -212,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). @@ -247,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. @@ -318,6 +343,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 @@ -325,7 +360,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 @@ -349,7 +398,7 @@ The default is With the .B network backend the sample format is forced to -.B 16/44100/2b +.B 16b/44100/2 and with the .B coreaudio backend it is forced to @@ -377,6 +426,9 @@ default. 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. +.TP .B command Execute a command. This is the default if .B speaker_command @@ -391,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 @@ -407,20 +460,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. @@ -428,10 +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 @@ -442,12 +494,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. @@ -468,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 @@ -480,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. @@ -487,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 @@ -503,6 +576,9 @@ Configuration files are read in the following order: .I pkgconfdir/config.private Should be readable only by the jukebox group, and contain \fBallow\fR commands for authorised users. +.IP +If this file does not exist at startup then the server will create it with a +randomly chosen password for the root user. .TP .I pkgconfdir/config.\fRUSER Per-user system-controlled client configuration. Optional but if it @@ -535,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. @@ -674,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. @@ -708,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 @@ -803,12 +887,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. @@ -947,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@