Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
M

mpv-handler

> 编程语言
Open source

A protocol handler for mpv. Use mpv and yt-dlp to play video and music from the websites.

399 stars0 likes1 views
WebsiteGitHub

About

A protocol handler for mpv. Use mpv and yt-dlp to play video and music from the websites.

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:

play-with-mpv

Breaking changes

v0.4.0

To avoid conflicts with the mpv:// protocol provided by mpv.

mpv://...

mpv protocol. This is used for starting mpv from URL handler. The protocol is stripped and the rest is passed to the player as a normal open argument. Only safe network protocols are allowed to be opened this way.

Scheme mpv:// and mpv-debug:// are deprecated, use mpv-handler:// and mpv-handler-debug://.

Require manual intervention

Windows

Run handler-uninstall.bat to uninstall deprecated protocol, and run handler-install.bat to install new procotol.

Linux

If you installed manually, please repeat the manual installation process.

Protocol

Scheme

  • mpv-handler: Run mpv-handler without console window
  • mpv-handler-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):

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) ]
referrer = [ Encoded URL ]

Installation

Linux

Arch Linux

mpv-handler mpv-handler-git

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 and muse90673#122)

    • $ xdg-mime default mpv-handler.desktop x-scheme-handler/mpv-handler
      $ xdg-mime default mpv-handler-debug.desktop x-scheme-handler/mpv-handler-debug
      $ update-desktop-database $HOME/.local/share/applications/
  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

toml
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

Issues· 3 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Rust

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言