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