Note that prefsync doesn't do anything any more.

[disorder] / doc / disorder_config.5.in

diff --git a/doc/disorder_config.5.in b/doc/disorder_config.5.in
index 952b2b99010f88639801e872bf83ef6b13c247e5..4588d5958e7573e4680aba1be85f816570af8d75 100644 (file)
--- a/doc/disorder_config.5.in
+++ b/doc/disorder_config.5.in
@@ -1,20 +1,18 @@
 .\"
 .\"

-.\" 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
 .\" 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.
 .\" (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
 .\" 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
 .\"
 .TH disorder_config 5
 .SH NAME


@@ -37,7 +35,7 @@ See \fBdisorder\fR(3) for more details about this.
 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.
 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 "Track Names"
 Track names are derived from filenames under the control of regular
 expressions, rather than attempting to interpret format-specific embedded name


@@ -50,6 +48,7 @@ the displayed track titles are not lexically sorted.
 .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.
 .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
 .SS "Users And Access Control"
 DisOrder distinguishes between multiple users.
 This is for access control and reporting, not to provide different


@@ -276,13 +275,19 @@ Execute a command.
 This is the default if
 .B speaker_command
 is specified, or if no native is available.
 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
 .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.
 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
 .RE
 .TP
 .B authorization_algorithm \fIALGORITHM\fR


@@ -292,14 +297,22 @@ See
 .BR disorder_protocol (5)
 for more details.
 .TP
 .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.
 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
 .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.
 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.
 .TP
 .B channel \fICHANNEL\fR
 The mixer channel that the volume control should use.


@@ -308,6 +321,7 @@ For \fBapi oss\fR the possible values are:
 .RS
 .TP 8
 .B pcm
 .RS
 .TP 8
 .B pcm

+

 Output level for the audio device.
 This is probably what you want and is the default.
 .TP
 Output level for the audio device.
 This is probably what you want and is the default.
 .TP


@@ -387,7 +401,12 @@ will be tried.
 .IP
 For \fBapi alsa\fR this is the device name to use.
 .IP
 .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.
 .IP
 The default is \fBdefault\fR, which is intended to map to whatever the system's
 default is.


@@ -403,10 +422,14 @@ reinstated.
 Specifies the number of recently played tracks to remember (including
 failed tracks and scratches).
 .TP
 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.
 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
 .IP
 Normally the server only listens on a UNIX domain socket.
 .TP


@@ -431,12 +454,12 @@ For \fBapi coreaudio\fR, volume setting is not currently supported.
 .B multicast_loop yes\fR|\fBno
 Determines whether multicast packets are loop backed to the sending host.
 The default is \fByes\fR.
 .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.
 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
 \fBbroadcast\fR is actually a multicast address.
 The default is 1.
 .TP


@@ -478,7 +501,7 @@ namepart ext    "(\\.[a-zA-Z0-9]+)$"                        $1 *
 .TP
 .B new_bias \fIWEIGHT\fR
 The weight for new tracks.
 .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
 to be picked as normal.
 .TP
 .B new_bias_age \fISECONDS\fR


@@ -521,6 +544,19 @@ The maximum days that a track can survive in the database of newly added
 tracks.
 The default is 31.
 .TP
 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.
 .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.


@@ -529,6 +565,10 @@ The following options are supported:
 .RS
 .TP
 .B \-\-wait\-for\-device\fR[\fB=\fIDEVICE\fR]
 .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
 Waits (for up to a couple of seconds) for the default, or specified, libao
 device to become openable.
 .TP


@@ -580,8 +620,7 @@ If
 is used without arguments, the list of players is cleared.
 .TP
 .B prefsync \fISECONDS\fR
 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.
 .TP
 .B queue_pad \fICOUNT\fR
 The target size of the queue.


@@ -624,7 +663,7 @@ The default is
 .BR 16/44100/2 .
 .PP
 With the
 .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
 backend the sample format is forced to
 .B 16b/44100/2
 and with the


@@ -647,7 +686,10 @@ Determines whether calls to \fBsox\fR(1) should use \fB\-b\fR, \fB\-x\fR, etc (i
 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 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.
 .TP
 .B speaker_backend \fINAME
 This is an alias for \fBapi\fR; see above.


@@ -703,16 +745,20 @@ These options would normally be used in \fI~\fRUSERNAME\fI/.disorder/passwd\fR
 or
 \fIpkgconfdir/config.\fRUSERNAME.
 .TP
 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.
 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.
 .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
 .SS "Web Interface Configuration"
 .\" TODO this section is misnamed really...
 .TP


@@ -725,6 +771,12 @@ This must be set if you have online registration enabled.
 Specifies the maximum refresh period in seconds.
 Default 15.
 .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 short_display \fICHARACTERS\fR
 Defines the maximum number of characters to include in a \fBshort\fR name
 part.


@@ -733,6 +785,7 @@ Default 30.
 .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.
 .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.
 .TP
 .B transform \fITYPE\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]]
 Determines how names are sorted and displayed in track choice displays.


@@ -773,34 +826,6 @@ longer needs to be specified.
 This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not
 \fB/cgi-bin/jukebox\fR.
 .SH "GLOBAL PREFERENCES"
 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 "LIBAO DRIVER"
 .SS "Raw Protocol Players"
 Raw protocol players are expected to use the \fBdisorder\fR libao driver.


@@ -856,7 +881,7 @@ name and \fBext\fR which is the filename extension, including the initial dot
 .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),
 .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
 .\" Local Variables:
 .\" mode:nroff
 .\" fill-column:79