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.0Follow 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
| Key | Description | Default | Accepted values |
|---|---|---|---|
enabled | Enable the background. | false | true, false |
source | Image source. | "file" | "file", "sweetbg" |
path | File source: PNG, JPEG, or WebP. Absolute, ~/..., or config-relative path. | unset | string |
low_cutoff_hz | Lower bass cutoff, shared by all outputs. | 30 | 20..1000 Hz |
high_cutoff_hz | Upper bass cutoff, at least twice the lower cutoff. | 150 | 40..2000 Hz |
sensitivity | Bass response strength. | 6.7 | 0..1000 |
threshold | Minimum bass amplitude for movement. | 0.012 | 0..1 |
zoom | Maximum extra zoom (0.04 = 4%). | 0.04 | 0..0.25 |
shake | Maximum offset as a fraction of the visible image. Try 0.003. | 0.0 | 0..0.02 |
attack_ms | Response time as bass rises. | 35 | 1..5000 ms |
release_ms | Return time as bass decreases. | 220 | 1..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 = trueWorks 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.
| Key | Default | Accepted values |
|---|---|---|
enabled | false | true, false |
low_cutoff_hz | 250 | 100..10000 Hz |
high_cutoff_hz | 4000 | 200..20000 Hz, at least twice the lower cutoff |
sensitivity | 20.0 | 0..1000 |
threshold | 0.001 | 0..1 |
zoom | 0.0 | 0..0.25 |
shake | 0.003 | 0..0.02 |
attack_ms | 8 | 1..5000 ms |
release_ms | 110 | 1..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 = falseUse [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
backgroundlayer. Setoverlay.layer = "bottom"to keep bars above it. Withsource = "file", disable any wallpaper program covering the same outputs. - Requires layer-shell and
wp_viewporter. Check support withkwybars 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-configto check settings and image paths.
For a static foreground image, see Image Overlay.