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