pavol-dunst

A keybindable application to modify volume levels on audio sinks within PulseAudio with dunst-centric libnotify integrations to display performant volume notifications in dunst. This was partially inspired by pavol and pavolume, as well as my previous attempt of this application pavolumenotify.

_{on-screen keyboard input display software is key-mon}

_{These color schemes are achieved using this application's Xresource support and my project wpal which generates color palettes from the desktop wallpaper and exports the colors to Xresources.}

Install

Succinctly:

cd ./src/
make && sudo make install

make will execute a multi-threaded build by default; alternatively run make pavol-dunst.

If you do not have sudo privileges then modify the PREFIX variable, for example: PREFIX=$HOME/.local make install

Usage

See pavol-dunst --help for documentation on the various command flags:

  [-h|--help] - print this usage information and exit
  
  [-m|--mute] [ [1|"on"] | [0|"off"] | [-1|"toggle"] ]
      Mute audio if arg is "1" or "on"
      Unmute audio if arg is "0" or "off"
      Toggle audio muted if arg is "-1" or "toggle"
      
  [-v|--volume] [+|-]VAL
      If arg starts with "+" increase by VAL -> +5 is current volume + 5
      If arg starts with "-" decrease by VAL -> -7 is current volume - 7
      Set absolute VAL if neither "+" or "-" are present -> 50 sets volume to 50
      
  [-t|--timeout] MILLISECONDS - end volume notification after MILLISECONDS milliseconds.
  
  [-b|--body] BODY - set volume notification body to whatever string is provided as BODY.
  
  [-u|--unlock]
      Forcibly unlock (or prevent the locking of) the shared-memory mutex lock that prevents
      concurrent instances of this process from running.
      
  [-P|--primary-color] CSS_COLOR - set volume notification icon primary color.
      If this arg is unset it will be read from the Xresources key pavol-dunst.primaryColor
      or a default value.
      
  [-S|--secondary-color] CSS_COLOR - set volume notification icon secondary color.
      If this arg is unset it will be read from the Xresources key pavol-dunst.secondaryColor
      or a default value.
      
  [-I|--icon-size] PIXELS - render volume notification icon size to be PIXELS pixels big.

For extra usage details please see the Shared Memory Singleton-Process Mutex Lock, PulseAudio Support, and Xresource Support sections below.

About

Key Binding

This will obviously depend on your Linux distribution, desktop environment, and preferred means of creating global keyboard shortcuts.

For i3wm I use the following in my i3 configuration file:

bindsym XF86AudioRaiseVolume exec --no-startup-id pavol-dunst -v +5
bindsym XF86AudioLowerVolume exec --no-startup-id pavol-dunst -v -5
bindsym XF86AudioMute        exec --no-startup-id pavol-dunst -m toggle

Custom Icons

In theory this application supports adding custom icons, however this was not intended as a first-class feature. Consequently, there is no minification pipeline to reduce the embedded SVG string body sizes. This application renders icon colors dynamically by implementing CSS classes that get passed to the RSVG rendering backend. To reduce compiled binary size, these CSS classes are not named verbosely. One may find the raw CSS stylesheet string that gets passed to the icon rendering in svg.cpp, however a more semantically expressive version follows:

* { --primary: #fff; --secondary: #888; } /* librsvg doesn't support var() in stylesheet rendering, this is just for explanation */
.A { fill: var(--primary); stroke:none }  /* class A is "fill this path with the primary color */
/* Currently no icons need filled with the secondary color, but I would use class B to represent that */
.a { stroke: var(--primary); }            /* class "a" is "stroke this path with the primary color" */
.b { stroke: var(--secondary); }          /* class "b" is "stroke this path with the secondary color" */
.a,.b {stroke-width:.378; fill:none}      /* these styles apply to any strokes (irrelvant to fill styles) */

As such your custom icons should implement classes A, a, and b to work with the current code to render properly with the application's color arguments.

For reference, here was a previous possible icon set I designed myself, you may use these under the same license as the rest of this repository.

                                   

PulseAudio Support

As one might expect, this application changes the volume of the current default audio sink in PulseAudio. Emphasis on "the current default audio sink". If you have multiple sinks registered this application may not modify the volume of the audio source you are expecting. This is currently a limitation and the user will need to modify the default sink using a different application (probably pavucontrol).

Xresource Support

This application supports reading the CSS colors for the SVG icon renderring from Xresources. The user may also provide color changing arguments via the --primary and --secondary flags. The user can see which Xresource keys are most currently expected in Xresources.h. As of writing the application will query for the following keys:

• pavol-dunst.primaryColor: valid CSS color
• pavol-dunst.secondaryColor: valid CSS color

For example the user may test this feature with:

xrdb -merge <(echo -e "pavol-dunst.primaryColor: #f00 \n pavol-dunst.primaryColor: #0ff")

Shared Memory Singleton-Process Mutex Lock

This application uses shared memory to set a process mutually-exclusive (mutex) lock. This is simply to prevent jumpy audio level fluctuations caused by several instances being spawned in short succession. This may be due to either to the oparting system scheduling the processes in an unexpected order or the audio sink having a large latency. For example, a user may easily reproduce this behavior by holding down a keyboard key that this process is bound to, while the audio sink is a bluetooth device—the processes execute and queue a volume change faster than the bluetooth sink can receive and acknowledge the volume change, leading to unpredicatble volume level "relapsing".

If the process unexpectedly exits due to an unforeseen error, this single-process lock memory might be locked and not unlocked due to the unexpected exit. If you see the error message Process mutex locked, dying. when no other iteration of this process is running, then use the --unlock a.k.a. -u flag to forcibly unlock the process mutex. This flag may also be provided to each invocation of this application to disable the single-process mutex lock feature entirely.

Developer Notes

When scaling the rendered SVG to GdkPixBuf—especially in the context of creating an icon for libnotify—it seemed obvious to me that the appropriate function to reference the allocated pixbuf would be rsvg_handle_get_pixbuf using the RSVG handle containing the rendered graphic. However this function failed to produce a re-scaled image, i.e. the resulting icon was always whatever the intrinsic document scale was despite passing in differing viewbox values. As a workaround, I found that rendering to the cairo surface directly and then producing the pixbuf from the cairo surface was successful in producing a re-scaled image. In short, using the pixbuf from gdk_pixbuf_get_from_surface as the notification icon was sufficient to enable dynamic image scaling. This required linking the gdk main library.