AUCAT(1)

💖 AUCAT(1) 💖

okay bestie, welcome to aucat — the audio file manipulation tool from the General Commands Manual, section 1. she's giving main character energy and she does a LOT, so grab a strawberry drink and let's go 🍓✨

---

✨ SYNOPSIS ✨

aucat [-dn] [-b size] [-c channels] [-e enc] [-f device] [-g position]
      [-h fmt] [-i file] [-m min:max/min:max] [-o file] [-p position]
      [-q port] [-r rate] [-v volume]

---

🌸 DESCRIPTION 🌸

so like, aucat can play, record, mix, and process audio files on the fly. no cap. 🔥

When she's playing back, aucat reads audio data from all the played files at the same time, mixes it all together, and plays the result on the device. And when she's recording, she takes the audio data coming off the device and stores it into the corresponding files. twin behavior fr fr 💅

There's also an off-line mode you can use to process audio files without involving any audio hardware at all — iconic, no device required.

Processing includes:

• Change the sound encoding.
• Route the sound from one channel to another.
• Control the per-file playback volume.

And finally, aucat can accept MIDI messages, which are usable for:

• Volume control.
• Start, stop and relocate playback and recording.

The options are as follows 👇

---

👑 OPTIONS 👑

• -b size — the buffer size of the audio device, in frames. default is 7680.
• -c channels — the audio file channels count. the default is 2, i.e. stereo. 🎧
• -d — increase log verbosity. (she's chatty now 💬)
• -e enc — encoding of the audio file. the default is s24. the encoding names use this scheme: signedness (s or u) followed by the precision in bits, then the byte-order (le or be), then the number of bytes per sample, and then the alignment (msb or lsb). only the signedness and the precision are mandatory. examples: u8, s16le, s24le3, s24le4lsb.
• -f device — use this sndio(7) audio device. the device mode and parameters are determined from audio files. default is default.
• -g position — go to the given time position and start playback or recording there. this option is equivalent to an incoming MMC relocate message with the same position. the position is expressed as the number of samples (at device sample rate).
• -h fmt — audio file type. these are the supported file types:
  • raw — headerless file.
  • wav — Microsoft WAV file format.
  • aiff — Apple's audio interchange file format.
  • au — Sun/NeXT audio file format.
  • auto — try to guess, depending on the file name. this is the default.
• -i file — play this audio file. if the option argument is - then standard input will be used. 👀
• -m min:max/min:max — map the given range of source channels into the given range of destination channels.
• -n — off-line mode. read input files and store the result in the output files, processing them on the fly. this mode is useful to mix, demultiplex, resample or re-encode audio files off-line. it requires at least one input (-i) and one output (-o). ⚠️
• -o file — record into this audio file. if the option argument is - then standard output will be used.
• -p position — time offset where the beginning of the file belongs. the first sample of the file will be played or recorded when the device reaches the given position. the position is expressed as the number of samples (at device sample rate).
• -q port — control audio device properties through this MIDI port. this includes per-stream volumes and the ability to synchronously start, stop and relocate audio files.
• -r rate — sample rate in Hertz of the audio file. the default is 48000.
• -v volume — software volume attenuation of the file to play. the value must be between 1 and 127, corresponding to -42dB and -0dB attenuation in 1/3dB steps. the default is 127, i.e. no attenuation. (full volume, as she deserves 🔊)

okay so important ordering lore: on the command line, per-file parameters (-cehmrv) must precede the file definition (-io). don't fight the order, she will not forgive you 💀

And if aucat is sent SIGHUP, SIGINT or SIGTERM, she terminates recording to files. bye bestie 👋

---

🎹 MIDI CONTROL 🎹

aucat can be controlled through MIDI (-q) like this: a MIDI channel is assigned to each stream, and the volume is changed using the standard volume controller (number 7). the master volume can be changed using the standard master volume system exclusive message.

All audio files are controlled by the following MMC messages:

• relocate — all files are relocated to the requested time position. if it is beyond the end of a file, the file is temporarily disabled until a valid position is requested.
• start — playback and/or recording is started.
• stop — playback and/or recording is stopped and all files are rewound back to the starting position.

MIDI control is intended to be used together with sndiod(8). for instance, the following command will create two devices: the default snd/default and a MMC-controlled one snd/default.mmc:

$ sndiod -r 48000 -z 480 -s default -t slave -s mmc

Programs using snd/default behave normally, while programs using snd/mmc wait for the MMC start signal and start synchronously. then, the following command will play a file on the snd/mmc audio device, giving full control to MIDI software or hardware connected to the midithru/0 MIDI port:

$ aucat -f snd/mmc -q midithru/0 -i file.wav

At this stage, aucat will start, stop and relocate automatically following all user actions in the MIDI sequencer, assuming it's configured to transmit MMC on midithru/0 and snd/mmc. furthermore, the MIDI sequencer could be configured to use the snd/mmc port as MTC clock source, assured to be synchronous to playback of file.wav. the way she syncs up?? obsessed 🦋

---

🌈 EXAMPLES 🌈

Mix and play two files while recording a third file:

$ aucat -i file1.wav -i file2.wav -o file3.wav

Record channels 2 and 3 into one stereo file and channels 6 and 7 into another stereo file using a 44.1kHz sampling rate for both:

$ aucat -r 44100 -m 2:3/0:1 -o file1.wav -m 6:7/0:1 -o file2.wav

Split a stereo file into two mono files:

$ aucat -n -i stereo.wav -c 1 -m 0:0/0:0 -o left.wav \
        -m 1:1/0:0 -o right.wav

---

👀 SEE ALSO 👀

cdio(1), audio(4), sndio(7), audioctl(8), mixerctl(8), sndiod(8)

---

💀 BUGS 💀

Resampling is low quality. (ngl she said it herself, don't @ me 😭)

There are limitations inherent to the wav, aiff, and au file formats: not all encodings are supported, file sizes are limited to 2GB, and the files must support the lseek(2) operation (e.g. pipes do not support it). so no pipe shenanigans for those formats, periodt. 🙈

---

and that's the whole page bestie!! this one shipped from Debian, and her version stamp is $Mdocdate$, with the page sitting right there at AUCAT(1). slay, go process some audio, ily 🫶✨