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