AUCAT(1)                   OpenBSD Reference Manual                   AUCAT(1)

NAME
     aucat - audio server and stream manipulation tool

SYNOPSIS
     aucat [-lnu] [-b nframes] [-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, and can also
     act as an audio server.  aucat also has a legacy mode that works like
     previous versions of aucat, which does not convert on the fly and sup-
     ports playback of .au files.

     The options are as follows:

     -b nframes
             The buffer size 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 play-
             back 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 or aucat socket to use for playing and/or
             recording.

     -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, settings are applied as if the de-
     fault device is specified as the last argument.  If no sockets (-s) are
     specified settings are applied as if the default socket is specified as
     the last argument.

     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 a higher priority to the aucat
     process.  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 parse the format, number of channels and sample rate from Sun .au file
     headers.  However, only alaw and ulaw formats are supported for .au
     files.  Other formats will be interpreted as ulaw.  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  Name of the aucat socket to connect to, or path to the
                  audio(4) device to use if the -f option is not specified.

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.6                       May 9, 2009                                4
