Media Controls (MPRIS)

Nokkvi registers on the MPRIS D-Bus interface as org.mpris.MediaPlayer2.nokkvi.instance<pid> — the per-PID suffix is required by the MPRIS spec so concurrent launches don’t fight over the same well-known name. playerctl -p nokkvi still matches both forms because playerctl resolves the -p argument as a name prefix. Any MPRIS-compatible controller — playerctl, your desktop’s media keys, or a window manager keybind — will work.

For verbs MPRIS doesn’t expose (switch-view, love, rate, clear-queue, consume), see the nokkvi CLI.

Supported MPRIS surface

Beyond the basics, Nokkvi wires up the following MPRIS methods and properties:

Method / property	Notes	playerctl example
PlayPause, Play, Pause, Next, Previous	Standard transport.	playerctl -p nokkvi play-pause
Stop	Stops playback.	playerctl -p nokkvi stop
Seek (offset)	Relative seek in microseconds.	playerctl -p nokkvi position 10+
SetPosition	Absolute seek.	playerctl -p nokkvi position 90
LoopStatus	None / Track / Playlist — set directly, doesn’t cycle.	playerctl -p nokkvi loop Track
Shuffle	Toggles random mode when the requested state differs.	playerctl -p nokkvi shuffle On
Volume	Set directly; clamped to 0.0–1.0.	playerctl -p nokkvi volume 0.05+
xesam:title, xesam:artist, xesam:album, mpris:length	Standard track metadata, refreshed on every track change (for radio, ICY title/artist override the station name).	playerctl -p nokkvi metadata
mpris:artUrl	Published as a file:// URI pointing to $XDG_CACHE_HOME/nokkvi/mpris-art-<pid>-<cover_id>.jpg. Nokkvi writes a new file per cover so desktop notifications never reuse a stale image.

CLI

playerctl -p nokkvi play-pause
playerctl -p nokkvi next
playerctl -p nokkvi previous
playerctl -p nokkvi volume 0.05+
playerctl -p nokkvi metadata

Hyprland keybinds

Hyprland’s Lua config is the current binding API — hl.bind(keys, hl.dsp.exec_cmd(cmd), opts?) matches the shape from the upstream example/hyprland.lua. The legacy .conf syntax still works on older Hyprland builds (e.g. stable, non-rolling distros).

Lua (current)

-- ~/.config/hypr/keybinds.lua
local mod_alt = "SUPER + ALT"

hl.bind(mod_alt .. " + space", hl.dsp.exec_cmd("playerctl -p nokkvi play-pause"))
hl.bind(mod_alt .. " + right", hl.dsp.exec_cmd("playerctl -p nokkvi next"))
hl.bind(mod_alt .. " + left",  hl.dsp.exec_cmd("playerctl -p nokkvi previous"))
hl.bind(mod_alt .. " + up",    hl.dsp.exec_cmd("playerctl -p nokkvi volume 0.01+"), { repeating = true })
hl.bind(mod_alt .. " + down",  hl.dsp.exec_cmd("playerctl -p nokkvi volume 0.01-"), { repeating = true })

Legacy .conf

~/.config/hypr/hyprland.conf

bind  = $mainMod ALT, space, exec, playerctl -p nokkvi play-pause
bind  = $mainMod ALT, right, exec, playerctl -p nokkvi next
bind  = $mainMod ALT, left,  exec, playerctl -p nokkvi previous
binde = $mainMod ALT, up,   exec, playerctl -p nokkvi volume 0.01+
binde = $mainMod ALT, down, exec, playerctl -p nokkvi volume 0.01-

{ repeating = true } in Lua matches binde (e for “repeating”) in .conf. Drop the option / use plain bind for one-shot keys.

Other window managers

The playerctl commands above work the same in any WM. Bind them however your compositor handles exec keybinds (e.g. sway’s bindsym, i3’s bindsym, dwm’s config.h).