138 lines
4.6 KiB
Markdown
138 lines
4.6 KiB
Markdown
# 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
|
|
|
|
- Start the app with `npm start` and connect a Hydrus server from the web settings screen
|
|
- Use `npm run dev` when you want the live-reload development server
|
|
- Add one or more Hydrus clients 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 app:
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
4. Open the local URL printed in the terminal. By default it starts on `http://localhost:4173`, but it will move to the next free port if that one is already in use.
|
|
|
|
On a fresh install the app opens the Hydrus server settings first. Add your host, port, and API key there, test the connection, then save the server before browsing the library. Playback itself is always external, so actual media launch still depends on the platform-specific player flow below.
|
|
|
|
`npm start` now builds the app and serves the production output, which is the safer default for devices like Raspberry Pi. Use `npm run dev` only when you specifically want the Vite development server and live reload.
|
|
|
|
## 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 entirely from Settings inside the app. Nothing is preconfigured on first launch, so you enter the Hydrus connection details yourself.
|
|
|
|
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:4173/userscripts/api-media-player-open-in-mpv.user.js
|
|
http://127.0.0.1:4173/userscripts/api-media-player-open-in-mpv.user.js
|
|
```
|
|
|
|
If preview chooses a different port because `4173` is busy, use that same port for the userscript URL too.
|
|
|
|
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 start
|
|
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.
|