AUCAT(1)                   OpenBSD Reference Manual                   AUCAT(1)

NAME
     aucat - audio server and stream manipulation tool

SYNOPSIS
     aucat [-dlnu] [-b nframes] [-C min:max] [-c min:max] [-e enc] [-f device]
           [-h fmt] [-i file] [-m mode] [-o file] [-r rate] [-s name]
           [-t mode] [-U unit] [-v volume] [-x policy] [-z nframes]

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.

     -d      Do not daemonize.  If this option is specified, aucat will run in
             the foreground and log to stderr.

     -e enc  Encoding of the playback or recording stream (see below).  The
             default is signed, 16-bit, native byte order.

     -f device
             The sndio(7) audio device 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 a UNIX-domain socket.  This
             allows clients to use aucat instead of the physical audio device
             for audio input and output in order to share the physical device
             with other clients.  The default sndio(7) device exposed is
             aucat:0 (also known as aucat:0.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 name
             Add name to the list of sub-devices to expose in server mode.
             Defining multiple sub-devices allows splitting a physical audio
             device into logical devices having different properties (e.g.
             channel ranges).  The given name corresponds to the ``option''
             part of the sndio(7) device name string.

     -t mode
             Select the way sub-devices are controlled by MMC (MIDI Machine
             Control) messages.  If the mode is off (the default), then
             streams are not affected by MMC messages.  If the mode is slave,
             then streams are started synchronously by MMC start messages; ad-
             ditionally, the server clock is exposed as MTC (MIDI Time Code)
             messages allowing MTC-capable software or hardware to be synchro-
             nized to audio streams.

     -U unit
             Unit number to use when running in server mode.  Each aucat serv-
             er instance has an unique unit number, used in sndio(7) device
             names.  The default is 0.

     -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 a sub-device is created with -t, the ``ignore'' action is dis-
             abled for any stream connected to it to ensure proper synchro-
             nization.

     -z nframes
             The audio block size in frames.  This is the number of frames be-
             tween audio clock ticks, i.e. the clock resolution.  If a sub-de-
             vice is created with -t, and MTC (Midi Time Code) 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.

     If aucat is sent SIGHUP, SIGINT or SIGTERM, it terminates recording to
     files.

     Settings for input files (-i), output files (-o), and sub-devices (-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 sub-devices (-s)
     are specified settings are applied as if default 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`

MIDI CONTROL
     While running in server mode (-l) aucat exposes a MIDI device with the
     same name as the default audio device.  It allows MIDI hardware or soft-
     ware to control programs using aucat or to synchronize to them.

     A MIDI channel is assigned to each stream, and the volume is changed us-
     ing the standard volume controller (number 7).  Similarly, when the audio
     application changes its volume, the same MIDI controller message is sent
     out; it can be used for instance for monitoring or as feedback for motor-
     ized faders.

     Clients connected to sub-devices created with -t are controlled by the
     following MMC (MIDI Machine Control) messages:

            stop         Put the sub-device in stopped mode (the default).  In
                         this mode, any stream attempting to start playback or
                         recording is paused.  Streams that are already start-
                         ed are not affected until they stop and try to start
                         again.

            relocate     Gives aucat the time, relative to the beginning of
                         the stream, at which playback and recording must
                         start.  It is not interpreted by aucat itself.  The
                         given time position is sent to MIDI clients as an MTC
                         ``full frame'' message forcing all MTC-slaves to re-
                         locate to the given position (see below).

            start        Put the sub-device in starting mode.  In this mode,
                         the sub-device waits for all streams to become ready
                         to start, and then starts them synchronously.  Once
                         started, new streams can be created, but they will be
                         blocked until the next stop-to-start transition.

     Sub-devices created with -t will export the server clock using MTC (MIDI
     Time Code), allowing non-audio software or hardware to be synchronized to
     the audio stream.  The following sample rates (-r) and block sizes (-z)
     are recommended for maximum accuracy:

            o   44100Hz, 441 frames
            o   48000Hz, 400 frames
            o   48000Hz, 480 frames
            o   48000Hz, 500 frames

     For instance, the following command will create two devices: the default
     aucat:0 and a MIDI-controlled aucat:0.mmc:

           $ aucat -l -r 48000 -z 400 -s default -t slave -s mmc

     Streams connected to aucat:0 behave normally, while streams connected to
     aucat:0.mmc wait for the MMC start signal and start synchronously.  Re-
     gardless of which device a stream is connected to, its playback volume
     knob is exposed.

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
     AUDIODEVICE  sndio(7) audio device to use if the -f option is not speci-
                  fied.

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 sub-device for output to channels 2:3 only
     (rear speakers on most cards), exposing the aucat:0 and aucat:0.rear de-
     vices:

           $ aucat -l -s default -c 2:3 -s rear

     The following will start aucat in server mode creating the default sub-
     device with low volume and an additional sub-device for high volume out-
     put, exposing the aucat:0 and aucat:0.max devices:

           $ aucat -l -v 65 -s default -v 127 -s max

SEE ALSO
     audioctl(1), cdio(1), mixerctl(1), audio(4), sndio(7)

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