Configuration
Image Overlay
Draw a transparent image above the visualizer and match it to your wallpaper.
[image_overlay] draws one optional image above the visualizer. This is useful for Rainmeter-style compositions where transparent PNG artwork sits in front of bars, waves, or particles.
[image_overlay]
enabled = true
path = "~/.config/kwybars/overlays/mountain.png"
opacity = 1.0
fit = "contain"
width = 0
height = 0
offset_x = 0
offset_y = 0| Key | Description | Default | Accepted values |
|---|---|---|---|
enabled | Enable image overlay drawing. | false | true, false |
path | Image file path. Absolute paths, ~/..., and paths relative to the active config file directory are supported. PNG, JPEG, and WebP files work. | "" | string |
opacity | Image alpha multiplier. | 1.0 | 0.0..1.0 |
fit | How the image fits inside the target box. | "contain" | "contain", "cover", "stretch" |
width | Target image box width. 0 uses the current overlay width. | 0 | integer pixels |
height | Target image box height. 0 uses the current overlay height. | 0 | integer pixels |
offset_x | Horizontal offset from centered placement. | 0 | number pixels |
offset_y | Vertical offset from centered placement. | 0 | number pixels |
Notes:
- The image is centered on the overlay area and is not limited to it. Set
widthandheightlarger than the overlay and the image reaches past it; with0it fits inside the overlay. - A bigger image grows equally on both sides of the center. Use
offset_xandoffset_yto move it, for example a negativeoffset_yto lift a tall image above a bottom overlay. - A monitor can have its own image through
[output.NAME.image_overlay]. See Per-Monitor Settings. - Use transparent PNG artwork if you want the visualizer to remain visible around or behind the image.
- Images larger than 40 megapixels are refused.
- If the image cannot be read, the visualizer runs without it and the log says why.
kwybars validate-configandkwybars doctorreport it too.
Match Overlays to Wallpapers
kwybars image-overlay match picks the overlay image that matches your wallpaper's file name. See Config Switching.