Annotation of src/usr.bin/aucat/aucat.1, Revision 1.22
1.22 ! ratchov 1: .\" $OpenBSD: aucat.1,v 1.21 2008/05/29 13:53:47 jmc 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.22 ! ratchov 17: .Dd $Mdocdate: May 29 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.19 jmc 26: .Op Fl qu
1.16 ratchov 27: .Op Fl C Ar min : Ns Ar max
28: .Op Fl c Ar min : Ns Ar max
29: .Op Fl E Ar enc
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 h Ar fmt
34: .Op Fl i Ar file
35: .Op Fl o Ar file
36: .Op Fl R Ar rate
37: .Op Fl r Ar rate
1.22 ! ratchov 38: .Op Fl X Ar policy
! 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.17 jmc 47: It can play, convert, and mix multiple input files simultaneously.
1.9 millert 48: .Nm
1.16 ratchov 49: also has a legacy mode that works like previous versions of
50: .Nm ,
51: which does not convert on the fly and supports playback of .au files.
1.17 jmc 52: .Pp
1.16 ratchov 53: The options are as follows:
54: .Bl -tag -width "-m mmmmmmmm "
55: .It Fl C Ar min : Ns Ar max
1.17 jmc 56: The range of channel numbers on the output stream.
57: The default is 0:1, i.e. stereo.
1.16 ratchov 58: .It Fl c Ar min : Ns Ar max
1.17 jmc 59: The range of channel numbers on the input stream.
60: The default is 0:1, i.e. stereo.
1.16 ratchov 61: .It Fl E Ar enc
1.20 jmc 62: Encoding of the output stream (see below).
1.17 jmc 63: The default is signed, 16-bit, native byte order.
1.16 ratchov 64: .It Fl e Ar enc
1.20 jmc 65: Encoding of the input 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.16 ratchov 73: .It Fl H Ar fmt
1.17 jmc 74: File format of the output stream (see below).
75: The default is auto.
1.16 ratchov 76: .It Fl h Ar fmt
1.17 jmc 77: File format of the input stream (see below).
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: The format of the file is specified by the last
1.17 jmc 82: .Fl c ,
1.16 ratchov 83: .Fl e ,
1.17 jmc 84: .Fl h ,
1.16 ratchov 85: and
86: .Fl r
87: options.
88: If the option argument is
89: .Sq -
90: then standard input will be used.
91: .It Fl o Ar file
92: Add this file to the list of files in which to store recorded samples.
93: The format of the file is specified by the last
1.17 jmc 94: .Fl C ,
1.16 ratchov 95: .Fl E ,
1.17 jmc 96: .Fl H ,
1.16 ratchov 97: and
98: .Fl R
99: options.
100: If the option argument is
101: .Sq -
102: then standard output will be used.
1.19 jmc 103: .It Fl q
104: Do not print progress information; run quietly.
1.16 ratchov 105: .It Fl R Ar rate
1.17 jmc 106: Sample rate in Hertz of the output stream.
107: The default is 44100Hz.
1.16 ratchov 108: .It Fl r Ar rate
1.17 jmc 109: Sample rate in Hertz of the input stream.
110: The default is 44100Hz.
1.16 ratchov 111: .It Fl u
1.21 jmc 112: Normally
113: .Nm
114: tries to automatically determine the optimal parameters for the audio device;
115: if this option is specified,
116: it will instead use the parameters specified by the
117: .Fl CcEeRr
118: options.
1.22 ! ratchov 119: .It Fl X Ar policy
! 120: Action when the output stream cannot accept
! 121: recorded data fast enough.
! 122: If the policy
! 123: is
! 124: .Ar ignore
! 125: (the default) then samples that cannot be written are discarded.
! 126: If the policy is
! 127: .Ar sync
! 128: then samples are discarded, but the same amount of silence will be written
! 129: once the stream is unblocked, in order to reach the right position in time.
! 130: If the policy is
! 131: .Ar error
! 132: then the stream is closed permanenty.
! 133: .It Fl x Ar policy
! 134: Action when the input stream cannot provide
! 135: data to play fast enough.
! 136: If the policy is
! 137: .Ar ignore
! 138: (the default) then silence is played.
! 139: If the policy is
! 140: .Ar sync
! 141: then silence is played, but the same amount of samples will be discarded
! 142: once the stream is unblocked, in order to reach the right position in time.
! 143: If the policy is
! 144: .Ar error
! 145: then the stream is closed permanenty.
1.21 jmc 146: .El
147: .Pp
148: Settings for input
149: .Pq Fl i
150: and output
151: .Pq Fl o
152: files can be changed using the
1.22 ! ratchov 153: .Fl CcEeHhRrXx
1.16 ratchov 154: options.
1.21 jmc 155: The last
1.22 ! ratchov 156: .Fl CcEeHhRrXx
1.21 jmc 157: option specified before an
1.16 ratchov 158: .Fl i
1.21 jmc 159: or
1.16 ratchov 160: .Fl o
1.21 jmc 161: is applied to
162: .Ar file .
163: .Pp
164: Settings for the audio device
165: can be changed using the
166: .Fl CcEeRr
167: options.
168: They apply to the audio device only if the
169: .Fl u
170: option is given as well.
171: The last
172: .Fl CcEeRr
173: option specified before an
1.16 ratchov 174: .Fl f
1.21 jmc 175: is applied to
176: .Ar device .
177: .Pp
178: If no audio device
179: .Pq Fl f
180: is specified but
181: .Fl u
182: is given anyway,
183: any
184: .Fl CcEeRr
185: options specified before
186: .Fl io
187: options are applied both to
188: .Ar file
189: and the default audio device;
190: if they are specified after
191: .Fl io
192: options,
193: they will be applied only to the default audio device.
1.14 jmc 194: .Pp
1.20 jmc 195: File formats are specified using the
196: .Fl H
197: and
198: .Fl h
199: options.
1.16 ratchov 200: The following file formats are supported:
201: .Bl -tag -width s32lexxx -offset -indent
202: .It raw
203: Headerless file.
1.17 jmc 204: This format is recommended since it has no limitations.
1.16 ratchov 205: .It wav
206: Microsoft WAVE file format.
207: There are limitations inherent to the file format itself:
208: not all encodings are supported,
209: file sizes are limited to 2GB,
1.17 jmc 210: and the file must support the
1.16 ratchov 211: .Xr lseek 2
1.17 jmc 212: operation (e.g. pipes do not support it).
1.16 ratchov 213: .It auto
214: Try to guess, depending on the file name.
1.9 millert 215: .El
216: .Pp
1.20 jmc 217: Encodings are specified using the
218: .Fl E
219: and
220: .Fl e
221: options.
1.16 ratchov 222: The following encodings are supported:
223: .Pp
224: .Bl -tag -width s32lexxx -offset -indent -compact
225: .It s8
226: signed 8-bit
227: .It u8
228: unsigned 8-bit
229: .It s16le
230: signed 16-bit, little endian
231: .It u16le
232: unsigned 16-bit, little endian
233: .It s16be
234: signed 16-bit, big endian
235: .It u16be
236: unsigned 16-bit, big endian
237: .It s24le
238: signed 24-bit, stored in 4 bytes, little endian
239: .It u24le
240: unsigned 24-bit, stored in 4 bytes, little endian
241: .It s24be
242: signed 24-bit, stored in 4 bytes, big endian
243: .It u24be
244: unsigned 24-bit, stored in 4 bytes, big endian
245: .It s32le
246: signed 32-bit, little endian
247: .It u32le
248: unsigned 32-bit, little endian
249: .It s32be
250: signed 32-bit, big endian
251: .It u32be
252: unsigned 32-bit, big endian
253: .It s24le3
254: signed 24-bit, packed in 3 bytes, little endian
255: .It u24le3
256: unsigned 24-bit, packed in 3 bytes, big endian
257: .It s24be3
258: signed 24-bit, packed in 3 bytes, little endian
259: .It u24be3
260: unsigned 24-bit, packed in 3 bytes, big endian
261: .It s20le3
262: signed 20-bit, packed in 3 bytes, little endian
263: .It u20le3
264: unsigned 20-bit, packed in 3 bytes, big endian
265: .It s20be3
266: signed 20-bit, packed in 3 bytes, little endian
267: .It u20be3
268: unsigned 20-bit, packed in 3 bytes, big endian
269: .It s18le3
270: signed 18-bit, packed in 3 bytes, little endian
271: .It u18le3
272: unsigned 18-bit, packed in 3 bytes, big endian
273: .It s18be3
274: signed 18-bit, packed in 3 bytes, little endian
275: .It u18be3
276: unsigned 18-bit, packed in 3 bytes, big endian
277: .El
278: .Sh LEGACY MODE
279: If neither
280: .Fl i
281: nor
282: .Fl o
1.17 jmc 283: are specified,
1.16 ratchov 284: .Nm
1.17 jmc 285: will run in legacy mode, and won't convert sample formats or sampling rates.
1.16 ratchov 286: In legacy mode, all options except
1.17 jmc 287: .Fl f
288: are ignored, and all other arguments are assumed to be names of files.
1.16 ratchov 289: In legacy mode
290: .Nm
291: reads files sequentially, and writes them to the specified device.
292: If a Sun .au header is detected it is skipped over and not copied to
293: the audio device.
294: .Nm
295: will attempt to play data from Sun .au files as monaural 8-bit ulaw
296: samples with a sampling frequency of 8000 Hz.
297: However,
298: .Nm
299: will not fail if the audio device cannot be configured for these
300: parameters.
301: If a Microsoft .wav header (RIFF) is detected it is interpreted
302: to select the right audio encoding for playback and the data chunk of the
303: file is copied to the audio device.
304: If the device does not support the encoding,
305: .Nm
306: will exit with an error.
1.9 millert 307: .Sh ENVIRONMENT
308: .Bl -tag -width AUDIODEVICE
309: .It Ev AUDIODEVICE
310: The audio device to use.
1.22 ! ratchov 311: .It Ev AUCAT_DEBUG
! 312: The debug level:
! 313: may be a value between 0 and 4.
1.9 millert 314: .El
1.16 ratchov 315: .Sh EXAMPLES
316: The following command will record a stereo s16le stream at
317: 44100Hz from the default device.
1.17 jmc 318: If necessary, the stream will be converted and/or resampled
1.16 ratchov 319: to match parameters supported by the device:
320: .Bd -literal -offset indent
321: $ aucat -o file.raw
322: .Ed
323: .Pp
324: The following command will play a stereo s16le stream at
325: 44100Hz on the default device, doing any necessary conversions:
326: .Bd -literal -offset indent
327: $ aucat -i file.raw
328: .Ed
329: .Pp
330: The following will mix and play two stereo streams,
331: the first at 48kHz and the second at 44.1kHz:
332: .Bd -literal -offset indent
333: $ aucat -r 48000 -i file1.raw -r 44100 -i file2.raw
334: .Ed
335: .Pp
336: The following will record channels 2 and 3 into one stereo file and
337: channels 6 and 7 into another stereo file using a 96kHz sampling rate for
338: both:
339: .Bd -literal -offset indent
340: $ aucat -R 96000 -C 2:3 -o file1.raw -C 6:7 -o file2.raw
341: .Ed
342: .Pp
343: The following will play two s18le mono files, one on each channel:
344: .Bd -literal -offset indent
345: $ aucat -e s18le -c 0:0 -i f1.raw -c 1:1 -i f2.raw
346: .Ed
347: .Pp
348: The following will mix and play two files and record a third one in
349: full-duplex:
350: .Bd -literal -offset indent
351: $ aucat -i drums.raw -i bass.raw -o guitar.raw
352: .Ed
1.2 kstailey 353: .Sh SEE ALSO
1.12 jmc 354: .Xr audioctl 1 ,
1.17 jmc 355: .Xr cdio 1 ,
1.9 millert 356: .Xr mixerctl 1 ,
1.2 kstailey 357: .Xr audio 4
1.16 ratchov 358: .Sh BUGS
359: The
1.1 kstailey 360: .Nm
1.16 ratchov 361: utility assumes non-blocking I/O for input and output streams.
362: It will not work reliably on files that may block
363: (ordinary files block, pipes don't).
364: .Pp
365: Resampling is low quality; down-sampling especially should be avoided
366: when recording.
367: .Pp
368: CPU usage is the same for all conversions.
369: It should be smaller for simpler ones.
370: .Pp
371: Processing is done using 16-bit arithmetic,
372: thus samples with more than 16 bits are rounded.
1.17 jmc 373: 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