AUCAT(1)                   OpenBSD Reference Manual                   AUCAT(1)

NAME
     aucat - manipulate linear audio streams

SYNOPSIS
     aucat [-qu] [-C min:max] [-c min:max] [-E enc] [-e enc] [-f device]
           [-H fmt] [-h fmt] [-i file] [-o file] [-R rate] [-r rate]
           [-X policy] [-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:

     -C min:max, -c min:max
                   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 stan-
                   dard 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, respec-
                   tively.  The default is 44100Hz.

     -u            Normally aucat tries to automatically determine the optimal
                   parameters for the audio device; if this option is speci-
                   fied, 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 un-
                   blocked, in order to reach the right position in time.  If
                   the policy is ``error'' then the stream is closed perma-
                   nently.

     -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 si-
                   lence 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 de-
     fault 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 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 and -e options.  The following en-
     codings 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 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 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 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 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 sim-
     pler 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.

OpenBSD 4.4                      June 3, 2008                                3
