Dark Volume OSD (PyQt6 / PyQt5)

A slick, black, shiny on-screen display (OSD) for system volume on Linux.

Lock keys integration: Num, Caps Scroll.

ALT + p && Keyboard toggle play/pause: Playerctl integration for toggle play/pause

	- Does not include the function key related action due to Wayland limitations.
	
	
	- Requires playerctl supporting media player.

Default theme:

Alternative themes:

Features

Works with PyQt6 or PyQt5 (auto-fallback).

Listens to media keys and Alt+↑ / Alt+↓ / Alt+M via evdev.

Controls all active PulseAudio/PipeWire sinks (every playback device).

Glossy black progress bar; centered near bottom; auto-hides.

Graceful fallback when window opacity/animations aren’t supported.

Multiple themes to choose from.

Requirements

Debian/Ubuntu packages

Pick one Qt binding (PyQt6 or PyQt5):

sudo apt update

PyQt6 route:

	sudo apt install -y python3-pyqt6 python3-evdev pulseaudio-utils udev playerctl

OR PyQt5 route:

	sudo apt install -y python3-pyqt5 python3-evdev pulseaudio-utils udev playerctl

Run:

	sudo bash install_rule.sh #To install the needed rule.
	sudo cp osd.py /usr/share/
	sudo chmod +x  /usr/share/osd.py
	python3 systemd.py
	systemctl --user start volume-osd  # Start the service
	systemctl --user enable volume-osd  # Enable the service during system startup
	systemctl --user status volume-osd  # Status of the service

Uninstall: sudo bash uninstall_rule.sh # To uninstall the needed rule. sudo rm osd.py /usr/share/

Usage

• ALT arrow up == Volume up.
• ALT arrow down == Volume down.
• ALT m == Volume mute/unmute.

Using themes

How to use

Default theme (dark): python3 osd.py

Select a theme:

	python3 osd.py --theme=blue   # futuristic blue

	python3 osd.py --theme=grey   # grey worn-out

	python3 osd.py --theme=wood   # wood-like

	python3 osd.py --theme=dark   # dark this is the default

Customizing via Systemd

	mkdir -p ~/.config/volume-osd
	printf 'theme=blue\n' > ~/.config/volume-osd/osd.conf
	systemctl --user restart volume-osd

Tip: On Wayland I have found that the best way to get the osd working or deactivated is to reboot after running the scripts.

Running the Volume OSD via .xinitrc or .config/openbox/autostart etc. is also possible by adding the line: python3 osd.py &

Copyright (c) 2025 JJ Posti <techtimejourney.net> This program comes with ABSOLUTELY NO WARRANTY; for details see: http://www.gnu.org/copyleft/gpl.html.
This is free software, and you are welcome to redistribute it under GPL Version 2, June 1991")