Volbar

Simple X11 volume bar. Tiny footprint, highly customizable.

---

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Options
• Themes
• Auto-Theming (Mabox Only)
• Manual Theming (All Systems)
• Openbox/XFCE4 Integration
• Files
• Contributing
• License

---

Features

• Minimal & fast GTK3 volume indicator
• Auto-detects audio backend (PipeWire/PulseAudio/ALSA)
• Daemon mode with configurable poll interval
• System tray support
• 13 included themes + full CSS customization
• Multiple slider styles and placements

---

Requirements

Debian/Ubuntu

sudo apt install python3-gi gir1.2-gtk-3.0

Arch Linux

sudo pacman -S python-gobject gtk3

---

Installation

git clone https://github.com/musqz/volbar.git
cd volbar
sudo ./install.sh

Custom prefix:

sudo ./install.sh --prefix /usr

---

Quick Start

# Show volume bar once
volbar --show

# Start daemon (auto-shows on volume changes)
volbar --start-daemon

# Stop daemon
volbar --stop-daemon

---

Options

Option	Values	Default	Description
--size	small, medium, large	medium	Window size
--placement	center, top, bottom, left, right, top-left, top-right, bottom-left, bottom-right	center	Screen position
--slider	blocks, dots, line	blocks	Slider style
--theme	theme name or auto (Mabox only)	default	CSS theme
--timeout	milliseconds	2000	Display duration
--poll-interval	milliseconds	200	Daemon check interval
--icon	on, off	on	Show volume icon
--percent	on, off	on	Show percentage

Slider Styles

blocks   █████░░░░░
dots     ●●●●●○○○○○
line     ━━━━━─────

System Tray

Option	Default	Description
--systray-icon	off	Enable tray icon
--tray-step	5	Volume step per scroll
--mixer	pavucontrol	Mixer app for menu

---

Themes

Included Themes:
default, catppuccin, cyberpunk, dracula, gruvbox, neon-green, nord, solarized-dark, tokyo-night, vibrant-blue, vibrant-brown, vibrant-green, vibrant-orange

# List available themes
volbar --list-themes
# Preview all themes
volbar --test-themes
# Test single theme
volbar --show --theme nord

Theme Paths:

• System: /usr/local/share/volbar/themes/
• User: ~/.config/volbar/themes/

---

Auto-Theming (Mabox Only)

On Mabox Linux, Volbar can auto-match your wallpaper colors using --theme auto:

volbar --show --theme auto
volbar --start-daemon --theme auto

Note:

• Enable Conky auto theming in mabox to have effect on volbar.
• Auto-theming reads colors from ~/.config/conky/sysinfo_mbcolor.conkyrc.
• After changing wallpaper, restart the daemon:

  volbar --stop-daemon
  volbar --start-daemon --theme auto

---

Manual Theming (All Systems)

For Openbox, XFCE4, or other systems, manually edit or create theme files in ~/.config/volbar/themes/.

Example (mytheme.css):

#volbar-container {
    background-color: #1a1a1a;
    border: 2px solid #00ff00;
}
label#icon { color: #00ff00; }
label#slider { color: #00ff00; }
label#percentage { color: #ffffff; }
/* Muted state */
label#icon.muted,
label#slider.muted,
label#percentage.muted { color: #ff0000; }

Use your theme:

volbar --show --theme mytheme

---

Openbox/XFCE4 Integration

Autostart

Add to ~/.config/openbox/autostart or XFCE4 autostart:

volbar --start-daemon --placement top-right --theme mytheme &

Keybindings

Edit ~/.config/openbox/rc.xml or XFCE4 keyboard shortcuts:

<keybind key="XF86AudioRaiseVolume">
  <action name="Execute"><command>wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+</command></action>
</keybind>
<keybind key="XF86AudioLowerVolume">
  <action name="Execute"><command>wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-</command></action>
</keybind>
<keybind key="XF86AudioMute">
  <action name="Execute"><command>wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle</command></action>
</keybind>

Note: Replace wpctl with pactl for PulseAudio.

---

Files

Path	Description
~/.config/volbar/themes/	User theme directory
/usr/local/share/volbar/themes/	System theme directory
~/.cache/volbar.pid	Daemon PID file

---

License

This project is licensed under the MIT License.