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