mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-12 13:37:20 -05:00
36 lines
1.8 KiB
Markdown
36 lines
1.8 KiB
Markdown
# Stream API
|
|
|
|
<p class="page-description">An optional self-hosted HTTP and SSE layer built on top of Vyla SDK.</p>
|
|
|
|
## 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](/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
|
|
|
|
```bash
|
|
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](/stream-api/deployment/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. |