aucat man page on OpenBSD

Man page or keyword search:  
man Server   11362 pages
apropos Keyword Search (all sections)
Output format
OpenBSD logo
[printable version]

AUCAT(1)		   OpenBSD Reference Manual		      AUCAT(1)

     aucat - audio server and stream manipulation tool

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

     aucat is an audio utility which can simultaneously play and record any
     number of audio streams on any number of audio devices, possibly
     controlled through MIDI.  It can also act as an audio server, in which
     case streams correspond to client connections rather than plain files.

     Audio devices are independent.  A list of streams is attached to each
     audio device, as well as an optional list of MIDI ports to control the
     device.  A typical invocation of aucat consists in providing streams to
     play and record, and possibly the audio device to use, if the default is
     not desired.

     This also applies to server mode, except that streams are created
     dynamically when clients connect to the server.  Thus, instead of actual
     streams (paths to plain files), templates for client streams (sub-device
     names) must be provided.

     The options are as follows:

     -a flag
	     Control whether aucat opens the audio device only when needed or
	     keeps it open all the time.  If the flag is on then the device is
	     kept open all the time, ensuring no other program can steal it.
	     If the flag is off, then it's automatically closed, allowing
	     other programs to have direct access to the device, or the device
	     to be disconnected.  The default is on.

     -b nframes
	     The buffer size of the audio device 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 playback latency.

     -C min:max, -c min:max
	     The range of stream channel numbers for recording and playback
	     directions, respectively.	The default is 0:1, i.e. stereo.

     -d	     Increase log verbosity.  aucat logs on stderr until it

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

     -f device
	     Add this sndio(7) audio device to devices used for playing and/or
	     recording.	 Preceding streams (-ios), control MIDI ports (-q),
	     and per-device options (-abz) apply to this device.  Device mode
	     and parameters are determined from streams attached to it.

     -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 streams to play.  If the option
	     argument is `-' then standard input will be used.

     -j flag
	     Control whether stream channels are joined or expanded if the
	     stream number of channels is not equal to the device number of
	     channels.	If the flag is off then stream channels are routed to
	     the corresponding device channel, possibly discarding channels
	     not present in the device.	 If the flag is on, then a single
	     stream channel may be sent on multiple device channels, or
	     multiple stream channels may be sent to a single device channel.
	     For instance, this feature could be used to request mono streams
	     to be sent on multiple outputs or to record a stereo input into a
	     mono stream.  The default is on.

     -l	     Detach and become a daemon.

     -m mode
	     Set the stream mode.  Valid modes are play, rec, and mon,
	     corresponding to playback, recording and monitoring.  A
	     monitoring stream is a fake recording stream corresponding to the
	     mix of all playback streams.  Multiple modes can be specified,
	     separated by commas, but the same stream cannot be used for both
	     recording and monitoring.	The default is play,rec (i.e. full-

     -n	     Loopback mode.  Instead of using audio devices, send input
	     streams to the output, processing them on the fly.	 This mode is
	     useful to mix, demultiplex, resample or reencode audio files

     -o file
	     Add this file to the list of recording streams.  If the option
	     argument is `-' then standard output will be used.

     -q device
	     Expose the audio device clock on this sndio(7) MIDI port and
	     allow audio device properties to be controlled through MIDI.
	     This includes per-stream volumes and the ability to synchronously
	     start, stop and relocate streams created in MIDI Machine Control
	     (MMC) slave mode (-t).

     -r rate
	     Sample rate in Hertz of the stream.  The default is 44100Hz.

     -s name
	     Add name to the list of sub-devices to expose in server mode.
	     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.	 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

     -t mode
	     Select the way streams are controlled by MIDI Machine Control
	     (MMC) 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;
	     additionally, the server clock is exposed as MIDI Time Code (MTC)
	     messages allowing MTC-capable software or hardware to be
	     synchronized to audio streams.

     -U unit
	     Unit number to use when running in server mode.  Each aucat
	     server 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
	     parameters 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
	     attenuation.  In server mode, clients inherit this parameter.
	     Reducing 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
	     compromise is to use -4dB attenuation (12 volume units) for each
	     additional 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
	     unblocked.	 If the policy is ``error'' then the stream is closed

	     If a stream is created with the -t option, the ``ignore'' action
	     is disabled for any stream connected to it to ensure proper

     -z nframes
	     The audio device block size in frames.  This is the number of
	     frames between audio clock ticks, i.e. the clock resolution.  If
	     a stream is created with the -t option, and MTC 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.

     On the command line, per-device parameters (-abz) must precede the device
     definition (-f), and per-stream parameters (-Ccehjmrtvx) must precede the
     stream definition (-ios).	MIDI ports (-q) and streams definitions (-ios)
     must precede the definition of the device (-f) to which they are
     attached.	Global parameters (-dlnu) are position-independent.

     If no audio devices (-f) are specified, settings are applied as if the
     default device is specified as the last argument.	If no streams (-ios)
     are specified for a device, a default server sub-device is created
     attached to it, meaning that aucat behaves as an audio server.  The
     default sndio(7) device is aucat:0 (also known as aucat:0.default)

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

     File formats are specified using the -h option.  The following file
     formats are supported:

	   raw	     Headerless file.  This format is recommended since it has
		     no limitations.

	   wav	     Microsoft WAVE file format.  There are limitations
		     inherent 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

	   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

     If at least one sub-device (-s) is exposed by aucat, including the case
     when no stream options are given, then aucat can be used as a server to
     overcome hardware limitations and allow applications to run on fixed
     sample rate devices or on devices supporting only unusual encodings.

     Certain applications, such as synthesis software, require a low latency
     audio setup.  To reduce the probability of buffer underruns or overruns,
     especially on busy machines, the server can be started by the super-user,
     in which case it will run with higher priority.  Any user will still be
     able to connect to it, but for privacy reasons only one user may have
     connections to it at a given time.

     aucat can expose the audio device clock on registered MIDI ports (-q) and
     allows audio device properties to be controlled through MIDI.  If running
     in server mode aucat creates a MIDI port with the same name as the
     default audio device to which MIDI programs can connect.

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

     Streams created with the -t option are controlled by the following MMC

	   relocate	Streams are relocated to the requested time postion
			relative to the beginning of the stream, at which
			playback and recording must start.  If the requested
			position is beyond the end of file, the stream is
			temporarly disabled until a valid postion is
			requested.  This message is ignored by client streams
			(server mode).	The given time position is sent to
			MIDI ports as an MTC ``full frame'' message forcing
			all MTC-slaves to relocate to the given position (see

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

	   stop		Put all streams in stopped mode (the default).	In
			this mode, any stream attempting to start playback or
			recording is paused.  Files are stopped and rewound
			back to the starting position, while client streams
			(server mode) that are already started are not
			affected until they stop and try to start again.

     Streams created with the -t option export the server clock using MTC,
     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.
     Regardless of which device a stream is connected to, its playback volume
     knob is exposed.

     For instance, the following command will play a file on the aucat:0.mmc
     audio device, and give full control to MIDI software or hardware
     connected to the midithru:0 MIDI device:

	   $ aucat -t slave -q midithru:0 -i file.wav -f aucat:0.mmc

     At this stage, aucat will start, stop and relocate automatically
     following all user actions in the MIDI sequencer.	Note that the
     sequencer must use aucat:0 as the MTC source, i.e. the audio server, not
     the audio player.

     AUDIODEVICE  sndio(7) audio device to use if the -f option is not

     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
     channels 6 and 7 into another stereo file using a 96kHz sampling rate for

	   $ 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

	   $ 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
     output, exposing the aucat:0 and aucat:0.max devices:

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

     The following will start aucat in server mode configuring the audio
     device to use a 48kHz sample frequency, 240-frame block size, and 2-block
     buffers.  The corresponding latency is 10ms, which is the time it takes
     the sound to propagate 3.5 meters.

	   $ aucat -l -r 48000 -b 480 -z 240

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

     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).  To avoid audio underruns/overruns or MIDI jitter caused by
     file I/O, it's recommended to use two aucat processes: a server handling
     audio and MIDI I/O and a client handling disk I/O.

     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.

     If -a off is used in server mode, aucat creates sub-devices to expose
     first and then opens the audio hardware on demand.	 Technically, this
     allows aucat to attempt to use one of the sub-devices it exposes as audio
     device, creating a deadlock.  To avoid this, -a off is disabled for the
     default audio device, but nothing prevents the user from shooting himself
     in the foot by creating a similar deadlock.

OpenBSD 4.9			 July 31, 2010			   OpenBSD 4.9

List of man pages available for OpenBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net