2011-03-17 02:43:36 -05:00
|
|
|
.\" $OpenBSD$
|
2010-08-19 15:38:45 -05:00
|
|
|
.\"
|
|
|
|
.\" Copyright (c) 2006 Alexandre Ratchov <alex@caoua.org>
|
|
|
|
.\"
|
|
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
|
|
.\"
|
|
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
|
|
.\"
|
2011-03-17 02:43:36 -05:00
|
|
|
.Dd $Mdocdate$
|
2010-08-19 15:38:45 -05:00
|
|
|
.Dt AUCAT 1
|
|
|
|
.Os
|
|
|
|
.Sh NAME
|
|
|
|
.Nm aucat
|
|
|
|
.Nd audio server and stream manipulation tool
|
|
|
|
.Sh SYNOPSIS
|
|
|
|
.Nm aucat
|
|
|
|
.Bk -words
|
2011-06-29 02:36:03 -05:00
|
|
|
.Op Fl dln
|
2010-08-19 15:38:45 -05:00
|
|
|
.Op Fl a Ar flag
|
|
|
|
.Op Fl b Ar nframes
|
|
|
|
.Op Fl C Ar min : Ns Ar max
|
|
|
|
.Op Fl c Ar min : Ns Ar max
|
|
|
|
.Op Fl e Ar enc
|
|
|
|
.Op Fl f Ar device
|
|
|
|
.Op Fl h Ar fmt
|
|
|
|
.Op Fl i Ar file
|
|
|
|
.Op Fl j Ar flag
|
2011-04-18 05:14:27 -05:00
|
|
|
.Op Fl L Ar addr
|
2010-08-19 15:38:45 -05:00
|
|
|
.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
|
|
|
|
.Op Fl U Ar unit
|
2011-06-29 02:36:03 -05:00
|
|
|
.Op Fl u Ar flag
|
2010-08-19 15:38:45 -05:00
|
|
|
.Op Fl v Ar volume
|
2011-05-13 06:38:34 -05:00
|
|
|
.Op Fl w Ar flag
|
2010-08-19 15:38:45 -05:00
|
|
|
.Op Fl x Ar policy
|
|
|
|
.Op Fl z Ar nframes
|
|
|
|
.Ek
|
|
|
|
.Sh DESCRIPTION
|
|
|
|
.Nm
|
|
|
|
is an audio utility which can simultaneously play and record
|
|
|
|
any number of audio
|
|
|
|
.Em streams
|
|
|
|
on any number of audio devices,
|
|
|
|
possibly controlled through MIDI.
|
|
|
|
It can also act as an audio server, in which case streams
|
|
|
|
correspond to client connections rather than plain files.
|
|
|
|
.Pp
|
|
|
|
Audio devices are independent.
|
|
|
|
A list of streams is attached to each audio device,
|
|
|
|
as well as an optional list of MIDI ports to control the device.
|
|
|
|
A typical invocation of
|
|
|
|
.Nm
|
|
|
|
consists in providing streams to play and record,
|
|
|
|
and possibly the audio device to use, if the default is not desired.
|
|
|
|
.Pp
|
|
|
|
This also applies to server mode, except that streams are created
|
|
|
|
dynamically when clients connect to the server.
|
|
|
|
Thus, instead of actual streams (paths to plain files),
|
|
|
|
templates for client streams (sub-device names) must be provided.
|
|
|
|
.Pp
|
|
|
|
The options are as follows:
|
|
|
|
.Bl -tag -width Ds
|
|
|
|
.It Fl a Ar flag
|
|
|
|
Control whether
|
|
|
|
.Nm
|
2011-06-20 11:17:11 -05:00
|
|
|
opens the audio device only when needed or keeps it open all the time.
|
|
|
|
This applies to MIDI ports controlling the device as well.
|
2010-08-19 15:38:45 -05:00
|
|
|
If the flag is
|
|
|
|
.Va on
|
2011-06-20 11:17:11 -05:00
|
|
|
then the device is kept open all the time, ensuring no other program can
|
|
|
|
steal it.
|
2010-08-19 15:38:45 -05:00
|
|
|
If the flag is
|
|
|
|
.Va off ,
|
|
|
|
then it's automatically closed, allowing other programs to have direct
|
2011-06-20 11:17:11 -05:00
|
|
|
access to the device, or the device to be disconnected.
|
2010-08-19 15:38:45 -05:00
|
|
|
The default is
|
|
|
|
.Va on .
|
|
|
|
.It Fl b Ar nframes
|
|
|
|
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.
|
|
|
|
.It Xo
|
|
|
|
.Fl C Ar min : Ns Ar max ,
|
|
|
|
.Fl c Ar min : Ns Ar max
|
|
|
|
.Xc
|
|
|
|
The range of stream channel numbers for recording and playback directions,
|
|
|
|
respectively.
|
|
|
|
The default is 0:1, i.e. stereo.
|
|
|
|
.It Fl d
|
|
|
|
Increase log verbosity.
|
|
|
|
.Nm
|
2011-04-05 10:42:38 -05:00
|
|
|
logs on
|
|
|
|
.Em stderr
|
|
|
|
until it daemonizes.
|
2010-08-19 15:38:45 -05:00
|
|
|
.It Fl e Ar enc
|
|
|
|
Encoding of the playback or recording stream (see below).
|
|
|
|
The default is signed, 16-bit, native byte order.
|
|
|
|
.It Fl f Ar device
|
|
|
|
Add this
|
|
|
|
.Xr sndio 7
|
|
|
|
audio device to devices used for playing and/or recording.
|
|
|
|
Preceding streams
|
|
|
|
.Pq Fl ios ,
|
|
|
|
control MIDI ports
|
|
|
|
.Pq Fl q ,
|
|
|
|
and per-device options
|
2011-06-29 02:36:03 -05:00
|
|
|
.Pq Fl abuwz
|
2010-08-19 15:38:45 -05:00
|
|
|
apply to this device.
|
|
|
|
Device mode and parameters are determined from streams
|
|
|
|
attached to it.
|
|
|
|
.It Fl h Ar fmt
|
|
|
|
File format of the playback or record stream (see below).
|
|
|
|
The default is auto.
|
|
|
|
.It Fl i Ar file
|
|
|
|
Add this file to the list of streams to play.
|
|
|
|
If the option argument is
|
|
|
|
.Sq -
|
|
|
|
then standard input will be used.
|
|
|
|
.It Fl j Ar flag
|
|
|
|
Control whether stream channels are joined or expanded if
|
|
|
|
the stream number of channels is not equal to the device number of channels.
|
|
|
|
If the flag is
|
|
|
|
.Va off
|
|
|
|
then stream channels are routed to the corresponding
|
|
|
|
device channel, possibly discarding channels not present in the device.
|
|
|
|
If the flag is
|
|
|
|
.Va on ,
|
|
|
|
then a single stream channel may be sent on multiple device channels,
|
|
|
|
or multiple stream channels may be sent to a single device channel.
|
|
|
|
For instance, this feature could be used to request mono streams to
|
|
|
|
be sent on multiple outputs or to record a stereo input into a mono stream.
|
|
|
|
The default is
|
|
|
|
.Ar on .
|
2011-04-18 05:14:27 -05:00
|
|
|
.It Fl L Ar addr
|
2011-04-27 14:17:27 -05:00
|
|
|
Specify a local network address to listen on in server mode.
|
2011-04-18 08:17:04 -05:00
|
|
|
.Nm
|
|
|
|
will listen on TCP port 11025+n, where n is the unit number
|
|
|
|
specified with
|
|
|
|
.Fl U .
|
2011-04-18 05:14:27 -05:00
|
|
|
Without this option,
|
|
|
|
.Nm
|
2011-04-18 08:17:04 -05:00
|
|
|
listens on the
|
|
|
|
.Ux Ns -domain
|
2011-04-27 14:17:27 -05:00
|
|
|
socket only, and is not reachable from any network.
|
2011-05-03 14:36:52 -05:00
|
|
|
If the option argument is
|
|
|
|
.Sq -
|
|
|
|
then
|
|
|
|
.Nm
|
|
|
|
will accept connections from any address.
|
2010-08-19 15:38:45 -05:00
|
|
|
.It Fl l
|
|
|
|
Detach and become a daemon.
|
|
|
|
.It Fl m Ar mode
|
|
|
|
Set the stream mode.
|
|
|
|
Valid modes are
|
|
|
|
.Ar play ,
|
|
|
|
.Ar rec ,
|
|
|
|
and
|
|
|
|
.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 play , Ns Ar rec
|
|
|
|
(i.e. full-duplex).
|
|
|
|
.It Fl n
|
|
|
|
Loopback mode.
|
|
|
|
Instead of using audio devices, send input streams
|
|
|
|
to the output, processing them on the fly.
|
|
|
|
This mode is useful to mix, demultiplex, resample or reencode
|
|
|
|
audio files offline.
|
|
|
|
.It Fl o Ar file
|
|
|
|
Add this file to the list of recording streams.
|
|
|
|
If the option argument is
|
|
|
|
.Sq -
|
|
|
|
then standard output will be used.
|
|
|
|
.It Fl q Ar device
|
|
|
|
Expose the audio device clock on this
|
|
|
|
.Xr sndio 7
|
|
|
|
MIDI port and allow audio device properties to be controlled
|
|
|
|
through MIDI.
|
|
|
|
This includes per-stream volumes and the ability to
|
|
|
|
synchronously start, stop and relocate streams created in
|
|
|
|
MIDI Machine
|
|
|
|
Control (MMC) slave mode
|
|
|
|
.Pq Fl t .
|
|
|
|
.It Fl r Ar rate
|
|
|
|
Sample rate in Hertz of the stream.
|
|
|
|
The default is 44100Hz.
|
|
|
|
.It Fl s Ar name
|
|
|
|
Add
|
|
|
|
.Ar name
|
|
|
|
to the list of sub-devices to expose in server mode.
|
|
|
|
This allows clients to use
|
|
|
|
.Nm
|
|
|
|
instead of the physical audio device for audio input and output
|
|
|
|
in order to share the physical device with other clients.
|
|
|
|
Defining multiple sub-devices allows splitting a physical audio device
|
|
|
|
into logical devices having different properties (e.g. channel ranges).
|
|
|
|
The given
|
|
|
|
.Ar name
|
|
|
|
corresponds to the
|
|
|
|
.Dq option
|
|
|
|
part of the
|
|
|
|
.Xr sndio 7
|
|
|
|
device name string.
|
|
|
|
.It Fl t Ar mode
|
|
|
|
Select the way streams are controlled by MIDI Machine Control (MMC)
|
|
|
|
messages.
|
|
|
|
If the mode is
|
|
|
|
.Va off
|
|
|
|
(the default), then streams are not affected by MMC messages.
|
|
|
|
If the mode is
|
|
|
|
.Va slave ,
|
|
|
|
then streams are started synchronously by MMC start messages;
|
|
|
|
additionally, the server clock is exposed as MIDI Time Code (MTC)
|
|
|
|
messages allowing MTC-capable software or hardware to be synchronized
|
|
|
|
to audio streams.
|
|
|
|
.It Fl U Ar unit
|
|
|
|
Unit number to use when running in server mode.
|
|
|
|
Each
|
|
|
|
.Nm
|
|
|
|
server instance has an unique unit number,
|
|
|
|
used in
|
|
|
|
.Xr sndio 7
|
|
|
|
device names.
|
|
|
|
The default is 0.
|
2011-06-29 02:36:03 -05:00
|
|
|
.It Fl u Ar flag
|
|
|
|
Control how parameters of the audio device are chosen.
|
|
|
|
If the flag is
|
|
|
|
.Va on
|
|
|
|
then
|
2010-08-19 15:38:45 -05:00
|
|
|
.Nm
|
2011-06-29 02:36:03 -05:00
|
|
|
tries to automatically determine the optimal parameters to
|
|
|
|
match stream parameters and avoid conversions if possible.
|
|
|
|
If the flag is
|
|
|
|
.Va off
|
2010-08-19 15:38:45 -05:00
|
|
|
it will instead use the parameters specified by the
|
|
|
|
.Fl Ccer
|
|
|
|
options.
|
2011-06-29 02:36:03 -05:00
|
|
|
The default is
|
|
|
|
.Va on .
|
2010-08-19 15:38:45 -05:00
|
|
|
.It Fl v Ar volume
|
|
|
|
Software volume attenuation of the playback stream.
|
|
|
|
The value must be between 1 and 127,
|
2011-05-26 09:16:47 -05:00
|
|
|
corresponding to \-42dB and \-0dB attenuation in 1/3dB steps.
|
2010-08-19 15:38:45 -05:00
|
|
|
In server mode, clients inherit this parameter.
|
2011-05-26 09:16:47 -05:00
|
|
|
Reducing the volume in advance allows a client's volume to stay independent
|
2011-05-26 04:15:54 -05:00
|
|
|
from the number of clients as long as their number is small enough.
|
2011-05-26 09:16:47 -05:00
|
|
|
18 volume units (i.e. \-6dB attenuation) allows the number
|
2011-05-26 04:15:54 -05:00
|
|
|
of playback streams to be doubled.
|
2011-05-26 09:16:47 -05:00
|
|
|
The default is 127 i.e. no attenuation.
|
2011-05-13 06:38:34 -05:00
|
|
|
.It Fl w Ar flag
|
2011-05-26 01:57:55 -05:00
|
|
|
Control
|
|
|
|
.Nm
|
|
|
|
behaviour when the maximum volume of the hardware is reached
|
|
|
|
and a new stream is connected.
|
|
|
|
This happens only when stream volumes
|
|
|
|
are not properly set using the
|
|
|
|
.Fl v
|
|
|
|
option.
|
2011-05-13 06:38:34 -05:00
|
|
|
If the flag is
|
|
|
|
.Va on ,
|
2011-05-26 01:57:55 -05:00
|
|
|
then the master volume (corresponding to the mix of all playback streams)
|
|
|
|
is automatically adjusted to avoid clipping.
|
|
|
|
Using
|
2011-05-26 09:16:47 -05:00
|
|
|
.Va off
|
2011-05-26 01:57:55 -05:00
|
|
|
makes sense when all streams are recorded or produced with properly lowered
|
|
|
|
volumes.
|
2011-05-13 06:38:34 -05:00
|
|
|
The default is
|
|
|
|
.Va on .
|
2010-08-19 15:38:45 -05:00
|
|
|
.It Fl x Ar policy
|
|
|
|
Action when the output stream cannot accept
|
|
|
|
recorded data fast enough or the input stream
|
|
|
|
cannot provide data to play fast enough.
|
|
|
|
If the policy
|
|
|
|
is
|
|
|
|
.Dq ignore
|
|
|
|
(the default) then samples that cannot be written are discarded
|
|
|
|
and samples that cannot be read are replaced by silence.
|
|
|
|
If the policy is
|
|
|
|
.Dq sync
|
|
|
|
then recorded samples are discarded,
|
|
|
|
but the same amount of silence will be written
|
|
|
|
once the stream is unblocked, in order to reach the right position in time.
|
|
|
|
Similarly silence is played, but the same amount of samples will be discarded
|
|
|
|
once the stream is unblocked.
|
|
|
|
If the policy is
|
|
|
|
.Dq error
|
|
|
|
then the stream is closed permanently.
|
|
|
|
.Pp
|
|
|
|
If a stream is created with the
|
|
|
|
.Fl t
|
|
|
|
option,
|
|
|
|
the
|
|
|
|
.Dq ignore
|
|
|
|
action is disabled for any stream connected to it
|
|
|
|
to ensure proper synchronization.
|
|
|
|
.It Fl z Ar nframes
|
|
|
|
The audio device block size in frames.
|
|
|
|
This is the number of frames between audio clock ticks,
|
|
|
|
i.e. the clock resolution.
|
|
|
|
If a stream is created with the
|
|
|
|
.Fl t
|
|
|
|
option,
|
|
|
|
and MTC is used for synchronization, the clock
|
|
|
|
resolution must be 96, 100 or 120 ticks per second for maximum
|
|
|
|
accuracy.
|
|
|
|
For instance, 120 ticks per second at 48000Hz corresponds
|
|
|
|
to a 400 frame block size.
|
|
|
|
.El
|
|
|
|
.Pp
|
|
|
|
On the command line,
|
|
|
|
per-device parameters
|
2011-06-29 02:36:03 -05:00
|
|
|
.Pq Fl abuwz
|
2010-08-19 15:38:45 -05:00
|
|
|
must precede the device definition
|
2011-06-20 11:17:11 -05:00
|
|
|
.Pq Fl f ,
|
2010-08-19 15:38:45 -05:00
|
|
|
and per-stream parameters
|
|
|
|
.Pq Fl Ccehjmrtvx
|
|
|
|
must precede the stream definition
|
|
|
|
.Pq Fl ios .
|
|
|
|
MIDI ports
|
|
|
|
.Pq Fl q
|
2011-04-05 10:42:38 -05:00
|
|
|
and stream definitions
|
2010-08-19 15:38:45 -05:00
|
|
|
.Pq Fl ios
|
|
|
|
must precede the definition of the device
|
|
|
|
.Pq Fl f
|
|
|
|
to which they are attached.
|
|
|
|
Global parameters
|
2011-03-17 02:43:36 -05:00
|
|
|
.Pq Fl dlnUu
|
2010-08-19 15:38:45 -05:00
|
|
|
are position-independent.
|
|
|
|
.Pp
|
|
|
|
If no audio devices
|
|
|
|
.Pq Fl f
|
|
|
|
are specified,
|
|
|
|
settings are applied as if
|
|
|
|
the default device is specified as the last argument.
|
|
|
|
If no streams
|
|
|
|
.Pq Fl ios
|
|
|
|
are specified for a device, a default server sub-device is
|
|
|
|
created attached to it, meaning that
|
|
|
|
.Nm
|
|
|
|
behaves as an audio server.
|
|
|
|
The default
|
|
|
|
.Xr sndio 7
|
|
|
|
device is
|
|
|
|
.Pa aucat:0
|
|
|
|
.Pq also known as Pa aucat:0.default
|
|
|
|
.Pp
|
|
|
|
If
|
|
|
|
.Nm
|
|
|
|
is sent
|
|
|
|
.Dv SIGHUP ,
|
|
|
|
.Dv SIGINT
|
|
|
|
or
|
|
|
|
.Dv SIGTERM ,
|
|
|
|
it terminates recording to files.
|
|
|
|
.Pp
|
|
|
|
File formats are specified using the
|
|
|
|
.Fl h
|
|
|
|
option.
|
|
|
|
The following file formats are supported:
|
|
|
|
.Bl -tag -width s32lexxx -offset indent
|
|
|
|
.It raw
|
|
|
|
Headerless file.
|
|
|
|
This format is recommended since it has no limitations.
|
|
|
|
.It wav
|
|
|
|
Microsoft WAVE file format.
|
|
|
|
There are limitations inherent to the file format itself:
|
|
|
|
not all encodings are supported,
|
|
|
|
file sizes are limited to 2GB,
|
|
|
|
and the file must support the
|
|
|
|
.Xr lseek 2
|
|
|
|
operation (e.g. pipes do not support it).
|
|
|
|
.It auto
|
|
|
|
Try to guess, depending on the file name.
|
|
|
|
.El
|
|
|
|
.Pp
|
|
|
|
Encodings are specified using the
|
|
|
|
.Fl e
|
|
|
|
option.
|
|
|
|
The following encodings are supported:
|
|
|
|
.Pp
|
|
|
|
.Bl -tag -width s32lexxx -offset indent -compact
|
|
|
|
.It s8
|
|
|
|
signed 8-bit
|
|
|
|
.It u8
|
|
|
|
unsigned 8-bit
|
|
|
|
.It s16le
|
|
|
|
signed 16-bit, little endian
|
|
|
|
.It u16le
|
|
|
|
unsigned 16-bit, little endian
|
|
|
|
.It s16be
|
|
|
|
signed 16-bit, big endian
|
|
|
|
.It u16be
|
|
|
|
unsigned 16-bit, big endian
|
|
|
|
.It s24le
|
|
|
|
signed 24-bit, stored in 4 bytes, little endian
|
|
|
|
.It u24le
|
|
|
|
unsigned 24-bit, stored in 4 bytes, little endian
|
|
|
|
.It s24be
|
|
|
|
signed 24-bit, stored in 4 bytes, big endian
|
|
|
|
.It u24be
|
|
|
|
unsigned 24-bit, stored in 4 bytes, big endian
|
|
|
|
.It s32le
|
|
|
|
signed 32-bit, little endian
|
|
|
|
.It u32le
|
|
|
|
unsigned 32-bit, little endian
|
|
|
|
.It s32be
|
|
|
|
signed 32-bit, big endian
|
|
|
|
.It u32be
|
|
|
|
unsigned 32-bit, big endian
|
|
|
|
.It s24le3
|
|
|
|
signed 24-bit, packed in 3 bytes, little endian
|
|
|
|
.It u24le3
|
|
|
|
unsigned 24-bit, packed in 3 bytes, big endian
|
|
|
|
.It s24be3
|
|
|
|
signed 24-bit, packed in 3 bytes, little endian
|
|
|
|
.It u24be3
|
|
|
|
unsigned 24-bit, packed in 3 bytes, big endian
|
|
|
|
.It s20le3
|
|
|
|
signed 20-bit, packed in 3 bytes, little endian
|
|
|
|
.It u20le3
|
|
|
|
unsigned 20-bit, packed in 3 bytes, big endian
|
|
|
|
.It s20be3
|
|
|
|
signed 20-bit, packed in 3 bytes, little endian
|
|
|
|
.It u20be3
|
|
|
|
unsigned 20-bit, packed in 3 bytes, big endian
|
|
|
|
.It s18le3
|
|
|
|
signed 18-bit, packed in 3 bytes, little endian
|
|
|
|
.It u18le3
|
|
|
|
unsigned 18-bit, packed in 3 bytes, big endian
|
|
|
|
.It s18be3
|
|
|
|
signed 18-bit, packed in 3 bytes, little endian
|
|
|
|
.It u18be3
|
|
|
|
unsigned 18-bit, packed in 3 bytes, big endian
|
|
|
|
.El
|
|
|
|
.Sh SERVER MODE
|
|
|
|
If at least one sub-device
|
|
|
|
.Pq Fl s
|
|
|
|
is exposed by
|
|
|
|
.Nm ,
|
|
|
|
including the case when no stream options are given,
|
|
|
|
then
|
|
|
|
.Nm
|
|
|
|
can be used as a server
|
|
|
|
to overcome hardware limitations and allow applications
|
|
|
|
to run on fixed sample rate devices or on devices
|
|
|
|
supporting only unusual encodings.
|
|
|
|
.Pp
|
|
|
|
Certain applications, such as synthesis software,
|
|
|
|
require a low latency audio setup.
|
|
|
|
To reduce the probability of buffer underruns or overruns, especially
|
|
|
|
on busy machines, the server can be started by the super-user, in which
|
|
|
|
case it will run with higher priority.
|
|
|
|
Any user will still be able to connect to it,
|
|
|
|
but for privacy reasons only one user may have
|
|
|
|
connections to it at a given time.
|
|
|
|
.Sh MIDI CONTROL
|
|
|
|
.Nm
|
|
|
|
can expose the audio device clock on registered
|
|
|
|
MIDI ports
|
|
|
|
.Pq Fl q
|
|
|
|
and allows audio device properties to be controlled
|
|
|
|
through MIDI.
|
|
|
|
If running in server mode
|
|
|
|
.Nm
|
|
|
|
creates a MIDI port with the same name as the default audio
|
|
|
|
device to which MIDI programs can connect.
|
|
|
|
.Pp
|
|
|
|
A MIDI channel is assigned to each stream, and the volume
|
|
|
|
is changed using the standard volume controller (number 7).
|
|
|
|
Similarly, when the audio client changes its volume,
|
|
|
|
the same MIDI controller message is sent out; it can be used
|
|
|
|
for instance for monitoring or as feedback for motorized
|
|
|
|
faders.
|
|
|
|
.Pp
|
|
|
|
Streams created with the
|
|
|
|
.Fl t
|
|
|
|
option are controlled by the following MMC messages:
|
|
|
|
.Bl -tag -width relocateXXX -offset indent
|
|
|
|
.It relocate
|
2011-05-23 10:31:00 -05:00
|
|
|
Streams are relocated to the requested time position
|
2010-08-19 15:38:45 -05:00
|
|
|
relative to the beginning of the stream, at which playback
|
|
|
|
and recording must start.
|
|
|
|
If the requested position is beyond the end of file,
|
2011-05-23 10:31:00 -05:00
|
|
|
the stream is temporarly disabled until a valid position is requested.
|
2010-08-19 15:38:45 -05:00
|
|
|
This message is ignored by client streams (server mode).
|
|
|
|
The given time position is sent to MIDI ports as an MTC
|
|
|
|
.Dq "full frame"
|
|
|
|
message forcing all MTC-slaves to relocate to the given
|
|
|
|
position (see below).
|
|
|
|
.It start
|
|
|
|
Put all streams in starting mode.
|
|
|
|
In this mode,
|
|
|
|
.Nm
|
|
|
|
waits for all streams to become ready
|
|
|
|
to start, and then starts them synchronously.
|
|
|
|
Once started, new streams can be created (server mode)
|
|
|
|
but they will be blocked
|
|
|
|
until the next stop-to-start transition.
|
|
|
|
.It stop
|
|
|
|
Put all streams in stopped mode (the default).
|
|
|
|
In this mode, any stream attempting to start playback or recording
|
|
|
|
is paused.
|
|
|
|
Files are stopped and rewound back to the starting position,
|
|
|
|
while client streams (server mode) that are already
|
|
|
|
started are not affected until they stop and try to start again.
|
|
|
|
.El
|
|
|
|
.Pp
|
|
|
|
Streams created with the
|
|
|
|
.Fl t
|
|
|
|
option export the server clock using MTC, allowing non-audio
|
|
|
|
software or hardware to be synchronized to the audio stream.
|
2011-06-03 11:20:51 -05:00
|
|
|
Maximum accuracy is achieved when the number of blocks per
|
|
|
|
second is equal to one of the standard MTC clock rates (96, 100 and 120Hz).
|
2010-08-19 15:38:45 -05:00
|
|
|
The following sample rates
|
|
|
|
.Pq Fl r
|
|
|
|
and block sizes
|
|
|
|
.Pq Fl z
|
2011-06-03 11:20:51 -05:00
|
|
|
are recommended:
|
2010-08-19 15:38:45 -05:00
|
|
|
.Pp
|
|
|
|
.Bl -bullet -offset indent -compact
|
|
|
|
.It
|
2011-06-03 11:20:51 -05:00
|
|
|
44100Hz, 441 frames (MTC rate is 100Hz)
|
2010-08-19 15:38:45 -05:00
|
|
|
.It
|
2011-06-03 11:20:51 -05:00
|
|
|
48000Hz, 400 frames (MTC rate is 120Hz)
|
2010-08-19 15:38:45 -05:00
|
|
|
.It
|
2011-06-03 11:20:51 -05:00
|
|
|
48000Hz, 480 frames (MTC rate is 100Hz)
|
2010-08-19 15:38:45 -05:00
|
|
|
.It
|
2011-06-03 11:20:51 -05:00
|
|
|
48000Hz, 500 frames (MTC rate is 96Hz)
|
2010-08-19 15:38:45 -05:00
|
|
|
.El
|
|
|
|
.Pp
|
|
|
|
For instance, the following command will create two devices:
|
|
|
|
the default
|
|
|
|
.Va aucat:0
|
|
|
|
and a MIDI-controlled
|
|
|
|
.Va aucat:0.mmc :
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
$ aucat -l -r 48000 -z 400 -s default -t slave -s mmc
|
|
|
|
.Ed
|
|
|
|
.Pp
|
|
|
|
Streams connected to
|
|
|
|
.Va aucat:0
|
|
|
|
behave normally, while streams connected to
|
|
|
|
.Va aucat:0.mmc
|
|
|
|
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
|
|
|
|
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 -t slave -q midithru:0 -i file.wav -f aucat:0.mmc
|
|
|
|
.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 ENVIRONMENT
|
2011-04-16 11:30:24 -05:00
|
|
|
.Bl -tag -width "AUCAT_COOKIE" -compact
|
2011-04-27 14:17:27 -05:00
|
|
|
.It Ev AUCAT_COOKIE
|
2011-05-03 02:10:45 -05:00
|
|
|
File containing user's session cookie.
|
2010-08-19 15:38:45 -05:00
|
|
|
.It Ev AUDIODEVICE
|
|
|
|
.Xr sndio 7
|
|
|
|
audio device to use if the
|
|
|
|
.Fl f
|
|
|
|
option is not specified.
|
|
|
|
.El
|
|
|
|
.Sh EXAMPLES
|
2011-05-03 02:10:45 -05:00
|
|
|
Mix and play two stereo streams,
|
2010-08-19 15:38:45 -05:00
|
|
|
the first at 48kHz and the second at 44.1kHz:
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
$ aucat -r 48000 -i file1.raw -r 44100 -i file2.raw
|
|
|
|
.Ed
|
|
|
|
.Pp
|
2011-05-03 02:10:45 -05:00
|
|
|
Record channels 2 and 3 into one stereo file and
|
2010-08-19 15:38:45 -05:00
|
|
|
channels 6 and 7 into another stereo file using a 96kHz sampling rate for
|
|
|
|
both:
|
|
|
|
.Bd -literal -offset indent
|
2011-06-03 04:07:16 -05:00
|
|
|
$ aucat -j off -r 96000 -C 2:3 -o file1.raw -C 6:7 -o file2.raw
|
2010-08-19 15:38:45 -05:00
|
|
|
.Ed
|
|
|
|
.Pp
|
2011-05-03 02:10:45 -05:00
|
|
|
Split a stereo file into two mono files:
|
2010-08-19 15:38:45 -05:00
|
|
|
.Bd -literal -offset indent
|
2011-06-03 04:07:16 -05:00
|
|
|
$ aucat -n -j off -i stereo.wav -C 0:0 -o left.wav -C 1:1 -o right.wav
|
2010-08-19 15:38:45 -05:00
|
|
|
.Ed
|
|
|
|
.Pp
|
2011-05-03 02:10:45 -05:00
|
|
|
Start
|
2010-08-19 15:38:45 -05:00
|
|
|
.Nm
|
2011-05-03 02:10:45 -05:00
|
|
|
in server mode using default parameters, creating an
|
2010-08-19 15:38:45 -05:00
|
|
|
additional sub-device for output to channels 2:3 only (rear speakers
|
|
|
|
on most cards), exposing the
|
|
|
|
.Pa aucat:0
|
|
|
|
and
|
|
|
|
.Pa aucat:0.rear
|
|
|
|
devices:
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
$ aucat -l -s default -c 2:3 -s rear
|
|
|
|
.Ed
|
|
|
|
.Pp
|
2011-05-03 02:10:45 -05:00
|
|
|
Start
|
2010-08-19 15:38:45 -05:00
|
|
|
.Nm
|
2011-05-03 02:10:45 -05:00
|
|
|
in server mode, creating the default sub-device with low volume and
|
2010-08-19 15:38:45 -05:00
|
|
|
an additional sub-device for high volume output, exposing the
|
|
|
|
.Pa aucat:0
|
|
|
|
and
|
|
|
|
.Pa aucat:0.max
|
|
|
|
devices:
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
$ aucat -l -v 65 -s default -v 127 -s max
|
|
|
|
.Ed
|
|
|
|
.Pp
|
2011-05-03 02:10:45 -05:00
|
|
|
Start
|
2010-08-19 15:38:45 -05:00
|
|
|
.Nm
|
2011-05-03 02:10:45 -05:00
|
|
|
in server mode, configuring the audio device to use
|
2010-08-19 15:38:45 -05:00
|
|
|
a 48kHz sample frequency, 240-frame block size,
|
|
|
|
and 2-block buffers.
|
|
|
|
The corresponding latency is 10ms, which is
|
|
|
|
the time it takes the sound to propagate 3.5 meters.
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
$ aucat -l -r 48000 -b 480 -z 240
|
|
|
|
.Ed
|
|
|
|
.Sh SEE ALSO
|
|
|
|
.Xr audioctl 1 ,
|
|
|
|
.Xr cdio 1 ,
|
|
|
|
.Xr mixerctl 1 ,
|
|
|
|
.Xr audio 4 ,
|
|
|
|
.Xr sndio 7
|
|
|
|
.Sh BUGS
|
|
|
|
The
|
|
|
|
.Nm
|
|
|
|
utility assumes non-blocking I/O for input and output streams.
|
|
|
|
It will not work reliably on files that may block
|
|
|
|
(ordinary files block, pipes don't).
|
|
|
|
To avoid audio underruns/overruns or MIDI jitter caused by file I/O,
|
|
|
|
it's recommended to use two
|
|
|
|
.Nm
|
|
|
|
processes: a server handling audio and MIDI I/O and a client handling
|
|
|
|
disk I/O.
|
|
|
|
.Pp
|
|
|
|
Resampling is low quality; down-sampling especially should be avoided
|
|
|
|
when recording.
|
|
|
|
.Pp
|
|
|
|
Processing is done using 16-bit arithmetic,
|
|
|
|
thus samples with more than 16 bits are rounded.
|
|
|
|
16 bits (i.e. 97dB dynamic) are largely enough for most applications though.
|
|
|
|
.Pp
|
|
|
|
If
|
|
|
|
.Fl a Ar off
|
|
|
|
is used in server mode,
|
|
|
|
.Nm
|
|
|
|
creates sub-devices to expose first
|
|
|
|
and then opens the audio hardware on demand.
|
|
|
|
Technically, this allows
|
|
|
|
.Nm
|
2011-04-05 10:42:38 -05:00
|
|
|
to attempt to use one of the sub-devices it exposes as an audio device,
|
2010-08-19 15:38:45 -05:00
|
|
|
creating a deadlock.
|
|
|
|
To avoid this,
|
|
|
|
.Fl a Ar off
|
|
|
|
is disabled for the default audio device, but nothing prevents the user
|
|
|
|
from shooting himself in the foot by creating a similar deadlock.
|