documentation/stream-api/overview/index.md

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

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.
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.