Skip to Content
Kwybars
Configuration

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
KeyDescriptionDefaultAccepted values
positionScreen edge used by normal edge-based layouts."bottom""bottom", "top", "left", "right"
layerLayer-shell stacking layer."background""background", "bottom", "top"
exclusive_zoneWhether 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_marginMargin on the active anchored edge.20integer pixels
margin_leftExplicit left margin.20integer pixels
margin_rightExplicit right margin.20integer pixels
margin_topExplicit top margin.0integer pixels
margin_bottomExplicit bottom margin.0integer pixels
fade_in_msFade duration when audio starts and the visualizer appears.180integer milliseconds
fade_out_msFade duration after audio has stayed silent for activity.deactivate_delay_ms.350integer milliseconds
full_lengthStretch along the full selected edge.truetrue, false
widthFixed width for horizontal overlays, or thickness for left/right overlays.800integer pixels
heightFixed height for vertical overlays, or thickness for top/bottom overlays.500integer pixels
horizontal_alignmentAlignment for top/bottom overlays when full_length = false."center""left", "center", "right"
vertical_alignmentAlignment for left/right overlays when full_length = false."center""top", "center", "bottom"
show_onWhich 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 = false

Here 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 = false

bars, 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_on chooses the monitors. A section only changes settings, or removes its monitor with enabled = false.
  • If you leave show_on out 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

LayerBehavior
"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 position to the edge your bar is on and height to the bar's height (width for 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_alignment and margin_left or margin_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 bottom layer and keep Kwybars on top.
  • 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.

On this page