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