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