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