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