xenial (1) aucat.1.gz

Provided by: sndio-tools_1.1.0-2_amd64 bug

NAME

     aucat — audio files manipulation tool

SYNOPSIS

     aucat [-dn] [-b size] [-c min:max] [-e enc] [-f device] [-h fmt] [-i file] [-j flag] [-o file] [-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 min:max
             The range of audio file channel numbers.  The default is 0:1, i.e. stereo.

     -d      Increase log verbosity.

     -e enc  Encoding of the audio file.  The default is s16.  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.

     -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.

     -j flag
             Control whether source channels are joined or expanded if they don't match the destination number
             of channels.  If the flag is off, then each source channel is routed to a single destination
             channel, possibly discarding channels.  If the flag is on, then a single source may be sent to
             multiple destinations and multiple sources may be mixed into a single destination.  For instance,
             this feature could be used to convert a stereo file into a mono file mixing left and right channels
             together.  The default is off.

     -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.

     -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 (-cehjrv) 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 temporarly 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/0 and a MMC-controlled one snd/0.mmc:

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

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

           $ aucat -f snd/0.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.  Furthermore, the MIDI sequencer could
     be configured to use the snd/0 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 -c 2:3 -o file1.wav -c 6:7 -o file2.wav

     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

SEE ALSO

     audioctl(1), cdio(1), mixerctl(1), audio(4), sndio(7), 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).