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
.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
.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)
.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.
.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.
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.
.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).
.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.
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
.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
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
.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
.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
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.
.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
.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.
.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
.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
.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.
\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.
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
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@
~mdw / disorder / blobdiff