Annotation of src/usr.bin/aucat/aucat.1, Revision 1.57
1.57 ! ratchov 1: .\" $OpenBSD: aucat.1,v 1.56 2009/08/21 21:25:31 jmc 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.56 jmc 17: .Dd $Mdocdate: August 21 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: If sent
191: .Dv SIGUSR1
192: or
193: .Dv SIGUSR2 ,
194: it increases or decreases debug level, respectively.
195: .Pp
1.35 ratchov 196: Settings for input files
197: .Pq Fl i ,
198: output files
1.39 jmc 199: .Pq Fl o ,
1.57 ! ratchov 200: and sub-devices
1.35 ratchov 201: .Pq Fl s
202: can be changed using the
203: .Fl Ccehrvx
1.16 ratchov 204: options.
1.21 jmc 205: The last
1.35 ratchov 206: .Fl Ccehrvx
1.23 jmc 207: options specified before an
1.35 ratchov 208: .Fl i ,
1.39 jmc 209: .Fl o ,
210: or
1.35 ratchov 211: .Fl s
1.41 jmc 212: are applied to the corresponding file.
1.21 jmc 213: .Pp
214: Settings for the audio device
215: can be changed using the
1.26 ratchov 216: .Fl Ccer
1.21 jmc 217: options.
218: They apply to the audio device only if the
219: .Fl u
220: option is given as well.
221: The last
1.26 ratchov 222: .Fl Ccer
1.21 jmc 223: option specified before an
1.16 ratchov 224: .Fl f
1.21 jmc 225: is applied to
226: .Ar device .
227: .Pp
228: If no audio device
229: .Pq Fl f
1.53 ratchov 230: is specified,
231: settings are applied as if
232: the default device is specified as the last argument.
1.57 ! ratchov 233: If no sub-devices
1.53 ratchov 234: .Pq Fl s
235: are specified
236: settings are applied as if
1.57 ! ratchov 237: .Ar default
! 238: is specified as the last argument.
1.14 jmc 239: .Pp
1.20 jmc 240: File formats are specified using the
241: .Fl h
1.26 ratchov 242: option.
1.16 ratchov 243: The following file formats are supported:
244: .Bl -tag -width s32lexxx -offset -indent
245: .It raw
246: Headerless file.
1.17 jmc 247: This format is recommended since it has no limitations.
1.16 ratchov 248: .It wav
249: Microsoft WAVE file format.
250: There are limitations inherent to the file format itself:
251: not all encodings are supported,
252: file sizes are limited to 2GB,
1.17 jmc 253: and the file must support the
1.16 ratchov 254: .Xr lseek 2
1.17 jmc 255: operation (e.g. pipes do not support it).
1.16 ratchov 256: .It auto
257: Try to guess, depending on the file name.
1.9 millert 258: .El
259: .Pp
1.20 jmc 260: Encodings are specified using the
261: .Fl e
1.26 ratchov 262: option.
1.16 ratchov 263: The following encodings are supported:
264: .Pp
265: .Bl -tag -width s32lexxx -offset -indent -compact
266: .It s8
267: signed 8-bit
268: .It u8
269: unsigned 8-bit
270: .It s16le
271: signed 16-bit, little endian
272: .It u16le
273: unsigned 16-bit, little endian
274: .It s16be
275: signed 16-bit, big endian
276: .It u16be
277: unsigned 16-bit, big endian
278: .It s24le
279: signed 24-bit, stored in 4 bytes, little endian
280: .It u24le
281: unsigned 24-bit, stored in 4 bytes, little endian
282: .It s24be
283: signed 24-bit, stored in 4 bytes, big endian
284: .It u24be
285: unsigned 24-bit, stored in 4 bytes, big endian
286: .It s32le
287: signed 32-bit, little endian
288: .It u32le
289: unsigned 32-bit, little endian
290: .It s32be
291: signed 32-bit, big endian
292: .It u32be
293: unsigned 32-bit, big endian
294: .It s24le3
295: signed 24-bit, packed in 3 bytes, little endian
296: .It u24le3
297: unsigned 24-bit, packed in 3 bytes, big endian
298: .It s24be3
299: signed 24-bit, packed in 3 bytes, little endian
300: .It u24be3
301: unsigned 24-bit, packed in 3 bytes, big endian
302: .It s20le3
303: signed 20-bit, packed in 3 bytes, little endian
304: .It u20le3
305: unsigned 20-bit, packed in 3 bytes, big endian
306: .It s20be3
307: signed 20-bit, packed in 3 bytes, little endian
308: .It u20be3
309: unsigned 20-bit, packed in 3 bytes, big endian
310: .It s18le3
311: signed 18-bit, packed in 3 bytes, little endian
312: .It u18le3
313: unsigned 18-bit, packed in 3 bytes, big endian
314: .It s18be3
315: signed 18-bit, packed in 3 bytes, little endian
316: .It u18be3
317: unsigned 18-bit, packed in 3 bytes, big endian
318: .El
1.46 ratchov 319: .Sh SERVER MODE
320: .Nm
321: can be used in server mode
322: .Pq Fl l
323: to overcome hardware limitations and allow applications
324: to run on fixed sample rate devices or on devices
325: supporting only unusual encodings.
326: It is generally not desirable to have multiple
327: instances of
328: .Nm
329: running in server mode,
330: so it is good practice to start it thus:
331: .Bd -literal -offset indent
332: $ pgrep -x aucat || aucat -l
333: .Ed
334: .Pp
335: This also ensures privacy by preventing
336: other users from accessing the audio system.
337: On multi-user machines
338: .Nm
339: should be killed when no longer in use to make audio resources
340: available again to others:
341: .Bd -literal -offset indent
342: $ pkill -x aucat
343: .Ed
344: .Pp
345: Certain applications, such as synthesis software,
346: require a low latency audio setup.
347: To reduce the probability of buffer underruns or overruns,
348: the
349: .Xr renice 8
1.49 jmc 350: command can be used to give a higher priority to the
1.46 ratchov 351: .Nm
1.49 jmc 352: process.
1.46 ratchov 353: Superuser privileges are required.
354: For example:
355: .Bd -literal -offset indent
356: $ aucat -b 3500 -l
357: $ sudo renice -n -20 -p `pgrep -x aucat`
358: .Ed
1.55 ratchov 359: .Sh MIDI CONTROL
360: While running in server mode
361: .Pq Fl l
362: .Nm
363: exposes a MIDI device with the same name as the default audio
364: device.
365: It allows MIDI hardware or software to be used to control
366: the volume of played streams.
1.56 jmc 367: A MIDI channel is assigned to each stream, and the volume
1.55 ratchov 368: is changed using the standard volume controller (number 7).
369: Similarly, when the audio application changes its volume,
370: the same MIDI controller message is sent out; it can be used
1.56 jmc 371: for instance for monitoring or as feedback for motorized
1.55 ratchov 372: faders.
1.16 ratchov 373: .Sh LEGACY MODE
374: If neither
375: .Fl i
376: nor
377: .Fl o
1.17 jmc 378: are specified,
1.16 ratchov 379: .Nm
1.17 jmc 380: will run in legacy mode, and won't convert sample formats or sampling rates.
1.16 ratchov 381: In legacy mode, all options except
1.17 jmc 382: .Fl f
383: are ignored, and all other arguments are assumed to be names of files.
1.16 ratchov 384: In legacy mode
385: .Nm
386: reads files sequentially, and writes them to the specified device.
387: If a Sun .au header is detected it is skipped over and not copied to
388: the audio device.
389: .Nm
1.52 jakemsr 390: will attempt to parse the format, number of channels and sample rate
391: from Sun .au file headers.
392: However, only alaw and ulaw formats are supported for .au files.
393: Other formats will be interpreted as ulaw.
1.16 ratchov 394: If a Microsoft .wav header (RIFF) is detected it is interpreted
395: to select the right audio encoding for playback and the data chunk of the
396: file is copied to the audio device.
397: If the device does not support the encoding,
398: .Nm
399: will exit with an error.
1.9 millert 400: .Sh ENVIRONMENT
1.35 ratchov 401: .Bl -tag -width "AUDIODEVICE" -compact
1.22 ratchov 402: .It Ev AUCAT_DEBUG
403: The debug level:
404: may be a value between 0 and 4.
1.24 jmc 405: .It Ev AUDIODEVICE
1.57 ! ratchov 406: .Xr sndio 7
! 407: audio device to use if the
1.50 ratchov 408: .Fl f
409: option is not specified.
1.9 millert 410: .El
1.16 ratchov 411: .Sh EXAMPLES
412: The following will mix and play two stereo streams,
413: the first at 48kHz and the second at 44.1kHz:
414: .Bd -literal -offset indent
415: $ aucat -r 48000 -i file1.raw -r 44100 -i file2.raw
416: .Ed
417: .Pp
418: The following will record channels 2 and 3 into one stereo file and
419: channels 6 and 7 into another stereo file using a 96kHz sampling rate for
420: both:
421: .Bd -literal -offset indent
1.26 ratchov 422: $ aucat -r 96000 -C 2:3 -o file1.raw -C 6:7 -o file2.raw
1.42 ratchov 423: .Ed
424: .Pp
1.43 jmc 425: The following will split a stereo file into two mono files:
1.42 ratchov 426: .Bd -literal -offset indent
427: $ aucat -n -i stereo.wav -C 0:0 -o left.wav -C 1:1 -o right.wav
1.16 ratchov 428: .Ed
429: .Pp
1.35 ratchov 430: The following will start
431: .Nm
1.40 jmc 432: in server mode using default parameters, but will create an
1.57 ! ratchov 433: additional sub-device for output to channels 2:3 only (rear speakers
! 434: on most cards), exposing the
! 435: .Pa aucat:0
! 436: and
! 437: .Pa aucat:0.rear
! 438: devices:
1.35 ratchov 439: .Bd -literal -offset indent
1.45 ratchov 440: $ aucat -l -s default -c 2:3 -s rear
1.35 ratchov 441: .Ed
442: .Pp
443: The following will start
444: .Nm
1.57 ! ratchov 445: in server mode creating the default sub-device with low volume and
! 446: an additional sub-device for high volume output, exposing the
! 447: .Pa aucat:0
! 448: and
! 449: .Pa aucat:0.max
! 450: devices:
1.35 ratchov 451: .Bd -literal -offset indent
1.45 ratchov 452: $ aucat -l -v 65 -s default -v 127 -s max
1.16 ratchov 453: .Ed
1.2 kstailey 454: .Sh SEE ALSO
1.12 jmc 455: .Xr audioctl 1 ,
1.17 jmc 456: .Xr cdio 1 ,
1.9 millert 457: .Xr mixerctl 1 ,
1.54 ratchov 458: .Xr audio 4 ,
459: .Xr sndio 7
1.16 ratchov 460: .Sh BUGS
461: The
1.1 kstailey 462: .Nm
1.16 ratchov 463: utility assumes non-blocking I/O for input and output streams.
464: It will not work reliably on files that may block
465: (ordinary files block, pipes don't).
466: .Pp
467: Resampling is low quality; down-sampling especially should be avoided
468: when recording.
469: .Pp
470: Processing is done using 16-bit arithmetic,
471: thus samples with more than 16 bits are rounded.
1.17 jmc 472: 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