mirror of
https://github.com/ericonr/sndio.git
synced 2024-02-18 04:45:21 -06:00
310 lines
7.7 KiB
Groff
310 lines
7.7 KiB
Groff
.\" $OpenBSD$
|
|
.\"
|
|
.\" 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$
|
|
.Dt AUCAT 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm aucat
|
|
.Nd audio files 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 s16 .
|
|
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).
|