background: Add audio visualizer widget

[ParanoidExtreme]

Describe your changes

Adds an audio visualizer widget to the background, rendered using cava. The implementation is inspired by the media controls widget but with its own distinct styling. Two display styles are available: bars and wave, both can be customized with opacity, border width, max height etc. Customization is exposed through several variables (target bar/point width, gap, smoothing, border, and more), these are configurable in BackgroundConfig like the other widgets are.

Resource management: cava + bar/wave rendering is automatically paused when all monitors are fullscreened, when a window is detected over the visualizer, or when gamemode is active.

Performance: includes a configurable performance limiter to cap rendering load, this applies only to wave which uses a canvas to render which happens to be quite GPU and CPU heavy. Bars hardly has any CPU usage and quite low GPU usage hence it doesn't need a performance limiter.

Changed files

New files:

• widgets/PinnedWidget.qml - Base component for static (non-moving/anchored) widgets
• widgets/visualizer/VisualizerWidget.qml - The audio visualizer widget (bars and wave styles, performance limiter)

Modified files:

• background/Background.qml - Reworked layout to support static background widgets; wraps content in a scope, integrates the new visualizer widget, and adds gamemode-aware cava pausing + window/fullscreen/gamemode detection
• settings/BackgroundConfig.qml - Adds a configuration section with options for the audio visualizer (style, sizing, smoothing, border, performance limiter, etc.)
• common/Config.qml - Adds config entries for the visualizer (enable, height, barRounding, smoothing, opacity, barSpacing, targetBarWidth, mono, showWhenLocked, and more)

Is it ready? Questions/feedback needed?

Mostly ready, happy with the current state but open to feedback on both the visual styling and the code structure.

Showcase

recording_2026-03-29_20.31.54.mp4

[daisith]

Nice, great job !

[ParanoidExtreme]

Nice, great job ! Is it colored by matugen ?

Thanks!

Yeah it's just the primary color used in the rest of the quickshell widgets.

[daisith]

i hope it will be merge, that's a missing feature.
thanks to make it happen ^^

[fb24m]

there should be a "wave" mode, I think, like in the existing media widget in the bar
it would be more minimalistic and consistent

something like this maybe

[ParanoidExtreme]

there should be a "wave" mode, I think, like in the existing media widget in the bar it would be more minimalistic and consistent

something like this maybe

I originally had this implemented but decided to remove it as I personally didn't think I made it well enough, I'll try it again though and see if I can manage to do it better this time.

[ParanoidExtreme]

there should be a "wave" mode, I think, like in the existing media widget in the bar it would be more minimalistic and consistent

something like this maybe

About this... I decided to retry it and it turned out quite well. Sadly though rendering a wave uses quite a bit more processing/rendering power than the bars so not sure how well it will run for others, but personally I see around 10% cpu (on a single thread) and 15-20% GPU rendering wave and under 10% for both when rendering bars. That's for a single 60hz monitor. Running both my secondary 60hz monitor and my primary 240hz monitor I see around 35-40% gpu usage and 40-ish% cpu (single thread). I don't always render the widget though so if one screen is fullscreened, nothing is rendered on it, and if both screens are covered there is basically 0 resource usage since I stop cava and the renderer.

