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