AUCAT(1) AerieBSD 1.0 Refernce Manual AUCAT(1)

NAME

aucat — manipulate linear audio streams

SYNOPSIS

aucat .Bk -words [-qu] [-C min: ] [-c min: ] [-E enc] [-e enc] [-f device] [-H fmt] [-h fmt] [-i file] [-o file] [-R rate] [-r rate] [-X policy] [-x policy] .Ek

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:
-C min: , -c min: The range of channel numbers on the output or input stream, respectively. The default is 0:1, i.e. stereo.
-E enc, -e enc
Encoding of the output or input stream, respectively (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 default is /dev/audio.
-H fmt, -h fmt
File format of the output or input stream, respectively (see below). The default is auto.
-i file
Add this file to the list of files to play. If the option argument is ‘-’ then standard input will be used.
-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.
-q
Do not print progress information; run quietly.
-R rate, -r rate
Sample rate in Hertz of the output or input stream, respectively. The default is 44100Hz.
-u
Normally aucat tries to automatically determine the optimal parameters for the audio device; if this option is specified, it will instead use the parameters specified by the -CcEeRr options.
-X policy
Action when the output stream cannot accept recorded data fast enough. If the policy is “ignore” (the default) then samples that cannot be written are discarded. If the policy is “sync” then 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. If the policy is “error” then the stream is closed permanently.
-x policy
Action when the input stream cannot provide data to play fast enough. If the policy is “ignore” (the default) then silence is played. If the policy is “sync” then silence is played, but the same amount of samples will be discarded once the stream is unblocked, in order to reach the right position in time. If the policy is “error” then the stream is closed permanently.

Settings for input (-i) and output (-o) files can be changed using the -CcEeHhRrXx options. The last -CcEeHhRrXx options specified before an -i or -o are applied to file.

Settings for the audio device can be changed using the -CcEeRr options. They apply to the audio device only if the -u option is given as well. The last -CcEeRr option specified before an -f is applied to device.

If no audio device (-f) is specified but -u is given anyway, any -CcEeRr options specified before -io options are applied both to file and the default audio device; if they are specified after -io options, they will be applied only to the default audio device.

File formats are specified using the -H and -h options. The following file formats are supported:
raw
Headerless file. This format is recommended since it has no limitations.
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 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 and -e options. 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

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 options 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 encoding 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 command will record a stereo s16le stream at 44100Hz from the default device. If necessary, the stream will be converted and/or resampled to match parameters supported by the device: 

$ aucat -o file.raw

The following command will play a stereo s16le stream at 44100Hz on the default device, doing any necessary conversions: 

$ aucat -i file.raw

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 channels 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 play two s18le mono files, one on each channel: 

$ aucat -e s18le -c 0:0 -i f1.raw -c 1:1 -i f2.raw

The following will mix and play two files and record a third one in full-duplex: 

$ aucat -i drums.raw -i bass.raw -o guitar.raw

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.

CPU usage is the same for all conversions. It should be smaller for simpler ones.

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.

AerieBSD 1.0 Reference Manual December 26 2008 AUCAT(1)