I could perhaps require the background to actually be in focus (no windows that aren't floating) for it to render as an optimization but I'm open to suggestion.

recording_2026-03-29_03.14.46.1.mp4

[fb24m]

that's a good idea to add toggle hides visualizer when something is in focus (or even make it default option), since it will distract attention and, as you said, consume resources, but i'd also add a "Show only on primary monitor" toggle, to save resources and keep minimalistic look
you could also try reducing frame rate, i believe we don't need 240 fps for this widget

i'm not sure if this feature will be merged, but you could keep it as optional because i really like this

[ParanoidExtreme]

that's a good idea to add toggle hides visualizer when something is in focus (or even make it default option), since it will distract attention and, as you said, consume resources, but i'd also add a "Show only on primary monitor" toggle, to save resources and keep minimalistic look you could also try reducing frame rate, i believe we don't need 240 fps for this widget

i'm not sure if this feature will be merged, but you could keep it as optional because i really like this

Yeah that wouldn't be too hard to add, although you don't actually set the primary monitor in hyprland so it would probably just have to be a dropdown selector or so. I did attempt to reduce framerate yesterday, it didn't work very well given how quickshell works, it ended up looking terrible and flickering was a major issue.

If you have any ideas on how to properly add framerate limiting, I'd love to hear them.

[unixr77]

"wave" mode look better

[ParanoidExtreme]

that's a good idea to add toggle hides visualizer when something is in focus (or even make it default option), since it will distract attention and, as you said, consume resources, but i'd also add a "Show only on primary monitor" toggle, to save resources and keep minimalistic look you could also try reducing frame rate, i believe we don't need 240 fps for this widget

I added a helper function that checks for each monitor if it's covered by a window or not while managing to ignore floating windows. Works really really well it seems, cpu/gpu usage is basically not effected when it's not actively running. I also added toggles accordingly in settings.

TODO: MAYBE add an option to lock it to a single monitor
TODO: Add fps cap to decrease GPU usage.
TODO: Look into a way of decreasing CPU usage for Wave canvas, bars are very efficent already.

https://raw.githubusercontent.com/ParanoidExtreme/Images/main/recording_2026-03-29_14.59.25.mp4

[fb24m]

i'd suggest updating chart every 3rd frame (just as an example)

this reduces cpu usage from 6-7 to 2-3 for me and looks smooth

[ParanoidExtreme]

i'd suggest updating chart every 3rd frame (just as an example)

this reduces cpu usage from 6-7 to 2-3 for me and looks smooth

Yes thank you, I'll make this a configurable performance limiter in the settings widget.

[fb24m]

to respect "game mode"

[ParanoidExtreme]

i'd suggest updating chart every 3rd frame (just as an example)

this reduces cpu usage from 6-7 to 2-3 for me and looks smooth

Thanks for the logic, I added a variable to it which is controllable

to respect "game mode"

Thank you I will try this, I added a configuration item for the performance limiter, max is 3x currently which I think anything below looks like a slideshow haha. But yeah it helps CPU and GPU usage a lot. Probably useful for laptops and such with iGPU's. On my 240hz monitor, running half speed lowers cpu usage by around half (one thread) and gpu by around half as well, while looking almost identical to full speed.

[fb24m]

i'd suggest updating chart every 3rd frame (just as an example)
this reduces cpu usage from 6-7 to 2-3 for me and looks smooth

Thanks for the logic, I added a variable to it which is controllable

to respect "game mode"

Thank you I will try this, I added a configuration item for the performance limiter, max is 3x currently which I think anything below looks like a slideshow haha. But yeah it helps CPU and GPU usage a lot. Probably useful for laptops and such with iGPU's. On my 240hz monitor, running half speed lowers cpu usage by around half (one thread) and gpu by around half as well, while looking almost identical to full speed.

yes, updating every 3rd frame is perfect for me too

as for game mode, some users may prefer to always use the smoothest wave, even when there're tiled windows, so this option could be helpful

by the way, you can mention a co-author by adding Co-authored-by: NAME <NAME@EXAMPLE.COM>, for example Co-authored-by: fb24m <hello@fb24m.ru>, in the commit message (not the title)

[fb24m]

typo

[ParanoidExtreme]

by the way, you can mention a co-author by adding Co-authored-by: NAME <NAME@EXAMPLE.COM>, for example Co-authored-by: fb24m <hello@fb24m.ru>, in the commit message (not the title)

Thanks, I mostly just use git commit -m "message" but I should probably start writing in the commit body as well.

I improved the check to stop rendering when gamemode is active by also adding the check to background.qml so the cava process is stopped.

[fb24m]

by the way, you can mention a co-author by adding Co-authored-by: NAME <NAME@EXAMPLE.COM>, for example Co-authored-by: fb24m <hello@fb24m.ru>, in the commit message (not the title)

Thanks, I mostly just use git commit -m "message" but I should probably start writing in the commit body as well.

I improved the check to stop rendering when gamemode is active by also adding the check to background.qml so the cava process is stopped.

git commit -m "message

other strings"

via shift+enter is also ok

[ParanoidExtreme]

i actually think there shouldn’t be a bottom border

Agreed, managed to solve it by drawing just the top border (sides had the same issue)

[unixr77]

The performance on the lock screen is very bad. Is this just me or is it the same for everyone?

recording_2026-03-30_18.08.44.mp4

[fb24m]

The performance on the lock screen is very bad. Is this just me or is it the same for everyone?

recording_2026-03-30_18.08.44.mp4

try switching to "Smooth mode"

[unixr77]

GPU usage crazy %95+

[fb24m]

GPU usage crazy %95+

then try "Performance mode"
if it doesn't help, the GPU is likely the bottleneck

[fb24m]

you could also try increasing the "Point width"

[ParanoidExtreme]

GPU usage crazy %95+

Interesting, is it just in "wave" mode or does "bars" also underperform? Asking as bars is much less GPU intensive. My school laptop ran extremely well with about 30% iGPU usage or so. What CPU/GPU do you have? Personally my laptop uses an Intel Core i5-1335U + Intel Iris Xe Graphics

[unixr77]

@ParanoidExtreme
using intel iGPU ( HD 630 ) no have discreate GPU
bar mode gpu usage %84 Still usage is too high

[ParanoidExtreme]

@ParanoidExtreme using intel iGPU ( HD 630 ) no have discreate GPU bar mode gpu usage %84 Still usage is too high

Mhmm I see, I could try putting my config on an older system I have laying around to see how horrible it is.

[ParanoidExtreme]

@ParanoidExtreme using intel iGPU ( HD 630 ) no have discreate GPU bar mode gpu usage %84 Still usage is too high

Mhmm, so a quick follow up on this. I decided to try it on my homelab server, which has an i5-4590t (2014), meaning it's like 12 years old. And with it I see around 70-80% gpu usage which is high of course but pretty acceptable CPU usage. Despite the high GPU usage it actually ran extremely smooth and looked really nice (basically no lag). It ran fine on the lockscreen as well, so aside from the high GPU usage (which is not optimal of course) it wasn't as bad as I expected.

If you have any ideas on how to decrease GPU usage (aside from the framerate cap) feel free to share them.

[fb24m]

@ParanoidExtreme using intel iGPU ( HD 630 ) no have discreate GPU bar mode gpu usage %84 Still usage is too high

Mhmm, so a quick follow up on this. I decided to try it on my homelab server, which has an i5-4590t (2014), meaning it's like 12 years old. And with it I see around 70-80% gpu usage which is high of course but pretty acceptable CPU usage. Despite the high GPU usage it actually ran extremely smooth and looked really nice (basically no lag). It ran fine on the lockscreen as well, so aside from the high GPU usage (which is not optimal of course) it wasn't as bad as I expected.

If you have any ideas on how to decrease GPU usage (aside from the framerate cap) feel free to share them.

I think you should move away from canvas, but have no idea how to replace it

[ParanoidExtreme]

I think you should move away from canvas, but have no idea how to replace it

Yeah, I think it's mostly fine for now but I'll def have to look into that once I've got more time, maybe later this week/next week.

[unixr77]

i5-4590t

ihave i7-9700K
A more up to date processor compared to yours
but my screen resolution is 1440x2560
That's why GPU usage is high
I think it will perform better on a 1080 monitor

[ParanoidExtreme]

i5-4590t

ihave i7-9700K A more up to date processor compared to yours but my screen resolution is 1440x2560 That's why GPU usage is high I think it will perform better on a 1080 monitor

Fair enough I'm using a 1080p monitor for my tests, although I can drive 2 screens with the visualizer which is about the same as a 1440p monitor. I see maybe around 40-50% then using a rtx 2060 dedicated GPU.

[BharathBala21]

Works Perfectly well

[kepalakubik]

How about enable visualizer only on lockscreen?