chiark - git - mdw - disorder/blob - doc/disorder-playrtp.1.in

   1 .\"
   2 .\" Copyright (C) 2007-2009, 2013 Richard Kettlewell
   3 .\"
   4 .\" This program is free software: you can redistribute it and/or modify
   5 .\" it under the terms of the GNU General Public License as published by
   6 .\" the Free Software Foundation, either version 3 of the License, or
   7 .\" (at your option) any later version.
   8 .\"
   9 .\" This program is distributed in the hope that it will be useful,
  10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 .\" GNU General Public License for more details.
  13 .\"
  14 .\" You should have received a copy of the GNU General Public License
  15 .\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16 .\"
  17 .TH disorder-playrtp 1
  18 .SH NAME
  19 disorder-playrtp \- play DisOrder network broadcasts
  20 .SH SYNOPSIS
  21 .B disorder\-playrtp
  22 .RI [ OPTIONS ]
  23 .RB [ \-\- ]
  24 .RI [[ ADDRESS ]
  25 .IR PORT ]
  26 .SH DESCRIPTION
  27 \fBdisorder\-playrtp\fR plays a network broadcast sent from the specified
  28 address.
  29 .PP
  30 If neither an address nor port are specified then the local DisOrder
  31 configuration is consulted to find the server and the server is asked where the
  32 RTP stream is.
  33 .PP
  34 If just a port is specified then the RTP stream is assumed to be unicast or
  35 broadcast to that port.
  36 .PP
  37 If an address and a port are specified then the RTP stream is assumed to be
  38 multicast to that group address and port.
  39 .PP
  40 Alternatively, the
  41 .I ADDRESS
  42 can start with a
  43 .RB ` \- ',
  44 in which case
  45 .B disorder-playrtp
  46 will request a dedicated unicast stream from the server.  The
  47 .RB ` \- '
  48 may be followed by an optional port, or address/port pair, which will be the
  49 local address/port to bind to and announce to the server.
  50 .SH OPTIONS
  51 .TP
  52 .B \-\-api\fR, -\fB-A\fR \fIAPI\fR
  53 Select the playback API.
  54 The possibilities are, depending on platform and compilation options:
  55 .RS 8
  56 .TP
  57 .B pulseaudio
  58 PulseAudio.
  59 .TP
  60 .B alsa
  61 ALSA.
  62 Linux only.
  63 .TP
  64 .B oss
  65 OSS.
  66 .TP
  67 .B coreaudio
  68 Core Audio.
  69 OS X only.
  70 .TP
  71 .B command
  72 Pipe audio to a command.
  73 .RE
  74 .IP
  75 The default is the first of the possibilities above that is supported.
  76 .TP
  77 .B \-\-device \fIDEVICE\fR, \fB\-D \fIDEVICE\fR
  78 Specifies the audio device to use.
  79 See
  80 .B "DEVICE NAMES"
  81 below for more information.
  82 .TP
  83 .B \-\-command \fICOMMAND\fR, \fB-e \fICOMMAND\fR
  84 Instead of sending to a physical audio device, invoke \fICOMMAND\fR using the
  85 shell and write audio samples to its standard input.
  86 Currently the input will be 44100KHz 16-bit signed stereo samples.
  87 If \fICOMMAND\fR exits it is re-executed; any samples that had been written to
  88 the pipe but not processed by the previous instance will be lost.
  89 .IP
  90 .B \-\-device
  91 is redundant with this option, but you might want to set
  92 .BR \-\-pause\-mode .
  93 .IP
  94 As an example,
  95 .B "-e \(aqcat > dump\(aq"
  96 would log audio data to a file for later processing.
  97 You could convert it to another format with, for instance:
  98 .IP
  99 .B "sox -c2 -traw -r44100 -s -w dump dump.wav"
 100 .TP
 101 .B \-\-pause\-mode \fIMODE\fR, \fB-P \fIMODE
 102 Set the pause mode for \fB\-\-command\fR to either \fBsilence\fR (the default), in
 103 which pauses are represented by sending silent samples, or \fBsuspend\fR, in which
 104 writes to  the subprocess are suspended, requiring it to infer a pause from flow
 105 control.
 106 .TP
 107 .B \-\-config \fIPATH\fR, \fB\-C \fIPATH
 108 Set the system configuration file.
 109 The default is
 110 given by the
 111 .B DISORDER_CONFIG
 112 environment variable, defaulting to
 113 .IR pkgconfdir/config .
 114 .TP
 115 .B \-\-user-config \fIPATH\fR, \fB\-u \fIPATH
 116 Set the user configuration file.
 117 THe default is given by the
 118 .B DISORDER_USERCONFIG
 119 environment variable, defaulting to
 120 .IR $HOME/.disorder/passwd .
 121 .TP
 122 .B \-\-socket \fIPATH\fR, \fB\-s \fIPATH
 123 Set the control socket.
 124 Normally this would not be used manually.
 125 .TP
 126 .B \-\-help\fR, \fB\-h
 127 Display a usage message.
 128 .TP
 129 .B \-\-version\fR, \fB\-V
 130 Display version number.
 131 .SS "Buffer Control Options"
 132 You shouldn't need to use these options.
 133 Their effects are subject to change between version without warning.
 134 You should consult the source code for details of their effects.
 135 .TP
 136 .B \-\-min \fIFRAMES\fR, \fB\-m \fIFRAMES\fR
 137 Specifies the buffer low watermark in frames.
 138 This also acts as the target buffer occupancy.
 139 The default is taken from the
 140 .B rtp_minbuffer
 141 configuration parameter.
 142 .TP
 143 .B \-\-max \fIFRAMES\fR, \fB\-x \fIFRAMES\fR
 144 Specifies the maximum buffer size in frames.
 145 If there are this many frames in the buffer then reading from the
 146 network socket will be suspended.
 147 The default is twice the \fB\-\-min\fR value.
 148 The default is taken from the
 149 .B rtp_maxbuffer
 150 configuration parameter.
 151 .TP
 152 .B \-\-rcvbuf \fIBYTES\fR, \fB\-R \fIBYTES\fR
 153 Specifies socket receive buffer size.
 154 The default is not to change the buffer size, i.e. you get whatever the
 155 local operating system chooses.
 156 The buffer size will not be reduced below the operating system's default.
 157 The default is taken from the
 158 .B rtp_rcvbuf
 159 configuration parameter.
 160 .TP
 161 .B \-\-monitor\fR, \fB\-M
 162 Periodically report how close to the buffer low watermark the buffer is.
 163 If you have trouble with poor playback quality, enable this option to see if
 164 the buffer is emptying out (or overfilling, though there are measures to
 165 prevent that from happening).
 166 .SS "Deprecated Options"
 167 These options may be removed in a future version.
 168 Use \fB\-\-api\fR instead.
 169 .TP
 170 .B \-\-alsa\fR, \fB\-a
 171 Use ALSA to play sound.
 172 Only available on Linux.
 173 .TP
 174 .B \-\-oss\fR, \fB\-o
 175 Use OSS to play sound.
 176 Only available on Linux and FreeBSD.
 177 .TP
 178 .B \-\-core\-audio\fR, \fB\-c
 179 Use Core Audio to play sound.
 180 Only available on Macs.
 181 .SH "REMOTE CONTROL"
 182 The
 183 .B \-\-socket
 184 option is used by Disobedience to control a background
 185 .B disorder\-playrtp
 186 daemon.
 187 The socket will be created as a UNIX domain stream socket.
 188 When a connection is received a single line is read from it.
 189 The following commands are known:
 190 .TP
 191 .B stop
 192 Causes
 193 .B disorder\-playrtp
 194 to terminate.
 195 .TP
 196 .B query
 197 Causes the string "running" to be sent back.
 198 .TP
 199 .B getvol
 200 Print the left and right volume levels,
 201 as two decimal integers between 0 and 100,
 202 separated by a space.
 203 .TP
 204 .BI "setvol " left " " right
 205 Set the left and right volume levels to the given decimal values,
 206 which should be between 0 and 100;
 207 echo back the new values as for
 208 .B getvol
 209 above.
 210 .PP
 211 Other commands are ignored.
 212 After the first command the connection is closed.
 213 Only one connection at a time will be serviced.
 214 .PP
 215 This protocol is not guaranteed to be stable.
 216 .SH "DEVICE NAMES"
 217 .SS "Core Audio"
 218 On a Mac, the device name can either be the human-readable name of the desired
 219 output or its UID.
 220 To get a list of the human-readable names, visit System Preferences -> Sound;
 221 the Type column has the name you want.
 222 .PP
 223 For example, you might use "Built-in Output" for the built-in speaker
 224 or "Built-in Line Output" if you have connected external speakers.
 225 Remember to quote the name.
 226 .SH "SEE ALSO"
 227 .BR disobedience (1),
 228 .BR disorder_config (5),
 229 .BR disorderd (8)
 230 .\" Local Variables:
 231 .\" mode:nroff
 232 .\" fill-column:79
 233 .\" End: