termwave

Terminal audio visualizer for macOS. Renders real-time spectrum bars, waveforms, oscilloscopes, and stereo visualizations from mic input or system audio.

Install

Requires Rust and (optionally) Swift for system audio capture.

just

This builds and installs termwave and termwave-tap to ~/.cargo/bin.

Usage

termwave                        # spectrum visualizer (system audio by default)
termwave --mode wave            # waveform mode
termwave --mode scope           # oscilloscope mode
termwave --mode stereo          # stereo L/R visualization
termwave --device "system"      # capture system audio (requires termwave-tap)
termwave --theme fire           # use the fire color theme
termwave --bars 128             # set number of spectrum bars
termwave --list-devices         # list available audio devices

Keybindings

Key	Action
?	Help
m	Cycle visualization mode
d	Select audio device
s	Settings (theme, smoothing, noise, etc.)
Up / Down	Increase / decrease sensitivity
Right / Left	More / fewer bars
q / Esc	Quit

Modes

• spectrum — frequency bars with color gradient and gravity fall-off
• wave — real-time waveform amplitude plot
• scope — oscilloscope with zero-crossing trigger
• stereo — left channel bars up, right channel bars down from center

Themes

Seven built-in color themes, selectable via --theme or in the settings menu (s):

• classic — blue, cyan, green, yellow, red
• fire — dark red to bright yellow
• ocean — deep navy to bright aqua
• purple — dark violet to pink
• matrix — green monochrome
• synthwave — indigo, violet, magenta, pink, orange
• mono — grayscale

Settings

Press s to open the settings overlay (visualizer keeps running behind it). Adjust with arrow keys or vim bindings:

• Theme — cycle through color themes with live preview
• Smoothing — temporal smoothing between frames (0.0–0.99)
• Monstercat — smooth envelope connecting bar tops
• Noise floor — threshold to zero out quiet bars
• Gradient mode — color by amplitude or by bar position
• Bar width — width of each bar in columns (1–8)
• Bar spacing — gap between bars (0–4)
• Sensitivity — manual gain adjustment (10–500%)

All settings persist to ~/.config/termwave/config.toml.

System audio capture

To visualize audio from Apple Music or other apps, termwave uses a companion Swift binary (termwave-tap) that captures system audio via ScreenCaptureKit.

Requirements:

• macOS 13+
• Screen Recording permission must be granted to your terminal app (System Settings > Privacy & Security > Screen Recording)

Select "System Audio (ScreenCaptureKit)" from the device menu (d), or pass --device system.

Alternative: Install BlackHole, create a Multi-Output Device in Audio MIDI Setup (speakers + BlackHole), set it as your output, then select "BlackHole 2ch" as the input device.