API Media Player (PWA)

This is a small web-first PWA prototype for browsing media from a Hydrus client via its Client API. The app ships with a demo library and routes playback to external players such as mpv or VLC instead of using an in-browser player.

Quick start (PowerShell)

1. Install dependencies:

pwsh -c "npm install"

2. Run the dev server:

pwsh -c "npm run dev"

Open http://localhost:5173 in your browser to test the PWA and external-player launch flow.

Configuring Hydrus

Create a .env file in the project root (not committed) with these variables if you want to connect to a real Hydrus instance:

VITE_HYDRUS_HOST=http://localhost
VITE_HYDRUS_PORT=45869
VITE_HYDRUS_API_KEY=
VITE_HYDRUS_SSL=false

Note: browsers cannot attach custom Hydrus API headers to direct media URLs. If your Hydrus server requires header-based authentication for file access, use a reverse proxy or another trusted layer that can mint playable URLs for your external player.

Settings UI & quick test

On first run the app will seed a sample server entry for 192.168.1.128:45869 so you can quickly add your API key and test connectivity via the app's Settings (top-right gear). Open Settings, choose the server, paste your Hydrus-Client-API-Access-Key (if needed), and click Test connection. The test reports whether the server is reachable, whether authentication is required (HTTP 401/403), and whether byte-range requests are supported (needed for seeking).

If you get a CORS or network error in the browser, consider running a reverse proxy that adds proper CORS headers or packaging the app with Capacitor to avoid browser CORS limitations.

Violentmonkey mpv userscript

If you want desktop or Android browsers to hand media straight to mpv instead of the in-browser player, install the userscript at:

/userscripts/api-media-player-open-in-mpv.user.js

Examples:

http://localhost:5173/userscripts/api-media-player-open-in-mpv.user.js
http://127.0.0.1:4173/userscripts/api-media-player-open-in-mpv.user.js

What it does:

• On desktop, direct media playback is redirected to mpv-handler://...
• On Android, direct media playback is redirected to the mpv app via intent://...
• It only activates by default on localhost, loopback, RFC1918 LAN IPs, and .local / .lan hosts so it does not hijack unrelated public websites

Notes:

• Desktop requires mpv-handler to be installed and registered.
• Android requires mpv-android (is.xyz.mpv) to be installed.
• The script intercepts direct file URLs and Hydrus /get_files/file playback requests before the browser player starts.

Desktop setup for mpv-handler

Official project:

https://github.com/akiirui/mpv-handler

Latest releases:

https://github.com/akiirui/mpv-handler/releases

Windows:

1. Install mpv itself first if you do not already have it.
2. Download the latest Windows archive:

https://github.com/akiirui/mpv-handler/releases/latest/download/mpv-handler-windows-amd64.zip

3. Extract it somewhere permanent.
4. Edit config.toml in that folder and set the path to your mpv executable. If you use yt-dlp, set that path too.
5. Register the protocol with either the upstream batch file or the PowerShell installer in this repo.

Upstream batch option:

Set-Location C:\path\to\mpv-handler
.\handler-install.bat

PowerShell alternative from this repo:

Set-Location C:\Forgejo\API-MediaPlayer
powershell -ExecutionPolicy Bypass -File .\scripts\install-mpv-handler.ps1 -InstallRoot 'C:\path\to\mpv-handler'

Or from an already elevated PowerShell window:

& 'C:\Forgejo\API-MediaPlayer\scripts\install-mpv-handler.ps1' -InstallRoot 'C:\path\to\mpv-handler'

If you copied config.toml, mpv-handler.exe, and mpv-handler-debug.exe into the same folder as scripts/install-mpv-handler.ps1, you can also run it without -InstallRoot:

& 'C:\Forgejo\API-MediaPlayer\scripts\install-mpv-handler.ps1'

What the PowerShell installer does:

• validates that config.toml, mpv-handler.exe, and mpv-handler-debug.exe exist
• removes old mpv:// and existing mpv-handler:// protocol keys unless you tell it not to
• registers mpv-handler:// and mpv-handler-debug:// in the Windows registry
• uses the mpv path from config.toml as the icon when possible, otherwise falls back to mpv-handler.exe

Requirements for the PowerShell installer:

• run it from an elevated PowerShell window
• point -InstallRoot at the extracted mpv-handler folder
• do not dot-source it from the repo root without -InstallRoot, because this repo does not contain the extracted mpv-handler binaries

Linux:

1. Download the latest Linux archive:

https://github.com/akiirui/mpv-handler/releases/latest/download/mpv-handler-linux-amd64.zip

2. Extract it.
3. Copy mpv-handler to $HOME/.local/bin.
4. Copy mpv-handler.desktop and mpv-handler-debug.desktop to $HOME/.local/share/applications/.
5. Make the binary executable:

chmod +x $HOME/.local/bin/mpv-handler

6. Register the protocol handlers:

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

7. Add $HOME/.local/bin to PATH if needed.
8. Optionally copy and edit config.toml for your mpv and yt-dlp paths.

After setup, clicking an mpv-handler://... link in the browser should launch mpv instead of showing an unknown protocol error.

Next steps

• Wire the UI to a real Hydrus instance (update src/api/hydrusClient.ts).
• Add Capacitor for native packaging and secure storage for API keys.
• Improve Hydrus browsing and filtering UX for large libraries.

If you want, I can run npm install and start the dev server now and confirm the app is reachable locally. Let me know and I'll proceed.