# 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.