setup-mpv-handler.mjs: cross-platform helper used by npm run setup:mpv-handler
install-mpv-handler.ps1: Windows protocol registration script
uninstall-mpv-handler.ps1: Windows protocol cleanup script
handler-install.bat and handler-uninstall.bat: thin Windows wrappers for the PowerShell scripts
config.toml: template used when the helper needs to create or refresh an mpv-handler config
mpv-handler.exe and mpv-handler-debug.exe: bundled Windows handler binaries

Recommended commands

Windows

Run from an elevated PowerShell or Windows Terminal:

npm run setup:mpv-handler

Remove the registration later with:

npm run uninstall:mpv-handler

Linux

Download and extract the upstream Linux release:

https://github.com/akiirui/mpv-handler/releases/latest/download/mpv-handler-linux-amd64.zip

The official upstream Linux release is currently amd64 only. On Raspberry Pi or other ARM Linux systems, build or obtain a compatible mpv-handler binary first and point --root at that extracted folder.

Point the helper at that extracted folder:

npm run setup:mpv-handler -- --root /path/to/extracted/mpv-handler-linux-amd64

Run this on the Linux desktop client that should handle mpv-handler://, not on the machine that is only serving the web app.

The helper copies files into ~/.local/bin and ~/.local/share/applications, writes config to ~/.config/mpv-handler/config.toml (or $XDG_CONFIG_HOME/mpv-handler/config.toml), and runs xdg-mime for both protocol handlers.

Useful flags

npm run setup:mpv-handler -- --help
npm run setup:mpv-handler -- --root /path/to/mpv-handler
npm run setup:mpv-handler -- --mpv /path/to/mpv
npm run setup:mpv-handler -- --ytdl /path/to/yt-dlp
npm run setup:mpv-handler -- --skip-config
npm run setup:mpv-handler -- --dry-run

--root points at the extracted upstream mpv-handler folder. On Windows it is optional because this repo already ships the handler files under scripts/. On Linux it is normally required.

What the helper does

Windows

finds the bundled handler files in this folder unless you override --root
creates or updates config.toml
tries to detect mpv and yt-dlp from PATH
registers mpv-handler:// and mpv-handler-debug:// through the PowerShell installer

Linux

validates the extracted upstream release layout
creates or updates config.toml
copies the handler binary to ~/.local/bin/mpv-handler
copies the desktop entries to ~/.local/share/applications
rewrites Exec= entries to the installed absolute binary path
runs xdg-mime default ... for both schemes

Manual fallback

If you would rather install without the helper:

Windows

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-mpv-handler.ps1 -InstallRoot .\scripts

Linux

cp /path/to/mpv-handler/mpv-handler ~/.local/bin/mpv-handler
cp /path/to/mpv-handler/mpv-handler.desktop ~/.local/share/applications/
cp /path/to/mpv-handler/mpv-handler-debug.desktop ~/.local/share/applications/
chmod +x ~/.local/bin/mpv-handler
xdg-mime default mpv-handler.desktop x-scheme-handler/mpv-handler
xdg-mime default mpv-handler-debug.desktop x-scheme-handler/mpv-handler-debug

Upstream project

Upstream mpv-handler releases and source:

https://github.com/akiirui/mpv-handler
https://github.com/akiirui/mpv-handler/releases

This repo uses the upstream protocol scheme and binaries; the docs here only describe the setup flow for API Media Player.