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