X-Git-Url: https://git.distorted.org.uk/~mdw/disorder/blobdiff_plain/00753f260a8cdb283cfde8cd096ed0ef6e0751cb..0c4101ecabe0fafc07524c77958b71de3e054e98:/doc/disorder_config.5.in diff --git a/doc/disorder_config.5.in b/doc/disorder_config.5.in index 952b2b9..4588d59 100644 --- 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 -.\" 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 . .\" .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. -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 @@ -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. +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 @@ -276,13 +275,19 @@ Execute a command. 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 @@ -292,14 +297,22 @@ See .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. @@ -308,6 +321,7 @@ For \fBapi oss\fR the possible values are: .RS .TP 8 .B pcm + 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 -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. @@ -403,10 +422,14 @@ reinstated. 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 @@ -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. -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 @@ -478,7 +501,7 @@ namepart ext "(\\.[a-zA-Z0-9]+)$" $1 * .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 @@ -521,6 +544,19 @@ The maximum days that a track can survive in the database of newly added 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. @@ -529,6 +565,10 @@ The following options are supported: .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 @@ -580,8 +620,7 @@ If 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. @@ -624,7 +663,7 @@ The default is .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 @@ -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 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. @@ -703,16 +745,20 @@ These options would normally be used in \fI~\fRUSERNAME\fI/.disorder/passwd\fR 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 @@ -725,6 +771,12 @@ This must be set if you have online registration enabled. 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. @@ -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. +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. @@ -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" -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. @@ -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), -\fBdisorder.cgi\fR(8) +\fBdisorder.cgi\fR(8), \fBdisorder_preferences\fR(5) .\" Local Variables: .\" mode:nroff .\" fill-column:79