X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/23205f9cdd229343a83d8c5a6317d9187e90c3d4..591bec8587c71a025bcc83092145b0ef9ffbe944:/doc/disorder-playrtp.1.in diff --git a/doc/disorder-playrtp.1.in b/doc/disorder-playrtp.1.in index 7ff59b9..c92c55a 100644 --- a/doc/disorder-playrtp.1.in +++ b/doc/disorder-playrtp.1.in @@ -1,64 +1,162 @@ .\" -.\" 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 . .\" .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. .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 --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 \-\-alsa\fR, \fB\-a +Use ALSA to play sound. +Only available on Linux. .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 \-\-oss\fR, \fB\-o +Use OSS to play sound. +Only available on Linux and FreeBSD. .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 \-\-core\-audio\fR, \fB\-c +Use Core Audio to play sound. +Only available on Macs. .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 \-\-device \fIDEVICE\fR, \fB\-D \fIDEVICE\fR +Specifies the audio device to use. +See +.B "DEVICE NAMES" +below for more information. .TP -.B --rcvbuf \fIBYTES\fR, \fB-R \fIBYTES\fR -Specifies socket receive buffer size. +.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 --multicast \fIGROUP\fR, \fB-M \fIGROUP\fR -Specifies a multicast group to join. +.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 --help\fR, \fB-h +.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: