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