English | 简体中文 | 繁体中文

mpv handler

A protocol handler for mpv, written by Rust.

Use mpv and yt-dlp to play video and music from the websites.

Please use it with userscript:

Protocol

Scheme

• mpv: Run mpv-handler without console window
• mpv-debug: Run mpv-handler with console window to view outputs and errors

Plugins

• play: Use mpv player to play video

Encoded Data

Use URL-safe base64 to encode the URL or TITLE.

Replace / to _, + to - and remove padding =.

Example (JavaScript):

let data = btoa("https://www.youtube.com/watch?v=Ggkn2f5e-IU");
let safe = data.replace(/\//g, "_").replace(/\+/g, "-").replace(/\=/g, "");

Parameters (Optional)

cookies = [ www.domain.com.txt ]
profile = [ default, low-latency, etc... ]
quality = [ 2160p, 1440p, 1080p, 720p, 480p, 360p ]
v_codec = [ av01, vp9, h265, h264 ]
v_title = [ Encoded Title ]
subfile = [ Encoded URL ]
startat = [ Seconds (float) ]

Installation

Linux

• Arch Linux

  \

Manual installation

1. Download latest Linux release

2. Unzip the archive

3. Copy mpv-handler to $HOME/.local/bin

4. Copy mpv-handler.desktop to $HOME/.local/share/applications/

5. Copy mpv-handler-debug.desktop to $HOME/.local/share/applications/

6. Set executable permission for binary

   • $ chmod +x $HOME/.local/bin/mpv-handler

7. Register xdg-mime (thanks for the linuxuprising reminder)

   • $ xdg-mime default mpv-handler.desktop x-scheme-handler/mpv
     $ xdg-mime default mpv-handler-debug.desktop x-scheme-handler/mpv-debug

8. Add $HOME/.local/bin to your environment variable PATH

9. Optional: Copy config.toml to $HOME/.config/mpv-handler/config.toml and configure

Windows

Windows users need to install manually.

Manual installation

1. Download latest Windows release
2. Unzip the archive to the directory you want
3. Run handler-install.bat to register protocol handler
4. Edit config.toml and set mpv and ytdl path

Configuration

mpv = "/usr/bin/mpv"
# Optional, Type: String
# The path of mpv executable binary
# Default value:
# - Linux: mpv
# - Windows: mpv.com

ytdl = "/usr/bin/yt-dlp"
# Optional, Type: String
# The path of yt-dlp executable binary

proxy = "http://example.com:8080"
# Optional, Type: String
# HTTP(S) proxy server address

# For Windows users:
#   - The path can be "C:\\folder\\some.exe" or "C:/folder/some.exe"
#   - The path target is an executable binary file, not a directory