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