.\"
-.\" Copyright (C) 2004-2009 Richard Kettlewell
+.\" Copyright (C) 2004-2011, 2013 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
This is for access control and reporting, not to provide different
views of the world: i.e. preferences and so on are global.
.PP
-Each user has an associated set of rights which contorl which commands they may
+Each user has an associated set of rights which control which commands they may
execute.
Normally you would give all users most rights, and expect them to
cooperate (they are after all presumed to be in a shared sound environment).
Configuration files are read in the following order:
.TP
.I pkgconfdir/config
+Or
+.BR $DISORDER_CONFIG ,
+if that's set; overridden by
+.B \-c
+.RB ( \-\-config )
+command line option, except in
+.BR disrder-playrtp (1),
+which uses
+.BR \-C .
.TP
.I pkgconfdir/config.private
+Or
+.BR $DISORDER_PRIVCONFIG ,
+if that's set, else
+.BR $DISORDER_CONFIG.private .
Should be readable only by the jukebox group.
Not really useful any more and will be abolished in future.
.TP
.I ~\fRUSERNAME\fI/.disorder/passwd
+Or
+.BR $DISORDER_USERCONFIG ,
+if that's set; else
+.BR $DISORDER_HOME/passwd ;
+overridden by
+.B \-u
+.RB ( \-\-user-config )
+command-line option.
Per-user client configuration.
Optional but if it exists must be readable only by the relevant user.
Would normally contain a \fBpassword\fR directive.
.TP
.I pkgconfdir/config.\fRUSERNAME
+(Or
+.BR $DISORDER_USERCONFIG_SYS ,
+if that's set; else
+.BR $DISORDER_CONFIG.\fIUSERNAME .)
Per-user system-controlled client configuration.
Optional but if it exists must be readable only by the relevant user.
Would normally contain a \fBpassword\fR directive.
.B "Users And Access Control"
above.
.IP
-The default is to allow everything except \fBadmin\fR and \fBregister\fR
-(modified in legacy configurations by the obsolete \fBrestrict\fR directive).
+The default is to allow everything except \fBadmin\fR and \fBregister\fR.
.TP
.B device \fINAME\fR
Sound output device.
The default is \fBdefault\fR, which is intended to map to whatever the system's
default is.
.TP
-.B gap \fISECONDS\fR
-This option no longer does anything and will be removed in a future version.
-.TP
.B history \fIINTEGER\fR
Specifies the number of recently played tracks to remember (including
failed tracks and scratches).
.IP
Normally the server only listens on a UNIX domain socket.
.TP
-.B lock yes\fR|\fBno
-This option no longer does anything and will be removed in a future version.
-.TP
.B mixer \fIDEVICE\fR
The mixer device name, if it needs to be specified separately from
\fBdevice\fR.
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
.B \-\-
Defines the end of the list of options.
Needed if the first argument to the plugin starts with a "\-".
background decoders will not be stopped and restarted using changed
configuration once they have been started.
.TP
-.B prefsync \fISECONDS\fR
-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.
If random play is enabled then randomly picked tracks will be added until
New values of this option may be picked up from the configuration file even
without a reload.
.TP
+.B rtp_always_request yes\fR|\fBno
+If
+.B yes
+then
+.BR disorder-playrtp (1)
+will always request a dedicated RTP stream,
+rather than contacting the server to discover
+a broadcast or multicast address.
+(This behaviour can be overridden by
+setting a suitable address on the command-line.)
+The default is
+.BR no .
+.IP
+This option is experimental,
+and may change or be removed in a future release.
+.TP
+.B rtp_maxbuffer \fIFRAMES\fR
+Set
+.BR disorder-playrtp (1)'s
+buffer size to the given number of
+.IR FRAMES .
+If this is zero, then
+.B disorder-playrtp
+will select a default buffer size.
+(This setting can be overridden by passing
+a suitable command-line option.)
+The default value is
+.BR 0 .
+.IP
+This option is experimental,
+and may change or be removed in a future release.
+.TP
+.B rtp_max_payload \fBYTES\fR
+Don't send RTP packets with a UDP payload larger than
+.I BYTES
+(including the 12-byte RTP header). If you know that you will be transmitting
+RTP over networks with an unusually low MTU size, then it is probably useful to
+set this option.
+.IP
+This option is experimental,
+and may change or be removed in a future release.
+.TP
+.B rtp_minbuffer \fIFRAMES\fR
+Set
+.BR disorder-playrtp (1)'s
+buffer low-water-mark to the given number of
+.IR FRAMES .
+If this is zero, then
+.B disorder-playrtp
+will select a default low-water-mark.
+(This setting can be overridden by passing
+a suitable command-line option.)
+.IP
+This option is experimental,
+and may change or be removed in a future release.
+The default value is
+.BR 0 .
+.IP
+This option is experimental, and may change or be removed in a future release.
+.TP
+.B rtp_mode \fIMODE\fR
+The network transmission mode for the \fBrtp\fR backend.
+Possible values are:
+.RS
+.TP
+.B unicast
+Unicast transmission to the address given by \fBbroadcast\fR.
+.TP
+.B broadcast
+Broadcast transmission to the address given by \fBbroadcast\fR.
+.TP
+.B multicast
+Multicast transmission to the address given by \fBbroadcast\fR.
+.TP
+.B request
+Unicast transmission to addresses requested by clients.
+.TP
+.B auto
+Choose one of the above based on the destination address.
+This is the default, for backwards compatibility reasons.
+.RE
+.TP
+.B rtp_mtu_discovery \fIOPTION\fR
+Control whether the system attemps path-MTU discovery using RTP packets
+transmitted over IPv4. (This is not configurable in IPv6.) Possible values
+are:
+.RS
+.TP
+.B default
+Do whatever the kernel usually does with UDP packets. This is, err, the
+default.
+.TP
+.B yes
+Force path-MTU disocvery. The `don't fragment' bit is set on outgoing packets
+and we assume that the kernel will handle ICMP `fragmentation needed' errors
+coming back and fragment accordingly.
+.TP
+.B no
+Disable path-MTU discovery. Packets will be sent without the `don't fragment'
+bit, and routers will be expected to fragment packets as necessary.
+.RE
+.IP
+This option is experimental, and may change or be removed in a future release.
+.TP
+.B rtp_rcvbuf \fISIZE\fR
+Set
+.BR disorder-playrtp (1)'s
+socket receive buffer to at least
+.IB SIZE .
+(This setting can be overridden by passing
+a suitable command-line option.)
+The default value is
+.BR 0 .
+.IP
+This option is experimental,
+and may change or be removed in a future release.
+.TP
+.B rtp_request_address \fR[\fIFAMILY\fR] \fR[\fIHOST\fR] \fISERVICE\fR
+If
+.BR disorder-playrtp (1)
+is to request a unicast RTP stream,
+then it should establish its receiving socket
+to listen on the given address.
+The
+.I FAMILY
+and
+.I HOST
+may be omitted, in which case
+.B disorder-playrtp
+uses heuristics to determine suitable values.
+The
+.I PORT
+may be omitted, in which case
+.B disorder-playrtp
+uses a kernel-allocated port.
+(This setting can be overridden by passing
+a suitable address on the command line.)
+The default is
+.RB ` "\- 0" ',
+which uses a heuristically-chosen address and a kernel-allocated port.
+.IP
+This option is experimental,
+and may change or be removed in a future release.
+.TP
.B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS
Describes the sample format expected by the \fBspeaker_command\fR (below).
The components of the format specification are as follows:
~mdw / disorder / blobdiff