api-HydrusNetwork/README.md

# API Media Player

API Media Player is a web-first PWA for browsing Hydrus media and handing playback off to native apps instead of an in-browser player.

## What works today

- Browse the seeded demo library right after `npm install` and `npm run dev`
- Connect to a real Hydrus client from the Settings page or a local `.env` file
- Launch playback in native apps:
	- Windows and Linux desktop: `mpv` through `mpv-handler://`
	- Android: `mpv-android` through `intent://`
	- iPhone and iPad: VLC through `vlc-x-callback://`

## Fast start

1. Install Node.js 20 or newer.
2. Install dependencies:

```bash
npm install
```

3. Start the dev server:

```bash
npm run dev
```

4. Open `http://localhost:5173`.

The app includes sample data, so you can verify the UI immediately. Playback itself is always external, so browsing works before player setup, but actual media launch depends on the platform-specific player flow below.

## Connect Hydrus (optional)

If you want real library data, duplicate `.env.example` as `.env` and fill in your Hydrus values:

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

You can also add or edit servers from Settings inside the app. The first run seeds a sample server entry so you only need to supply your `Hydrus-Client-API-Access-Key` and test the connection.

Browsers cannot attach custom Hydrus API headers to direct media URLs. If your Hydrus setup requires header-based authentication for file access, put a trusted reverse proxy in front of it or provide playable URLs another way.

## Playback setup by device

### Windows desktop

1. Install `mpv` and optionally `yt-dlp`.
2. Open an elevated PowerShell or Windows Terminal.
3. From the repo root, run:

```bash
npm run setup:mpv-handler
```

The repo already includes the Windows `mpv-handler` binaries under `scripts/`, so the helper script can:

- reuse the bundled handler files
- detect `mpv` and `yt-dlp` from `PATH` when possible
- update `scripts/config.toml`
- register `mpv-handler://` and `mpv-handler-debug://`

To remove the registration later:

```bash
npm run uninstall:mpv-handler
```

### Linux desktop

1. Install `mpv` and optionally `yt-dlp`.
2. Download and extract the latest upstream Linux release:

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

3. Run the helper against the extracted folder:

```bash
npm run setup:mpv-handler -- --root /path/to/extracted/mpv-handler-linux-amd64
```

On Linux the helper copies the binary and desktop files into `~/.local`, writes `config.toml`, and runs `xdg-mime` for both protocol handlers.

### Android

Install `mpv-android` (`is.xyz.mpv`). No extra handler setup is needed.

### iPhone / iPad

Install VLC for iOS. The app sends playback to `vlc-x-callback://` automatically.

### macOS desktop

The app can still browse Hydrus and demo content on macOS, but this repo does not currently automate `mpv-handler://` registration for desktop macOS. If you already have a compatible custom protocol handler installed, the desktop playback flow will use it. Otherwise, use another supported playback platform for now.

## Optional userscript for direct media URLs

If you want direct file loads in the browser to jump into `mpv` before the page player starts, install the userscript served by this app:

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

It only activates on `localhost`, loopback, RFC1918 LAN IPs, and `.local` or `.lan` hosts. On desktop it redirects to `mpv-handler://...`; on Android it redirects to the `mpv` app through `intent://...`.

## Useful commands

```bash
npm run dev
npm run build
npm run preview
npm run typecheck
npm run setup:mpv-handler -- --help
```

## More detail

See `scripts/README.md` for the helper script behavior, flags, and the Windows/Linux manual fallbacks.