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:
| Section | What 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:
--config /path/to/config.tomlKWYBARS_CONFIG$XDG_CONFIG_HOME/kwybars/config.toml~/.config/kwybars/config.toml
The packaged example config is installed at:
/usr/share/doc/kwybars/examples/config.tomlTo run with a specific config:
kwybars --config ~/.config/kwybars/custom/my_config.tomlHot 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:
| Mistake | What happens |
|---|---|
| Unknown key | Ignored, with a warning that names the key |
| Value out of range | Set 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 version | Ignored, 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