Open YouTube (And More) Videos From Your Web Browser With mpv [Firefox, Chrome]

play with mpv handler

mpv-handler is a protocol handler for mpv written in Rust which, accompanied by a browser userscript, allows users to open videos from YouTube, Twitch and Bilibili with mpv.

It works with both Firefox and Chromium-based web browsers on Linux and Microsoft Windows, without making use of any background service.

With everything set up, visiting a video on one of the websites mentioned above, a new button is displayed on the video web page (in the bottom left-hand side corner), allowing you to play that video using mpv, a free and open source media player.

From its settings, you can control the video quality and if you want to pass cookies or not, useful to watch member videos.

Since mpv makes use of youtube-dl to play the videos, and youtube-dl supports hundreds of websites, you can add support for other video sharing websites yourself, by editing the "Play with mpv" user script.

Using this is especially useful if your web browser doesn't support hardware-accelerated video playback. In this case, playing the video in mpv (with hardware-acceleration enabled) should result in smoother playback of high quality videos, as well as lower CPU usage (and thus, less battery draining). Using this also means that you won't get any in-video ads.

Related: How To Enable Hardware Accelerated Video Decode In Google Chrome, Brave, Vivaldi And Opera Browsers On Debian, Ubuntu Or Linux Mint

mpv-handler isn't something new. There are various alternatives, like Play with MPV for example. The difference with most alternatives, though, is that mpv-handler works with both Firefox and Chromium-based browsers, and it doesn't require using a server.

Install mpv-handler on Linux

1. Download the latest from GitHub, extract the archive and copy mpv-handler to ~/.local/bin/ and mpv-handler.desktop to ~/.local/share/applications/ and config.toml to ~/.config/mpv-handler

On Arch Linux / Manjaro you can install mpv-handler from AUR.

For other Linux distributions, you can do all of this from the command line, by using:


unzip -d mpv-handler

mkdir ~/.local/bin/ #just in case

mkdir ~/.local/share/applications/ #just in case

cp mpv-handler/mpv-handler ~/.local/bin/

cp mpv-handler/mpv-handler.desktop ~/.local/share/applications/

mkdir ~/.config/mpv-handler

cp mpv-handler/config.toml ~/.config/mpv-handler/

It's important to note that you need to have ~/.local/bin in your PATH. If it's not already, add PATH="$HOME/.local/bin:$PATH" to ~/.profile (and restart the session).

2. Make sure you have mpv and the latest youtube-dl installed on your system.

mpv is available in the official repositories for most Linux distributions, so install it from there.

Because websites change frequently and break youtube-dl, I recommend removing youtube-dl if you have it installed from your Linux distributions repositories (unless it's constantly updated), and install it using PIP instead:

python3 -m pip install --user --upgrade youtube-dl

Use the same command to upgrade youtube-dl.

3. Install Violentmonkey or Tampermonkey userscript manager addon for your web browser.

Greasemonkey 4.0+ is not supported by the "Play with mpv" user script, so you'll need to install either Violentmonkey or Tampermonkey addons:

4.  Install the "Play with mpv" userscript.

Visit the "Play with mpv" userscript page and click the install button.

5. Register the new URL scheme handler with XDG.

You should now see a new button in the bottom left-hand corner of a supported website like YouTube, which allows playing the current video in mpv. 

But this didn't work for me out of the box. I had to register the new URL scheme handler with XDG to get this to work, even though this is not mentioned in the mpv-handler documentation.

This can be done by using the following command:

xdg-mime default mpv-handler.desktop x-scheme-handler/mpv

And that's it. Open a video on YouTube and you should see a new floating button in the bottom left-hand side of the website. Click it and the web browser should ask you if you want to allow the site to open mpv links:


Play with mpv dialog Firefox


Chromium-based web browsers (I'm using Brave browser in the screenshot below):

Play with mpv chromium-based dialog

Once you open the link, the video should open with mpv media player. Note that this also opens a new terminal window. You need to leave it open while you watch the video. When you close mpv, the terminal window will automatically close too.

Also, in both browser cases, you can check the box to always use mpv-handler to open mpv links.

For how to install this for Microsoft Windows, see this page.

You might also like: mpv-Based Haruna Video Player 0.6.0 Adds MPRISv2 And YouTube Playlists Support