1 files changed, 70 insertions, 11 deletions
diff --git a/usr.bin/aucat/aucat.1 b/usr.bin/aucat/aucat.1
index d29af368242..d0a75d212f8 100644
--- a/usr.bin/aucat/aucat.1
+++ b/usr.bin/aucat/aucat.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: aucat.1,v 1.65 2010/04/03 17:59:17 ratchov Exp $
+.\"	$OpenBSD: aucat.1,v 1.66 2010/04/06 20:07:01 ratchov Exp $
 .\"
 .\" Copyright (c) 2006 Alexandre Ratchov <alex@caoua.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: April 3 2010 $
+.Dd $Mdocdate: April 6 2010 $
 .Dt AUCAT 1
 .Os
 .Sh NAME
@@ -33,6 +33,7 @@
 .Op Fl i Ar file
 .Op Fl m Ar mode
 .Op Fl o Ar file
+.Op Fl q Ar device
 .Op Fl r Ar rate
 .Op Fl s Ar name
 .Op Fl t Ar mode
@@ -57,7 +58,7 @@ which does not convert on the fly and supports playback of .au files.
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl b Ar nframes
-The buffer size in frames.
+The buffer size of the audio device in frames.
 A frame consists of one sample for each channel in the stream.
 This is the number of frames that will be buffered before being played
 and thus controls the playback latency.
@@ -105,15 +106,20 @@ but other names can be used with the
 .Fl s
 option.
 .It Fl m Ar mode
-Set the server mode.
+Set the stream mode.
 Valid modes are
 .Ar play ,
 .Ar rec ,
 and
-.Ar duplex ,
-for play-only, record-only, and full-duplex, respectively.
+.Ar mon ,
+corresponding to playback, recording and monitoring.
+A monitoring stream is a fake recording stream corresponding to
+the mix of all playback streams.
+Multiple modes can be specified, separated by commas,
+but the same stream cannot be used for both recording and monitoring.
 The default is
-.Ar duplex .
+.Ar play , rec
+(i.e. full-duplex).
 .It Fl n
 Loopback mode.
 Instead of using an audio device, send input streams
@@ -125,6 +131,11 @@ Add this file to the list of files in which to store recorded samples.
 If the option argument is
 .Sq -
 then standard output will be used.
+.It Fl q Ar device
+The
+.Xr sndio 7
+MIDI device to use for controlling stream volumes or
+to start multiple streams synchronously.
 .It Fl r Ar rate
 Sample rate in Hertz of the playback or record stream.
 The default is 44100Hz.
@@ -275,7 +286,7 @@ File formats are specified using the
 .Fl h
 option.
 The following file formats are supported:
-.Bl -tag -width s32lexxx -offset -indent
+.Bl -tag -width s32lexxx -offset indent
 .It raw
 Headerless file.
 This format is recommended since it has no limitations.
@@ -296,7 +307,7 @@ Encodings are specified using the
 option.
 The following encodings are supported:
 .Pp
-.Bl -tag -width s32lexxx -offset -indent -compact
+.Bl -tag -width s32lexxx -offset indent -compact
 .It s8
 signed 8-bit
 .It u8
@@ -411,7 +422,7 @@ faders.
 Clients connected to sub-devices created with
 .Fl t
 are controlled by the following MMC (MIDI Machine Control) messages:
-.Bl -tag -width relocateXXX -offset -indent
+.Bl -tag -width relocateXXX -offset indent
 .It stop
 Put the sub-device in stopped mode (the default).
 In this mode, any stream attempting to start playback or recording
@@ -448,7 +459,7 @@ and block sizes
 .Pq Fl z
 are recommended for maximum accuracy:
 .Pp
-.Bl -bullet -offset -indent -compact
+.Bl -bullet -offset indent -compact
 .It
 44100Hz, 441 frames
 .It
@@ -475,6 +486,54 @@ behave normally, while streams connected to
 wait for the MMC start signal and start synchronously.
 Regardless of which device a stream is connected to,
 its playback volume knob is exposed.
+.Pp
+If
+.Nm
+is used to play and record audio files, it offers
+similar MIDI control.
+.Nm
+can open a
+.Xr sndio 7
+MIDI device allowing MIDI hardware or software
+to control playback and recording in real time.
+.Pp
+A MIDI channel is assigned to each stream, and the volume
+is changed using the standard volume controller (number 7).
+Streams created with
+.Fl t
+option are controlled by the following MIDI Machine Control (MMC) messages:
+.Bl -tag -width relocateXXX -offset indent
+.It start
+Start all streams synchronously.
+By default, streams are created in a stopped state.
+.It stop
+Playback or recording is stopped, and
+the stream is rewound back to the starting position.
+.It relocate
+Streams are relocated to the requested time postion
+relative to the beginning of the stream, at which playback
+and recording must start.
+If the requested position is beyond the end of file,
+the stream is temporarly disabled until a valid postion is requested.
+.El
+.Pp
+For instance, the following command will play a file on the
+.Va aucat:0.mmc
+audio device, and give full control to MIDI software or hardware
+connected to the
+.Va midithru:0
+MIDI device:
+.Bd -literal -offset indent
+$ aucat -f aucat:0.mmc -t slave -q midithru:0 -i file.wav
+.Ed
+.Pp
+At this stage,
+.Nm
+will start, stop and relocate automatically following all user
+actions in the MIDI sequencer.
+Note that the sequencer must use
+.Va aucat:0
+as the MTC source, i.e. the audio server, not the audio player.
 .Sh LEGACY MODE
 If neither
 .Fl i