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