A keybindable application to modify volume levels on audio sinks within PulseAudio with dunst-centric libnotify integrations to display volume notifications in dunst performantly. 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 use this application's Xresource support and my project wpal which exports color palettes generated from the desktop wallpaper to Xresources.
Succinctly:
cd ./src/
make && sudo make installmake 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
Stray positional arguments without a preceding flag will be parsed as arguments to --volume, e.g.
pavol-dunst 5 # == pavol-dunst -v 5
pavol-dunst +5 # == pavol-dunst -v +5
pavol-dunst -- -5 # == pavol-dunst -v -5
# '-5' without '--' would parse as a flag '-5' and throw an error, '--' indicates no more flag argsSee 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.
The user will need to have an appropriate configuration in their dunst config, most commonly $HOME/.config/dunst/dunstrc
The notification generated by this binary will have the category volume (this can be modified in notification.h by changing NOTIFICATION_LITERAL_CATEGORY).
As of writing, I am using dunst version 1.8.1 which supports hide_text to hide the notification body, and icon_position = top to display the icon top and centered within the notification window.
I use the following configuration section in my dunstrc to achieve the notification style featured in the screenshots:
[volume]
category="volume" # Match criteria
format = %b
icon_position = top
hide_text = yes
alignment = center
fullscreen = show
history_ignore = yes
min_icon_size=64For extra usage details please see the Shared Memory Singleton-Process Mutex Lock, PulseAudio Support, and Xresource Support sections below.
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 toggleIn theory this application supports adding custom icons, simply modify the .svg files in svg/. However, this was not intended as a first-class feature so there is no minification pipeline to reduce the embedded SVG string body sizes (the user will need to manually minify their SVGs). This application renders icon colors dynamically by implementing CSS classes referenced in the CSS stylesheet that get passed to the RSVG rendering backend. To reduce compiled binary size, these CSS classes are currently named with just a single character. 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.
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 sound output you are expecting. This is currently a limitation and the user will need to modify the default sink using a different application (probably pavucontrol).
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")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.
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.