.\"
-.\" Copyright (C) 2004-2008 Richard Kettlewell
+.\" Copyright (C) 2004-2009 Richard Kettlewell
.\"
-.\" This program is free software; you can redistribute it and/or modify
+.\" 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
-.\" the Free Software Foundation; either version 2 of the License, or
+.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
-.\"
-.\" This program is distributed in the hope that it will be useful, but
-.\" WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-.\" General Public License for more details.
-.\"
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
.\" You should have received a copy of the GNU General Public License
-.\" along with this program; if not, write to the Free Software
-.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
-.\" USA
+.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
.\"
.TH disorder_config 5
.SH NAME
Each track can have a set of preferences associated with it.
These are simple key-value pairs; they can be used for anything you
like, but a number of keys have specific meanings.
-See \fBdisorder\fR(1) for more details about these.
+See \fBdisorder_preferences\fR(5) for more details about these.
.SS "Track Names"
Track names are derived from filenames under the control of regular
expressions, rather than attempting to interpret format-specific embedded name
.SS "Server State"
A collection of global preferences define various bits of server state: whether
random play is enabled, what tags to check for when picking at random, etc.
+See \fBdisorder_preferences\fR(5) for more information.
.SS "Users And Access Control"
DisOrder distinguishes between multiple users.
This is for access control and reporting, not to provide different
This is the default if
.B speaker_command
is specified, or if no native is available.
+.IP
+You might want to set
+.B pause_mode
+with this backend.
.TP
-.B network
+.B rtp
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.
+.B network
+is a deprecated synonym for this API.
.RE
.TP
.B authorization_algorithm \fIALGORITHM\fR
.BR disorder_protocol (5)
for more details.
.TP
-.B broadcast \fIADDRESS\fR \fIPORT\fR
+.B broadcast \fR[\fIFAMILY\fR] \fIADDRESS\fR \fIPORT\fR
Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR.
-This implies \fBapi network\fR.
+This implies \fBapi rtp\fR.
+.IP
+\fIFAMILY\fR can be \fB-4\fR or \fB-6\fR to force IPv4 or IPv6, if this is not
+implied by \fIADDRESS\fR.
+Note that IPv6 is not currently well tested.
.IP
See also \fBmulticast_loop\fR and \fBmulticast_ttl\fR.
.TP
-.B broadcast_from \fIADDRESS\fR \fIPORT\fR
+.B broadcast_from \fR[\fIFAMILY\fR] \fIADDRESS\fR \fIPORT\fR
Sets the (local) source address used by \fBbroadcast\fR.
+.IP
+\fIFAMILY\fR can be \fB-4\fR or \fB-6\fR to force IPv4 or IPv6, if this is not
+implied by \fIADDRESS\fR.
+Note that IPv6 is not currently well tested.
.TP
.B channel \fICHANNEL\fR
The mixer channel that the volume control should use.
.RS
.TP 8
.B pcm
+
Output level for the audio device.
This is probably what you want and is the default.
.TP
.IP
For \fBapi alsa\fR this is the device name to use.
.IP
-For \fBapi coreaudio\fR this is currently ignored.
+For \fBapi coreaudio\fR this can be either the UID or the human-readable
+name of the desired device.
+For a list of names, visit System Preferences -> Sound and look at the Type column.
+For example, you might use "Built-in Output" for the built-in speaker
+or "Built-in Line Output" if you have connected external speakers.
+Remember to quote the name.
.IP
The default is \fBdefault\fR, which is intended to map to whatever the system's
default is.
Specifies the number of recently played tracks to remember (including
failed tracks and scratches).
.TP
-.B listen \fR[\fIHOST\fR] \fISERVICE\fR
+.B listen \fR[\fIFAMILY\fR] \fR[\fIHOST\fR] \fISERVICE\fR
Listen for connections on the address specified by \fIHOST\fR and port
specified by \fISERVICE\fR.
-If \fIHOST\fR is omitted then listens on all local addresses.
+If \fIHOST\fR is omitted, or is \fB*\fR, then listens on all local addresses.
+.IP
+\fIFAMILY\fR can be \fB-4\fR or \fB-6\fR to force IPv4 or IPv6, if this is not
+implied by \fIHOST\fR.
+Note that IPv6 is not currently well tested.
.IP
Normally the server only listens on a UNIX domain socket.
.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 \fBapi\fR is set to \fBnetwork\fR and \fBbroadcast\fR
+This only applies if \fBapi\fR is set to \fBrtp\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 \fBapi\fR is set to \fBnetwork\fR and
+This only applies if \fBapi\fR is set to \fBrtp\fR and
\fBbroadcast\fR is actually a multicast address.
The default is 1.
.TP
.TP
.B new_bias \fIWEIGHT\fR
The weight for new tracks.
-The default is 900000, i.e. recently added tracks are a hundred times as likely
+The default is 450000, i.e. recently added tracks are a fifty times as likely
to be picked as normal.
.TP
.B new_bias_age \fISECONDS\fR
tracks.
The default is 31.
.TP
+.B pause_mode \fIMODE
+Sets the pause mode for the \fBcommand\fR backend.
+The possible values are:
+.RS
+.TP
+.B silence
+Send silent (0-value) samples when paused.
+This is the default.
+.TP
+.B suspend
+Stop writing when paused.
+.RE
+.TP
.B player \fIPATTERN\fR \fIMODULE\fR [\fIOPTIONS.. [\fB\-\-\fR]] \fIARGS\fR...
Specifies the player for files matching the glob \fIPATTERN\fR.
\fIMODULE\fR specifies which plugin module to use.
.RS
.TP
.B \-\-wait\-for\-device\fR[\fB=\fIDEVICE\fR]
+\fBThis option is deprecated\fR.
+If you want gapless play use raw-format players and the speaker process instead.
+(This the default in any case.)
+.IP
Waits (for up to a couple of seconds) for the default, or specified, libao
device to become openable.
.TP
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 to 3600, i.e. one hour.
+This option no longer does anything and will be removed in a future version.
.TP
.B queue_pad \fICOUNT\fR
The target size of the queue.
.BR 16/44100/2 .
.PP
With the
-.B network
+.B rtp
backend the sample format is forced to
.B 16b/44100/2
and with the
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.
+The default is set according to the version of sox found when DisOrder was
+built.
+If you run on a system with a different version of sox, you will need to
+set this option.
.TP
.B speaker_backend \fINAME
This is an alias for \fBapi\fR; see above.
or
\fIpkgconfdir/config.\fRUSERNAME.
.TP
-.B connect \fIHOST SERVICE\fR
+.B connect \fR[\fIFAMILY\fR] \fIHOST SERVICE\fR
Connect to the address specified by \fIHOST\fR and port specified by
\fISERVICE\fR.
+.IP
+\fIFAMILY\fR can be \fB-4\fR or \fB-6\fR to force IPv4 or IPv6, if this is not
+implied by \fIHOST\fR.
+Note that IPv6 is not currently well tested.
.TP
.B password \fIPASSWORD\fR
Specify password.
.TP
.B username \fIUSERNAME\fR
Specify username.
-The default is taken from the environment variable \fBLOGNAME\fR.
+The default is inferred from the current UID.
.SS "Web Interface Configuration"
.\" TODO this section is misnamed really...
.TP
Specifies the maximum refresh period in seconds.
Default 15.
.TP
+.B sendmail \fIPATH\fR
+The path to the Sendmail executable.
+This must support the \fB-bs\fR option (Postfix, Exim and Sendmail should all
+work).
+The default is the sendmail executable found at compile time.
+.TP
.B short_display \fICHARACTERS\fR
Defines the maximum number of characters to include in a \fBshort\fR name
part.
.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.
+If \fBsendmail\fR is set then that is used instead.
.TP
.B transform \fITYPE\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]]
Determines how names are sorted and displayed in track choice displays.
This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not
\fB/cgi-bin/jukebox\fR.
.SH "GLOBAL PREFERENCES"
-These are the values set with \fBset\-global\fR.
-.TP
-.B required\-tags
-If this is set an nonempty then randomly played tracks will always have at
-least one of the listed tags.
-.TP
-.B prohibited\-tags
-If this is set an nonempty then randomly played tracks will never have any of
-the listed tags.
-.TP
-.B playing
-If unset or \fByes\fR then play is enabled.
-Otherwise it is disabled.
-Use \fBdisable\fR rather than setting it directly.
-.TP
-.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.
.SH "SEE ALSO"
\fBdisorder\fR(1), \fBsox\fR(1), \fBdisorderd\fR(8), \fBdisorder\-dump\fR(8),
\fBpcrepattern\fR(3), \fBdisorder_templates\fR(5), \fBdisorder_actions\fR(5),
-\fBdisorder.cgi\fR(8)
+\fBdisorder.cgi\fR(8), \fBdisorder_preferences\fR(5)
.\" Local Variables:
.\" mode:nroff
.\" fill-column:79