.\"
-.\" Copyright (C) 2007-2009 Richard Kettlewell
+.\" Copyright (C) 2007-2009, 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
.PP
If an address and a port are specified then the RTP stream is assumed to be
multicast to that group address and port.
+.PP
+Alternatively, the
+.I ADDRESS
+can start with a
+.RB ` \- ',
+in which case
+.B disorder-playrtp
+will request a dedicated unicast stream from the server. The
+.RB ` \- '
+may be followed by an optional port, or address/port pair, which will be the
+local address/port to bind to and announce to the server.
.SH OPTIONS
-The default sound API is the first of the ones listed below that are available.
-Usually this implies ALSA under Linux and Core Audio under OS X.
.TP
-.B \-\-alsa\fR, \fB-\a
-Use ALSA to play sound.
+.B \-\-api\fR, -\fB-A\fR \fIAPI\fR
+Select the playback API.
+The possibilities are, depending on platform and compilation options:
+.RS 8
.TP
-.B \-\-oss\fR, \fB\-o
-Use OSS to play sound.
+.B pulseaudio
+PulseAudio.
.TP
-.B \-\-core\-audio\fR, \fB\-c
-Use Core Audio to play sound.
+.B alsa
+ALSA.
+Linux only.
+.TP
+.B oss
+OSS.
+.TP
+.B coreaudio
+Core Audio.
+OS X only.
+.TP
+.B command
+Pipe audio to a command.
+.RE
+.IP
+The default is the first of the possibilities above that is supported.
.TP
.B \-\-device \fIDEVICE\fR, \fB\-D \fIDEVICE\fR
Specifies the audio device to use.
.B "DEVICE NAMES"
below for more information.
.TP
+.B \-\-command \fICOMMAND\fR, \fB-e \fICOMMAND\fR
+Instead of sending to a physical audio device, invoke \fICOMMAND\fR using the
+shell and write audio samples to its standard input.
+Currently the input will be 44100KHz 16-bit signed stereo samples.
+If \fICOMMAND\fR exits it is re-executed; any samples that had been written to
+the pipe but not processed by the previous instance will be lost.
+.IP
+.B \-\-device
+is redundant with this option, but you might want to set
+.BR \-\-pause\-mode .
+.IP
+As an example,
+.B "-e \(aqcat > dump\(aq"
+would log audio data to a file for later processing.
+You could convert it to another format with, for instance:
+.IP
+.B "sox -c2 -traw -r44100 -s -w dump dump.wav"
+.TP
+.B \-\-pause\-mode \fIMODE\fR, \fB-P \fIMODE
+Set the pause mode for \fB\-\-command\fR to either \fBsilence\fR (the default), in
+which pauses are represented by sending silent samples, or \fBsuspend\fR, in which
+writes to the subprocess are suspended, requiring it to infer a pause from flow
+control.
+.TP
.B \-\-config \fIPATH\fR, \fB\-C \fIPATH
-Set the configuration file.
+Set the system configuration file.
The default is
+given by the
+.B DISORDER_CONFIG
+environment variable, defaulting to
.IR pkgconfdir/config .
.TP
+.B \-\-user-config \fIPATH\fR, \fB\-u \fIPATH
+Set the user configuration file.
+THe default is given by the
+.B DISORDER_USERCONFIG
+environment variable, defaulting to
+.IR $HOME/.disorder/passwd .
+.TP
.B \-\-socket \fIPATH\fR, \fB\-s \fIPATH
Set the control socket.
Normally this would not be used manually.
Display version number.
.SS "Buffer Control Options"
You shouldn't need to use these options.
+Their effects are subject to change between version without warning.
+You should consult the source code for details of their effects.
.TP
.B \-\-min \fIFRAMES\fR, \fB\-m \fIFRAMES\fR
Specifies the buffer low watermark in frames.
-If the number of frames falls below this value then playing will be
-stopped until the buffer fills up.
-.TP
-.B \-\-buffer \fIFRAMES\fR, \fB\-b \fIFRAMES\fR
-Specifies the buffer high watermark in frames.
-Once there are this many frames in the buffer, playing will be (re-)started.
+This also acts as the target buffer occupancy.
+The default is taken from the
+.B rtp_minbuffer
+configuration parameter.
.TP
.B \-\-max \fIFRAMES\fR, \fB\-x \fIFRAMES\fR
Specifies the maximum buffer size in frames.
If there are this many frames in the buffer then reading from the
network socket will be suspended.
-The default is four times the \fB\-\-buffer\fR value.
+The default is twice the \fB\-\-min\fR value.
+The default is taken from the
+.B rtp_maxbuffer
+configuration parameter.
.TP
.B \-\-rcvbuf \fIBYTES\fR, \fB\-R \fIBYTES\fR
Specifies socket receive buffer size.
-The default is 131072 (128Kbytes).
+The default is not to change the buffer size, i.e. you get whatever the
+local operating system chooses.
The buffer size will not be reduced below the operating system's default.
+The default is taken from the
+.B rtp_rcvbuf
+configuration parameter.
+.TP
+.B \-\-monitor\fR, \fB\-M
+Periodically report how close to the buffer low watermark the buffer is.
+If you have trouble with poor playback quality, enable this option to see if
+the buffer is emptying out (or overfilling, though there are measures to
+prevent that from happening).
+.SS "Deprecated Options"
+These options may be removed in a future version.
+Use \fB\-\-api\fR instead.
+.TP
+.B \-\-alsa\fR, \fB\-a
+Use ALSA to play sound.
+Only available on Linux.
+.TP
+.B \-\-oss\fR, \fB\-o
+Use OSS to play sound.
+Only available on Linux and FreeBSD.
+.TP
+.B \-\-core\-audio\fR, \fB\-c
+Use Core Audio to play sound.
+Only available on Macs.
.SH "REMOTE CONTROL"
The
.B \-\-socket
.TP
.B query
Causes the string "running" to be sent back.
+.TP
+.B getvol
+Print the left and right volume levels,
+as two decimal integers between 0 and 100,
+separated by a space.
+.TP
+.BI "setvol " left " " right
+Set the left and right volume levels to the given decimal values,
+which should be between 0 and 100;
+echo back the new values as for
+.B getvol
+above.
.PP
Other commands are ignored.
After the first command the connection is closed.
~mdw / disorder / blobdiff