Annotation of src/usr.bin/aucat/aucat.1, Revision 1.59
1.59 ! ratchov 1: .\" $OpenBSD: aucat.1,v 1.58 2009/09/27 11:51:20 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.59 ! ratchov 17: .Dd $Mdocdate: September 27 2009 $
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.49 jmc 27: .Op Fl b Ar nframes
1.16 ratchov 28: .Op Fl C Ar min : Ns Ar max
29: .Op Fl c Ar min : Ns Ar max
30: .Op Fl e Ar enc
1.9 millert 31: .Op Fl f Ar device
1.16 ratchov 32: .Op Fl h Ar fmt
33: .Op Fl i Ar file
1.37 ratchov 34: .Op Fl m Ar mode
1.16 ratchov 35: .Op Fl o Ar file
36: .Op Fl r Ar rate
1.57 ratchov 37: .Op Fl s Ar name
1.54 ratchov 38: .Op Fl U Ar unit
1.30 ratchov 39: .Op Fl v Ar volume
1.22 ratchov 40: .Op Fl x Ar policy
1.16 ratchov 41: .Ek
1.1 kstailey 42: .Sh DESCRIPTION
43: The
1.7 aaron 44: .Nm
1.16 ratchov 45: utility can record one input stream
46: and store it on multiple destination files,
47: doing the necessary conversions on the fly.
1.48 ratchov 48: It can play, convert, and mix multiple input files simultaneously,
49: and can also act as an audio server.
1.9 millert 50: .Nm
1.16 ratchov 51: also has a legacy mode that works like previous versions of
52: .Nm ,
53: which does not convert on the fly and supports playback of .au files.
1.17 jmc 54: .Pp
1.16 ratchov 55: The options are as follows:
1.26 ratchov 56: .Bl -tag -width Ds
1.49 jmc 57: .It Fl b Ar nframes
1.26 ratchov 58: The buffer size in frames.
1.49 jmc 59: A frame consists of one sample for each channel in the stream.
60: This is the number of frames that will be buffered before being played
61: and thus controls the playback latency.
1.25 jmc 62: .It Xo
63: .Fl C Ar min : Ns Ar max ,
64: .Fl c Ar min : Ns Ar max
65: .Xc
1.26 ratchov 66: The range of channel numbers on the record or playback stream, respectively.
1.17 jmc 67: The default is 0:1, i.e. stereo.
1.59 ! ratchov 68: .It Fl d
! 69: Do not daemonize.
! 70: If this option is specified,
! 71: .Nm
! 72: will run in the foreground and log to
! 73: .Em stderr .
1.26 ratchov 74: .It Fl e Ar enc
75: Encoding of the playback or recording stream (see below).
1.17 jmc 76: The default is signed, 16-bit, native byte order.
77: .It Fl f Ar device
78: The
1.57 ratchov 79: .Xr sndio 7
80: audio device to use for playing and/or recording.
1.26 ratchov 81: .It Fl h Ar fmt
82: File format of the playback or record stream (see below).
1.17 jmc 83: The default is auto.
1.16 ratchov 84: .It Fl i Ar file
85: Add this file to the list of files to play.
86: If the option argument is
87: .Sq -
88: then standard input will be used.
1.26 ratchov 89: .It Fl l
1.57 ratchov 90: Listen for incoming connections on a Unix domain socket.
1.39 jmc 91: This allows clients to use
1.26 ratchov 92: .Nm
1.57 ratchov 93: instead of the physical audio device for audio input and output
1.26 ratchov 94: in order to share the physical device with other clients.
1.57 ratchov 95: The default
96: .Xr sndio 7
97: device exposed is
98: .Pa aucat:0
99: .Pq "also known as" Pa aucat:0.default
1.45 ratchov 100: but other names can be used with the
1.35 ratchov 101: .Fl s
102: option.
1.37 ratchov 103: .It Fl m Ar mode
104: Set the server mode.
105: Valid modes are
1.39 jmc 106: .Ar play ,
107: .Ar rec ,
1.37 ratchov 108: and
1.39 jmc 109: .Ar duplex ,
110: for play-only, record-only, and full-duplex, respectively.
1.37 ratchov 111: The default is
1.39 jmc 112: .Ar duplex .
1.42 ratchov 113: .It Fl n
114: Loopback mode.
115: Instead of using an audio device, send input streams
116: to the output, processing them on the fly.
117: This mode is useful to mix, demultiplex, resample or reencode
1.43 jmc 118: audio files offline.
1.16 ratchov 119: .It Fl o Ar file
120: Add this file to the list of files in which to store recorded samples.
121: If the option argument is
122: .Sq -
123: then standard output will be used.
1.26 ratchov 124: .It Fl r Ar rate
125: Sample rate in Hertz of the playback or record stream.
1.17 jmc 126: The default is 44100Hz.
1.57 ratchov 127: .It Fl s Ar name
128: Add
129: .Ar name
130: to the list of sub-devices to expose in server mode.
131: Defining multiple sub-devices allows splitting a physical audio device
132: into logical devices having different properties (eg. channel ranges).
133: The given
134: .Ar name
135: correponds to the
136: .Dq option
137: part of the
138: .Xr sndio 7
139: device name string.
1.54 ratchov 140: .It Fl U Ar unit
141: Unit number to use when running in server mode.
142: Each
143: .Nm
144: server instance has an unique unit number,
145: used in
146: .Xr sndio 7
147: device names.
148: The default is 0.
1.16 ratchov 149: .It Fl u
1.21 jmc 150: Normally
151: .Nm
152: tries to automatically determine the optimal parameters for the audio device;
153: if this option is specified,
154: it will instead use the parameters specified by the
1.26 ratchov 155: .Fl Ccer
1.21 jmc 156: options.
1.30 ratchov 157: .It Fl v Ar volume
158: Software volume attenuation of the playback stream.
159: The value must be between 1 and 127,
1.31 jmc 160: corresponding to \-42dB and \-0dB attenuation.
1.33 ratchov 161: In server mode, clients inherit this parameter.
1.34 jmc 162: Reducing the volume in advance reduces a client's dynamic range,
163: but allows client volume to stay independent from the number
1.33 ratchov 164: of clients as long as their number is small enough.
1.34 jmc 165: A good compromise is to use \-4dB attenuation (12 volume units)
166: for each additional client expected
167: (115 if 2 clients are expected, 103 for 3 clients, and so on).
1.26 ratchov 168: .It Fl x Ar policy
1.22 ratchov 169: Action when the output stream cannot accept
1.26 ratchov 170: recorded data fast enough or the input stream
171: cannot provide data to play fast enough.
1.22 ratchov 172: If the policy
173: is
1.23 jmc 174: .Dq ignore
1.26 ratchov 175: (the default) then samples that cannot be written are discarded
176: and samples that cannot be read are replaced by silence.
1.22 ratchov 177: If the policy is
1.23 jmc 178: .Dq sync
1.26 ratchov 179: then recorded samples are discarded, but the same amount of silence will be written
1.22 ratchov 180: once the stream is unblocked, in order to reach the right position in time.
1.26 ratchov 181: Similarly silence is played, but the same amount of samples will be discarded
182: once the stream is unblocked.
1.22 ratchov 183: If the policy is
1.23 jmc 184: .Dq error
185: then the stream is closed permanently.
1.21 jmc 186: .El
187: .Pp
1.32 ratchov 188: If
189: .Nm
190: is sent
1.44 ratchov 191: .Dv SIGHUP ,
192: .Dv SIGINT
193: or
194: .Dv SIGTERM ,
1.32 ratchov 195: it terminates recording to files.
196: .Pp
1.35 ratchov 197: Settings for input files
198: .Pq Fl i ,
199: output files
1.39 jmc 200: .Pq Fl o ,
1.57 ratchov 201: and sub-devices
1.35 ratchov 202: .Pq Fl s
203: can be changed using the
204: .Fl Ccehrvx
1.16 ratchov 205: options.
1.21 jmc 206: The last
1.35 ratchov 207: .Fl Ccehrvx
1.23 jmc 208: options specified before an
1.35 ratchov 209: .Fl i ,
1.39 jmc 210: .Fl o ,
211: or
1.35 ratchov 212: .Fl s
1.41 jmc 213: are applied to the corresponding file.
1.21 jmc 214: .Pp
215: Settings for the audio device
216: can be changed using the
1.26 ratchov 217: .Fl Ccer
1.21 jmc 218: options.
219: They apply to the audio device only if the
220: .Fl u
221: option is given as well.
222: The last
1.26 ratchov 223: .Fl Ccer
1.21 jmc 224: option specified before an
1.16 ratchov 225: .Fl f
1.21 jmc 226: is applied to
227: .Ar device .
228: .Pp
229: If no audio device
230: .Pq Fl f
1.53 ratchov 231: is specified,
232: settings are applied as if
233: the default device is specified as the last argument.
1.57 ratchov 234: If no sub-devices
1.53 ratchov 235: .Pq Fl s
236: are specified
237: settings are applied as if
1.57 ratchov 238: .Ar default
239: is specified as the last argument.
1.14 jmc 240: .Pp
1.20 jmc 241: File formats are specified using the
242: .Fl h
1.26 ratchov 243: option.
1.16 ratchov 244: The following file formats are supported:
245: .Bl -tag -width s32lexxx -offset -indent
246: .It raw
247: Headerless file.
1.17 jmc 248: This format is recommended since it has no limitations.
1.16 ratchov 249: .It wav
250: Microsoft WAVE file format.
251: There are limitations inherent to the file format itself:
252: not all encodings are supported,
253: file sizes are limited to 2GB,
1.17 jmc 254: and the file must support the
1.16 ratchov 255: .Xr lseek 2
1.17 jmc 256: operation (e.g. pipes do not support it).
1.16 ratchov 257: .It auto
258: Try to guess, depending on the file name.
1.9 millert 259: .El
260: .Pp
1.20 jmc 261: Encodings are specified using the
262: .Fl e
1.26 ratchov 263: option.
1.16 ratchov 264: The following encodings are supported:
265: .Pp
266: .Bl -tag -width s32lexxx -offset -indent -compact
267: .It s8
268: signed 8-bit
269: .It u8
270: unsigned 8-bit
271: .It s16le
272: signed 16-bit, little endian
273: .It u16le
274: unsigned 16-bit, little endian
275: .It s16be
276: signed 16-bit, big endian
277: .It u16be
278: unsigned 16-bit, big endian
279: .It s24le
280: signed 24-bit, stored in 4 bytes, little endian
281: .It u24le
282: unsigned 24-bit, stored in 4 bytes, little endian
283: .It s24be
284: signed 24-bit, stored in 4 bytes, big endian
285: .It u24be
286: unsigned 24-bit, stored in 4 bytes, big endian
287: .It s32le
288: signed 32-bit, little endian
289: .It u32le
290: unsigned 32-bit, little endian
291: .It s32be
292: signed 32-bit, big endian
293: .It u32be
294: unsigned 32-bit, big endian
295: .It s24le3
296: signed 24-bit, packed in 3 bytes, little endian
297: .It u24le3
298: unsigned 24-bit, packed in 3 bytes, big endian
299: .It s24be3
300: signed 24-bit, packed in 3 bytes, little endian
301: .It u24be3
302: unsigned 24-bit, packed in 3 bytes, big endian
303: .It s20le3
304: signed 20-bit, packed in 3 bytes, little endian
305: .It u20le3
306: unsigned 20-bit, packed in 3 bytes, big endian
307: .It s20be3
308: signed 20-bit, packed in 3 bytes, little endian
309: .It u20be3
310: unsigned 20-bit, packed in 3 bytes, big endian
311: .It s18le3
312: signed 18-bit, packed in 3 bytes, little endian
313: .It u18le3
314: unsigned 18-bit, packed in 3 bytes, big endian
315: .It s18be3
316: signed 18-bit, packed in 3 bytes, little endian
317: .It u18be3
318: unsigned 18-bit, packed in 3 bytes, big endian
319: .El
1.46 ratchov 320: .Sh SERVER MODE
321: .Nm
322: can be used in server mode
323: .Pq Fl l
324: to overcome hardware limitations and allow applications
325: to run on fixed sample rate devices or on devices
326: supporting only unusual encodings.
327: It is generally not desirable to have multiple
328: instances of
329: .Nm
330: running in server mode,
331: so it is good practice to start it thus:
332: .Bd -literal -offset indent
333: $ pgrep -x aucat || aucat -l
334: .Ed
335: .Pp
336: This also ensures privacy by preventing
337: other users from accessing the audio system.
338: On multi-user machines
339: .Nm
340: should be killed when no longer in use to make audio resources
341: available again to others:
342: .Bd -literal -offset indent
343: $ pkill -x aucat
344: .Ed
345: .Pp
346: Certain applications, such as synthesis software,
347: require a low latency audio setup.
348: To reduce the probability of buffer underruns or overruns,
349: the
350: .Xr renice 8
1.49 jmc 351: command can be used to give a higher priority to the
1.46 ratchov 352: .Nm
1.49 jmc 353: process.
1.46 ratchov 354: Superuser privileges are required.
355: For example:
356: .Bd -literal -offset indent
357: $ aucat -b 3500 -l
358: $ sudo renice -n -20 -p `pgrep -x aucat`
359: .Ed
1.55 ratchov 360: .Sh MIDI CONTROL
361: While running in server mode
362: .Pq Fl l
363: .Nm
364: exposes a MIDI device with the same name as the default audio
365: device.
366: It allows MIDI hardware or software to be used to control
367: the volume of played streams.
1.56 jmc 368: A MIDI channel is assigned to each stream, and the volume
1.55 ratchov 369: is changed using the standard volume controller (number 7).
370: Similarly, when the audio application changes its volume,
371: the same MIDI controller message is sent out; it can be used
1.56 jmc 372: for instance for monitoring or as feedback for motorized
1.55 ratchov 373: faders.
1.16 ratchov 374: .Sh LEGACY MODE
375: If neither
376: .Fl i
377: nor
378: .Fl o
1.17 jmc 379: are specified,
1.16 ratchov 380: .Nm
1.17 jmc 381: will run in legacy mode, and won't convert sample formats or sampling rates.
1.16 ratchov 382: In legacy mode, all options except
1.17 jmc 383: .Fl f
384: are ignored, and all other arguments are assumed to be names of files.
1.16 ratchov 385: In legacy mode
386: .Nm
387: reads files sequentially, and writes them to the specified device.
388: If a Sun .au header is detected it is skipped over and not copied to
389: the audio device.
390: .Nm
1.52 jakemsr 391: will attempt to parse the format, number of channels and sample rate
392: from Sun .au file headers.
393: However, only alaw and ulaw formats are supported for .au files.
394: Other formats will be interpreted as ulaw.
1.16 ratchov 395: If a Microsoft .wav header (RIFF) is detected it is interpreted
396: to select the right audio encoding for playback and the data chunk of the
397: file is copied to the audio device.
398: If the device does not support the encoding,
399: .Nm
400: will exit with an error.
1.9 millert 401: .Sh ENVIRONMENT
1.35 ratchov 402: .Bl -tag -width "AUDIODEVICE" -compact
1.24 jmc 403: .It Ev AUDIODEVICE
1.57 ratchov 404: .Xr sndio 7
405: audio device to use if the
1.50 ratchov 406: .Fl f
407: option is not specified.
1.9 millert 408: .El
1.16 ratchov 409: .Sh EXAMPLES
410: The following will mix and play two stereo streams,
411: the first at 48kHz and the second at 44.1kHz:
412: .Bd -literal -offset indent
413: $ aucat -r 48000 -i file1.raw -r 44100 -i file2.raw
414: .Ed
415: .Pp
416: The following will record channels 2 and 3 into one stereo file and
417: channels 6 and 7 into another stereo file using a 96kHz sampling rate for
418: both:
419: .Bd -literal -offset indent
1.26 ratchov 420: $ aucat -r 96000 -C 2:3 -o file1.raw -C 6:7 -o file2.raw
1.42 ratchov 421: .Ed
422: .Pp
1.43 jmc 423: The following will split a stereo file into two mono files:
1.42 ratchov 424: .Bd -literal -offset indent
425: $ aucat -n -i stereo.wav -C 0:0 -o left.wav -C 1:1 -o right.wav
1.16 ratchov 426: .Ed
427: .Pp
1.35 ratchov 428: The following will start
429: .Nm
1.40 jmc 430: in server mode using default parameters, but will create an
1.57 ratchov 431: additional sub-device for output to channels 2:3 only (rear speakers
432: on most cards), exposing the
433: .Pa aucat:0
434: and
435: .Pa aucat:0.rear
436: devices:
1.35 ratchov 437: .Bd -literal -offset indent
1.45 ratchov 438: $ aucat -l -s default -c 2:3 -s rear
1.35 ratchov 439: .Ed
440: .Pp
441: The following will start
442: .Nm
1.57 ratchov 443: in server mode creating the default sub-device with low volume and
444: an additional sub-device for high volume output, exposing the
445: .Pa aucat:0
446: and
447: .Pa aucat:0.max
448: devices:
1.35 ratchov 449: .Bd -literal -offset indent
1.45 ratchov 450: $ aucat -l -v 65 -s default -v 127 -s max
1.16 ratchov 451: .Ed
1.2 kstailey 452: .Sh SEE ALSO
1.12 jmc 453: .Xr audioctl 1 ,
1.17 jmc 454: .Xr cdio 1 ,
1.9 millert 455: .Xr mixerctl 1 ,
1.54 ratchov 456: .Xr audio 4 ,
457: .Xr sndio 7
1.16 ratchov 458: .Sh BUGS
459: The
1.1 kstailey 460: .Nm
1.16 ratchov 461: utility assumes non-blocking I/O for input and output streams.
462: It will not work reliably on files that may block
463: (ordinary files block, pipes don't).
464: .Pp
465: Resampling is low quality; down-sampling especially should be avoided
466: when recording.
467: .Pp
468: Processing is done using 16-bit arithmetic,
469: thus samples with more than 16 bits are rounded.
1.17 jmc 470: 16 bits (i.e. 97dB dynamic) are largely enough for most applications though.
![[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