Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



29 Commits

Repository files navigation

A widget for the Awesome Window Manager 4.x to control the volume

A widget for the Awesome Window Manager (version 4.x) that uses pulseaudio_dbus to control your audio devices.


In addition to the requirements listed in the rockspec file, you will need the Awesome Window Manager version 4.x and PulseAudio with DBus enabled.

To enable DBus in PulseAudio, ensure that the line

load-module module-dbus-protocol

is present in /etc/pulse/ or ~/.config/pulse/



The easiest way to install this widget is to use luarocks:

luarocks install pulseaudio_widget

You can use the --local option if you don't want or can't install it system-wide

This will ensure that all its dependencies are installed.

Note that if you install with --local you will have to make sure that the LUA_PATH environment variable includes the local luarocks path. This can be achieved by evaling the command luarocks path --bin before Awesome is started.

For example, if you start Awesome from the Linux console (e.g. xinit awesome) and you use zsh, you can add the following lines to your ~/.zprofile:

if (( $+commands[luarocks] )); then
    eval `luarocks path --bin`

If you use bash, you can add the following lines to your ~/.bash_profile:

if [[ -n "`which luarocks 2>/dev/null`" ]]; then
    eval `luarocks path --bin`

If you use an X Display Manager you will need to do what explained above in your ~/.xprofile or ~/.xinitrc. See the documentation of your display manager of choice for more information.


If you are on NixOS, you can install this package from nix-stefano-m-overlays.


The widget will display the audio icons defined in your GTK+ theme and it will resize them to fit in the available space. This means that you can switch your icon theme, for example using lxappearance, and update the widget by restarting AwesomeWM.

Specifically, you will need icons named:

  • audio-volume-high-symbolic
  • audio-volume-medium-symbolic
  • audio-volume-low-symbolic
  • audio-volume-muted-symbolic

Mouse controls

When the widget is focused:

  • Scroll: controls the volume
  • Left button: toggles mute
  • Right button: launches mixer (mixer field of the widget table, defaults to pavucontrol)


Add the following to your ~/.config/awesome/rc.lua:

Require the module:

-- require *after* `beautiful.init` or the theme will be inconsistent!
local pulse = require("pulseaudio_widget")

-- Optionally, change the notification timeout default of 1 second to 5.
pulse.notification_timeout_seconds = 5

Add the widget to your layout:

s.mywibox:setup {
  layout = wibox.layout.align.horizontal,
  { -- Left widgets },
  s.mytasklist, -- Middle widget
  { -- Right widgets

Finally add some keyboard shortcuts to control the volume:

  -- Audio
  awful.key({ }, "XF86AudioRaiseVolume", pulse.volume_up),
  awful.key({ }, "XF86AudioLowerVolume", pulse.volume_down),
  awful.key({ }, "XF86AudioMute",  pulse.toggle_muted),
  -- Microphone
  awful.key({"Shift"}, "XF86AudioRaiseVolume", pulse.volume_up_mic),
  awful.key({"Shift"}, "XF86AudioLowerVolume", pulse.volume_down_mic),
  awful.key({ }, "XF86MicMute",  pulse.toggle_muted_mic)


This project is developed in the author's spare time. Contributions in the form of issues, patches and pull requests are welcome.


This program was inspired by the Awesome Pulseaudio Widget (APW).