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