chvol

chvol is a utility written in Python that provides advanced volume control, media management, and DND (Do Not Disturb) functionality for Linux desktop environments, particularly tailored for KDE Plasma running under PipeWire.

The tool offers both simple command-line volume adjustment and a daemon mode for automatic actions based on the screen lock status.

---

✨ Features

• Fine-Grained Volume Control: Adjusts the volume of a specified audio output device node (e.g., a specific headset or monitor).
• Over-Amplification Support: Allows volume adjustment above 100% up to 150% (configurable).
• KDE Integration: Triggers the native KDE Plasma Volume OSD (On-Screen Display) and plays a volume change sound.
• Lock Screen Automation (Daemon Mode): Automatically pauses media (MPRIS players), mutes the primary audio device, and activates Do Not Disturb when the screen locks, then reverts these changes upon unlock.
• Configuration File: Uses a TOML configuration file (chvol.conf) for persistent settings like default device, volume amount, sound path, and MPRIS player exclusions.

---

🚀 Installation and Setup

Prerequisites

1. Python 3
2. PipeWire (for wpctl and pactl)
3. DBus bindings (e.g., python3-dbus, python3-gi)
4. KDE Plasma (for OSD and DND shortcuts)
5. Required Python Library:

pip install tomli

Configuration File Setup

The tool loads configuration from the XDG config path: $HOME/.config/chvol/chvol.conf.

1. mkdir -p "$HOME/.config/chvol"
   

2. Create the configuration file chvol.conf (see Configuration section below).

📝 Usage

Single-Run Mode (run)

Use the run command for immediate actions, typically bound to keyboard shortcuts. The script file should be executable (e.g., named chvol or linked to a directory in your PATH).

Action	Command Example	Description
Volume Up	chvol run +	Increases volume by the default amount (5.0%).
Volume Down	chvol run - 2.5	Decreases volume by 2.5%.
Over-Amplify	chvol run up --over	Allows volume to exceed 100% (up to 150%).
Mute/Unmute	chvol run mute	Toggles the system mute state via KDE shortcut.
DND Toggle	chvol run dnd	Toggles KDE's Do Not Disturb mode.
Media Pause	chvol run pause	Sends a pause signal to all non-excluded MPRIS players.
Media Play	chvol run play	Sends a play signal to media players.

Daemon Mode (watch)

The watch command runs as a background process, listening for screen lock/unlock signals. This is ideal for running as a systemd --user service.

/path/to/chvol.py watch

Example Daemon Service (systemd)

For persistent lock-screen automation, create a user service file (e.g., ~/.config/systemd/user/chvol.service):

[Unit]
Description=chvol Lock Screen Daemon
Requires=plasma-plasmashell.service
After=plasma-plasmashell.service

[Service]
ExecStart=/usr/bin/python3 /path/to/chvol.py watch
Restart=on-failure
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

Reload, enable, and start the service:

systemctl --user daemon-reload
systemctl --user enable chvol.service
systemctl --user start chvol.service

⚙️Configuration File (chvol.conf)

The configuration file uses the TOML format and should be placed at $HOME/.config/chvol/chvol.conf. Command-line arguments always override any settings found in this file.

Example chvol.conf

[settings]
# Mandatory: The internal identifier of your audio output device node.
# Find this value in the "Name" or similar field of your primary sink using 'pactl list sinks'.
audio_device = "alsa_output.usb-SteelSeries_Arctis_Nova_Pro_Wireless-00.analog-stereo"

# Optional: Default percentage amount to adjust volume by when using 'chvol run +/-'.
volume_adjust = 2.5 # Defaults to 5.0

# Optional: Full path to the sound file to play when the volume is changed.
volume_sound = "/usr/share/sounds/freedesktop/stereo/audio-volume-change.oga"

[media]
# Optional: An array of MPRIS bus names to ignore when sending pause/play signals.
mpris_exclusions = [
    "org.mpris.MediaPlayer2.kdeconnect",
    "org.mpris.MediaPlayer2.plasma-browser-integration",
    # "org.mpris.MediaPlayer2.spotify" # Example: uncomment to exclude Spotify
]

Section	Option	Command Line Override	Description
[settings]	audio_device	--device or -d	The exact PipeWire/PulseAudio sink name to control.
[settings]	volume_adjust	amount argument	Default volume change in percent for chvol run +/-.
[settings]	volume_sound	--sound or -s	Path to the sound file played with the volume OSD.
[media]	mpris_exclusions	N/A	List of MPRIS bus names to ignore for media control.