Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
AUCAT(1)		FreeBSD	General	Commands Manual		      AUCAT(1)

     aucat -- audio files manipulation tool

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

     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 au-
     dio hardware.  Processing includes:

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

     Finally, aucat can	accept MIDI messages usable for:

	   +o   Volume control.
	   +o   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,

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

     -i	file
	     Play this audio file.  If the option argument is `-' then stan-
	     dard 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

     -n	     Off-line mode.  Read input	files and store	the result in the out-
	     put 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 in-
	     cludes 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

     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 temporar-
		     ily 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 in-
     stance, 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 con-
     trol 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 follow-
     ing 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 syn-
     chronous to playback of file.wav.

     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

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

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

FreeBSD	13.0			April 22, 2020			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help