clients/playrtp.c: Improve message reporting a unicast stream request.

[disorder] / doc / disorder-playrtp.1.in

.\"
.\" 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
.\" 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.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" 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
.RI [ OPTIONS ]
.RB [ \-\- ]
.RI [[ ADDRESS ]
.IR PORT ]
.SH DESCRIPTION
\fBdisorder\-playrtp\fR plays a network broadcast sent from the specified
address.
.PP
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.
.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
.TP
.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 pulseaudio
PulseAudio.
.TP
.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.
See
.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.
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
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).
.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
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.
.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.
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:
.\" mode:nroff
.\" fill-column:79
.\" End: