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