.\"
-.\" Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell
+.\" Copyright (C) 2004-2008 Richard Kettlewell
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.IP
The default is \fB{/artist}{/album}{/title}{ext}\fR.
.TP
+.B api \fINAME\fR
+Selects the backend used to play sound and to set the volume. The following
+options are available:
+.RS
+.TP
+.B alsa
+Use the ALSA API. This is only available on Linux systems, on which it is the
+default.
+.TP
+.B coreaudio
+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
+is specified, or if no native is available.
+.TP
+.B network
+Transmit audio over the network. This is the default if
+\fBbroadcast\fR is specified. You can use
+.BR disorder-playrtp (1)
+to receive and play the resulting stream on Linux and OS X.
+.RE
+.TP
.B authorization_algorithm \fIALGORITHM\fR
Defines the algorithm used to authenticate clients. The valid options
are sha1 (the default), sha256, sha384 and sha512. See
.TP
.B broadcast \fIADDRESS\fR \fIPORT\fR
Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR. This implies
-\fBspeaker_backend network\fR.
+\fBapi network\fR.
.IP
See also \fBmulticast_loop\fR and \fBmulticast_ttl\fR.
.TP
Sets the (local) source address used by \fBbroadcast\fR.
.TP
.B channel \fICHANNEL\fR
-The mixer channel that the volume control should use. Valid names depend on
-your operating system and hardware, but some standard ones that might be useful
-are:
+The mixer channel that the volume control should use.
+.IP
+For \fBapi oss\fR the possible values are:
.RS
.TP 8
.B pcm
it affects all output devices.
.RE
.IP
-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).
+You can also specify channels by number, if you know the right value.
+.IP
+For \fBapi alsa\fR, this is the name of the mixer control to use. The default
+is \fBPCM\fR. Use \fBamixer scontrols\fR or similar to get a full list.
+.IP
+For \fBapi coreaudio\fR, volume setting is not currently supported.
.TP
.B collection \fIMODULE\fR \fIENCODING\fR \fIROOT\fR
+.TP
+.B collection \fIMODULE\fR \fIROOT\fR
+.TP
+.B collection \fIROOT\fR
Define a collection of tracks.
.IP
\fIMODULE\fR defines which plugin module should be used for this
-collection. Use the supplied \fBfs\fR module for tracks that exists
-as ordinary files in the filesystem.
+collection. Use the supplied \fBfs\fR module for tracks that exist
+as ordinary files in the filesystem. If no \fIMODULE\fR is specified
+then \fBfs\fR is assumed.
.IP
-\fIENCODING\fR defines the encoding of filenames in this collection.
-For \fBfs\fR this would be the encoding you use for filenames.
-Examples might be \fBiso-8859-1\fR or \fButf-8\fR.
+\fIENCODING\fR defines the encoding of filenames in this collection. For
+\fBfs\fR this would be the encoding you use for filenames. Examples might be
+\fBiso-8859-1\fR or \fButf-8\fR. If no encoding is specified then the current
+locale's character encoding is used.
+.IP
+NB that this default depends on the locale the server runs in, which is not
+necessarily the same as that of ordinary users, depending how the system is
+configured. It's best to explicitly specify it to be certain.
.IP
\fIROOT\fR is the root in the filesystem of the filenames and is
-passed to the plugin module.
+passed to the plugin module. It must be an absolute path and should not
+end with a "/".
.TP
.B default_rights \fIRIGHTS\fR
Defines the set of rights given to new users. The argument is a
(modified in legacy configurations by the obsolete \fBrestrict\fR directive).
.TP
.B device \fINAME\fR
-ALSA device to play raw-format audio. Default is \fBdefault\fR, i.e. to use
-the whatever the ALSA configured default is.
+Sound output device.
+.IP
+For \fBapi oss\fR this is the path to the device to use. If it is set to
+\fBdefault\fR then \fI/dev/dsp\fR and \fI/dev/audio\fR will be tried.
+.IP
+For \fBapi alsa\fR this is the device name to use.
+.IP
+For \fBapi coreaudio\fR this is currently ignored.
+.IP
+The default is \fBdefault\fR, which is intended to map to whatever the system's
+default is.
.TP
.B gap \fISECONDS\fR
Specifies the number of seconds to leave between tracks. The default
-is 2.
+is 0.
.TP
.B history \fIINTEGER\fR
Specifies the number of recently played tracks to remember (including
\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 (the default).
+.B mixer \fIDEVICE\fR
+The mixer device name, if it needs to be specified separately from
+\fBdevice\fR.
+.IP
+For \fBapi oss\fR this should be the path to the mixer device and the default
+is \fI/dev/mixer\fR.
+.IP
+For \fBapi alsa\fR, this is the index of the mixer control to use. The default
+is 0.
+.IP
+For \fBapi coreaudio\fR, volume setting is not currently supported.
.TP
.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
+\fBapi\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
+\fBapi\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]]
Signals are specified by their full C name, i.e. \fBSIGINT\fR and not \fBINT\fR
or \fBInterrupted\fR or whatever.
.TP
-.B speaker_backend \fINAME\fR
-Selects the backend use by the speaker process. The following options are
-available:
-.RS
-.TP
-.B alsa
-Use the ALSA API. This is only available on Linux systems, on which it is the
-default.
-.TP
-.B coreaudio
-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
-is specified, or if no native is available.
-.TP
-.B network
-Transmit audio over the network. This is the default if
-\fBbroadcast\fR is specified. You can use
-.BR disorder-playrtp (1)
-to receive and play the resulting stream on Linux and OS X.
-.RE
-.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). See the
documentation for your installed copy of \fBsox\fR to determine which you need.
The default is 0.
.TP
+.B speaker_backend \fINAME
+This is an alias for \fBapi\fR; see above.
+.TP
.B speaker_command \fICOMMAND
Causes the speaker subprocess to pipe audio data into shell command
\fICOMMAND\fR, rather than writing to a local sound card. The sample format is
.IP
If \fBstopword\fR is used without arguments then the list of stopwords is
cleared.
+.IP
+There is a default set of stopwords built in, but this option can be used to
+augment or replace that list.
.TP
.B tracklength \fIPATTERN\fR \fIMODULE\fR
Specifies the module used to calculate the length of files matching
\fISERVICE\fR.
.SS "Web Interface Configuration"
.TP
+.B mail_sender \fIADDRESS\fR
+The email address that appears in the From: field of any mail messages sent by
+the web interface. This must be set if you have online registration enabled.
+.TP
.B refresh \fISECONDS\fR
Specifies the maximum refresh period in seconds. Default 15.
.TP
Defines the maximum number of characters to include in a \fBshort\fR name
part. Default 30.
.TP
+.B smtp_server \fIHOSTNAME\fR
+The hostname (or address) of the SMTP server to use for sending mail. The
+default is 127.0.0.1.
+.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
Included at the end of the main content \fB<DIV>\fR element.
.TP
.B topbar.html
-Included at the start of the \fB<BODY>\fR element. (This supplants
-\fBsidebar.html\fR, though the latter is still available; override label
-\fBmenu\fR to choose between them.)
+Included at the start of the \fB<BODY>\fR element.
+.TP
+.B topbarend.html
+Included at the end of the \fB<BODY>\fR element.
.TP
.B stdhead.html
Included in the \fB<HEAD>\fR element.
If \fIBOOL\fR expands to \fBtrue\fR then expands to \fITRUEPART\fR, otherwise
to \fIFALSEPART\fR (which may be omitted).
.TP
-.B @include:\fIPATH\fR@
+.B @image:\fINAME\fB@
+Expands to the (possibly relative) URL for image \fINAME\fR.
+.IP
+If there is a label \fBimages.\fINAME\fR then that will be the image base name.
+Otherwise the image base name is \fINAME\fB.png\fR or just \fINAME\fR if it
+alraedy has an extension. Thus labels may be defined to give images role
+names.
+.IP
+If there is a label \fBurl.static\fR then that is the base URL for images. If
+it is not defined then \fB/disorder\fR is used as a default.
+.TP
+.B @include:\fIPATH\fB@
Include the named file as if it were a template file. If \fIPATH\fR
starts with a \fB/\fR then it is used as-is; otherwise, ".html" is
appended and the template path is searched.
.B @user@
The current username. This will be "guest" if nobody is logged in.
.TP
+.B @userinfo{\fIPROPERTY\fB}@
+Look up a property of the logged-in user.
+.TP
.B @version@
Expands to \fBdisorder.cgi\fR's version string.
.TP
~mdw / disorder / blobdiff