path: root/usr.bin/aucat/aucat.1

.\"	$OpenBSD: aucat.1,v 1.118 2022/10/14 06:46:52 jmc Exp $
.\"
.\" Copyright (c) 2006 Alexandre Ratchov <alex@caoua.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: October 14 2022 $
.Dt AUCAT 1
.Os
.Sh NAME
.Nm aucat
.Nd audio file manipulation tool
.Sh SYNOPSIS
.Nm aucat
.Op Fl dn
.Op Fl b Ar size
.Op Fl c Ar min : Ns Ar max
.Op Fl e Ar enc
.Op Fl f Ar device
.Op Fl g Ar position
.Op Fl h Ar fmt
.Op Fl i Ar file
.Op Fl j Ar flag
.Op Fl o Ar file
.Op Fl p Ar position
.Op Fl q Ar port
.Op Fl r Ar rate
.Op Fl v Ar volume
.Sh DESCRIPTION
The
.Nm
utility can play, record, mix, and process audio files
on the fly.
During playback,
.Nm
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
.Em off-line
mode could be used to process audio files without
involving audio hardware.
Processing includes:
.Pp
.Bl -bullet -offset indent -compact
.It
Change the sound encoding.
.It
Route the sound from one channel to another.
.It
Control the per-file playback volume.
.El
.Pp
Finally,
.Nm
can accept MIDI messages usable for:
.Pp
.Bl -bullet -offset indent -compact
.It
Volume control.
.It
Start, stop and relocate playback and recording.
.El
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl b Ar size
The buffer size of the audio device in frames.
Default is 7680.
.It Fl c Ar min : Ns Ar max
The range of audio file channel numbers.
The default is
.Cm 0:1 ,
i.e. stereo.
.It Fl d
Increase log verbosity.
.It Fl e Ar enc
Encoding of the audio file.
The default is
.Va s24 .
Encoding names use the following scheme: signedness
.Po
.Va s
or
.Va u
.Pc
followed
by the precision in bits, the byte-order
.Po
.Va le
or
.Va be
.Pc ,
the number of
bytes per sample, and the alignment
.Po
.Va msb
or
.Va lsb
.Pc .
Only the signedness and the precision are mandatory.
Examples:
.Va u8 , s16le , s24le3 , s24le4lsb .
.It Fl f Ar device
Use this
.Xr sndio 7
audio device.
Device mode and parameters are determined from audio files.
Default is
.Pa default .
.It Fl g Ar 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).
.It Fl h Ar fmt
Audio file type.
The following file types are supported:
.Pp
.Bl -tag -width auto -compact
.It Cm raw
Headerless file.
.It Cm wav
Microsoft WAV file format.
.It Cm aiff
Apple's audio interchange file format.
.It Cm au
Sun/NeXT audio file format.
.It Cm auto
Try to guess, depending on the file name.
This is the default.
.El
.It Fl i Ar file
Play this audio file.
If the option argument is
.Sq -
then standard input will be used.
.It Fl j Ar flag
Control whether source channels are joined or expanded if
they don't match the destination number of channels.
If the flag is
.Cm off ,
then each source channel is routed to a single destination channel,
possibly discarding channels.
If the flag is
.Cm 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
.Cm off .
.It Fl 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
.Pq Fl i
and one output
.Pq Fl o .
.It Fl o Ar file
Record into this audio file.
If the option argument is
.Sq -
then standard output will be used.
.It Fl p Ar 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).
.It Fl q Ar 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.
.It Fl r Ar rate
Sample rate in Hertz of the audio file.
The default is
.Cm 48000 .
.It Fl v Ar 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.
.El
.Pp
On the command line,
per-file parameters
.Pq Fl cehjrv
must precede the file definition
.Pq Fl io .
.Pp
If
.Nm
is sent
.Dv SIGHUP ,
.Dv SIGINT
or
.Dv SIGTERM ,
it terminates recording to files.
.Sh MIDI CONTROL
.Nm
can be controlled through MIDI
.Pq Fl q
as follows:
a MIDI channel is assigned to each stream, and the volume
is changed using the standard volume controller (number 7).
.Pp
The master volume can be changed using the standard master volume
system exclusive message.
.Pp
All audio files are controlled by the following MMC messages:
.Bl -tag -width relocate -offset indent
.It 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.
.It start
Playback and/or recording is started.
.It stop
Playback and/or recording is stopped and all files are rewound
back to the starting position.
.El
.Pp
MIDI control is intended to be used together with
.Xr sndiod 8 .
For instance, the following command will create two devices:
the default
.Va snd/0
and a MMC-controlled one
.Va snd/0.mmc :
.Bd -literal -offset indent
$ sndiod -r 48000 -z 480 -s default -t slave -s mmc
.Ed
.Pp
Programs using
.Va snd/0
behave normally, while programs using
.Va snd/0.mmc
wait for the MMC start signal and start synchronously.
Then, the following command will play a file on the
.Va snd/0.mmc
audio device, giving full control to MIDI software or hardware
connected to the
.Va midithru/0
MIDI port:
.Bd -literal -offset indent
$ aucat -f snd/0.mmc -q midithru/0 -i file.wav
.Ed
.Pp
At this stage,
.Nm
will start, stop and relocate automatically following all user
actions in the MIDI sequencer, assuming it's configured to
transmit MMC on
.Va midithru/0 .
Furthermore, the MIDI sequencer could be configured to use the
.Va snd/0
port as MTC clock source, assured to be synchronous to playback of
.Pa file.wav .
.Sh EXAMPLES
Mix and play two files while recording a third file:
.Bd -literal -offset indent
$ aucat -i file1.wav -i file2.wav -o file3.wav
.Ed
.Pp
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:
.Bd -literal -offset indent
$ aucat -r 44100 -c 2:3 -o file1.wav -c 6:7 -o file2.wav
.Ed
.Pp
Split a stereo file into two mono files:
.Bd -literal -offset indent
$ aucat -n -i stereo.wav -c 0:0 -o left.wav \e
	-c 1:1 -o right.wav
.Ed
.Sh SEE ALSO
.Xr cdio 1 ,
.Xr audio 4 ,
.Xr sndio 7 ,
.Xr audioctl 8 ,
.Xr mixerctl 8 ,
.Xr sndiod 8
.Sh BUGS
Resampling is low quality.
.Pp
There are limitations inherent to the
.Ar wav ,
.Ar aiff ,
and
.Ar au
file formats: not all encodings are supported,
file sizes are limited to 2GB, and the files must support the
.Xr lseek 2
operation (e.g. pipes do not support it).