Annotation of src/usr.bin/aucat/aucat.1, Revision 1.17
1.17 ! jmc 1: .\" $OpenBSD: aucat.1,v 1.16 2008/05/23 07:15:46 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.17 ! jmc 17: .Dd $Mdocdate: May 23 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
26: .Op Fl u
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.17 ! jmc 64: Encoding of the output stream.
! 65: The default is signed, 16-bit, native byte order.
1.16 ratchov 66: .It Fl e Ar enc
1.17 ! jmc 67: Encoding of the input stream.
! 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.
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
112: Don't try to automatically determine the optimal parameters for the
113: audio device;
114: instead use the parameters specified by the last
1.17 ! jmc 115: .Fl C ,
! 116: .Fl c ,
1.16 ratchov 117: .Fl E ,
1.17 ! jmc 118: .Fl e ,
! 119: .Fl H ,
! 120: .Fl h ,
1.16 ratchov 121: .Fl R ,
122: and
123: .Fl r
124: options.
1.17 ! jmc 125: For the
1.16 ratchov 126: .Fl i
127: and
128: .Fl o
1.17 ! jmc 129: options, if
1.16 ratchov 130: .Fl f
1.17 ! jmc 131: is used then parameters must be specified before it.
1.16 ratchov 132: .El
1.14 jmc 133: .Pp
1.16 ratchov 134: The following file formats are supported:
135: .Bl -tag -width s32lexxx -offset -indent
136: .It raw
137: Headerless file.
1.17 ! jmc 138: This format is recommended since it has no limitations.
1.16 ratchov 139: .It wav
140: Microsoft WAVE file format.
141: There are limitations inherent to the file format itself:
142: not all encodings are supported,
143: file sizes are limited to 2GB,
1.17 ! jmc 144: and the file must support the
1.16 ratchov 145: .Xr lseek 2
1.17 ! jmc 146: operation (e.g. pipes do not support it).
1.16 ratchov 147: .It auto
148: Try to guess, depending on the file name.
1.9 millert 149: .El
150: .Pp
1.16 ratchov 151: The following encodings are supported:
152: .Pp
153: .Bl -tag -width s32lexxx -offset -indent -compact
154: .It s8
155: signed 8-bit
156: .It u8
157: unsigned 8-bit
158: .It s16le
159: signed 16-bit, little endian
160: .It u16le
161: unsigned 16-bit, little endian
162: .It s16be
163: signed 16-bit, big endian
164: .It u16be
165: unsigned 16-bit, big endian
166: .It s24le
167: signed 24-bit, stored in 4 bytes, little endian
168: .It u24le
169: unsigned 24-bit, stored in 4 bytes, little endian
170: .It s24be
171: signed 24-bit, stored in 4 bytes, big endian
172: .It u24be
173: unsigned 24-bit, stored in 4 bytes, big endian
174: .It s32le
175: signed 32-bit, little endian
176: .It u32le
177: unsigned 32-bit, little endian
178: .It s32be
179: signed 32-bit, big endian
180: .It u32be
181: unsigned 32-bit, big endian
182: .It s24le3
183: signed 24-bit, packed in 3 bytes, little endian
184: .It u24le3
185: unsigned 24-bit, packed in 3 bytes, big endian
186: .It s24be3
187: signed 24-bit, packed in 3 bytes, little endian
188: .It u24be3
189: unsigned 24-bit, packed in 3 bytes, big endian
190: .It s20le3
191: signed 20-bit, packed in 3 bytes, little endian
192: .It u20le3
193: unsigned 20-bit, packed in 3 bytes, big endian
194: .It s20be3
195: signed 20-bit, packed in 3 bytes, little endian
196: .It u20be3
197: unsigned 20-bit, packed in 3 bytes, big endian
198: .It s18le3
199: signed 18-bit, packed in 3 bytes, little endian
200: .It u18le3
201: unsigned 18-bit, packed in 3 bytes, big endian
202: .It s18be3
203: signed 18-bit, packed in 3 bytes, little endian
204: .It u18be3
205: unsigned 18-bit, packed in 3 bytes, big endian
206: .El
207: .Sh LEGACY MODE
208: If neither
209: .Fl i
210: nor
211: .Fl o
1.17 ! jmc 212: are specified,
1.16 ratchov 213: .Nm
1.17 ! jmc 214: will run in legacy mode, and won't convert sample formats or sampling rates.
1.16 ratchov 215: In legacy mode, all options except
1.17 ! jmc 216: .Fl f
! 217: are ignored, and all other arguments are assumed to be names of files.
1.16 ratchov 218: In legacy mode
219: .Nm
220: reads files sequentially, and writes them to the specified device.
221: If a Sun .au header is detected it is skipped over and not copied to
222: the audio device.
223: .Nm
224: will attempt to play data from Sun .au files as monaural 8-bit ulaw
225: samples with a sampling frequency of 8000 Hz.
226: However,
227: .Nm
228: will not fail if the audio device cannot be configured for these
229: parameters.
230: If a Microsoft .wav header (RIFF) is detected it is interpreted
231: to select the right audio encoding for playback and the data chunk of the
232: file is copied to the audio device.
233: If the device does not support the encoding,
234: .Nm
235: will exit with an error.
1.9 millert 236: .Sh ENVIRONMENT
237: .Bl -tag -width AUDIODEVICE
238: .It Ev AUDIODEVICE
239: The audio device to use.
240: .El
1.16 ratchov 241: .Sh EXAMPLES
242: The following command will record a stereo s16le stream at
243: 44100Hz from the default device.
1.17 ! jmc 244: If necessary, the stream will be converted and/or resampled
1.16 ratchov 245: to match parameters supported by the device:
246: .Bd -literal -offset indent
247: $ aucat -o file.raw
248: .Ed
249: .Pp
250: The following command will play a stereo s16le stream at
251: 44100Hz on the default device, doing any necessary conversions:
252: .Bd -literal -offset indent
253: $ aucat -i file.raw
254: .Ed
255: .Pp
256: The following will mix and play two stereo streams,
257: the first at 48kHz and the second at 44.1kHz:
258: .Bd -literal -offset indent
259: $ aucat -r 48000 -i file1.raw -r 44100 -i file2.raw
260: .Ed
261: .Pp
262: The following will record channels 2 and 3 into one stereo file and
263: channels 6 and 7 into another stereo file using a 96kHz sampling rate for
264: both:
265: .Bd -literal -offset indent
266: $ aucat -R 96000 -C 2:3 -o file1.raw -C 6:7 -o file2.raw
267: .Ed
268: .Pp
269: The following will play two s18le mono files, one on each channel:
270: .Bd -literal -offset indent
271: $ aucat -e s18le -c 0:0 -i f1.raw -c 1:1 -i f2.raw
272: .Ed
273: .Pp
274: The following will mix and play two files and record a third one in
275: full-duplex:
276: .Bd -literal -offset indent
277: $ aucat -i drums.raw -i bass.raw -o guitar.raw
278: .Ed
1.2 kstailey 279: .Sh SEE ALSO
1.12 jmc 280: .Xr audioctl 1 ,
1.17 ! jmc 281: .Xr cdio 1 ,
1.9 millert 282: .Xr mixerctl 1 ,
1.2 kstailey 283: .Xr audio 4
1.16 ratchov 284: .Sh BUGS
285: The
1.1 kstailey 286: .Nm
1.16 ratchov 287: utility assumes non-blocking I/O for input and output streams.
288: It will not work reliably on files that may block
289: (ordinary files block, pipes don't).
290: .Pp
291: Resampling is low quality; down-sampling especially should be avoided
292: when recording.
293: .Pp
294: CPU usage is the same for all conversions.
295: It should be smaller for simpler ones.
296: .Pp
297: Buffer overruns and underruns are not handled.
298: .Pp
299: Processing is done using 16-bit arithmetic,
300: thus samples with more than 16 bits are rounded.
1.17 ! jmc 301: 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