X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/22b9fa74de8e80471a5033ea067d3b360930b91d..8ab2aa9fd51a89e06d92a4f7c3792aaa4a08cc71:/doc/disorder-playrtp.1.in diff --git a/doc/disorder-playrtp.1.in b/doc/disorder-playrtp.1.in index 18ca149..24ad03f 100644 --- a/doc/disorder-playrtp.1.in +++ b/doc/disorder-playrtp.1.in @@ -1,61 +1,223 @@ .\" -.\" Copyright (C) 2007 Richard Kettlewell +.\" Copyright (C) 2007-2009, 2013 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-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 +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 --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 \-\-api\fR, -\fB-A\fR \fIAPI\fR +Select the playback API. +The possibilities are, depending on platform and compilation options: +.RS 8 .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 pulseaudio +PulseAudio. .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 alsa +ALSA. +Linux only. .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 oss +OSS. .TP -.B --rcvbuf \fIBYTES\fR, \fB-R \fIBYTES\fR -Specifies socket receive buffer size. +.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 +given by the +.B DISORDER_CONFIG +environment variable, defaulting to +.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 +.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. +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 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 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 +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: