Skip to Content
Kwybars
Configuration

Reactive Background

Make a wallpaper zoom and gently shake with the bass

[background] adds a bass-reactive wallpaper. It fills the output with a centered crop and stays visible when audio stops. Image buffers are sized for each monitor, with room for zoom and shake.

[overlay]
show_on = "DP-1"
layer = "bottom"

[background]
enabled = true
path = "~/Pictures/wallpapers/forest.jpg"
zoom = 0.04
shake = 0.0

Follow Sweetbg

Use a Sweetbg build with renderer subscription support:

[background]
enabled = true
source = "sweetbg"

Kwybars follows Sweetbg's cover wallpaper on each selected output, including changes from existing scripts. path is ignored. Sweetbg resumes rendering when Kwybars stops; other fit modes stay with Sweetbg. Run kwybars doctor if it does not connect.

Settings

KeyDescriptionDefaultAccepted values
enabledEnable the background.falsetrue, false
sourceImage source."file""file", "sweetbg"
pathFile source: PNG, JPEG, or WebP. Absolute, ~/..., or config-relative path.unsetstring
low_cutoff_hzLower bass cutoff, shared by all outputs.3020..1000 Hz
high_cutoff_hzUpper bass cutoff, at least twice the lower cutoff.15040..2000 Hz
sensitivityBass response strength.6.70..1000
thresholdMinimum bass amplitude for movement.0.0120..1
zoomMaximum extra zoom (0.04 = 4%).0.040..0.25
shakeMaximum offset as a fraction of the visible image. Try 0.003.0.00..0.02
attack_msResponse time as bass rises.351..5000 ms
release_msReturn time as bass decreases.2201..5000 ms

Raise sensitivity for stronger motion or threshold to ignore quiet audio.

Midrange Hits

Add short reactions to sudden midrange changes, such as snare-like hits:

[background.mid]
enabled = true

Works with file and Sweetbg sources. It reacts to frequency changes, so vocals and other instruments can also trigger it. Raise threshold to ignore small changes, or sensitivity for stronger hits.

KeyDefaultAccepted values
enabledfalsetrue, false
low_cutoff_hz250100..10000 Hz
high_cutoff_hz4000200..20000 Hz, at least twice the lower cutoff
sensitivity20.00..1000
threshold0.0010..1
zoom0.00..0.25
shake0.0030..0.02
attack_ms81..5000 ms
release_ms1101..5000 ms

Bass settings stay in [background]. Combined zoom and shake are capped at the larger configured amount for each. Set both bands' zoom and shake to 0 for a static image. Frequency cutoffs are capped by the captured sample rate.

Per-Output Settings

Backgrounds follow overlay.show_on. Override them with [output.NAME.background]:

[overlay]
show_on = "all"
layer = "bottom"

[background]
enabled = true
path = "~/Pictures/wallpapers/forest.jpg"

[output.DP-2.background]
path = "~/Pictures/wallpapers/mountain.png"
zoom = 0.06
shake = 0.003

[output.HDMI-A-1.background]
enabled = false

Use [output.DP-2.background.mid] to override midrange motion or disable it on one output. Frequency cutoffs stay global in [background] and [background.mid]. Disabling an entire [output.NAME] section hides both its bars and background.

Notes

  • The wallpaper uses the background layer. Set overlay.layer = "bottom" to keep bars above it. With source = "file", disable any wallpaper program covering the same outputs.
  • Requires layer-shell and wp_viewporter. Check support with kwybars doctor.
  • Config and images reload automatically. A broken replacement keeps the previous image visible. Images over 40 megapixels or 320 MB are refused.
  • Run kwybars validate-config to check settings and image paths.

For a static foreground image, see Image Overlay.

On this page