Annotation of src/usr.bin/aucat/aucat.1, Revision 1.113
1.111 bentley 1: .\" $OpenBSD: aucat.1,v 1.110 2015/10/17 21:11:42 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.111 bentley 17: .Dd $Mdocdate: October 17 2015 $
1.1 kstailey 18: .Dt AUCAT 1
1.5 aaron 19: .Os
1.1 kstailey 20: .Sh NAME
1.102 ratchov 21: .Nm aucat
1.107 ratchov 22: .Nd audio files manipulation tool
1.1 kstailey 23: .Sh SYNOPSIS
24: .Nm aucat
1.107 ratchov 25: .Op Fl dn
1.108 jmc 26: .Op Fl b Ar size
1.16 ratchov 27: .Op Fl c Ar min : Ns Ar max
28: .Op Fl e Ar enc
1.9 millert 29: .Op Fl f Ar device
1.113 ! ratchov 30: .Op Fl g Ar position
1.16 ratchov 31: .Op Fl h Ar fmt
32: .Op Fl i Ar file
1.68 ratchov 33: .Op Fl j Ar flag
1.94 ratchov 34: .Op Fl o Ar file
1.113 ! ratchov 35: .Op Fl p Ar position
1.94 ratchov 36: .Op Fl q Ar port
37: .Op Fl r Ar rate
38: .Op Fl v Ar volume
1.1 kstailey 39: .Sh DESCRIPTION
1.99 ratchov 40: The
1.102 ratchov 41: .Nm
1.107 ratchov 42: utility can play, record, mix, and process audio files
43: on the fly.
1.99 ratchov 44: During playback,
1.102 ratchov 45: .Nm
1.107 ratchov 46: reads audio data concurrently from all played files,
47: mixes it and plays the result on the device.
48: Similarly, it stores audio data recorded
49: from the device into corresponding files.
50: An
51: .Em off-line
52: mode could be used to process audio files without
53: involving audio hardware.
54: Processing includes:
1.99 ratchov 55: .Pp
56: .Bl -bullet -offset indent -compact
57: .It
1.102 ratchov 58: Change the sound encoding.
1.99 ratchov 59: .It
1.107 ratchov 60: Route the sound from one channel to another.
1.99 ratchov 61: .It
1.102 ratchov 62: Control the per-file playback volume.
1.99 ratchov 63: .El
64: .Pp
65: Finally,
1.102 ratchov 66: .Nm
67: can accept MIDI messages usable for:
1.99 ratchov 68: .Pp
69: .Bl -bullet -offset indent -compact
70: .It
71: Volume control.
72: .It
1.102 ratchov 73: Start, stop and relocate playback and recording.
1.99 ratchov 74: .El
75: .Pp
1.16 ratchov 76: The options are as follows:
1.26 ratchov 77: .Bl -tag -width Ds
1.109 schwarze 78: .It Fl b Ar size
1.107 ratchov 79: The buffer size of the audio device in frames.
80: Default is 7680.
1.110 jmc 81: .It Fl c Ar min : Ns Ar max
1.107 ratchov 82: The range of audio file channel numbers.
1.104 ratchov 83: The default is
84: .Cm 0:1 ,
85: i.e. stereo.
1.59 ratchov 86: .It Fl d
1.71 ratchov 87: Increase log verbosity.
1.26 ratchov 88: .It Fl e Ar enc
1.107 ratchov 89: Encoding of the audio file.
90: The default is
91: .Va s16 .
1.111 bentley 92: Encoding names use the following scheme: signedness
1.107 ratchov 93: .Po
94: .Va s
95: or
96: .Va u
97: .Pc
98: followed
99: by the precision in bits, the byte-order
100: .Po
101: .Va le
102: or
103: .Va be
104: .Pc ,
105: the number of
106: bytes per sample, and the alignment
107: .Po
108: .Va msb
109: or
110: .Va lsb
111: .Pc .
112: Only the signedness and the precision are mandatory.
113: Examples:
114: .Va u8 , s16le , s24le3 , s24le4lsb .
1.17 jmc 115: .It Fl f Ar device
1.102 ratchov 116: Use this
1.57 ratchov 117: .Xr sndio 7
1.102 ratchov 118: audio device.
1.107 ratchov 119: Device mode and parameters are determined from audio files.
120: Default is
121: .Pa default .
1.113 ! ratchov 122: .It Fl g Ar position
! 123: Go to the given time position and start playback or recording there.
! 124: This option is equivalent to an incoming MMC relocate message
! 125: with the same position.
! 126: The position is expressed as the number of samples (at device sample rate).
1.26 ratchov 127: .It Fl h Ar fmt
1.107 ratchov 128: Audio file type.
129: The following file types are supported:
1.110 jmc 130: .Pp
131: .Bl -tag -width auto -compact
132: .It Cm raw
1.107 ratchov 133: Headerless file.
1.110 jmc 134: .It Cm wav
1.107 ratchov 135: Microsoft WAV file format.
1.110 jmc 136: .It Cm aiff
1.107 ratchov 137: Apple's audio interchange file format.
1.110 jmc 138: .It Cm au
1.107 ratchov 139: Sun/NeXT audio file format.
1.110 jmc 140: .It Cm auto
1.107 ratchov 141: Try to guess, depending on the file name.
142: This is the default.
143: .El
1.16 ratchov 144: .It Fl i Ar file
1.107 ratchov 145: Play this audio file.
1.16 ratchov 146: If the option argument is
147: .Sq -
148: then standard input will be used.
1.68 ratchov 149: .It Fl j Ar flag
1.107 ratchov 150: Control whether source channels are joined or expanded if
151: they don't match the destination number of channels.
1.68 ratchov 152: If the flag is
1.107 ratchov 153: .Cm off ,
154: then each source channel is routed to a single destination channel,
155: possibly discarding channels.
1.68 ratchov 156: If the flag is
1.104 ratchov 157: .Cm on ,
1.107 ratchov 158: then a single source may be sent to multiple destinations
159: and multiple sources may be mixed into a single destination.
160: For instance, this feature could be used to convert
161: a stereo file into a mono file mixing left and right channels together.
1.68 ratchov 162: The default is
1.107 ratchov 163: .Cm off .
1.42 ratchov 164: .It Fl n
1.107 ratchov 165: Off-line mode.
166: Read input files and store the result in the output files,
167: processing them on the fly.
168: This mode is useful to mix, demultiplex, resample or re-encode
169: audio files off-line.
1.87 ratchov 170: It requires at least one input
171: .Pq Fl i
172: and one output
173: .Pq Fl o .
1.16 ratchov 174: .It Fl o Ar file
1.107 ratchov 175: Record into this audio file.
1.16 ratchov 176: If the option argument is
177: .Sq -
178: then standard output will be used.
1.113 ! ratchov 179: .It Fl p Ar position
! 180: Time offset where the beginning of the file belongs.
! 181: The first sample of the file will be played or recorded when the device
! 182: reaches the given postion.
! 183: The position is expressed as the number of samples (at device sample rate).
1.87 ratchov 184: .It Fl q Ar port
1.107 ratchov 185: Control audio device properties through this MIDI port.
1.71 ratchov 186: This includes per-stream volumes and the ability to
1.107 ratchov 187: synchronously start, stop and relocate audio files.
1.26 ratchov 188: .It Fl r Ar rate
1.107 ratchov 189: Sample rate in Hertz of the audio file.
1.104 ratchov 190: The default is
191: .Cm 48000 .
1.30 ratchov 192: .It Fl v Ar volume
1.107 ratchov 193: Software volume attenuation of the file to play.
1.30 ratchov 194: The value must be between 1 and 127,
1.82 jmc 195: corresponding to \-42dB and \-0dB attenuation in 1/3dB steps.
1.104 ratchov 196: The default is 127, i.e. no attenuation.
1.21 jmc 197: .El
198: .Pp
1.71 ratchov 199: On the command line,
1.107 ratchov 200: per-file parameters
201: .Pq Fl cehjrv
202: must precede the file definition
1.102 ratchov 203: .Pq Fl io .
1.71 ratchov 204: .Pp
1.32 ratchov 205: If
1.107 ratchov 206: .Nm
1.32 ratchov 207: is sent
1.44 ratchov 208: .Dv SIGHUP ,
209: .Dv SIGINT
210: or
211: .Dv SIGTERM ,
1.32 ratchov 212: it terminates recording to files.
1.55 ratchov 213: .Sh MIDI CONTROL
214: .Nm
1.102 ratchov 215: can be controlled through MIDI
1.71 ratchov 216: .Pq Fl q
1.102 ratchov 217: as follows:
218: a MIDI channel is assigned to each stream, and the volume
1.55 ratchov 219: is changed using the standard volume controller (number 7).
1.98 ratchov 220: .Pp
221: The master volume can be changed using the standard master volume
222: system exclusive message.
1.62 ratchov 223: .Pp
1.107 ratchov 224: All audio files are controlled by the following MMC messages:
225: .Bl -tag -width relocate -offset indent
1.62 ratchov 226: .It relocate
1.107 ratchov 227: All files are relocated to the requested time position.
228: If it is beyond the end of a file, the file is temporarly
229: disabled until a valid position is requested.
1.62 ratchov 230: .It start
1.107 ratchov 231: Playback and/or recording is started.
1.67 jmc 232: .It stop
1.107 ratchov 233: Playback and/or recording is stopped and all files are rewound
234: back to the starting position.
1.62 ratchov 235: .El
236: .Pp
1.102 ratchov 237: MIDI control is intended to be used together with
1.112 ratchov 238: .Xr sndiod 8 .
1.62 ratchov 239: For instance, the following command will create two devices:
240: the default
1.92 ratchov 241: .Va snd/0
1.102 ratchov 242: and a MMC-controlled one
1.92 ratchov 243: .Va snd/0.mmc :
1.62 ratchov 244: .Bd -literal -offset indent
1.107 ratchov 245: $ sndiod -r 48000 -z 480 -s default -t slave -s mmc
1.62 ratchov 246: .Ed
247: .Pp
1.102 ratchov 248: Programs using
1.92 ratchov 249: .Va snd/0
1.102 ratchov 250: behave normally, while programs using
1.92 ratchov 251: .Va snd/0.mmc
1.62 ratchov 252: wait for the MMC start signal and start synchronously.
1.102 ratchov 253: Then, the following command will play a file on the
1.92 ratchov 254: .Va snd/0.mmc
1.102 ratchov 255: audio device, giving full control to MIDI software or hardware
1.66 ratchov 256: connected to the
1.102 ratchov 257: .Va midithru/0
1.89 ratchov 258: MIDI port:
1.66 ratchov 259: .Bd -literal -offset indent
1.107 ratchov 260: $ aucat -f snd/0.mmc -q midithru/0 -i file.wav
1.66 ratchov 261: .Ed
262: .Pp
263: At this stage,
264: .Nm
265: will start, stop and relocate automatically following all user
1.102 ratchov 266: actions in the MIDI sequencer, assuming it's configured to
267: transmit MMC on
268: .Va midithru/0 .
269: Furthermore, the MIDI sequencer could be configured to use the
1.92 ratchov 270: .Va snd/0
1.102 ratchov 271: port as MTC clock source, assured to be synchronous to playback of
272: .Pa file.wav .
1.16 ratchov 273: .Sh EXAMPLES
1.107 ratchov 274: Mix and play two files while recording a third file:
1.16 ratchov 275: .Bd -literal -offset indent
1.107 ratchov 276: $ aucat -i file1.wav -i file2.wav -o file3.wav
1.16 ratchov 277: .Ed
278: .Pp
1.77 jmc 279: Record channels 2 and 3 into one stereo file and
1.107 ratchov 280: channels 6 and 7 into another stereo file using a 44.1kHz sampling
281: rate for both:
1.16 ratchov 282: .Bd -literal -offset indent
1.107 ratchov 283: $ aucat -r 44100 -c 2:3 -o file1.wav -c 6:7 -o file2.wav
1.42 ratchov 284: .Ed
285: .Pp
1.77 jmc 286: Split a stereo file into two mono files:
1.42 ratchov 287: .Bd -literal -offset indent
1.107 ratchov 288: $ aucat -n -i stereo.wav -c 0:0 -o left.wav \e
289: -c 1:1 -o right.wav
1.16 ratchov 290: .Ed
1.2 kstailey 291: .Sh SEE ALSO
1.12 jmc 292: .Xr audioctl 1 ,
1.17 jmc 293: .Xr cdio 1 ,
1.9 millert 294: .Xr mixerctl 1 ,
1.54 ratchov 295: .Xr audio 4 ,
1.112 ratchov 296: .Xr sndio 7 ,
297: .Xr sndiod 8
1.16 ratchov 298: .Sh BUGS
1.107 ratchov 299: Resampling is low quality.
1.16 ratchov 300: .Pp
1.107 ratchov 301: There are limitations inherent to the
302: .Ar wav ,
303: .Ar aiff ,
304: and
305: .Ar au
306: file formats: not all encodings are supported,
307: file sizes are limited to 2GB, and the files must support the
308: .Xr lseek 2
309: operation (e.g. pipes do not support it).
![[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