CleanStream Media Connector Reference

Self-hosted reference implementation of the v1 connector protocol.

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:

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.