NAME

     aucat — audio file manipulation tool

SYNOPSIS

     aucat [-dn] [-b size] [-c channels] [-e enc] [-f device] [-g position] [-h fmt] [-i file]
           [-m min:max/min:max] [-o file] [-p position] [-q port] [-r rate] [-v volume]

DESCRIPTION

     The aucat utility can play, record, mix, and process audio files on the fly.  During
     playback, aucat reads audio data concurrently from all played files, mixes it and plays the
     result on the device.  Similarly, it stores audio data recorded from the device into
     corresponding files.  An off-line mode could be used to process audio files without
     involving audio hardware.  Processing includes:

           •   Change the sound encoding.
           •   Route the sound from one channel to another.
           •   Control the per-file playback volume.

     Finally, aucat can accept MIDI messages usable for:

           •   Volume control.
           •   Start, stop and relocate playback and recording.

     The options are as follows:

     -b size
             The buffer size of the audio device in frames.  Default is 7680.

     -c channels
             The audio file channels count.  The default is 2, i.e. stereo.

     -d      Increase log verbosity.

     -e enc  Encoding of the audio file.  The default is s24.  Encoding names use the following
             scheme: signedness (s or u) followed by the precision in bits, the byte-order (le or
             be), the number of bytes per sample, and the alignment (msb or lsb).  Only the
             signedness and the precision are mandatory.  Examples: u8, s16le, s24le3, s24le4lsb.

     -f device
             Use this sndio(7) audio device.  Device mode and parameters are determined from
             audio files.  Default is default.

     -g position
             Go to the given time position and start playback or recording there.  This option is
             equivalent to an incoming MMC relocate message with the same position.  The position
             is expressed as the number of samples (at device sample rate).

     -h fmt  Audio file type.  The following file types are supported:

             raw    Headerless file.
             wav    Microsoft WAV file format.
             aiff   Apple's audio interchange file format.
             au     Sun/NeXT audio file format.
             auto   Try to guess, depending on the file name.  This is the default.

     -i file
             Play this audio file.  If the option argument is ‘-’ then standard input will be
             used.

     -m min:max/min:max
             Map the given range of source channels into the given range of destination channels.

     -n      Off-line mode.  Read input files and store the result in the output files,
             processing them on the fly.  This mode is useful to mix, demultiplex, resample or
             re-encode audio files off-line.  It requires at least one input (-i) and one output
             (-o).

     -o file
             Record into this audio file.  If the option argument is ‘-’ then standard output
             will be used.

     -p position
             Time offset where the beginning of the file belongs.  The first sample of the file
             will be played or recorded when the device reaches the given position.  The position
             is expressed as the number of samples (at device sample rate).

     -q port
             Control audio device properties through this MIDI port.  This includes per-stream
             volumes and the ability to synchronously start, stop and relocate audio files.

     -r rate
             Sample rate in Hertz of the audio file.  The default is 48000.

     -v volume
             Software volume attenuation of the file to play.  The value must be between 1 and
             127, corresponding to -42dB and -0dB attenuation in 1/3dB steps.  The default is
             127, i.e. no attenuation.

     On the command line, per-file parameters (-cehmrv) must precede the file definition (-io).

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

MIDI CONTROL

     aucat can be controlled through MIDI (-q) as follows: a MIDI channel is assigned to each
     stream, and the volume is changed using the standard volume controller (number 7).  The
     master volume can be changed using the standard master volume system exclusive message.

     All audio files are controlled by the following MMC messages:

           relocate   All files are relocated to the requested time position.  If it is beyond
                      the end of a file, the file is temporarily disabled until a valid position
                      is requested.
           start      Playback and/or recording is started.
           stop       Playback and/or recording is stopped and all files are rewound back to the
                      starting position.

     MIDI control is intended to be used together with sndiod(8).  For instance, the following
     command will create two devices: the default snd/default and a MMC-controlled one
     snd/default.mmc:

           $ sndiod -r 48000 -z 480 -s default -t slave -s mmc

     Programs using snd/default behave normally, while programs using snd/mmc wait for the MMC
     start signal and start synchronously.  Then, the following command will play a file on the
     snd/mmc audio device, giving full control to MIDI software or hardware connected to the
     midithru/0 MIDI port:

           $ aucat -f snd/mmc -q midithru/0 -i file.wav

     At this stage, aucat will start, stop and relocate automatically following all user actions
     in the MIDI sequencer, assuming it's configured to transmit MMC on midithru/0 and snd/mmc.
     Furthermore, the MIDI sequencer could be configured to use the snd/mmc port as MTC clock
     source, assured to be synchronous to playback of file.wav.

EXAMPLES

     Mix and play two files while recording a third file:

           $ aucat -i file1.wav -i file2.wav -o file3.wav

     Record channels 2 and 3 into one stereo file and channels 6 and 7 into another stereo file
     using a 44.1kHz sampling rate for both:

           $ aucat -r 44100 -m 2:3/0:1 -o file1.wav -m 6:7/0:1 -o file2.wav

     Split a stereo file into two mono files:

           $ aucat -n -i stereo.wav -c 1 -m 0:0/0:0 -o left.wav \
                   -m 1:1/0:0 -o right.wav

SEE ALSO

     cdio(1), audio(4), sndio(7), audioctl(8), mixerctl(8), sndiod(8)

BUGS

     Resampling is low quality.

     There are limitations inherent to the wav, aiff, and au file formats: not all encodings are
     supported, file sizes are limited to 2GB, and the files must support the lseek(2) operation
     (e.g. pipes do not support it).