BassBeat

A circular audio visualizer that reacts to your music in real-time. Runs natively on Linux as a desktop widget.

preview.mp4

⚠️ Beta — This project is experimental. Expect rough edges, especially with compositor integration and audio device detection across different distros.

Install

Install system dependencies first, then run setup:

Arch / Manjaro:

sudo pacman -S python-gobject gtk3 portaudio

Ubuntu / Debian:

sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-3.0 libportaudio2 python3-venv

Fedora:

sudo dnf install python3-gobject gtk3 portaudio

Void Linux:

sudo xbps-install -S python3-gobject gtk+3 portaudio

Then:

git clone https://github.com/AzizStark/bassbeat.git
cd bassbeat
./setup.sh

The setup script installs to ~/.local/share/bassbeat, creates the config at ~/.config/bassbeat/config.toml, and adds a bassbeat launcher to ~/.local/bin/.

Usage

bassbeat                 Run the visualizer
bassbeat --kill          Stop running instance
bassbeat --config        Print current config
bassbeat --edit          Open config in your editor
bassbeat --config-path   Print config file path
bassbeat --help          Show help

Configure

Edit with bassbeat --edit. Changes take effect on restart.

[display]
fps = 60                           # frames per second
position = "center"                # "center" or "x,y" coordinates (e.g. "100,200")
draggable = true                   # left-click drag to reposition
transparent = true
keep_below = true                  # desktop widget mode
fps_sync_decay = true              # consistent decay speed across fps values
sticky = true                      # show on all workspaces
zoom = 1.0                         # scale everything (1.5 = 50% bigger, 0.75 = smaller)

[renderer]
backend = "cairo"                  # "cairo" (CPU) or "opengl" (GPU, requires PyOpenGL)

[visualizer]
bars = 120
bar_width = 4.5
bar_height = 306
radius = 144
start_angle = 0
end_angle = 360
scale = 1.0
smoothing = 3
mirror = true
invert_mirror = false

[colors]
gradient = "210,228,255,255:0|239,33,177,255:50|222,231,254,255:100"
# Rainbow:
# gradient = "255,0,0,255:0|255,255,0,255:16|0,255,0,255:33|0,255,255,255:50|0,0,255,255:67|255,0,255,255:84|255,0,0,255:100"

[audio]
fft_size = 8192
fft_buffer_size = 16384
fft_attack = 0
fft_decay = 65
freq_min = 22
freq_max = 200
sensitivity = 33
bands = 60
latency = 128                      # PipeWire buffer (128=fast, 256=safe, 0=don't change)

[image]
path = "assets/default.png"        # center image
scale_factor = 80                  # 0-100, image overlap with bars

Compositor notes

BassBeat sets _NET_WM_WINDOW_TYPE_DESKTOP and compositor hint properties automatically.

picom v13+ — add "window_type = 'desktop' || " to the shadow = false rule in your picom config.

Note: When draggable = true, the window uses UTILITY type to receive mouse input, which may show blur/shadow on some compositors. Set draggable = false once positioned for clean desktop mode.

Autostart

The setup script can configure autostart for you. To add it manually:

bspwm (~/.config/bspwm/bspwmrc):

bassbeat &

i3 (~/.config/i3/config):

exec --no-startup-id bassbeat

Hyprland (~/.config/hypr/hyprland.conf):

exec-once = bassbeat

sway (~/.config/sway/config):

exec bassbeat

XDG autostart (GNOME, KDE, Xfce):

cp ~/.config/autostart/bassbeat.desktop  # created by setup.sh

Performance tips

Tip	Effect
Lower fps	Biggest impact — halving fps halves CPU usage. Match your monitor refresh rate for best results. Going below 60 will be visually noticeable
Use backend = "opengl"	Faster rendering, lower CPU per frame
Use backend = "cairo"	More compatible, no OpenGL dependency needed
Reduce bars (e.g. 60)	Fewer bars = fewer draw calls per frame
Set draggable = false	Uses DESKTOP window type which some compositors render more efficiently

Audio latency

BassBeat automatically lowers the PipeWire buffer size for responsive visuals. Configure with:

[audio]
latency = 128    # recommended — fast response without audio issues
latency = 256    # safer for weaker hardware
latency = 0      # don't touch system audio settings

Warning: Values below 128 may cause audio crackling in all apps (browser, games, players) since PipeWire quantum is system-wide. Below 64 requires a real-time audio kernel.

Typical resource usage at 60fps with cairo: ~1-3% CPU, ~45MB RAM. Results vary by hardware.

Uninstall

rm -rf ~/.local/share/bassbeat ~/.config/bassbeat ~/.local/bin/bassbeat

Remove any autostart entries you added.

Credits

Based on Bass-Beat-2 Rainmeter skin by SnGmng & AzizStark.

License

CC BY-SA 4.0