version 1.106, 2014/02/08 15:18:54 |
version 1.107, 2015/01/21 08:43:55 |
|
|
.Os |
.Os |
.Sh NAME |
.Sh NAME |
.Nm aucat |
.Nm aucat |
.Nd audio/MIDI stream manipulation tool |
.Nd audio files manipulation tool |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.Nm aucat |
.Nm aucat |
.Bk -words |
.Bk -words |
.Op Fl dMn |
.Op Fl dn |
.Op Fl C Ar min : Ns Ar max |
.Op Dl b Ar size |
.Op Fl c Ar min : Ns Ar max |
.Op Fl c Ar min : Ns Ar max |
.Op Fl e Ar enc |
.Op Fl e Ar enc |
.Op Fl f Ar device |
.Op Fl f Ar device |
|
|
.Op Fl o Ar file |
.Op Fl o Ar file |
.Op Fl q Ar port |
.Op Fl q Ar port |
.Op Fl r Ar rate |
.Op Fl r Ar rate |
.Op Fl t Ar mode |
|
.Op Fl v Ar volume |
.Op Fl v Ar volume |
.Op Fl w Ar flag |
|
.Op Fl x Ar policy |
|
.Ek |
.Ek |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm |
.Nm |
utility can play, record, mix, and convert audio files. |
utility can play, record, mix, and process audio files |
|
on the fly. |
During playback, |
During playback, |
.Nm |
.Nm |
reads audio data concurrently from all played files, mixes it and sends |
reads audio data concurrently from all played files, |
the result to the device. |
mixes it and plays the result on the device. |
Similarly, during recording it duplicates audio data recorded |
Similarly, it stores audio data recorded |
from the device and stores it into corresponding files. |
from the device into corresponding files. |
It can process audio data on the fly: |
An |
|
.Em off-line |
|
mode could be used to process audio files without |
|
involving audio hardware. |
|
Processing includes: |
.Pp |
.Pp |
.Bl -bullet -offset indent -compact |
.Bl -bullet -offset indent -compact |
.It |
.It |
Change the sound encoding. |
Change the sound encoding. |
.It |
.It |
Route the sound from one channel to another, |
Route the sound from one channel to another. |
join stereo or split mono. |
|
.It |
.It |
Control the per-file playback volume. |
Control the per-file playback volume. |
.It |
|
Monitor the sound being played, allowing the playback mix |
|
to be recorded. |
|
.El |
.El |
.Pp |
.Pp |
Finally, |
Finally, |
|
|
.Pp |
.Pp |
The options are as follows: |
The options are as follows: |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
|
.It Fl Ar b size |
|
The buffer size of the audio device in frames. |
|
Default is 7680. |
.It Xo |
.It Xo |
.Fl C Ar min : Ns Ar max , |
|
.Fl c Ar min : Ns Ar max |
.Fl c Ar min : Ns Ar max |
.Xc |
.Xc |
The range of stream channel numbers for recording and playback directions, |
The range of audio file channel numbers. |
respectively. |
|
The default is |
The default is |
.Cm 0:1 , |
.Cm 0:1 , |
i.e. stereo. |
i.e. stereo. |
.It Fl d |
.It Fl d |
Increase log verbosity. |
Increase log verbosity. |
.It Fl e Ar enc |
.It Fl e Ar enc |
Encoding of the playback or recording stream (see below). |
Encoding of the audio file. |
The default is signed, 16-bit, native byte order. |
The default is |
|
.Va s16 . |
|
Encoding names use the follwing 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 |
.It Fl f Ar device |
Use this |
Use this |
.Xr sndio 7 |
.Xr sndio 7 |
audio device. |
audio device. |
Preceding per-device options apply to this device. |
Device mode and parameters are determined from audio files. |
Streams |
Default is |
.Pq Fl io |
.Pa default . |
and control MIDI ports |
|
.Pq Fl q |
|
that are applied after will be attached to this device. |
|
Device mode and parameters are determined from streams |
|
attached to it. |
|
.It Fl h Ar fmt |
.It Fl h Ar fmt |
File format of the playback or record stream (see below). |
Audio file type. |
The default is |
The following file types are supported: |
.Cm auto . |
.Bl -tag -width auto |
|
.It Ar raw |
|
Headerless file. |
|
.It Ar wav |
|
Microsoft WAV file format. |
|
.It Ar aiff |
|
Apple's audio interchange file format. |
|
.It Ar au |
|
Sun/NeXT audio file format. |
|
.It Ar auto |
|
Try to guess, depending on the file name. |
|
This is the default. |
|
.El |
.It Fl i Ar file |
.It Fl i Ar file |
Add this file to the list of streams to play. |
Play this audio file. |
If the option argument is |
If the option argument is |
.Sq - |
.Sq - |
then standard input will be used. |
then standard input will be used. |
.It Fl j Ar flag |
.It Fl j Ar flag |
Control whether stream channels are joined or expanded if |
Control whether source channels are joined or expanded if |
the stream number of channels is not equal to the device number of channels. |
they don't match the destination number of channels. |
If the flag is |
If the flag is |
.Cm off |
.Cm off , |
then stream channels are routed to the corresponding |
then each source channel is routed to a single destination channel, |
device channel, possibly discarding channels not present in the device. |
possibly discarding channels. |
If the flag is |
If the flag is |
.Cm on , |
.Cm on , |
then a single stream channel may be sent on multiple device channels, |
then a single source may be sent to multiple destinations |
or multiple stream channels may be sent to a single device channel. |
and multiple sources may be mixed into a single destination. |
For instance, this feature could be used to request mono streams to |
For instance, this feature could be used to convert |
be sent on multiple outputs or to record a stereo input into a mono stream. |
a stereo file into a mono file mixing left and right channels together. |
The default is |
The default is |
.Cm on . |
.Cm off . |
.It Fl M |
|
Create a MIDI thru box |
|
.Pq i.e. MIDI-only pseudo device . |
|
It merges any number of MIDI inputs and broadcasts the result |
|
to any number of MIDI outputs, similarly to a hardware MIDI thru box. |
|
Only MIDI ports |
|
.Pq Fl q |
|
and MIDI files |
|
can be attached to it. |
|
.It Fl n |
.It Fl n |
Create a loopback pseudo audio device. |
Off-line mode. |
Send input streams |
Read input files and store the result in the output files, |
to the output, processing them on the fly. |
processing them on the fly. |
This pseudo-device is useful to mix, demultiplex, resample or re-encode |
This mode is useful to mix, demultiplex, resample or re-encode |
audio files offline. |
audio files off-line. |
It requires at least one input |
It requires at least one input |
.Pq Fl i |
.Pq Fl i |
and one output |
and one output |
.Pq Fl o . |
.Pq Fl o . |
.It Fl o Ar file |
.It Fl o Ar file |
Add this file to the list of recording streams. |
Record into this audio file. |
If the option argument is |
If the option argument is |
.Sq - |
.Sq - |
then standard output will be used. |
then standard output will be used. |
.It Fl q Ar port |
.It Fl q Ar port |
Allow audio device properties to be controlled |
Control audio device properties through this MIDI port. |
through this MIDI port. |
|
This includes per-stream volumes and the ability to |
This includes per-stream volumes and the ability to |
synchronously start, stop and relocate streams created in |
synchronously start, stop and relocate audio files. |
MIDI Machine |
|
Control (MMC) slave mode |
|
.Pq Fl t . |
|
.It Fl r Ar rate |
.It Fl r Ar rate |
Sample rate in Hertz of the stream. |
Sample rate in Hertz of the audio file. |
The default is |
The default is |
.Cm 48000 . |
.Cm 48000 . |
.It Fl t Ar mode |
|
Select the way streams are controlled by MIDI Machine Control (MMC) |
|
messages. |
|
If the mode is |
|
.Cm off |
|
(the default), then streams are not affected by MMC messages. |
|
If the mode is |
|
.Cm slave , |
|
then streams are started synchronously by MMC start messages. |
|
.It Fl v Ar volume |
.It Fl v Ar volume |
Software volume attenuation of the playback stream. |
Software volume attenuation of the file to play. |
The value must be between 1 and 127, |
The value must be between 1 and 127, |
corresponding to \-42dB and \-0dB attenuation in 1/3dB steps. |
corresponding to \-42dB and \-0dB attenuation in 1/3dB steps. |
The default is 127, i.e. no attenuation. |
The default is 127, i.e. no attenuation. |
.It Fl w Ar flag |
|
Control |
|
.Nm |
|
behaviour when the maximum volume of the hardware is reached |
|
and a new stream is connected. |
|
This happens only when stream volumes |
|
are not properly set using the |
|
.Fl v |
|
option. |
|
If the flag is |
|
.Cm on , |
|
then the master volume (corresponding to the mix of all playback streams) |
|
is automatically adjusted to avoid clipping. |
|
Using |
|
.Cm off |
|
makes sense when all streams are recorded or produced with properly lowered |
|
volumes. |
|
The default is |
|
.Cm on . |
|
.It Fl x Ar 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 |
|
.Cm 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 |
|
.Cm 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 |
|
.Cm error |
|
then the stream is closed permanently. |
|
.Pp |
|
If a stream is created with the |
|
.Fl t |
|
option, |
|
the |
|
.Cm ignore |
|
action is disabled for any stream connected to it |
|
to ensure proper synchronization. |
|
.El |
.El |
.Pp |
.Pp |
On the command line, |
On the command line, |
per-device parameters must precede the device definition |
per-file parameters |
.Pq Fl fMn , |
.Pq Fl cehjrv |
and per-stream parameters |
must precede the file definition |
.Pq Fl Ccehjmrtvx |
|
must precede the stream definition |
|
.Pq Fl io . |
.Pq Fl io . |
MIDI ports |
|
.Pq Fl q |
|
and stream definitions |
|
.Pq Fl io |
|
must follow the definition of the device |
|
.Pq Fl fMn |
|
to which they are attached. |
|
.Pp |
.Pp |
If no audio devices |
|
.Pq Fl fMn |
|
are specified, |
|
settings are applied as if |
|
the default device is specified. |
|
.Pp |
|
If |
If |
.Nm aucat |
.Nm |
is sent |
is sent |
.Dv SIGHUP , |
.Dv SIGHUP , |
.Dv SIGINT |
.Dv SIGINT |
or |
or |
.Dv SIGTERM , |
.Dv SIGTERM , |
it terminates recording to files. |
it terminates recording to files. |
.Pp |
|
File formats are specified using the |
|
.Fl h |
|
option. |
|
The following file formats are supported: |
|
.Bl -tag -width s32lexxx -offset indent |
|
.It raw |
|
Headerless file. |
|
This format is recommended since it has no limitations. |
|
.It 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 |
|
.Xr lseek 2 |
|
operation (e.g. pipes do not support it). |
|
.It auto |
|
Try to guess, depending on the file name. |
|
.El |
|
.Pp |
|
Encodings are specified using the |
|
.Fl e |
|
option. |
|
The following encodings are supported: |
|
.Pp |
|
.Bl -tag -width s32lexxx -offset indent -compact |
|
.It s8 |
|
signed 8-bit |
|
.It u8 |
|
unsigned 8-bit |
|
.It s16le |
|
signed 16-bit, little endian |
|
.It u16le |
|
unsigned 16-bit, little endian |
|
.It s16be |
|
signed 16-bit, big endian |
|
.It u16be |
|
unsigned 16-bit, big endian |
|
.It s24le |
|
signed 24-bit, stored in 4 bytes, little endian |
|
.It u24le |
|
unsigned 24-bit, stored in 4 bytes, little endian |
|
.It s24be |
|
signed 24-bit, stored in 4 bytes, big endian |
|
.It u24be |
|
unsigned 24-bit, stored in 4 bytes, big endian |
|
.It s32le |
|
signed 32-bit, little endian |
|
.It u32le |
|
unsigned 32-bit, little endian |
|
.It s32be |
|
signed 32-bit, big endian |
|
.It u32be |
|
unsigned 32-bit, big endian |
|
.It s24le3 |
|
signed 24-bit, packed in 3 bytes, little endian |
|
.It u24le3 |
|
unsigned 24-bit, packed in 3 bytes, big endian |
|
.It s24be3 |
|
signed 24-bit, packed in 3 bytes, little endian |
|
.It u24be3 |
|
unsigned 24-bit, packed in 3 bytes, big endian |
|
.It s20le3 |
|
signed 20-bit, packed in 3 bytes, little endian |
|
.It u20le3 |
|
unsigned 20-bit, packed in 3 bytes, big endian |
|
.It s20be3 |
|
signed 20-bit, packed in 3 bytes, little endian |
|
.It u20be3 |
|
unsigned 20-bit, packed in 3 bytes, big endian |
|
.It s18le3 |
|
signed 18-bit, packed in 3 bytes, little endian |
|
.It u18le3 |
|
unsigned 18-bit, packed in 3 bytes, big endian |
|
.It s18be3 |
|
signed 18-bit, packed in 3 bytes, little endian |
|
.It u18be3 |
|
unsigned 18-bit, packed in 3 bytes, big endian |
|
.El |
|
.Sh MIDI CONTROL |
.Sh MIDI CONTROL |
.Nm |
.Nm |
can be controlled through MIDI |
can be controlled through MIDI |
|
|
as follows: |
as follows: |
a MIDI channel is assigned to each stream, and the volume |
a MIDI channel is assigned to each stream, and the volume |
is changed using the standard volume controller (number 7). |
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. |
|
.Pp |
.Pp |
The master volume can be changed using the standard master volume |
The master volume can be changed using the standard master volume |
system exclusive message. |
system exclusive message. |
.Pp |
.Pp |
Streams created with the |
All audio files are controlled by the following MMC messages: |
.Fl t |
.Bl -tag -width relocate -offset indent |
option are controlled by the following MMC messages: |
|
.Bl -tag -width relocateXXX -offset indent |
|
.It relocate |
.It relocate |
Files are relocated to the requested time position. |
All files are relocated to the requested time position. |
If the requested position is beyond the end of file, |
If it is beyond the end of a file, the file is temporarly |
playback of the file is temporarly disabled until a valid |
disabled until a valid position is requested. |
position is requested. |
|
.It start |
.It start |
Files are started. |
Playback and/or recording is started. |
.It stop |
.It stop |
Files are stopped and rewound back to the starting position. |
Playback and/or recording is stopped and all files are rewound |
|
back to the starting position. |
.El |
.El |
.Pp |
.Pp |
MIDI control is intended to be used together with |
MIDI control is intended to be used together with |
|
|
and a MMC-controlled one |
and a MMC-controlled one |
.Va snd/0.mmc : |
.Va snd/0.mmc : |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
$ sndiod -r 48000 -z 400 -s default -t slave -s mmc |
$ sndiod -r 48000 -z 480 -s default -t slave -s mmc |
.Ed |
.Ed |
.Pp |
.Pp |
Programs using |
Programs using |
|
|
.Va midithru/0 |
.Va midithru/0 |
MIDI port: |
MIDI port: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
$ aucat -f snd/0.mmc -t slave -q midithru/0 -i file.wav |
$ aucat -f snd/0.mmc -q midithru/0 -i file.wav |
.Ed |
.Ed |
.Pp |
.Pp |
At this stage, |
At this stage, |
|
|
port as MTC clock source, assured to be synchronous to playback of |
port as MTC clock source, assured to be synchronous to playback of |
.Pa file.wav . |
.Pa file.wav . |
.Sh EXAMPLES |
.Sh EXAMPLES |
Mix and play two stereo streams, |
Mix and play two files while recording a third file: |
the first at 48kHz and the second at 44.1kHz: |
|
.Bd -literal -offset indent |
.Bd -literal -offset indent |
$ aucat -r 48000 -i file1.raw -r 44100 -i file2.raw |
$ aucat -i file1.wav -i file2.wav -o file3.wav |
.Ed |
.Ed |
.Pp |
.Pp |
Record channels 2 and 3 into one stereo file and |
Record channels 2 and 3 into one stereo file and |
channels 6 and 7 into another stereo file using a 96kHz sampling rate for |
channels 6 and 7 into another stereo file using a 44.1kHz sampling |
both: |
rate for both: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
$ aucat -j off -r 96000 -C 2:3 -o file1.raw -C 6:7 -o file2.raw |
$ aucat -r 44100 -c 2:3 -o file1.wav -c 6:7 -o file2.wav |
.Ed |
.Ed |
.Pp |
.Pp |
Split a stereo file into two mono files: |
Split a stereo file into two mono files: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
$ aucat -n -j off -i stereo.wav -C 0:0 -o left.wav -C 1:1 \e |
$ aucat -n -i stereo.wav -c 0:0 -o left.wav \e |
-o right.wav |
-c 1:1 -o right.wav |
.Ed |
.Ed |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr audioctl 1 , |
.Xr audioctl 1 , |
|
|
.Xr audio 4 , |
.Xr audio 4 , |
.Xr sndio 7 |
.Xr sndio 7 |
.Sh BUGS |
.Sh BUGS |
Resampling is low quality; down-sampling especially should be avoided |
Resampling is low quality. |
when recording. |
|
.Pp |
.Pp |
Processing is done using 16-bit arithmetic, |
There are limitations inherent to the |
thus samples with more than 16 bits are rounded. |
.Ar wav , |
16 bits (i.e. 97dB dynamic) are largely enough for most applications though. |
.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). |