api-HydrusNetwork/README.md

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

```powershell
pwsh -c "npm install"
```

2. Run the dev server:

```powershell
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:

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

Examples:

```text
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:

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

Latest releases:

```text
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:

```text
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:

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

PowerShell alternative from this repo:

```powershell
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:

```powershell
& '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](scripts/install-mpv-handler.ps1), you can also run it without `-InstallRoot`:

```powershell
& '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:

```text
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:

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

6. Register the protocol handlers:

```text
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.