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