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