Fixing media keys in Sway
Posted on 2026-04-19
TL;DR – Jump to the bottom to find the solution I installed Sway, my favorite Wayland compositor, on Debian Trixie several weeks ago. There were bumps along the way, as Wayland does things very differently than the X display server tha I'm used to… but overall I have been pleased with the results. That said, there has been one issue that had been a thorn in my side: my media keys did not work.
Media keys – play/pause, stop, next, previous. I had these function keys on my keyboard, and they became second nature to control whatever media I was enjoying. Podcasts, tv or movies from streaming services, videos on YouTube or Nebula, could all be paused or resumed whenever I want with a couple keystrokes.
These keys were nearly "automatic" under i3 and other X window managers, but it took more explicit steps to enable on Sway. This may work on other wayland compositors, but you'll have to tweak it to apply.
Using playerctl for media key behavior
First step is to install the playerctl app. It's in the Debian repositories, so apt install playerctl should work fine on Ubuntu as well.
Next, you need to launch the playerctl daemon with the playerctl daemon command when you start your Wayland session. I have a script to start sway, so I added a line there.
The third and final step is to configure the media keys, via your compositor, to call playerctl commands whenever you press the media keys. Pressing "play/pause" calls playerctl play-pause, pressing the "next" button calls playerctl next, etc.
Here are my sway configurations to set up the media keys I care about:
bindsym --locked XF86AudioPlay exec playerctl play-pause
bindsym --locked XF86AudioNext exec playerctl next
bindsym --locked XF86AudioPrev exec playerctl previous
Depending on how your compositor manages keys, you may have to tweak this a bit. Try running the playerctl commands in a terminal to test their functionality, and then you can try binding the media keys from there.
Tags: troubleshooting sway wayland