# 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**.

The port is derived from [macrecord](https://codeberg.org/armin/macrecord)
which was created by my good friend armin.

## Requirements

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

## Usage

```bash
# 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
```

## 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`)                 |
| `-h, --help`   | Show help                                                |

Run `arecord -l` to list available ALSA capture devices.

## 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.

```bash
# 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`.

## Build

```bash
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`):

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

Install to a custom prefix:

```bash
make install PREFIX=~/.local
```

Uninstall:

```bash
sudo make uninstall
```

## License

Apache License 2.0 — see the LICENSE file for details.

Copyright 2026 Johannes Findeisen