How to Bind Media Keys in mpv?

This article provides a quick overview of how the mpv media player integrates with system media keys for play, pause, next, and previous actions. By default, mpv includes built-in support for standard media keys on most operating systems, but it can also be customized via the input.conf configuration file or extended through third-party scripts. Below, we explore how mpv handles these keys natively, how to manually configure them, and how to troubleshoot common integration issues across Windows, macOS, and Linux.

Native Media Key Support in mpv

Out of the box, mpv is designed to recognize standard multimedia keys handled by your operating system’s window manager or desktop environment. When you press a media key, your OS sends a specific hardware scan code or media key event, which mpv maps to its internal playback commands.

• PLAYPAUSE: Toggles between pausing and resuming the video or audio.
• NEXT: Skips forward to the next item in the playlist.
• PREV: Skips backward to the previous item in the playlist.
• STOP: Halts playback and closes the file.

Customizing Media Keys via input.conf

If your system’s media keys are not working automatically, or if you want to remap them to different actions, you can explicitly define them in mpv’s key binding configuration file, input.conf. This file is typically located in your mpv configuration directory (e.g., %APPDATA%\mpv\ on Windows or ~/.config/mpv/ on Linux and macOS).

You can add the following lines to map the standard media keys:

XF86AudioPlay        cycle pause
XF86AudioPause       set pause yes
XF86AudioNext        playlist-next
XF86AudioPrev        playlist-prev

Note: The key names prefixed with XF86 are standard for Linux (X11/Wayland) and are frequently recognized by mpv across other platforms as well. If you are on Windows or macOS and the XF86 prefixes fail to register, you can use the literal key names like PLAYPAUSE, NEXT, and PREV.

Platform-Specific Integration and Troubleshooting

Depending on your operating system, background applications or desktop environments might intercept media keys before they ever reach mpv.

Linux (GNOME, KDE, MATE)

On Linux, desktop environments use the MPRIS D-Bus interface to control media players globally. Because mpv does not feature native MPRIS support out of the box, background media key demons might ignore it. To bridge this gap, users often utilize a Lua script like mpv-mpris. This script allows mpv to communicate with the system’s media daemon, enabling global system keys to control mpv even when it is minimized or running in the background.

Windows

On Windows, mpv generally hooks into the Windows media key APIs automatically when the player window is active. However, if another application (such as Spotify, web browsers like Chrome, or Discord) has global hooks enabled, it might steal the media key focus. Running mpv with administrator privileges can sometimes resolve focus conflicts, though configuring global hotkeys via external tools like AutoHotkey is a more robust alternative for background control.

macOS

On macOS, the OS native media key daemon handles play/pause requests globally, often routing them to Apple Music or QuickTime. To ensure mpv captures these keys reliably, users often rely on third-party application wrappers or input managers that force the operating system to pass media key events directly to the active open-source media player.