AUCAT(1)		    General Commands Manual		      AUCAT(1)

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

Debian			       October 17, 2025				Debian