Skip to Content
Kwybars
Configuration

Overview

Where the config lives, how reloads work, and the full default config.

Kwybars can run without a config file. If no file exists, it uses the built-in defaults.

The config file is split into six sections:

SectionWhat it controls
[overlay]Where the visualizer appears, which monitor it uses, and which layer it sits on
[visualizer]Layout, bar shape, colors, themes, and frame rate
[image_overlay]Optional transparent image layer drawn above the visualizer
[background]Optional bass-reactive wallpaper with independent zoom and shake
[activity]When the visualizer shows and hides as audio starts and stops
[audio]How the audio is turned into bar heights

If you only want something that works quickly, start with Preset Configs. The pages in this section explain each option.

Config Path

Kwybars looks for config files in this order:

  1. --config /path/to/config.toml
  2. KWYBARS_CONFIG
  3. $XDG_CONFIG_HOME/kwybars/config.toml
  4. ~/.config/kwybars/config.toml

The packaged example config is installed at:

/usr/share/doc/kwybars/examples/config.toml

To run with a specific config:

kwybars --config ~/.config/kwybars/custom/my_config.toml

Hot Reload

Kwybars watches the config file, colors.toml, the theme file, and the overlay and background images, and applies changes while it runs. Only what changed is rebuilt, so editing a color does not interrupt the audio.

If the new config has an error, Kwybars keeps running with the last good one and writes the error, with the file and line, to the log.

Mistakes are handled like this:

MistakeWhat happens
Unknown keyIgnored, with a warning that names the key
Value out of rangeSet to the nearest allowed value, with a warning
Wrong type, such as bars = "many"The config is rejected, with the key and line in the message
Key from an older versionIgnored, with one warning. See Upgrading from 0.2

kwybars validate-config shows all of this without starting the visualizer. See Command Line.

Default Config

This is the built-in default shape. You do not need to copy all of it; copy only the keys you want to change.

[overlay]
show_on = "primary"
layer = "background"
exclusive_zone = "respect"
position = "bottom"
full_length = true
width = 800
height = 500
anchor_margin = 20
margin_left = 20
margin_right = 20
margin_top = 0
margin_bottom = 0
fade_in_ms = 180
fade_out_ms = 350
horizontal_alignment = "center"
vertical_alignment = "center"

[visualizer]
layout = "line"
grow_from = "edge"
line_mode = "continuous"
line_split_gap = 200
mirror_orientation = "horizontal"
mirror_gap = 0
wave_stroke_width = 10
wave_fill = true
wave_glow = false
wave_smoothing = 1.0
wave_motion_smoothing = 0.22
wave_amplitude = 0.8
frame_edges = ["top", "bottom"]
frame_mirror_mode = "pairs"
bars = 50
bar_order = "bass_center"
bar_width = 8
bar_corner_radius = 20
segmented_bars = false
segment_length = 14
segment_gap = 6
radial_inner_radius = 180
radial_start_angle = -90
radial_arc_degrees = 360
radial_rotation_speed = 0
center_offset_x = 0
center_offset_y = 0
polygon_sides = 3
polygon_radius = 220
polygon_bar_length = 0
polygon_rotation = -90
polygon_rotation_speed = 0
gap = 20
framerate = 60
color_mode = "gradient"
gradient_direction = "vertical"
color_rgba = "rgba(175, 198, 255, 0.7)"
color2_rgba = "rgba(191, 198, 220, 0.7)"
theme_opacity = 1.0

[image_overlay]
enabled = false
path = ""
opacity = 1.0
fit = "contain"
width = 0
height = 0
offset_x = 0
offset_y = 0

[activity]
threshold = 0.035
activate_delay_ms = 180
deactivate_delay_ms = 2200

[audio]
sensitivity = 1.0
auto_sensitivity = true
low_cutoff_hz = 50
high_cutoff_hz = 10000
smoothing = 0.7

[background]
enabled = false
path = ""
low_cutoff_hz = 30
high_cutoff_hz = 150
sensitivity = 6.7
threshold = 0.012
zoom = 0.04
shake = 0.0
attack_ms = 35
release_ms = 220

On this page