.\"
-.\" Copyright (C) 2007 Richard Kettlewell
+.\" Copyright (C) 2007-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-playrtp 1
.SH NAME
disorder-playrtp \- play DisOrder network broadcasts
.SH SYNOPSIS
-.B disorder-playrtp
+.B disorder\-playrtp
.RI [ OPTIONS ]
-.RB [ -- ]
-.I ADDRESS
-.I PORT
+.RB [ \-\- ]
+.RI [[ ADDRESS ]
+.IR PORT ]
.SH DESCRIPTION
-\fBdisorder-playrtp\fR plays a network broadcast sent from the specified
+\fBdisorder\-playrtp\fR plays a network broadcast sent from the specified
address.
.PP
-It is currently a work in progress!
+If neither an address nor port are specified then the local DisOrder
+configuration is consulted to find the server and the server is asked where the
+RTP stream is.
+.PP
+If just a port is specified then the RTP stream is assumed to be unicast or
+broadcast to that port.
+.PP
+If an address and a port are specified then the RTP stream is assumed to be
+multicast to that group address and port.
.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.
+Only available on Linux.
.TP
-.B --device \fIDEVICE\fR, \fB-D \fIDEVICE\fR
-Specifies the audio device to use. The exact meaning of this is
-platform-dependent; on Linux it is the ALSA device name.
+.B \-\-oss\fR, \fB\-o
+Use OSS to play sound.
+Only available on Linux and FreeBSD.
.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.
+.B \-\-core\-audio\fR, \fB\-c
+Use Core Audio to play sound.
+Only available on Macs.
.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.
+.B \-\-device \fIDEVICE\fR, \fB\-D \fIDEVICE\fR
+Specifies the audio device to use.
+See
+.B "DEVICE NAMES"
+below for more information.
.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.
+.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 --help\fR, \fB-h
+.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.
+The default is
+.IR pkgconfdir/config .
+.TP
+.B \-\-socket \fIPATH\fR, \fB\-s \fIPATH
+Set the control socket.
+Normally this would not be used manually.
+.TP
+.B \-\-help\fR, \fB\-h
Display a usage message.
.TP
-.B --version\fR, \fB-V
+.B \-\-version\fR, \fB\-V
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.
+This also acts as the target buffer occupancy.
+.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 twice the \fB\-\-min\fR value.
+.TP
+.B \-\-rcvbuf \fIBYTES\fR, \fB\-R \fIBYTES\fR
+Specifies socket receive buffer size.
+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.
+.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).
+.SH "REMOTE CONTROL"
+The
+.B \-\-socket
+option is used by Disobedience to control a background
+.B disorder\-playrtp
+daemon.
+The socket will be created as a UNIX domain stream socket.
+When a connection is received a single line is read from it.
+The following commands are known:
+.TP
+.B stop
+Causes
+.B disorder\-playrtp
+to terminate.
+.TP
+.B query
+Causes the string "running" to be sent back.
+.PP
+Other commands are ignored.
+After the first command the connection is closed.
+Only one connection at a time will be serviced.
+.PP
+This protocol is not guaranteed to be stable.
+.SH "DEVICE NAMES"
+.SS "Core Audio"
+On a Mac, the device name can either be the human-readable name of the desired
+output or its UID.
+To get a list of the human-readable names, visit System Preferences -> Sound;
+the Type column has the name you want.
+.PP
+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.
.SH "SEE ALSO"
+.BR disobedience (1),
.BR disorder_config (5),
.BR disorderd (8)
.\" Local Variables:
~mdw / disorder / blobdiff