Annotation of src/usr.bin/aucat/aucat.1, Revision 1.105
1.102 ratchov 1: .\" $OpenBSD$
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.102 ratchov 17: .Dd $Mdocdate$
1.1 kstailey 18: .Dt AUCAT 1
1.5 aaron 19: .Os
1.1 kstailey 20: .Sh NAME
1.102 ratchov 21: .Nm aucat
22: .Nd audio/MIDI stream manipulation tool
1.1 kstailey 23: .Sh SYNOPSIS
24: .Nm aucat
1.16 ratchov 25: .Bk -words
1.102 ratchov 26: .Op Fl dMn
1.16 ratchov 27: .Op Fl C Ar min : Ns Ar max
28: .Op Fl c Ar min : Ns Ar max
29: .Op Fl e Ar enc
1.9 millert 30: .Op Fl f Ar device
1.16 ratchov 31: .Op Fl h Ar fmt
32: .Op Fl i Ar file
1.68 ratchov 33: .Op Fl j Ar flag
1.94 ratchov 34: .Op Fl o Ar file
35: .Op Fl q Ar port
36: .Op Fl r Ar rate
37: .Op Fl t Ar mode
38: .Op Fl v Ar volume
39: .Op Fl w Ar flag
40: .Op Fl x Ar policy
1.16 ratchov 41: .Ek
1.1 kstailey 42: .Sh DESCRIPTION
1.99 ratchov 43: The
1.102 ratchov 44: .Nm
45: utility can play, record, mix, and convert audio files.
1.99 ratchov 46: During playback,
1.102 ratchov 47: .Nm
48: reads audio data concurrently from all played files, mixes it and sends
49: the result to the device.
1.100 jmc 50: Similarly, during recording it duplicates audio data recorded
1.102 ratchov 51: from the device and stores it into corresponding files.
52: It can process audio data on the fly:
1.99 ratchov 53: .Pp
54: .Bl -bullet -offset indent -compact
55: .It
1.102 ratchov 56: Change the sound encoding.
1.99 ratchov 57: .It
58: Route the sound from one channel to another,
59: join stereo or split mono.
60: .It
1.102 ratchov 61: Control the per-file playback volume.
1.99 ratchov 62: .It
1.105 ! ratchov 63: Monitor the sound being played, allowing the playback mix
1.104 ratchov 64: to be recorded.
1.99 ratchov 65: .El
66: .Pp
67: Finally,
1.102 ratchov 68: .Nm
69: can accept MIDI messages usable for:
1.99 ratchov 70: .Pp
71: .Bl -bullet -offset indent -compact
72: .It
73: Volume control.
74: .It
1.102 ratchov 75: Start, stop and relocate playback and recording.
1.99 ratchov 76: .El
77: .Pp
1.16 ratchov 78: The options are as follows:
1.26 ratchov 79: .Bl -tag -width Ds
1.25 jmc 80: .It Xo
81: .Fl C Ar min : Ns Ar max ,
82: .Fl c Ar min : Ns Ar max
83: .Xc
1.72 jmc 84: The range of stream channel numbers for recording and playback directions,
85: respectively.
1.104 ratchov 86: The default is
87: .Cm 0:1 ,
88: i.e. stereo.
1.59 ratchov 89: .It Fl d
1.71 ratchov 90: Increase log verbosity.
1.26 ratchov 91: .It Fl e Ar enc
92: Encoding of the playback or recording stream (see below).
1.17 jmc 93: The default is signed, 16-bit, native byte order.
94: .It Fl f Ar device
1.102 ratchov 95: Use this
1.57 ratchov 96: .Xr sndio 7
1.102 ratchov 97: audio device.
98: Preceding per-device options apply to this device.
1.87 ratchov 99: Streams
1.102 ratchov 100: .Pq Fl io
1.87 ratchov 101: and control MIDI ports
102: .Pq Fl q
103: that are applied after will be attached to this device.
1.71 ratchov 104: Device mode and parameters are determined from streams
105: attached to it.
1.26 ratchov 106: .It Fl h Ar fmt
107: File format of the playback or record stream (see below).
1.104 ratchov 108: The default is
109: .Cm auto .
1.16 ratchov 110: .It Fl i Ar file
1.71 ratchov 111: Add this file to the list of streams to play.
1.16 ratchov 112: If the option argument is
113: .Sq -
114: then standard input will be used.
1.68 ratchov 115: .It Fl j Ar flag
1.71 ratchov 116: Control whether stream channels are joined or expanded if
1.68 ratchov 117: the stream number of channels is not equal to the device number of channels.
118: If the flag is
1.104 ratchov 119: .Cm off
1.68 ratchov 120: then stream channels are routed to the corresponding
121: device channel, possibly discarding channels not present in the device.
122: If the flag is
1.104 ratchov 123: .Cm on ,
1.68 ratchov 124: then a single stream channel may be sent on multiple device channels,
125: or multiple stream channels may be sent to a single device channel.
126: For instance, this feature could be used to request mono streams to
127: be sent on multiple outputs or to record a stereo input into a mono stream.
128: The default is
1.104 ratchov 129: .Cm on .
1.87 ratchov 130: .It Fl M
131: Create a MIDI thru box
132: .Pq i.e. MIDI-only pseudo device .
133: It merges any number of MIDI inputs and broadcasts the result
134: to any number of MIDI outputs, similarly to a hardware MIDI thru box.
135: Only MIDI ports
136: .Pq Fl q
137: and MIDI files
138: can be attached to it.
1.42 ratchov 139: .It Fl n
1.87 ratchov 140: Create a loopback pseudo audio device.
141: Send input streams
1.42 ratchov 142: to the output, processing them on the fly.
1.87 ratchov 143: This pseudo-device is useful to mix, demultiplex, resample or re-encode
1.43 jmc 144: audio files offline.
1.87 ratchov 145: It requires at least one input
146: .Pq Fl i
147: and one output
148: .Pq Fl o .
1.16 ratchov 149: .It Fl o Ar file
1.71 ratchov 150: Add this file to the list of recording streams.
1.16 ratchov 151: If the option argument is
152: .Sq -
153: then standard output will be used.
1.87 ratchov 154: .It Fl q Ar port
1.102 ratchov 155: Allow audio device properties to be controlled
156: through this MIDI port.
1.71 ratchov 157: This includes per-stream volumes and the ability to
158: synchronously start, stop and relocate streams created in
159: MIDI Machine
160: Control (MMC) slave mode
161: .Pq Fl t .
1.26 ratchov 162: .It Fl r Ar rate
1.71 ratchov 163: Sample rate in Hertz of the stream.
1.104 ratchov 164: The default is
165: .Cm 48000 .
1.62 ratchov 166: .It Fl t Ar mode
1.71 ratchov 167: Select the way streams are controlled by MIDI Machine Control (MMC)
1.67 jmc 168: messages.
1.62 ratchov 169: If the mode is
1.104 ratchov 170: .Cm off
1.62 ratchov 171: (the default), then streams are not affected by MMC messages.
172: If the mode is
1.104 ratchov 173: .Cm slave ,
1.102 ratchov 174: then streams are started synchronously by MMC start messages.
1.30 ratchov 175: .It Fl v Ar volume
176: Software volume attenuation of the playback stream.
177: The value must be between 1 and 127,
1.82 jmc 178: corresponding to \-42dB and \-0dB attenuation in 1/3dB steps.
1.104 ratchov 179: The default is 127, i.e. no attenuation.
1.80 ratchov 180: .It Fl w Ar flag
181: Control
182: .Nm
183: behaviour when the maximum volume of the hardware is reached
184: and a new stream is connected.
185: This happens only when stream volumes
186: are not properly set using the
187: .Fl v
188: option.
189: If the flag is
190: .Va on ,
191: then the master volume (corresponding to the mix of all playback streams)
192: is automatically adjusted to avoid clipping.
193: Using
1.82 jmc 194: .Va off
1.80 ratchov 195: makes sense when all streams are recorded or produced with properly lowered
196: volumes.
197: The default is
1.104 ratchov 198: .Cm on .
1.26 ratchov 199: .It Fl x Ar policy
1.22 ratchov 200: Action when the output stream cannot accept
1.26 ratchov 201: recorded data fast enough or the input stream
202: cannot provide data to play fast enough.
1.104 ratchov 203: If the policy is
204: .Cm ignore
1.26 ratchov 205: (the default) then samples that cannot be written are discarded
206: and samples that cannot be read are replaced by silence.
1.22 ratchov 207: If the policy is
1.104 ratchov 208: .Cm sync
1.72 jmc 209: then recorded samples are discarded,
210: but the same amount of silence will be written
1.22 ratchov 211: once the stream is unblocked, in order to reach the right position in time.
1.26 ratchov 212: Similarly silence is played, but the same amount of samples will be discarded
213: once the stream is unblocked.
1.22 ratchov 214: If the policy is
1.104 ratchov 215: .Cm error
1.23 jmc 216: then the stream is closed permanently.
1.62 ratchov 217: .Pp
1.71 ratchov 218: If a stream is created with the
1.67 jmc 219: .Fl t
220: option,
1.63 jmc 221: the
1.104 ratchov 222: .Cm ignore
1.63 jmc 223: action is disabled for any stream connected to it
224: to ensure proper synchronization.
1.21 jmc 225: .El
226: .Pp
1.71 ratchov 227: On the command line,
1.102 ratchov 228: per-device parameters must precede the device definition
1.87 ratchov 229: .Pq Fl fMn ,
1.71 ratchov 230: and per-stream parameters
231: .Pq Fl Ccehjmrtvx
232: must precede the stream definition
1.102 ratchov 233: .Pq Fl io .
1.71 ratchov 234: MIDI ports
235: .Pq Fl q
1.75 okan 236: and stream definitions
1.102 ratchov 237: .Pq Fl io
1.87 ratchov 238: must follow the definition of the device
239: .Pq Fl fMn
1.71 ratchov 240: to which they are attached.
241: .Pp
242: If no audio devices
1.87 ratchov 243: .Pq Fl fMn
1.71 ratchov 244: are specified,
245: settings are applied as if
1.87 ratchov 246: the default device is specified.
1.71 ratchov 247: .Pp
1.32 ratchov 248: If
1.94 ratchov 249: .Nm aucat
1.32 ratchov 250: is sent
1.44 ratchov 251: .Dv SIGHUP ,
252: .Dv SIGINT
253: or
254: .Dv SIGTERM ,
1.32 ratchov 255: it terminates recording to files.
256: .Pp
1.20 jmc 257: File formats are specified using the
258: .Fl h
1.26 ratchov 259: option.
1.16 ratchov 260: The following file formats are supported:
1.66 ratchov 261: .Bl -tag -width s32lexxx -offset indent
1.16 ratchov 262: .It raw
263: Headerless file.
1.17 jmc 264: This format is recommended since it has no limitations.
1.16 ratchov 265: .It wav
266: Microsoft WAVE file format.
267: There are limitations inherent to the file format itself:
268: not all encodings are supported,
269: file sizes are limited to 2GB,
1.17 jmc 270: and the file must support the
1.16 ratchov 271: .Xr lseek 2
1.17 jmc 272: operation (e.g. pipes do not support it).
1.16 ratchov 273: .It auto
274: Try to guess, depending on the file name.
1.9 millert 275: .El
276: .Pp
1.20 jmc 277: Encodings are specified using the
278: .Fl e
1.26 ratchov 279: option.
1.16 ratchov 280: The following encodings are supported:
281: .Pp
1.66 ratchov 282: .Bl -tag -width s32lexxx -offset indent -compact
1.16 ratchov 283: .It s8
284: signed 8-bit
285: .It u8
286: unsigned 8-bit
287: .It s16le
288: signed 16-bit, little endian
289: .It u16le
290: unsigned 16-bit, little endian
291: .It s16be
292: signed 16-bit, big endian
293: .It u16be
294: unsigned 16-bit, big endian
295: .It s24le
296: signed 24-bit, stored in 4 bytes, little endian
297: .It u24le
298: unsigned 24-bit, stored in 4 bytes, little endian
299: .It s24be
300: signed 24-bit, stored in 4 bytes, big endian
301: .It u24be
302: unsigned 24-bit, stored in 4 bytes, big endian
303: .It s32le
304: signed 32-bit, little endian
305: .It u32le
306: unsigned 32-bit, little endian
307: .It s32be
308: signed 32-bit, big endian
309: .It u32be
310: unsigned 32-bit, big endian
311: .It s24le3
312: signed 24-bit, packed in 3 bytes, little endian
313: .It u24le3
314: unsigned 24-bit, packed in 3 bytes, big endian
315: .It s24be3
316: signed 24-bit, packed in 3 bytes, little endian
317: .It u24be3
318: unsigned 24-bit, packed in 3 bytes, big endian
319: .It s20le3
320: signed 20-bit, packed in 3 bytes, little endian
321: .It u20le3
322: unsigned 20-bit, packed in 3 bytes, big endian
323: .It s20be3
324: signed 20-bit, packed in 3 bytes, little endian
325: .It u20be3
326: unsigned 20-bit, packed in 3 bytes, big endian
327: .It s18le3
328: signed 18-bit, packed in 3 bytes, little endian
329: .It u18le3
330: unsigned 18-bit, packed in 3 bytes, big endian
331: .It s18be3
332: signed 18-bit, packed in 3 bytes, little endian
333: .It u18be3
334: unsigned 18-bit, packed in 3 bytes, big endian
335: .El
1.55 ratchov 336: .Sh MIDI CONTROL
337: .Nm
1.102 ratchov 338: can be controlled through MIDI
1.71 ratchov 339: .Pq Fl q
1.102 ratchov 340: as follows:
341: a MIDI channel is assigned to each stream, and the volume
1.55 ratchov 342: is changed using the standard volume controller (number 7).
1.71 ratchov 343: Similarly, when the audio client changes its volume,
1.55 ratchov 344: the same MIDI controller message is sent out; it can be used
1.56 jmc 345: for instance for monitoring or as feedback for motorized
1.55 ratchov 346: faders.
1.98 ratchov 347: .Pp
348: The master volume can be changed using the standard master volume
349: system exclusive message.
1.62 ratchov 350: .Pp
1.71 ratchov 351: Streams created with the
1.63 jmc 352: .Fl t
1.67 jmc 353: option are controlled by the following MMC messages:
1.66 ratchov 354: .Bl -tag -width relocateXXX -offset indent
1.62 ratchov 355: .It relocate
1.102 ratchov 356: Files are relocated to the requested time position.
1.71 ratchov 357: If the requested position is beyond the end of file,
1.102 ratchov 358: playback of the file is temporarly disabled until a valid
359: position is requested.
1.62 ratchov 360: .It start
1.102 ratchov 361: Files are started.
1.67 jmc 362: .It stop
1.102 ratchov 363: Files are stopped and rewound back to the starting position.
1.62 ratchov 364: .El
365: .Pp
1.102 ratchov 366: MIDI control is intended to be used together with
367: .Xr sndiod 1 .
1.62 ratchov 368: For instance, the following command will create two devices:
369: the default
1.92 ratchov 370: .Va snd/0
1.102 ratchov 371: and a MMC-controlled one
1.92 ratchov 372: .Va snd/0.mmc :
1.62 ratchov 373: .Bd -literal -offset indent
1.94 ratchov 374: $ sndiod -r 48000 -z 400 -s default -t slave -s mmc
1.62 ratchov 375: .Ed
376: .Pp
1.102 ratchov 377: Programs using
1.92 ratchov 378: .Va snd/0
1.102 ratchov 379: behave normally, while programs using
1.92 ratchov 380: .Va snd/0.mmc
1.62 ratchov 381: wait for the MMC start signal and start synchronously.
1.102 ratchov 382: Then, the following command will play a file on the
1.92 ratchov 383: .Va snd/0.mmc
1.102 ratchov 384: audio device, giving full control to MIDI software or hardware
1.66 ratchov 385: connected to the
1.102 ratchov 386: .Va midithru/0
1.89 ratchov 387: MIDI port:
1.66 ratchov 388: .Bd -literal -offset indent
1.92 ratchov 389: $ aucat -f snd/0.mmc -t slave -q midithru/0 -i file.wav
1.66 ratchov 390: .Ed
391: .Pp
392: At this stage,
393: .Nm
394: will start, stop and relocate automatically following all user
1.102 ratchov 395: actions in the MIDI sequencer, assuming it's configured to
396: transmit MMC on
397: .Va midithru/0 .
398: Furthermore, the MIDI sequencer could be configured to use the
1.92 ratchov 399: .Va snd/0
1.102 ratchov 400: port as MTC clock source, assured to be synchronous to playback of
401: .Pa file.wav .
1.16 ratchov 402: .Sh EXAMPLES
1.77 jmc 403: Mix and play two stereo streams,
1.16 ratchov 404: the first at 48kHz and the second at 44.1kHz:
405: .Bd -literal -offset indent
406: $ aucat -r 48000 -i file1.raw -r 44100 -i file2.raw
407: .Ed
408: .Pp
1.77 jmc 409: Record channels 2 and 3 into one stereo file and
1.16 ratchov 410: channels 6 and 7 into another stereo file using a 96kHz sampling rate for
411: both:
412: .Bd -literal -offset indent
1.83 ratchov 413: $ aucat -j off -r 96000 -C 2:3 -o file1.raw -C 6:7 -o file2.raw
1.42 ratchov 414: .Ed
415: .Pp
1.77 jmc 416: Split a stereo file into two mono files:
1.42 ratchov 417: .Bd -literal -offset indent
1.88 jmc 418: $ aucat -n -j off -i stereo.wav -C 0:0 -o left.wav -C 1:1 \e
419: -o right.wav
1.16 ratchov 420: .Ed
1.2 kstailey 421: .Sh SEE ALSO
1.12 jmc 422: .Xr audioctl 1 ,
1.17 jmc 423: .Xr cdio 1 ,
1.9 millert 424: .Xr mixerctl 1 ,
1.102 ratchov 425: .Xr sndiod 1 ,
1.54 ratchov 426: .Xr audio 4 ,
427: .Xr sndio 7
1.16 ratchov 428: .Sh BUGS
429: Resampling is low quality; down-sampling especially should be avoided
430: when recording.
431: .Pp
432: Processing is done using 16-bit arithmetic,
433: thus samples with more than 16 bits are rounded.
1.17 jmc 434: 16 bits (i.e. 97dB dynamic) are largely enough for most applications though.
![[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