52 lines
2.4 KiB
Markdown
52 lines
2.4 KiB
Markdown
# CleanStream Media Connector Reference
|
|
|
|
Self-hosted reference implementation of the v1 connector protocol.
|
|
|
|
```sh
|
|
PAIRING_SECRET='choose-a-long-secret' MEDIA_ROOT='/path/to/videos' node server.js
|
|
```
|
|
|
|
For production, place the service behind HTTPS and set `PUBLIC_BASE_URL` and
|
|
`APPROVAL_BASE_URL` to its HTTPS address. Scanning the TV QR code opens a phone
|
|
approval form protected by `PAIRING_SECRET`; replace that form with your own
|
|
identity provider for a production connector.
|
|
|
|
For a password-protected production connector, generate a local owner password
|
|
hash with `node hash-password.js <password>` and set `PAIRING_PASSWORD_HASH`.
|
|
`PAIRING_SECRET` is a staging-only convenience PIN and must not be used for a
|
|
shared deployment.
|
|
|
|
## Local OrbStack development
|
|
|
|
Copy `.env.example` to `.env`, set `MEDIA_ROOT` to an absolute directory with
|
|
video files, then start the shared-Caddy stack:
|
|
|
|
```sh
|
|
docker compose -p cleanstream-connector-local-domain -f docker-compose.local-domain.yml up -d
|
|
```
|
|
|
|
The connector is available at `https://cleanstream-connector.test`. The TV and
|
|
phone must be on the same LAN. Because this uses Caddy's internal certificate,
|
|
the phone must trust the local Caddy root certificate before it can open the QR
|
|
approval URL.
|
|
|
|
## Library metadata
|
|
|
|
Open `/library` in a browser and authenticate with any username and the pairing password. The
|
|
scanner uses `guessit-js` to suggest a title, year, and episode information from
|
|
messy release names; confirm or correct the title and IMDb ID in the review UI.
|
|
Mappings persist in `data/library-index.json`, are keyed by relative media path,
|
|
and are used for the catalog and CleanStream skip lookup. The connector scans on
|
|
every catalog or library request, so added and removed files are reflected
|
|
without moving or renaming originals.
|
|
|
|
The scanner also reads a same-name `.nfo` sidecar or `movie.nfo` in the media
|
|
folder. NFO title, year, and IMDb IDs take precedence over filename suggestions;
|
|
explicit library-manager mappings take precedence over both.
|
|
|
|
When `TMDB_API_KEY` is set, it is used only by the connector to enrich catalog
|
|
and detail responses with public artwork and title metadata (overview, runtime,
|
|
genres, year, and rating). The key is never included in a response, image URL,
|
|
or client configuration. Without a key or when TMDB cannot match a title, the
|
|
connector continues to return the locally derived title and file description.
|