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