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