Play in MPV Setup

Complete the one-time local bridge setup to connect the browser extension with your MPV player.

Installation Steps

Download the Host Package

A minimal ZIP containing only the files needed to register the native host bridge.

Download Host Package

Ensure Requirements are Installed (If Missing)

Install MPV, yt-dlp, and Python 3 on your system. **Important:** You must ensure all three executables are added to your system's PATH during or after installation so they can be detected.

You can install them quickly using the built-in Windows Package Manager (winget) in Command Prompt or PowerShell:

winget install python3 shinchiro.mpv yt-dlp.yt-dlp

⚠️ Important: Chrome inherits PATH only at launch time. If you installed or added tools to PATH while Chrome was already open, you must fully close and reopen Chrome — including from the system tray — before the extension can detect them.
Extract the Host Package

Extract the downloaded ZIP folder to a permanent directory (e.g., inside C:\Users\YourName\play-in-mpv). Keep the folder there, as Chrome will execute the scripts directly from it.
Run the Installer

Open the extracted folder, navigate to the play-in-mpv-host subfolder, and double-click install.bat.
It will open a terminal and prompt you to register the extension. If you installed the extension via the Chrome Web Store, just press Enter to use the default configuration.
Reload Extension & Pages

Once the script completes, reload the extension at chrome://extensions (or restart Chrome), and refresh any open YouTube tabs for the changes to take effect. Setup is complete!

Download the Host Package

A minimal ZIP containing only the files needed to register the native host bridge.

Download Host Package

Install System Requirements (If Missing)

Install mpv, yt-dlp, and python3 on your system. **Important:** All three dependencies must be added to your system's PATH environment variable so the extension can locate and execute them. We recommend installing them using Homebrew (which handles path registration automatically):

brew install mpv yt-dlp python
Extract the Host Package

Extract the downloaded ZIP folder to a permanent directory on your machine. Keep the folder there, as Chrome will run the scripts directly from it.
Run the Python Installer

Open your Terminal inside the extracted play-in-mpv-host directory (or navigate into it, e.g. cd ~/Downloads/play-in-mpv-host), and run the installer:

python3 install.py

If you ran the script without arguments, press Enter at the prompt to use the default Chrome Web Store extension ID.
(If you are using a local developer version, specify your custom 32-character Extension ID as a command-line argument: python3 install.py <YOUR_EXTENSION_ID>)
Reload Extension & Pages

Go to chrome://extensions and reload the extension, then refresh any open YouTube tabs to activate the connection.

Download the Host Package

A minimal ZIP containing only the files needed to register the native host bridge.

Download Host Package

Install System Requirements (If Missing)

Install mpv, yt-dlp, and python3 on your system. **Important:** All three dependencies must be added to your system's PATH environment variable so the extension can locate and execute them. You can use your package manager to install them (example for Debian/Ubuntu):

sudo apt update && sudo apt install mpv yt-dlp python3
Extract the Host Package

Extract the downloaded ZIP folder to a permanent directory on your machine. Keep the folder there, as Chrome will run the scripts directly from it.
Run the Python Installer

Open your Terminal inside the extracted play-in-mpv-host directory (or navigate into it, e.g. cd ~/Downloads/play-in-mpv-host), and run the installer:

python3 install.py

If you ran the script without arguments, press Enter at the prompt to use the default Chrome Web Store extension ID.
(If you are using a local developer version, specify your custom 32-character Extension ID as a command-line argument: python3 install.py <YOUR_EXTENSION_ID>)
Reload Extension & Pages

Go to chrome://extensions and reload the extension, then refresh any open YouTube tabs to activate the connection.

Troubleshooting

Why does the extension popup say "Native messaging host not found"?

This happens when Chrome cannot find the registered native manifest or the path pointing to the launcher script is broken. Make sure you ran the installer script successfully and that the folder you extracted has not been moved. If you moved the folder, simply run the installer script again from its new location.

How do I add a folder to my system PATH?

Windows:

Open Start → System → Advanced system settings → Environment Variables.
Under System variables, select Path and click Edit.
Click New and add the folder containing the executable (e.g. C:\Program Files\mpv).
Click OK to save all dialogs, then restart your browser/terminal.

macOS & Linux:

Determine your active shell by running: echo $SHELL.
For zsh (default on macOS), open ~/.zshrc. For bash (default on most Linux distributions), open ~/.bashrc (or ~/.profile).
Add the following line at the bottom of the file (replace with your folder path):
export PATH="$PATH:$HOME/.local/bin"
Save the file and reload the shell config: source ~/.zshrc (or source ~/.bashrc).

Note for browsers on Linux/macOS: Browsers launched from desktop shortcuts or taskbars run in a system-level session that often ignores terminal configurations (like .bashrc or .zshrc). If the extension popup still warns that a tool is missing from your PATH, you can symlink the binary to a standard system directory that is always on the path (e.g., sudo ln -s ~/.local/bin/yt-dlp /usr/local/bin/yt-dlp), or launch the browser from your terminal.

Why does MPV open but show a playback error?

This is usually caused by an outdated version of yt-dlp. Websites like YouTube update their video streaming protocols frequently. Update your local copy of yt-dlp. If you installed it via Windows Package Manager, run winget upgrade yt-dlp.yt-dlp. If you installed it via Homebrew, run brew upgrade yt-dlp.

How do I uninstall the native bridge?

You can easily remove all trace files and registry entries by running the uninstaller script. In a terminal, run: python3 uninstall.py (or python uninstall.py on Windows) located inside your host directory (play-in-mpv-host for zip package users, or host for repository clones).

I loaded the extension manually (unpacked/developer mode). How do I install the host?

If you are not using the Chrome Web Store version, you need to provide your custom 32-character Extension ID to the installer:

Go to chrome://extensions and enable Developer mode (top-right).
Copy the 32-character ID string shown under the Play in MPV card.
Run the installer with your ID:
• On Windows, run install.bat and paste your ID when prompted.
• On macOS/Linux, run python3 install.py YOUR_EXTENSION_ID in terminal.