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, queue-push, queue-pull), 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+`
`Raise`	`CanRaise` is true. Reopens a window closed to the tray, or flags an open one for attention; the same action as `nokkvi show`.
`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>_<hash>.jpg`. Nokkvi writes a new file per cover so desktop notifications never reuse a stale image. See What art gets published.

What art gets published

Desktop shells keep showing the last image when mpris:artUrl is missing, so Nokkvi always publishes the key while something is current — otherwise a radio station would sit under the previous queue song’s cover. What it points at, in order:

A song — its cover, fetched once per track change; if that fetch fails, the Nokkvi icon.
A radio station — the station’s uploaded logo; failing that, the stream’s ICY StreamUrl when it’s an http(s) address (published verbatim, never fetched); failing that, the Nokkvi icon.

The icon placeholder is written once per process as mpris-art-<pid>-placeholder.jpg. Not Playing publishes no art at all. With no writable cache directory only a stream URL can go out, and a failed write is retried after a minute rather than on every tick.

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)
Legacy .conf

-- ~/.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 })

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).