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