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