goyimnose/api-HydrusNetwork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update installation instructions and add mpv handler setup script

Browse Source
This commit is contained in:
Nose
2026-04-18 18:12:17 -07:00
parent 0bd3bff92d
commit 3bd335cfb5
9 changed files with 982 additions and 413 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+91 -128
View File
@@ -1,45 +1,107 @@
# API Media Player (PWA)
# API Media Player
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.
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.
## Quick start (PowerShell)
## What works today
1. Install dependencies:
- 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://`
```powershell
pwsh -c "npm install"
## Fast start
1. Install Node.js 20 or newer.
2. Install dependencies:
```bash
npm install
```
2. Run the dev server:
3. Start the dev server:
```powershell
pwsh -c "npm run dev"
```bash
npm run dev
```
Open `http://localhost:5173` in your browser to test the PWA and external-player launch flow.
4. Open `http://localhost:5173`.
## Configuring Hydrus
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.
Create a `.env` file in the project root (not committed) with these variables if you want to connect to a real Hydrus instance:
## 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
```
> 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.
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.
### Settings UI & quick test
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.
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).
## Playback setup by device
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.
### Windows desktop
## Violentmonkey mpv userscript
1. Install `mpv` and optionally `yt-dlp`.
2. Open an elevated PowerShell or Windows Terminal.
3. From the repo root, run:
If you want desktop or Android browsers to hand media straight to mpv instead of the in-browser player, install the userscript at:
```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
@@ -52,117 +114,18 @@ 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:
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://...`.
- 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
## Useful commands
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
```bash
npm run dev
npm run build
npm run preview
npm run typecheck
npm run setup:mpv-handler -- --help
```
Latest releases:
## More detail
```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.
See `scripts/README.md` for the helper script behavior, flags, and the Windows/Linux manual fallbacks.