Stream API

An optional self-hosted HTTP and SSE layer built on top of Vyla SDK.

Use this only when HTTP is the right boundary

Stream API packages Vyla SDK behind a small Node.js HTTP service. It is useful when a browser, mobile app, or another process needs progressive playback candidates over HTTP. It is not required to use Vyla, and it is not the primary integration for a Node.js application—use Vyla SDK directly in that case.

The service accepts TMDB IDs, asks configured SDK providers for candidates, verifies results, and emits usable sources as they arrive. A player can start with the first source while retaining later sources as fallbacks.

What it provides

Capability Endpoint family Why it exists
Progressive playback /movie, /tv Stream metadata and verified source candidates with SSE
Supplemental media /subtitles, /downloads Fetch tracks or downloadable candidates separately
Operations /health, /test, /debug Check source status and investigate a provider when permitted

Start a local instance

git clone https://gitlab.com/vyla-entertainment/stream-api
cd stream-api
npm install
TMDB_API_KEY=your_key
node server.js

The default local address is http://localhost:7860. For remote access, place the service behind TLS and your own access controls. Full configuration is in Self-hosting.

Lifecycle of a playback request

  1. A client opens /movie?id=:tmdbId or /tv?id=:tmdbId&season=:season&episode=:episode.
  2. The API returns an SSE response and emits a meta event with title metadata and subtitle tracks when available.
  3. Active SDK providers resolve in parallel; verified results arrive as individual source events.
  4. The server sends done after all source attempts finish or time out.

Start the player on the first source. Never wait for done before allowing playback, and always retain a fallback queue. See Paths and events for the contract.

If your application is already a Node.js service, call VylaSDK#getStream, getSubtitles, and getDownloads directly. That removes an unnecessary network hop and lets you define your own public API.