CLI Audio Visualizer

Real‑time, flashy, terminal audio visualization powered by system audio capture (PulseAudio/PipeWire on Linux, WASAPI loopback on Windows, sounddevice input/loopback on macOS) and a bunch of lovingly over‑tuned DSP & effects.

✨ How To Use

Check out the releases section for binaries for the latest version: https://github.com/SimonBaars/cli-audio-visualizer/releases

⌨ Controls

Key	Action
SPACE	Next visualization mode
ENTER	Next color scheme
W	Cycle Adaptive EQ: off → medium (EQ~ default) → strong (EQ+)
B	Toggle ASCII/simple glyphs
S	Save config
Q / ESC	Quit

🚀 Execute For Development

git clone https://github.com/yourusername/cli-audio-visualizer.git
cd cli-audio-visualizer
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

📦 Single Executable (PyInstaller)

You can bundle a standalone binary (no Python needed) per platform:

python -m pip install -r packaging/pyinstaller-requirements.txt
bash packaging/build.pyinstaller.sh

Output goes to dist/cli-audio-visualizer-<platform>-<arch>.

Notes:

• Linux: relies on PulseAudio/PipeWire libs present on host (parec must be available in PATH).
• Windows: WASAPI loopback works only when sounddevice detects an output device supporting it.
• macOS: For true system output capture, user still needs a loopback device (e.g. BlackHole); binary will fall back to microphone otherwise.
• If terminal colors look off in the binary, ensure locale = UTF-8 and a color-capable terminal.

Reproducible build tip: use python -m venv build-env && source build-env/bin/activate before installing PyInstaller to isolate toolchain.

▶ Run

source .venv/bin/activate
python visualizer.py

🧩 Requirements

• Linux with PulseAudio or PipeWire (for monitor capture via parec)
• Python 3.9+ (tested newer)
• Terminal with UTF‑8 + color; ASCII mode available otherwise.

Dependencies: numpy, rich (for tooling), colorama, sounddevice (optional / future), standard curses.

🔊 Audio Capture Notes

Platform backends:

• Linux: parec (PulseAudio / PipeWire monitor) – auto-detects a monitor source.
• Windows: WASAPI loopback via sounddevice (captures system output if available).
• macOS: sounddevice input – tries to locate a virtual loopback device (BlackHole/Loopback). If none found, falls back to default input (microphone).

Linux – inspect monitor sources manually:

pactl list sources short | grep monitor

If nothing appears, enable monitor profiles in your sound settings or PipeWire config.

Windows – ensure an output device supports loopback (most do). No extra setup typically required.

macOS – to capture system output directly, install a virtual device like BlackHole and set it as an output (or aggregate). Otherwise you'll just see mic input.

🔧 Internals (Quick Tour)

• audio_visualizer/dsp/bars.py – core band computation (windowed rFFT, log bins, compensation, adaptive spatial smoothing).
• Visualizers under audio_visualizer/visualizers/ each implement a draw_* function.
• Adaptive EQ = slow running mean with blend strength (0 / 0.4 / 0.65).
• Radial & circular modes add procedural particles (time‑based + energy modulated).

🛠 Troubleshooting

Issue	Tip
No movement	Check system audio playing + correct monitor source exists
Too jittery	Enable medium adaptive EQ (press W) or ASCII mode for lighter rendering
Colors wrong	Try another terminal or disable themes forcing palette
High CPU	Reduce terminal size or switch to a simpler mode (bars / waveform)

📜 License

Apache 2.0 – see LICENSE.

Have fun melting your terminal. PRs / ideas welcome. Tuning the visualizations was a pain in the ass, if you can do a better job, please submit a PR!

Installation

# Clone the repository
git clone https://github.com/yourusername/cli-audio-visualizer.git
cd cli-audio-visualizer

# Create virtual environment and install dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Requirements

• Python 3.7+
• PulseAudio or PipeWire (Linux)
• parec (PulseAudio recorder - usually pre-installed)

Dependencies:

• numpy
• curses (built-in on Linux/macOS)

Usage

source venv/bin/activate
python visualizer.py

Controls:

• SPACE - Cycle through visualization modes
• ENTER - Cycle through color schemes
• Q or ESC - Quit

Visualization Modes

Below: representative screenshots of each visualization mode.

1. BARS – Classic frequency bars with full spectrum

   

2. SPECTRUM – Thin spaced analyzer columns

   

3. WAVEFORM – Time‑domain oscilloscope curve

   

4. MIRROR_CIRCULAR – Vertical bars mirrored from center axis

   

5. CIRCULAR_WAVE – Circular energy ring with embellishments (halo / sparks / rays)

   

6. LEVELS – VU style multi‑band level meters

   

7. RADIAL_BURST – Music‑reactive starfield burst

   

Color Schemes

1. MULTICOLOR (default) - Green→Yellow→Red (classic audio levels)
2. BLUE - Blue→Cyan→White
3. GREEN - Green→Yellow
4. RED - Yellow→Red
5. RAINBOW - Full spectrum colors
6. FIRE - Red→Yellow→White

Linux Audio Setup

The visualizer automatically detects PulseAudio/PipeWire monitor sources. If it doesn't capture system audio:

# Check available sources
pactl list sources short | grep monitor

# The visualizer will use: alsa_output.pci-0000_XX_XX.X.analog-stereo.monitor

If needed, you can set the default source:

pactl set-default-source alsa_output.pci-0000_XX_XX.X.analog-stereo.monitor

Troubleshooting

No audio detected:

• Ensure audio is playing on your system
• Check that PulseAudio/PipeWire is running
• The visualizer will show which source it's using at startup

Colors not showing:

• Make sure your terminal supports colors
• Try a different terminal emulator (kitty, alacritty, gnome-terminal)

Low visualization levels:

• Turn up your system volume (parec captures at output level)
• Try bass-heavy music for better visualization

Technical Details

• Audio Capture: Uses parec to directly capture from PulseAudio/PipeWire monitor sources
• FFT: 4096-point FFT for high frequency resolution
• Frequency Range: 20 Hz - 20 kHz with logarithmic binning
• Rendering: Curses with selective updates for smooth, flicker-free display
• Frame Rate: 60 FPS

License

Apache License 2.0 - See LICENSE file for details.