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