AUCAT(1) OpenBSD Reference Manual AUCAT(1)
NAME
aucat - audio server and stream manipulation tool
SYNOPSIS
aucat [-lnu] [-b nsamples] [-C min:max] [-c min:max] [-e enc] [-f device]
[-h fmt] [-i file] [-m mode] [-o file] [-r rate] [-s socket]
[-v volume] [-x policy]
DESCRIPTION
The aucat utility can record one input stream and store it on multiple
destination files, doing the necessary conversions on the fly. It can
play, convert, and mix multiple input files simultaneously. aucat also
has a legacy mode that works like previous versions of aucat, which does
not convert on the fly and supports playback of .au files.
The options are as follows:
-b nsamples
The buffer size in frames. This is the number of samples that
will be buffered before being played and controls the playback
latency.
-C min:max, -c min:max
The range of channel numbers on the record or playback stream,
respectively. The default is 0:1, i.e. stereo.
-e enc Encoding of the playback or recording stream (see below). The
default is signed, 16-bit, native byte order.
-f device
The audio(4) device to use for playing and/or recording. The de-
fault is /dev/audio.
-h fmt File format of the playback or record stream (see below). The
default is auto.
-i file
Add this file to the list of files to play. If the option argu-
ment is `-' then standard input will be used.
-l Listen for incoming connections on Unix domain sockets. This al-
lows clients to use aucat instead of the regular audio(4) device
for audio input and output in order to share the physical device
with other clients. The default socket name is default but other
names can be used with the -s option.
-m mode
Set the server mode. Valid modes are play, rec, and duplex, for
play-only, record-only, and full-duplex, respectively. The de-
fault is duplex.
-n Loopback mode. Instead of using an audio device, send input
streams to the output, processing them on the fly. This mode is
useful to mix, demultiplex, resample or reencode audio files of-
fline.
-o file
Add this file to the list of files in which to store recorded
samples. If the option argument is `-' then standard output will
be used.
-r rate
Sample rate in Hertz of the playback or record stream. The de-
fault is 44100Hz.
-s socket
Add the name socket to the list of sockets to listen on. socket
cannot contain '/'. Meaningful in server mode only.
-u Normally aucat tries to automatically determine the optimal pa-
rameters for the audio device; if this option is specified, it
will instead use the parameters specified by the -Ccer options.
-v volume
Software volume attenuation of the playback stream. The value
must be between 1 and 127, corresponding to -42dB and -0dB atten-
uation. In server mode, clients inherit this parameter. Reduc-
ing the volume in advance reduces a client's dynamic range, but
allows client volume to stay independent from the number of
clients as long as their number is small enough. A good compro-
mise is to use -4dB attenuation (12 volume units) for each addi-
tional client expected (115 if 2 clients are expected, 103 for 3
clients, and so on).
-x 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 ``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 ``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 un-
blocked. If the policy is ``error'' then the stream is closed
permanently.
If aucat is sent SIGHUP, SIGINT or SIGTERM, it terminates recording to
files. If sent SIGUSR1 or SIGUSR2, it increases or decreases debug lev-
el, respectively.
Settings for input files (-i), output files (-o), and sockets (-s) can be
changed using the -Ccehrvx options. The last -Ccehrvx options specified
before an -i, -o, or -s are applied to the corresponding file.
Settings for the audio device can be changed using the -Ccer options.
They apply to the audio device only if the -u option is given as well.
The last -Ccer option specified before an -f is applied to device.
If no audio device (-f) is specified but -u is given anyway, any -Ccer
options specified before -ios options are applied both to the correspond-
ing file and the default audio device; if they are specified after -ios
options, they will be applied only to the default audio device.
File formats are specified using the -h option. The following file for-
mats are supported:
raw Headerless file. This format is recommended since it
has no limitations.
wav Microsoft WAVE file format. There are limitations in-
herent to the file format itself: not all encodings are
supported, file sizes are limited to 2GB, and the file
must support the lseek(2) operation (e.g. pipes do not
support it).
auto Try to guess, depending on the file name.
Encodings are specified using the -e option. The following encodings are
supported:
s8 signed 8-bit
u8 unsigned 8-bit
s16le signed 16-bit, little endian
u16le unsigned 16-bit, little endian
s16be signed 16-bit, big endian
u16be unsigned 16-bit, big endian
s24le signed 24-bit, stored in 4 bytes, little endian
u24le unsigned 24-bit, stored in 4 bytes, little endian
s24be signed 24-bit, stored in 4 bytes, big endian
u24be unsigned 24-bit, stored in 4 bytes, big endian
s32le signed 32-bit, little endian
u32le unsigned 32-bit, little endian
s32be signed 32-bit, big endian
u32be unsigned 32-bit, big endian
s24le3 signed 24-bit, packed in 3 bytes, little endian
u24le3 unsigned 24-bit, packed in 3 bytes, big endian
s24be3 signed 24-bit, packed in 3 bytes, little endian
u24be3 unsigned 24-bit, packed in 3 bytes, big endian
s20le3 signed 20-bit, packed in 3 bytes, little endian
u20le3 unsigned 20-bit, packed in 3 bytes, big endian
s20be3 signed 20-bit, packed in 3 bytes, little endian
u20be3 unsigned 20-bit, packed in 3 bytes, big endian
s18le3 signed 18-bit, packed in 3 bytes, little endian
u18le3 unsigned 18-bit, packed in 3 bytes, big endian
s18be3 signed 18-bit, packed in 3 bytes, little endian
u18be3 unsigned 18-bit, packed in 3 bytes, big endian
SERVER MODE
aucat can be used in server mode (-l) to overcome hardware limitations
and allow applications to run on fixed sample rate devices or on devices
supporting only unusual encodings. It is generally not desirable to have
multiple instances of aucat running in server mode, so it is good prac-
tice to start it thus:
$ pgrep -x aucat || aucat -l
This also ensures privacy by preventing other users from accessing the
audio system. On multi-user machines aucat should be killed when no
longer in use to make audio resources available again to others:
$ pkill -x aucat
Certain applications, such as synthesis software, require a low latency
audio setup. To reduce the probability of buffer underruns or overruns,
the renice(8) command can be used to give higher priority to aucat pro-
cess to. Superuser privileges are required. For example:
$ aucat -b 3500 -l
$ sudo renice -n -20 -p `pgrep -x aucat`
LEGACY MODE
If neither -i nor -o are specified, aucat will run in legacy mode, and
won't convert sample formats or sampling rates. In legacy mode, all op-
tions except -f are ignored, and all other arguments are assumed to be
names of files. In legacy mode aucat reads files sequentially, and
writes them to the specified device. If a Sun .au header is detected it
is skipped over and not copied to the audio device. aucat will attempt
to play data from Sun .au files as monaural 8-bit ulaw samples with a
sampling frequency of 8000 Hz. However, aucat will not fail if the audio
device cannot be configured for these parameters. If a Microsoft .wav
header (RIFF) is detected it is interpreted to select the right audio en-
coding for playback and the data chunk of the file is copied to the audio
device. If the device does not support the encoding, aucat will exit
with an error.
ENVIRONMENT
AUCAT_DEBUG The debug level: may be a value between 0 and 4.
AUDIODEVICE The audio device to use.
EXAMPLES
The following will mix and play two stereo streams, the first at 48kHz
and the second at 44.1kHz:
$ aucat -r 48000 -i file1.raw -r 44100 -i file2.raw
The following will record channels 2 and 3 into one stereo file and chan-
nels 6 and 7 into another stereo file using a 96kHz sampling rate for
both:
$ aucat -r 96000 -C 2:3 -o file1.raw -C 6:7 -o file2.raw
The following will split a stereo file into two mono files:
$ aucat -n -i stereo.wav -C 0:0 -o left.wav -C 1:1 -o right.wav
The following will start aucat in server mode using default parameters,
but will create an additional socket for output to channels 2:3 only
(rear speakers on most cards):
$ aucat -l -s default -c 2:3 -s rear
The following will start aucat in server mode creating the default socket
with low volume and an additional socket for high volume output:
$ aucat -l -v 65 -s default -v 127 -s max
SEE ALSO
audioctl(1), cdio(1), mixerctl(1), audio(4)
BUGS
The aucat 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).
Resampling is low quality; down-sampling especially should be avoided
when recording.
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.
OpenBSD 4.5 February 27, 2009 4