112 lines
3.7 KiB
Markdown
112 lines
3.7 KiB
Markdown
# mpv-handler setup
|
|
|
|
This folder contains the desktop playback helper assets used by API Media Player.
|
|
|
|
## What is in this folder
|
|
|
|
- `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:
|
|
|
|
```bash
|
|
npm run setup:mpv-handler
|
|
```
|
|
|
|
Remove the registration later with:
|
|
|
|
```bash
|
|
npm run uninstall:mpv-handler
|
|
```
|
|
|
|
### Linux
|
|
|
|
1. Download and extract the upstream Linux release:
|
|
|
|
```text
|
|
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.
|
|
|
|
2. Point the helper at that extracted folder:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-mpv-handler.ps1 -InstallRoot .\scripts
|
|
```
|
|
|
|
### Linux
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
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.
|