Placement
Where the visualizer appears, on which monitors, and on which layer.
Use [overlay] to decide where Kwybars appears.
[overlay]
show_on = "primary"
layer = "background"
position = "bottom"
full_length = true
height = 500
anchor_margin = 20
margin_left = 20
margin_right = 20
fade_in_ms = 180
fade_out_ms = 350| Key | Description | Default | Accepted values |
|---|---|---|---|
position | Screen edge used by normal edge-based layouts. | "bottom" | "bottom", "top", "left", "right" |
layer | Layer-shell stacking layer. | "background" | "background", "bottom", "top" |
exclusive_zone | Whether the visualizer keeps out of the space that panels such as a status bar reserve. "ignore" lets it draw on top of a bar, see Drawing on a Status Bar. | "respect" | "respect", "ignore" |
anchor_margin | Margin on the active anchored edge. | 20 | integer pixels |
margin_left | Explicit left margin. | 20 | integer pixels |
margin_right | Explicit right margin. | 20 | integer pixels |
margin_top | Explicit top margin. | 0 | integer pixels |
margin_bottom | Explicit bottom margin. | 0 | integer pixels |
fade_in_ms | Fade duration when audio starts and the visualizer appears. | 180 | integer milliseconds |
fade_out_ms | Fade duration after audio has stayed silent for activity.deactivate_delay_ms. | 350 | integer milliseconds |
full_length | Stretch along the full selected edge. | true | true, false |
width | Fixed width for horizontal overlays, or thickness for left/right overlays. | 800 | integer pixels |
height | Fixed height for vertical overlays, or thickness for top/bottom overlays. | 500 | integer pixels |
horizontal_alignment | Alignment for top/bottom overlays when full_length = false. | "center" | "left", "center", "right" |
vertical_alignment | Alignment for left/right overlays when full_length = false. | "center" | "top", "center", "bottom" |
show_on | Which monitors show the visualizer. | "primary" | "primary", "all", a monitor name, or a list of names |
Choosing Monitors
show_on decides where the visualizer appears.
Show it on one monitor:
[overlay]
show_on = "DP-2"On several:
[overlay]
show_on = ["DP-1", "HDMI-A-1"]On all of them:
[overlay]
show_on = "all""primary", the default, means the first monitor your compositor reports. A name is the connector name, such as DP-2. kwybars doctor lists every monitor with its name and scale, and says which ones get the visualizer with the current config.
Names that are not connected are skipped. If none of the listed monitors is connected, Kwybars falls back to the primary monitor.
Monitors can be plugged in and unplugged while Kwybars runs. Fractional scaling is supported, so the bars stay sharp at scales such as 1.25 or 1.5.
Per-Monitor Settings
Sections that start with [output.NAME] change settings for one monitor. Under a monitor's name you can repeat the main sections: [output.NAME.overlay], [output.NAME.visualizer], and [output.NAME.image_overlay]. Each one starts from the main section of the same name and replaces only the keys you write.
[overlay]
show_on = "all"
height = 220
position = "bottom"
[output.DP-1.overlay]
height = 180
margin_left = 40
margin_right = 40
[output.DP-1.visualizer]
layout = "wave"
wave_glow = true
color_mode = "solid"
color_rgba = "rgba(175, 198, 255, 0.75)"
[output.HDMI-A-1.overlay]
position = "top"
height = 120
[output.HDMI-A-1.visualizer]
layout = "particle"
bar_width = 6
gap = 14
[output.DP-3]
enabled = falseHere every monitor shows the visualizer, DP-1 and HDMI-A-1 look different from the rest, and DP-3 is left out.
[output.NAME] itself has one key: enabled = false leaves that monitor without the visualizer.
[output.NAME.overlay] overrides placement for that monitor. It supports position, layer, exclusive_zone, anchor_margin, the edge margins, fade_in_ms, fade_out_ms, full_length, width, height, horizontal_alignment, and vertical_alignment. show_on belongs to the main [overlay] only.
Placement keys written directly in [output.NAME], without .overlay, still work and mean the same thing.
[output.NAME.visualizer] overrides visualizer settings for that monitor. It supports layout, line, mirror, wave, frame, radial, polygon, bar shape, gap, segmentation, and direct color keys. Setting a color here turns off the theme on that monitor.
[output.NAME.image_overlay] changes the image overlay for that monitor: another picture, another size or position, or enabled = false for no image there. Keys you leave out come from the main [image_overlay].
[image_overlay]
enabled = true
path = "~/.config/kwybars/overlays/city.png"
[output.DP-2.image_overlay]
path = "~/.config/kwybars/overlays/forest.png"
offset_y = -80
[output.HDMI-A-1.image_overlay]
enabled = falsebars, bar_order, framerate, theme, and theme_opacity cannot be set per monitor, because all monitors share one audio analysis. They are ignored there with a warning.
How show_on and the sections work together:
show_onchooses the monitors. A section only changes settings, or removes its monitor withenabled = false.- If you leave
show_onout and write sections, the visualizer appears on the monitors that have a section. - A section for a monitor that is not connected does nothing until that monitor is plugged in.
Layer Behavior
| Layer | Behavior |
|---|---|
"background" | Behind normal app windows. This is the default and usually the least intrusive option |
"bottom" | Above wallpaper but below normal windows, compositor dependent |
"top" | Above normal windows |
Drawing on a Status Bar
Kwybars can draw small bars inside a status bar such as Ironbar or Waybar. Normally the compositor keeps Kwybars out of the space a bar reserves, exclusive_zone = "ignore" lets it draw there.
[overlay]
show_on = "DP-1"
layer = "top"
exclusive_zone = "ignore"
position = "top"
full_length = false
horizontal_alignment = "left"
anchor_margin = 0
margin_left = 300
width = 400
height = 34
[visualizer]
grow_from = "opposite"
bars = 40
bar_width = 4
gap = 4
bar_corner_radius = 2- Set
positionto the edge your bar is on andheightto the bar's height (widthfor a bar on the left or right edge). grow_from = "opposite"makes the bars stand on the bottom of a top bar and grow upward. Leave it out to let them hang from the screen edge.- Move the bars along the bar with
horizontal_alignmentandmargin_leftormargin_right. - Kwybars never takes clicks, so the bar's own modules underneath keep working.
- If the bars appear behind your bar, put your bar on its
bottomlayer and keep Kwybars ontop. - Kwybars does not follow your bar's layout. To keep the slot free, give it an empty module with a fixed width in your bar's config.
Reactive Backgrounds
[output.NAME.background] overrides a monitor's reactive wallpaper image and motion settings. See Reactive Background for setup and all settings.