Terminal Audio Visualizers (WASAPI Loopback)

A small collection of terminal-based audio visualizers for Windows. Most scripts can capture system audio via WASAPI loopback (using PyAudioWPatch). Some scripts may fall back to microphone input if loopback is unavailable.

Tip: Run the launcher first: vis_ui.py.

Features

• Multiple visualizer modes (spectrum-like, oscilloscope/XY, circular, EEG-style, fire effect, etc.)
• Windows system-audio capture via WASAPI loopback (PyAudioWPatch)
• Terminal UI (ANSI colors via colorama)

Requirements

• Windows 10/11 recommended (WASAPI loopback)
• Python 3.9+ (3.10+ recommended)

Python packages

Install dependencies:

pip install numpy colorama PyAudioWPatch

Or from the included file:

pip install -r requirements.txt

Install as a global command (Windows)

This repo includes an automated setup script that can create a vis command usable from any terminal.

Run one of:

setup.cmd all

In PowerShell, run it with:

.\setup.cmd all

• all: installs a global vis command via pipx (recommended) and also enables the optional PATH-based launcher
• pipx: only installs the global vis command via pipx
• bat: creates a vis.bat launcher and adds this folder to your User PATH

Notes:

• The bat mode generates vis.bat locally (it is not committed to the repo).
• If pipx installs vis.exe, the script also adds C:\Users\<you>\.local\bin to your User PATH if needed.

Open a NEW terminal after setup so PATH changes take effect.

Quick start

1) Run the menu / launcher

python vis_ui.py

Use the on-screen controls to select and start a visualizer.

2) Run a visualizer directly

python vis.py
python vis_os.py
python vis_fire.py
python vis_circular.py
python vis_circular_braile.py
python vis_eeg.py
python vis_eeg_central.py

Controls

Controls can vary slightly per visualizer, but commonly:

• Left/Right (or Up/Down): switch items/modes (in the launcher)
• Enter: start selected visualizer (in the launcher)
• q or ESC: exit

Some visualizers also support additional keys (e.g., gain/threshold adjustments). Check the script header/docstring and the bottom status line while running.

Files

• vis_ui.py — menu/launcher that runs the other visualizers
• vis.py — basic terminal visualizer
• vis_os.py — XY / oscilloscope-style visualizer
• vis_fire.py — fire / particle-based visualizer
• vis_circular.py — circular oscilloscope-style visualizer
• vis_circular_braile.py — circular “braille”/dot-style visualizer
• vis_eeg.py — EEG-style bands visualizer
• vis_eeg_central.py — EEG-style bands with center baseline

Troubleshooting

“PyAudioWPatch is required …”

Install it:

pip install PyAudioWPatch

Loopback device list is empty / loopback not found

• Make sure you’re on Windows.
• Ensure audio is playing on the default output device.
• Try running the script as a normal user first; if needed, try as Administrator.
• If you have multiple output devices (headphones/speakers/HDMI), switch the default output device and try again.

“XY requires stereo (2 channels)”

The XY visualizer needs two channels. Try a stereo output device, or disable “mono audio” in Windows accessibility settings.

Notes

• These are terminal visualizers; performance depends on terminal rendering speed.
• WASAPI loopback is Windows-specific; non-Windows behavior may be limited or may require microphone input.

License

MIT License

AI-Assisted Development Disclosure

The ideas, design, and decisions in this project are my own. I used ChatGPT as an acceleration tool to translate those ideas into code (drafting, refactoring, and iteration). I reviewed and edited the output before committing.

Disclaimer (Use at Your Own Risk)

This software is provided "AS IS", without warranty of any kind. You are solely responsible for how you use it, including verifying correctness, security, and suitability for your purposes. The author(s) shall not be liable for any claim, damages, or other liability arising from the use of this software, to the extent permitted by law.