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