Annotation of src/usr.bin/aucat/aucat.1, Revision 1.89
1.89 ! ratchov 1: .\" $OpenBSD: aucat.1,v 1.88 2011/10/12 12:16:10 jmc 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.88 jmc 17: .Dd $Mdocdate: October 12 2011 $
1.1 kstailey 18: .Dt AUCAT 1
1.5 aaron 19: .Os
1.1 kstailey 20: .Sh NAME
21: .Nm aucat
1.87 ratchov 22: .Nd audio/MIDI server and stream manipulation tool
1.1 kstailey 23: .Sh SYNOPSIS
24: .Nm aucat
1.16 ratchov 25: .Bk -words
1.87 ratchov 26: .Op Fl dlMn
1.70 ratchov 27: .Op Fl a Ar flag
1.49 jmc 28: .Op Fl b Ar nframes
1.16 ratchov 29: .Op Fl C Ar min : Ns Ar max
30: .Op Fl c Ar min : Ns Ar max
31: .Op Fl e Ar enc
1.9 millert 32: .Op Fl f Ar device
1.16 ratchov 33: .Op Fl h Ar fmt
34: .Op Fl i Ar file
1.68 ratchov 35: .Op Fl j Ar flag
1.76 ratchov 36: .Op Fl L Ar addr
1.37 ratchov 37: .Op Fl m Ar mode
1.16 ratchov 38: .Op Fl o Ar file
1.87 ratchov 39: .Op Fl q Ar port
1.16 ratchov 40: .Op Fl r Ar rate
1.57 ratchov 41: .Op Fl s Ar name
1.62 ratchov 42: .Op Fl t Ar mode
1.54 ratchov 43: .Op Fl U Ar unit
1.30 ratchov 44: .Op Fl v Ar volume
1.80 ratchov 45: .Op Fl w Ar flag
1.22 ratchov 46: .Op Fl x Ar policy
1.62 ratchov 47: .Op Fl z Ar nframes
1.16 ratchov 48: .Ek
1.1 kstailey 49: .Sh DESCRIPTION
1.9 millert 50: .Nm
1.71 ratchov 51: is an audio utility which can simultaneously play and record
52: any number of audio
53: .Em streams
54: on any number of audio devices,
55: possibly controlled through MIDI.
56: It can also act as an audio server, in which case streams
57: correspond to client connections rather than plain files.
58: .Pp
59: Audio devices are independent.
60: A list of streams is attached to each audio device,
61: as well as an optional list of MIDI ports to control the device.
62: A typical invocation of
63: .Nm
64: consists in providing streams to play and record,
65: and possibly the audio device to use, if the default is not desired.
66: .Pp
67: This also applies to server mode, except that streams are created
68: dynamically when clients connect to the server.
69: Thus, instead of actual streams (paths to plain files),
70: templates for client streams (sub-device names) must be provided.
1.17 jmc 71: .Pp
1.16 ratchov 72: The options are as follows:
1.26 ratchov 73: .Bl -tag -width Ds
1.70 ratchov 74: .It Fl a Ar flag
75: Control whether
76: .Nm
1.71 ratchov 77: opens the audio device only when needed or keeps it open all the time.
1.85 ratchov 78: This applies to MIDI ports controlling the device as well.
1.70 ratchov 79: If the flag is
80: .Va on
81: then the device is kept open all the time, ensuring no other program can
82: steal it.
83: If the flag is
84: .Va off ,
85: then it's automatically closed, allowing other programs to have direct
86: access to the device, or the device to be disconnected.
87: The default is
88: .Va on .
1.49 jmc 89: .It Fl b Ar nframes
1.66 ratchov 90: The buffer size of the audio device in frames.
1.49 jmc 91: A frame consists of one sample for each channel in the stream.
92: This is the number of frames that will be buffered before being played
93: and thus controls the playback latency.
1.25 jmc 94: .It Xo
95: .Fl C Ar min : Ns Ar max ,
96: .Fl c Ar min : Ns Ar max
97: .Xc
1.72 jmc 98: The range of stream channel numbers for recording and playback directions,
99: respectively.
1.17 jmc 100: The default is 0:1, i.e. stereo.
1.59 ratchov 101: .It Fl d
1.71 ratchov 102: Increase log verbosity.
1.59 ratchov 103: .Nm
1.75 okan 104: logs on
105: .Em stderr
106: until it daemonizes.
1.26 ratchov 107: .It Fl e Ar enc
108: Encoding of the playback or recording stream (see below).
1.17 jmc 109: The default is signed, 16-bit, native byte order.
110: .It Fl f Ar device
1.71 ratchov 111: Add this
1.57 ratchov 112: .Xr sndio 7
1.71 ratchov 113: audio device to devices used for playing and/or recording.
1.87 ratchov 114: Preceding per-device options
115: .Pq Fl abwz
1.71 ratchov 116: apply to this device.
1.87 ratchov 117: Streams
118: .Pq Fl ios
119: and control MIDI ports
120: .Pq Fl q
121: that are applied after will be attached to this device.
1.71 ratchov 122: Device mode and parameters are determined from streams
123: attached to it.
1.26 ratchov 124: .It Fl h Ar fmt
125: File format of the playback or record stream (see below).
1.17 jmc 126: The default is auto.
1.16 ratchov 127: .It Fl i Ar file
1.71 ratchov 128: Add this file to the list of streams to play.
1.16 ratchov 129: If the option argument is
130: .Sq -
131: then standard input will be used.
1.68 ratchov 132: .It Fl j Ar flag
1.71 ratchov 133: Control whether stream channels are joined or expanded if
1.68 ratchov 134: the stream number of channels is not equal to the device number of channels.
135: If the flag is
136: .Va off
137: then stream channels are routed to the corresponding
138: device channel, possibly discarding channels not present in the device.
139: If the flag is
140: .Va on ,
141: then a single stream channel may be sent on multiple device channels,
142: or multiple stream channels may be sent to a single device channel.
143: For instance, this feature could be used to request mono streams to
144: be sent on multiple outputs or to record a stereo input into a mono stream.
145: The default is
146: .Ar on .
1.76 ratchov 147: .It Fl L Ar addr
148: Specify a local network address to listen on in server mode.
149: .Nm
150: will listen on TCP port 11025+n, where n is the unit number
151: specified with
152: .Fl U .
153: Without this option,
154: .Nm
155: listens on the
156: .Ux Ns -domain
157: socket only, and is not reachable from any network.
1.78 ratchov 158: If the option argument is
159: .Sq -
160: then
161: .Nm
162: will accept connections from any address.
1.26 ratchov 163: .It Fl l
1.71 ratchov 164: Detach and become a daemon.
1.87 ratchov 165: .It Fl M
166: Create a MIDI thru box
167: .Pq i.e. MIDI-only pseudo device .
168: It merges any number of MIDI inputs and broadcasts the result
169: to any number of MIDI outputs, similarly to a hardware MIDI thru box.
170: Only MIDI ports
171: .Pq Fl q
172: and MIDI files
173: .Po
174: .Fl io
175: preceded by
176: .Fl m Ar midi
177: .Pc
178: can be attached to it.
179: If sub-devices are exposed
180: .Pq Fl s
181: they behave like software MIDI ports,
182: allowing any MIDI-capable application to send MIDI messages to
183: MIDI hardware or to another application in a uniform way.
1.37 ratchov 184: .It Fl m Ar mode
1.66 ratchov 185: Set the stream mode.
1.37 ratchov 186: Valid modes are
1.39 jmc 187: .Ar play ,
188: .Ar rec ,
1.87 ratchov 189: .Ar mon ,
1.37 ratchov 190: and
1.87 ratchov 191: .Ar midi ,
192: corresponding to playback, recording, monitoring and MIDI control.
1.66 ratchov 193: A monitoring stream is a fake recording stream corresponding to
194: the mix of all playback streams.
195: Multiple modes can be specified, separated by commas,
196: but the same stream cannot be used for both recording and monitoring.
1.37 ratchov 197: The default is
1.87 ratchov 198: .Ar play , Ns Ar rec , Ns Ar midi
199: (i.e. full-duplex with MIDI control enabled).
1.42 ratchov 200: .It Fl n
1.87 ratchov 201: Create a loopback pseudo audio device.
202: Send input streams
1.42 ratchov 203: to the output, processing them on the fly.
1.87 ratchov 204: This pseudo-device is useful to mix, demultiplex, resample or re-encode
1.43 jmc 205: audio files offline.
1.87 ratchov 206: It requires at least one input
207: .Pq Fl i
208: and one output
209: .Pq Fl o .
210: It doesn't support MIDI control
211: .Pq Fl q
212: and can't expose sub-devices
213: .Pq Fl s .
1.16 ratchov 214: .It Fl o Ar file
1.71 ratchov 215: Add this file to the list of recording streams.
1.16 ratchov 216: If the option argument is
217: .Sq -
218: then standard output will be used.
1.87 ratchov 219: .It Fl q Ar port
1.71 ratchov 220: Expose the audio device clock on this
1.66 ratchov 221: .Xr sndio 7
1.71 ratchov 222: MIDI port and allow audio device properties to be controlled
223: through MIDI.
224: This includes per-stream volumes and the ability to
225: synchronously start, stop and relocate streams created in
226: MIDI Machine
227: Control (MMC) slave mode
228: .Pq Fl t .
1.26 ratchov 229: .It Fl r Ar rate
1.71 ratchov 230: Sample rate in Hertz of the stream.
1.17 jmc 231: The default is 44100Hz.
1.57 ratchov 232: .It Fl s Ar name
233: Add
234: .Ar name
235: to the list of sub-devices to expose in server mode.
1.71 ratchov 236: This allows clients to use
237: .Nm
238: instead of the physical audio device for audio input and output
239: in order to share the physical device with other clients.
1.57 ratchov 240: Defining multiple sub-devices allows splitting a physical audio device
1.63 jmc 241: into logical devices having different properties (e.g. channel ranges).
1.57 ratchov 242: The given
243: .Ar name
1.62 ratchov 244: corresponds to the
1.57 ratchov 245: .Dq option
246: part of the
247: .Xr sndio 7
248: device name string.
1.62 ratchov 249: .It Fl t Ar mode
1.71 ratchov 250: Select the way streams are controlled by MIDI Machine Control (MMC)
1.67 jmc 251: messages.
1.62 ratchov 252: If the mode is
253: .Va off
254: (the default), then streams are not affected by MMC messages.
255: If the mode is
256: .Va slave ,
257: then streams are started synchronously by MMC start messages;
1.67 jmc 258: additionally, the server clock is exposed as MIDI Time Code (MTC)
1.62 ratchov 259: messages allowing MTC-capable software or hardware to be synchronized
260: to audio streams.
1.54 ratchov 261: .It Fl U Ar unit
262: Unit number to use when running in server mode.
263: Each
264: .Nm
265: server instance has an unique unit number,
266: used in
267: .Xr sndio 7
268: device names.
269: The default is 0.
1.87 ratchov 270: The unit number must be set before any server-specific
271: options are used
272: .Pq Fl Ls .
1.30 ratchov 273: .It Fl v Ar volume
274: Software volume attenuation of the playback stream.
275: The value must be between 1 and 127,
1.82 jmc 276: corresponding to \-42dB and \-0dB attenuation in 1/3dB steps.
1.33 ratchov 277: In server mode, clients inherit this parameter.
1.82 jmc 278: Reducing the volume in advance allows a client's volume to stay independent
1.81 ratchov 279: from the number of clients as long as their number is small enough.
1.82 jmc 280: 18 volume units (i.e. \-6dB attenuation) allows the number
1.81 ratchov 281: of playback streams to be doubled.
1.82 jmc 282: The default is 127 i.e. no attenuation.
1.80 ratchov 283: .It Fl w Ar flag
284: Control
285: .Nm
286: behaviour when the maximum volume of the hardware is reached
287: and a new stream is connected.
288: This happens only when stream volumes
289: are not properly set using the
290: .Fl v
291: option.
292: If the flag is
293: .Va on ,
294: then the master volume (corresponding to the mix of all playback streams)
295: is automatically adjusted to avoid clipping.
296: Using
1.82 jmc 297: .Va off
1.80 ratchov 298: makes sense when all streams are recorded or produced with properly lowered
299: volumes.
300: The default is
301: .Va on .
1.26 ratchov 302: .It Fl x Ar policy
1.22 ratchov 303: Action when the output stream cannot accept
1.26 ratchov 304: recorded data fast enough or the input stream
305: cannot provide data to play fast enough.
1.22 ratchov 306: If the policy
307: is
1.23 jmc 308: .Dq ignore
1.26 ratchov 309: (the default) then samples that cannot be written are discarded
310: and samples that cannot be read are replaced by silence.
1.22 ratchov 311: If the policy is
1.23 jmc 312: .Dq sync
1.72 jmc 313: then recorded samples are discarded,
314: but the same amount of silence will be written
1.22 ratchov 315: once the stream is unblocked, in order to reach the right position in time.
1.26 ratchov 316: Similarly silence is played, but the same amount of samples will be discarded
317: once the stream is unblocked.
1.22 ratchov 318: If the policy is
1.23 jmc 319: .Dq error
320: then the stream is closed permanently.
1.62 ratchov 321: .Pp
1.71 ratchov 322: If a stream is created with the
1.67 jmc 323: .Fl t
324: option,
1.63 jmc 325: the
1.62 ratchov 326: .Dq ignore
1.63 jmc 327: action is disabled for any stream connected to it
328: to ensure proper synchronization.
1.62 ratchov 329: .It Fl z Ar nframes
1.71 ratchov 330: The audio device block size in frames.
1.63 jmc 331: This is the number of frames between audio clock ticks,
332: i.e. the clock resolution.
1.71 ratchov 333: If a stream is created with the
1.67 jmc 334: .Fl t
335: option,
336: and MTC is used for synchronization, the clock
1.62 ratchov 337: resolution must be 96, 100 or 120 ticks per second for maximum
1.63 jmc 338: accuracy.
339: For instance, 120 ticks per second at 48000Hz corresponds
340: to a 400 frame block size.
1.21 jmc 341: .El
342: .Pp
1.71 ratchov 343: On the command line,
344: per-device parameters
1.87 ratchov 345: .Pq Fl abwz
1.71 ratchov 346: must precede the device definition
1.87 ratchov 347: .Pq Fl fMn ,
1.71 ratchov 348: and per-stream parameters
349: .Pq Fl Ccehjmrtvx
350: must precede the stream definition
351: .Pq Fl ios .
352: MIDI ports
353: .Pq Fl q
1.75 okan 354: and stream definitions
1.71 ratchov 355: .Pq Fl ios
1.87 ratchov 356: must follow the definition of the device
357: .Pq Fl fMn
1.71 ratchov 358: to which they are attached.
359: Global parameters
1.87 ratchov 360: .Pq Fl dl
1.71 ratchov 361: are position-independent.
362: .Pp
363: If no audio devices
1.87 ratchov 364: .Pq Fl fMn
1.71 ratchov 365: are specified,
366: settings are applied as if
1.87 ratchov 367: the default device is specified.
1.71 ratchov 368: If no streams
369: .Pq Fl ios
370: are specified for a device, a default server sub-device is
371: created attached to it, meaning that
372: .Nm
373: behaves as an audio server.
1.87 ratchov 374: If a device
375: .Pq Fl fMn
376: is defined twice, both definitions are merged:
377: parameters of the first one are used but streams
378: .Pq Fl ios
379: and MIDI control ports
380: .Pq Fl q
381: of both definitions are created.
1.71 ratchov 382: The default
383: .Xr sndio 7
384: device is
385: .Pa aucat:0
386: .Pq also known as Pa aucat:0.default
387: .Pp
1.32 ratchov 388: If
389: .Nm
390: is sent
1.44 ratchov 391: .Dv SIGHUP ,
392: .Dv SIGINT
393: or
394: .Dv SIGTERM ,
1.32 ratchov 395: it terminates recording to files.
396: .Pp
1.20 jmc 397: File formats are specified using the
398: .Fl h
1.26 ratchov 399: option.
1.16 ratchov 400: The following file formats are supported:
1.66 ratchov 401: .Bl -tag -width s32lexxx -offset indent
1.16 ratchov 402: .It raw
403: Headerless file.
1.17 jmc 404: This format is recommended since it has no limitations.
1.16 ratchov 405: .It wav
406: Microsoft WAVE file format.
407: There are limitations inherent to the file format itself:
408: not all encodings are supported,
409: file sizes are limited to 2GB,
1.17 jmc 410: and the file must support the
1.16 ratchov 411: .Xr lseek 2
1.17 jmc 412: operation (e.g. pipes do not support it).
1.16 ratchov 413: .It auto
414: Try to guess, depending on the file name.
1.9 millert 415: .El
416: .Pp
1.20 jmc 417: Encodings are specified using the
418: .Fl e
1.26 ratchov 419: option.
1.16 ratchov 420: The following encodings are supported:
421: .Pp
1.66 ratchov 422: .Bl -tag -width s32lexxx -offset indent -compact
1.16 ratchov 423: .It s8
424: signed 8-bit
425: .It u8
426: unsigned 8-bit
427: .It s16le
428: signed 16-bit, little endian
429: .It u16le
430: unsigned 16-bit, little endian
431: .It s16be
432: signed 16-bit, big endian
433: .It u16be
434: unsigned 16-bit, big endian
435: .It s24le
436: signed 24-bit, stored in 4 bytes, little endian
437: .It u24le
438: unsigned 24-bit, stored in 4 bytes, little endian
439: .It s24be
440: signed 24-bit, stored in 4 bytes, big endian
441: .It u24be
442: unsigned 24-bit, stored in 4 bytes, big endian
443: .It s32le
444: signed 32-bit, little endian
445: .It u32le
446: unsigned 32-bit, little endian
447: .It s32be
448: signed 32-bit, big endian
449: .It u32be
450: unsigned 32-bit, big endian
451: .It s24le3
452: signed 24-bit, packed in 3 bytes, little endian
453: .It u24le3
454: unsigned 24-bit, packed in 3 bytes, big endian
455: .It s24be3
456: signed 24-bit, packed in 3 bytes, little endian
457: .It u24be3
458: unsigned 24-bit, packed in 3 bytes, big endian
459: .It s20le3
460: signed 20-bit, packed in 3 bytes, little endian
461: .It u20le3
462: unsigned 20-bit, packed in 3 bytes, big endian
463: .It s20be3
464: signed 20-bit, packed in 3 bytes, little endian
465: .It u20be3
466: unsigned 20-bit, packed in 3 bytes, big endian
467: .It s18le3
468: signed 18-bit, packed in 3 bytes, little endian
469: .It u18le3
470: unsigned 18-bit, packed in 3 bytes, big endian
471: .It s18be3
472: signed 18-bit, packed in 3 bytes, little endian
473: .It u18be3
474: unsigned 18-bit, packed in 3 bytes, big endian
475: .El
1.46 ratchov 476: .Sh SERVER MODE
1.71 ratchov 477: If at least one sub-device
478: .Pq Fl s
479: is exposed by
480: .Nm ,
481: including the case when no stream options are given,
482: then
1.46 ratchov 483: .Nm
1.71 ratchov 484: can be used as a server
1.46 ratchov 485: to overcome hardware limitations and allow applications
486: to run on fixed sample rate devices or on devices
487: supporting only unusual encodings.
1.69 ratchov 488: .Pp
1.46 ratchov 489: Certain applications, such as synthesis software,
490: require a low latency audio setup.
1.71 ratchov 491: To reduce the probability of buffer underruns or overruns, especially
492: on busy machines, the server can be started by the super-user, in which
493: case it will run with higher priority.
1.72 jmc 494: Any user will still be able to connect to it,
495: but for privacy reasons only one user may have
1.71 ratchov 496: connections to it at a given time.
1.55 ratchov 497: .Sh MIDI CONTROL
498: .Nm
1.71 ratchov 499: can expose the audio device clock on registered
500: MIDI ports
501: .Pq Fl q
502: and allows audio device properties to be controlled
503: through MIDI.
504: If running in server mode
1.62 ratchov 505: .Nm
1.71 ratchov 506: creates a MIDI port with the same name as the default audio
507: device to which MIDI programs can connect.
1.62 ratchov 508: .Pp
1.56 jmc 509: A MIDI channel is assigned to each stream, and the volume
1.55 ratchov 510: is changed using the standard volume controller (number 7).
1.71 ratchov 511: Similarly, when the audio client changes its volume,
1.55 ratchov 512: the same MIDI controller message is sent out; it can be used
1.56 jmc 513: for instance for monitoring or as feedback for motorized
1.55 ratchov 514: faders.
1.62 ratchov 515: .Pp
1.71 ratchov 516: Streams created with the
1.63 jmc 517: .Fl t
1.67 jmc 518: option are controlled by the following MMC messages:
1.66 ratchov 519: .Bl -tag -width relocateXXX -offset indent
1.62 ratchov 520: .It relocate
1.79 jmc 521: Streams are relocated to the requested time position
1.71 ratchov 522: relative to the beginning of the stream, at which playback
1.62 ratchov 523: and recording must start.
1.71 ratchov 524: If the requested position is beyond the end of file,
1.79 jmc 525: the stream is temporarly disabled until a valid position is requested.
1.71 ratchov 526: This message is ignored by client streams (server mode).
527: The given time position is sent to MIDI ports as an MTC
1.62 ratchov 528: .Dq "full frame"
529: message forcing all MTC-slaves to relocate to the given
530: position (see below).
531: .It start
1.71 ratchov 532: Put all streams in starting mode.
533: In this mode,
534: .Nm
535: waits for all streams to become ready
1.62 ratchov 536: to start, and then starts them synchronously.
1.72 jmc 537: Once started, new streams can be created (server mode)
538: but they will be blocked
1.62 ratchov 539: until the next stop-to-start transition.
1.67 jmc 540: .It stop
1.71 ratchov 541: Put all streams in stopped mode (the default).
1.67 jmc 542: In this mode, any stream attempting to start playback or recording
543: is paused.
1.71 ratchov 544: Files are stopped and rewound back to the starting position,
545: while client streams (server mode) that are already
546: started are not affected until they stop and try to start again.
1.62 ratchov 547: .El
548: .Pp
1.71 ratchov 549: Streams created with the
1.63 jmc 550: .Fl t
1.67 jmc 551: option export the server clock using MTC, allowing non-audio
1.62 ratchov 552: software or hardware to be synchronized to the audio stream.
1.84 ratchov 553: Maximum accuracy is achieved when the number of blocks per
554: second is equal to one of the standard MTC clock rates (96, 100 and 120Hz).
1.62 ratchov 555: The following sample rates
556: .Pq Fl r
557: and block sizes
558: .Pq Fl z
1.84 ratchov 559: are recommended:
1.62 ratchov 560: .Pp
1.66 ratchov 561: .Bl -bullet -offset indent -compact
1.62 ratchov 562: .It
1.84 ratchov 563: 44100Hz, 441 frames (MTC rate is 100Hz)
1.62 ratchov 564: .It
1.84 ratchov 565: 48000Hz, 400 frames (MTC rate is 120Hz)
1.62 ratchov 566: .It
1.84 ratchov 567: 48000Hz, 480 frames (MTC rate is 100Hz)
1.62 ratchov 568: .It
1.84 ratchov 569: 48000Hz, 500 frames (MTC rate is 96Hz)
1.62 ratchov 570: .El
571: .Pp
572: For instance, the following command will create two devices:
573: the default
574: .Va aucat:0
1.63 jmc 575: and a MIDI-controlled
576: .Va aucat:0.mmc :
1.62 ratchov 577: .Bd -literal -offset indent
578: $ aucat -l -r 48000 -z 400 -s default -t slave -s mmc
579: .Ed
580: .Pp
581: Streams connected to
582: .Va aucat:0
583: behave normally, while streams connected to
584: .Va aucat:0.mmc
585: wait for the MMC start signal and start synchronously.
1.63 jmc 586: Regardless of which device a stream is connected to,
587: its playback volume knob is exposed.
1.66 ratchov 588: .Pp
589: For instance, the following command will play a file on the
590: .Va aucat:0.mmc
591: audio device, and give full control to MIDI software or hardware
592: connected to the
1.89 ! ratchov 593: .Va aucat:0.thru
! 594: MIDI port:
1.66 ratchov 595: .Bd -literal -offset indent
1.89 ! ratchov 596: $ aucat -f aucat:0.mmc -t slave -q aucat:0.thru -i file.wav
1.66 ratchov 597: .Ed
598: .Pp
599: At this stage,
600: .Nm
601: will start, stop and relocate automatically following all user
602: actions in the MIDI sequencer.
603: Note that the sequencer must use
604: .Va aucat:0
605: as the MTC source, i.e. the audio server, not the audio player.
1.9 millert 606: .Sh ENVIRONMENT
1.76 ratchov 607: .Bl -tag -width "AUCAT_COOKIE" -compact
608: .It Ev AUCAT_COOKIE
1.77 jmc 609: File containing user's session cookie.
1.24 jmc 610: .It Ev AUDIODEVICE
1.57 ratchov 611: .Xr sndio 7
612: audio device to use if the
1.50 ratchov 613: .Fl f
614: option is not specified.
1.9 millert 615: .El
1.16 ratchov 616: .Sh EXAMPLES
1.77 jmc 617: Mix and play two stereo streams,
1.16 ratchov 618: the first at 48kHz and the second at 44.1kHz:
619: .Bd -literal -offset indent
620: $ aucat -r 48000 -i file1.raw -r 44100 -i file2.raw
621: .Ed
622: .Pp
1.77 jmc 623: Record channels 2 and 3 into one stereo file and
1.16 ratchov 624: channels 6 and 7 into another stereo file using a 96kHz sampling rate for
625: both:
626: .Bd -literal -offset indent
1.83 ratchov 627: $ aucat -j off -r 96000 -C 2:3 -o file1.raw -C 6:7 -o file2.raw
1.42 ratchov 628: .Ed
629: .Pp
1.77 jmc 630: Split a stereo file into two mono files:
1.42 ratchov 631: .Bd -literal -offset indent
1.88 jmc 632: $ aucat -n -j off -i stereo.wav -C 0:0 -o left.wav -C 1:1 \e
633: -o right.wav
1.16 ratchov 634: .Ed
635: .Pp
1.77 jmc 636: Start
1.35 ratchov 637: .Nm
1.77 jmc 638: in server mode using default parameters, creating an
1.57 ratchov 639: additional sub-device for output to channels 2:3 only (rear speakers
640: on most cards), exposing the
641: .Pa aucat:0
642: and
643: .Pa aucat:0.rear
644: devices:
1.35 ratchov 645: .Bd -literal -offset indent
1.45 ratchov 646: $ aucat -l -s default -c 2:3 -s rear
1.35 ratchov 647: .Ed
648: .Pp
1.77 jmc 649: Start
1.35 ratchov 650: .Nm
1.77 jmc 651: in server mode, creating the default sub-device with low volume and
1.57 ratchov 652: an additional sub-device for high volume output, exposing the
653: .Pa aucat:0
654: and
655: .Pa aucat:0.max
656: devices:
1.35 ratchov 657: .Bd -literal -offset indent
1.45 ratchov 658: $ aucat -l -v 65 -s default -v 127 -s max
1.16 ratchov 659: .Ed
1.71 ratchov 660: .Pp
1.77 jmc 661: Start
1.71 ratchov 662: .Nm
1.77 jmc 663: in server mode, configuring the audio device to use
1.72 jmc 664: a 48kHz sample frequency, 240-frame block size,
665: and 2-block buffers.
1.71 ratchov 666: The corresponding latency is 10ms, which is
667: the time it takes the sound to propagate 3.5 meters.
668: .Bd -literal -offset indent
669: $ aucat -l -r 48000 -b 480 -z 240
670: .Ed
1.2 kstailey 671: .Sh SEE ALSO
1.12 jmc 672: .Xr audioctl 1 ,
1.17 jmc 673: .Xr cdio 1 ,
1.9 millert 674: .Xr mixerctl 1 ,
1.54 ratchov 675: .Xr audio 4 ,
676: .Xr sndio 7
1.16 ratchov 677: .Sh BUGS
678: The
1.1 kstailey 679: .Nm
1.16 ratchov 680: utility assumes non-blocking I/O for input and output streams.
681: It will not work reliably on files that may block
682: (ordinary files block, pipes don't).
1.71 ratchov 683: To avoid audio underruns/overruns or MIDI jitter caused by file I/O,
684: it's recommended to use two
685: .Nm
686: processes: a server handling audio and MIDI I/O and a client handling
687: disk I/O.
1.16 ratchov 688: .Pp
689: Resampling is low quality; down-sampling especially should be avoided
690: when recording.
691: .Pp
692: Processing is done using 16-bit arithmetic,
693: thus samples with more than 16 bits are rounded.
1.17 jmc 694: 16 bits (i.e. 97dB dynamic) are largely enough for most applications though.
1.71 ratchov 695: .Pp
696: If
697: .Fl a Ar off
1.72 jmc 698: is used in server mode,
1.71 ratchov 699: .Nm
1.72 jmc 700: creates sub-devices to expose first
701: and then opens the audio hardware on demand.
1.71 ratchov 702: Technically, this allows
703: .Nm
1.75 okan 704: to attempt to use one of the sub-devices it exposes as an audio device,
1.71 ratchov 705: creating a deadlock.
706: To avoid this,
707: .Fl a Ar off
708: is disabled for the default audio device, but nothing prevents the user
709: from shooting himself in the foot by creating a similar deadlock.
1.87 ratchov 710: .Pp
711: The ability to merge multiple inputs is provided to allow multiple
712: applications producing MIDI data to keep their connection open while
713: idling; it does not replace a fully featured MIDI merger.
![[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