1.\" $OpenBSD: aucat.1,v 1.123 2024/05/21 05:09:29 ratchov Exp $ 2.\" 3.\" Copyright (c) 2006 Alexandre Ratchov <alex@caoua.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: May 21 2024 $ 18.Dt AUCAT 1 19.Os 20.Sh NAME 21.Nm aucat 22.Nd audio file manipulation tool 23.Sh SYNOPSIS 24.Nm aucat 25.Op Fl dn 26.Op Fl b Ar size 27.Op Fl c Ar channels 28.Op Fl e Ar enc 29.Op Fl f Ar device 30.Op Fl g Ar position 31.Op Fl h Ar fmt 32.Op Fl i Ar file 33.Op Fl m Ar min : Ns Ar max Ns / Ns Ar min : Ns Ar max 34.Op Fl o Ar file 35.Op Fl p Ar position 36.Op Fl q Ar port 37.Op Fl r Ar rate 38.Op Fl v Ar volume 39.Sh DESCRIPTION 40The 41.Nm 42utility can play, record, mix, and process audio files 43on the fly. 44During playback, 45.Nm 46reads audio data concurrently from all played files, 47mixes it and plays the result on the device. 48Similarly, it stores audio data recorded 49from the device into corresponding files. 50An 51.Em off-line 52mode could be used to process audio files without 53involving audio hardware. 54Processing includes: 55.Pp 56.Bl -bullet -offset indent -compact 57.It 58Change the sound encoding. 59.It 60Route the sound from one channel to another. 61.It 62Control the per-file playback volume. 63.El 64.Pp 65Finally, 66.Nm 67can accept MIDI messages usable for: 68.Pp 69.Bl -bullet -offset indent -compact 70.It 71Volume control. 72.It 73Start, stop and relocate playback and recording. 74.El 75.Pp 76The options are as follows: 77.Bl -tag -width Ds 78.It Fl b Ar size 79The buffer size of the audio device in frames. 80Default is 7680. 81.It Fl c Ar channels 82The audio file channels count. 83The default is 2, i.e. stereo. 84.It Fl d 85Increase log verbosity. 86.It Fl e Ar enc 87Encoding of the audio file. 88The default is 89.Va s24 . 90Encoding names use the following scheme: signedness 91.Po 92.Va s 93or 94.Va u 95.Pc 96followed 97by the precision in bits, the byte-order 98.Po 99.Va le 100or 101.Va be 102.Pc , 103the number of 104bytes per sample, and the alignment 105.Po 106.Va msb 107or 108.Va lsb 109.Pc . 110Only the signedness and the precision are mandatory. 111Examples: 112.Va u8 , s16le , s24le3 , s24le4lsb . 113.It Fl f Ar device 114Use this 115.Xr sndio 7 116audio device. 117Device mode and parameters are determined from audio files. 118Default is 119.Pa default . 120.It Fl g Ar position 121Go to the given time position and start playback or recording there. 122This option is equivalent to an incoming MMC relocate message 123with the same position. 124The position is expressed as the number of samples (at device sample rate). 125.It Fl h Ar fmt 126Audio file type. 127The following file types are supported: 128.Pp 129.Bl -tag -width autoX -compact 130.It Cm raw 131Headerless file. 132.It Cm wav 133Microsoft WAV file format. 134.It Cm aiff 135Apple's audio interchange file format. 136.It Cm au 137Sun/NeXT audio file format. 138.It Cm auto 139Try to guess, depending on the file name. 140This is the default. 141.El 142.It Fl i Ar file 143Play this audio file. 144If the option argument is 145.Sq - 146then standard input will be used. 147.It Fl m Ar min : Ns Ar max Ns / Ns Ar min : Ns Ar max 148Map the given range of source channels into the given range of 149destination channels. 150.It Fl n 151Off-line mode. 152Read input files and store the result in the output files, 153processing them on the fly. 154This mode is useful to mix, demultiplex, resample or re-encode 155audio files off-line. 156It requires at least one input 157.Pq Fl i 158and one output 159.Pq Fl o . 160.It Fl o Ar file 161Record into this audio file. 162If the option argument is 163.Sq - 164then standard output will be used. 165.It Fl p Ar position 166Time offset where the beginning of the file belongs. 167The first sample of the file will be played or recorded when the device 168reaches the given position. 169The position is expressed as the number of samples (at device sample rate). 170.It Fl q Ar port 171Control audio device properties through this MIDI port. 172This includes per-stream volumes and the ability to 173synchronously start, stop and relocate audio files. 174.It Fl r Ar rate 175Sample rate in Hertz of the audio file. 176The default is 177.Cm 48000 . 178.It Fl v Ar volume 179Software volume attenuation of the file to play. 180The value must be between 1 and 127, 181corresponding to \-42dB and \-0dB attenuation in 1/3dB steps. 182The default is 127, i.e. no attenuation. 183.El 184.Pp 185On the command line, 186per-file parameters 187.Pq Fl cehmrv 188must precede the file definition 189.Pq Fl io . 190.Pp 191If 192.Nm 193is sent 194.Dv SIGHUP , 195.Dv SIGINT 196or 197.Dv SIGTERM , 198it terminates recording to files. 199.Sh MIDI CONTROL 200.Nm 201can be controlled through MIDI 202.Pq Fl q 203as follows: 204a MIDI channel is assigned to each stream, and the volume 205is changed using the standard volume controller (number 7). 206The master volume can be changed using the standard master volume 207system exclusive message. 208.Pp 209All audio files are controlled by the following MMC messages: 210.Pp 211.Bl -tag -width relocateX -offset indent -compact 212.It relocate 213All files are relocated to the requested time position. 214If it is beyond the end of a file, the file is temporarily 215disabled until a valid position is requested. 216.It start 217Playback and/or recording is started. 218.It stop 219Playback and/or recording is stopped and all files are rewound 220back to the starting position. 221.El 222.Pp 223MIDI control is intended to be used together with 224.Xr sndiod 8 . 225For instance, the following command will create two devices: 226the default 227.Va snd/default 228and a MMC-controlled one 229.Va snd/default.mmc : 230.Bd -literal -offset indent 231$ sndiod -r 48000 -z 480 -s default -t slave -s mmc 232.Ed 233.Pp 234Programs using 235.Va snd/default 236behave normally, while programs using 237.Va snd/mmc 238wait for the MMC start signal and start synchronously. 239Then, the following command will play a file on the 240.Va snd/mmc 241audio device, giving full control to MIDI software or hardware 242connected to the 243.Va midithru/0 244MIDI port: 245.Bd -literal -offset indent 246$ aucat -f snd/mmc -q midithru/0 -i file.wav 247.Ed 248.Pp 249At this stage, 250.Nm 251will start, stop and relocate automatically following all user 252actions in the MIDI sequencer, assuming it's configured to 253transmit MMC on 254.Va midithru/0 255and 256.Va snd/mmc . 257Furthermore, the MIDI sequencer could be configured to use the 258.Va snd/mmc 259port as MTC clock source, assured to be synchronous to playback of 260.Pa file.wav . 261.Sh EXAMPLES 262Mix and play two files while recording a third file: 263.Bd -literal -offset indent 264$ aucat -i file1.wav -i file2.wav -o file3.wav 265.Ed 266.Pp 267Record channels 2 and 3 into one stereo file and 268channels 6 and 7 into another stereo file using a 44.1kHz sampling 269rate for both: 270.Bd -literal -offset indent 271$ aucat -r 44100 -m 2:3/0:1 -o file1.wav -m 6:7/0:1 -o file2.wav 272.Ed 273.Pp 274Split a stereo file into two mono files: 275.Bd -literal -offset indent 276$ aucat -n -i stereo.wav -c 1 -m 0:0/0:0 -o left.wav \e 277 -m 1:1/0:0 -o right.wav 278.Ed 279.Sh SEE ALSO 280.Xr cdio 1 , 281.Xr audio 4 , 282.Xr sndio 7 , 283.Xr audioctl 8 , 284.Xr mixerctl 8 , 285.Xr sndiod 8 286.Sh BUGS 287Resampling is low quality. 288.Pp 289There are limitations inherent to the 290.Ar wav , 291.Ar aiff , 292and 293.Ar au 294file formats: not all encodings are supported, 295file sizes are limited to 2GB, and the files must support the 296.Xr lseek 2 297operation (e.g. pipes do not support it). 298