tuxrecord

Record audio to a WAV file on Linux using ALSA as the recording source.

tuxrecord is the Linux port of the former macOS-only macrecord tool. The Swift/AVFoundation code was rewritten in C99 and now uses the native ALSA capture API (libasound); it builds with GCC. macrecord was created by my good friend Armin. You can find his code here: https://codeberg.org/armin/macrecord

Requirements

GCC and GNU make
ALSA development headers (libasound2-dev on Debian/Ubuntu, alsa-lib-devel on Fedora, alsa-lib on Arch)

Usage

# Record until q or Ctrl+C
tuxrecord

# Record for N seconds
tuxrecord -d 30

# Specify output directory
tuxrecord -o /path/to/dir

# Use a custom filename prefix
tuxrecord -p myrec

# Use a specific ALSA capture device
tuxrecord -D hw:1,0

# Record from PipeWire (the PipeWire sound server)
tuxrecord -D pipewire

Options

Option	Description
`-o <dir>`	Output directory (default: current directory)
`-d <secs>`	Stop automatically after `<secs>` seconds
`-p <prefix>`	Filename prefix instead of `tuxrecord`
`-D <device>`	ALSA capture device (default: `default`; `pipewire` on PipeWire systems)
`-h, --help`	Show help

Run arecord -l to list available ALSA capture devices. On systems with PipeWire, list the PipeWire source nodes with pactl list short sources or wpctl status (see "Recording from PipeWire" below).

Controls

q - Stop recording and save the file
Ctrl+C - Stop recording and save the file

The file is written as <prefix>__<timestamp>.wav (default prefix tuxrecord). The VU meter shows the input level of the left and right channels in real time when stderr is a terminal.

Recording system audio

The default ALSA capture device (default) is usually the microphone. To record system audio (everything playing on the machine), route playback through the ALSA loopback driver snd-aloop and capture from the other side of the loop.

# 1. Load the loopback module (once per boot)
sudo modprobe snd-aloop

# 2. Play audio on the "playback" side of the loop
aplay -D hw:Loopback,0 song.wav

# 3. In another terminal, record from the paired "capture" side
tuxrecord -D hw:Loopback,1

Audio written to hw:Loopback,0 (playback) is heard on hw:Loopback,1 (capture): the two subdevices form a loop and the samples pass straight through. Point your players at hw:Loopback,0 (default sink) and record from hw:Loopback,1 to capture the system mix. Subdevice pairing depends on the kernel version; if one direction is silent, try recording from hw:Loopback,0 while playing to hw:Loopback,1.

Recording from PipeWire

On modern distributions (Fedora 34+, Ubuntu 22.04+, Arch Linux) the PipeWire sound server takes over audio handling. PipeWire ships an ALSA compatibility plugin (pipewire-alsa) that exposes the server as a normal ALSA capture device named pipewire, so tuxrecord can record from it with no extra setup:

# Record from PipeWire's default source (usually the microphone)
tuxrecord -D pipewire

# Record a fixed duration
tuxrecord -D pipewire -d 10

What "pipewire" records

The pipewire-alsa plugin routes capture to PipeWire's default source:

# Show the current default source
pactl get-default-source   # or: wpctl status

# List all available PipeWire sources
wpctl status
pactl list short sources

Recording system audio (what you hear)

To capture everything that is currently playing (system audio), point the default source at the monitor of the default sink. This is the PipeWire equivalent of the ALSA loopback approach above but needs no kernel module:

# 1. Find the monitor of the default sink
pactl set-default-source "$(pactl get-default-sink).monitor"

# 2. Record it with tuxrecord
tuxrecord -D pipewire

The .monitor source carries exactly what the sink is playing, so anything your players output ends up in the WAV file. Every capture follows the same <prefix>__<timestamp>.wav naming and can be stopped with q or Ctrl+C. The default setting can be restored later with pactl set-default-source <your-input-source>.

Troubleshooting

"cannot open ALSA capture device 'pipewire'" — the pipewire-alsa plugin is missing. Install it (e.g. pipewire-alsa on Debian/Ubuntu/Arch, pipewire-alsa on Fedora), or the PipeWire server is not running (systemctl --user status pipewire). In that case fall back to a regular ALSA device with tuxrecord -D hw:0,0.
Recording from a specific device or virtual node instead of the default source is possible by setting the default source first (see pactl / wpctl output) or by creating a loopback with pw-loopback and recording that node.

Build

make
# or directly:
# gcc -std=c99 -O2 -Wall -Wextra tuxrecord.c -o tuxrecord $(pkg-config --libs alsa) -lm

Install (installs to $(PREFIX)/bin, default /usr/local/bin):

sudo make install
# or: sudo cp tuxrecord /usr/local/bin/tuxrecord

Install to a custom prefix:

make install PREFIX=~/.local

Uninstall:

sudo make uninstall

License

Apache License 2.0 — see the LICENSE file for details.

5.5 KiB Raw Blame History