A self-hosted Node.js HTTP and Server-Sent Events (SSE) streaming gateway for progressive source discovery, HLS proxying, and subtitle extraction.
## Overview
**Stream API** is the streaming gateway for the Vyla ecosystem. While the Vyla SDK executes directly in Node.js, browsers, mobile devices, and TVs require an HTTP/SSE bridge to communicate with scrapers, bypass browser CORS, and decrypt video streams.
Stream API wraps `@vyla-entertainment/sdk` in a high-concurrency service built for real-time progressive playback.
---
## Core Capabilities
### Multi-Core Cluster
Stream API uses Node's native `cluster` module to fork workers across all available CPU cores. If an upstream network timeout occurs on one worker, other workers continue handling client traffic without interruption.
### Progressive Server-Sent Events (SSE)
Instead of waiting 20 seconds for all 60 scrapers to finish:
- **Instant Metadata**: Title info and subtitles arrive in the first `meta` event.
- **Progressive Sources**: Each verified source is pushed immediately as a `source` event.
- **Clean Finish**: A `done` event signals stream completion.
### Shared In-Memory Cache
- **Capacity**: 1,500 entries with LRU eviction.
- **TTL**: 5 minutes (300,000 ms).
- **Lookup Latency**: < 2 ms for active titles.
### Reverse Proxy & Chunk Stripper
- Proxies HLS playlists (`/api?url=...`), rewriting AES encryption keys and `.ts` chunk URIs to inject permissive CORS headers.
- Strips 120-byte fake image headers prepended to video chunks by ByteDance and TikTok-based CDNs.
- Supports HTTP Range requests (`206 Partial Content`) for seeking MP4 and MKV containers.
---
## Key Routes
- `GET /movie?id=:id` — Progressive movie source resolution via SSE. [Docs](/stream-api/reference/paths)
- `GET /tv?id=:id&season=:s&episode=:e` — Progressive TV episode source resolution via SSE. [Docs](/stream-api/reference/paths)
- `GET /api?url=:url` — Universal HLS and video chunk reverse proxy. [Docs](/stream-api/reference/paths)
- `GET /subtitles/movie/:id` — Multi-language subtitle tracks for movies. [Docs](/stream-api/reference/media-data)
- `GET /subtitles/tv/:id/:s/:e` — Subtitle tracks for TV episodes. [Docs](/stream-api/reference/media-data)
- `GET /downloads/movie/:id` — Direct media download packages for movies. [Docs](/stream-api/reference/media-data)
- `GET /downloads/tv/:id/:s/:e` — Direct media download packages for TV. [Docs](/stream-api/reference/media-data)
- `GET /health` — Cluster status, cache metrics, and scraper health. [Docs](/stream-api/reference/operations)
- `GET /test/:source` — Direct test harness for individual scrapers. [Docs](/stream-api/reference/operations)
---
## Documentation Sections
- **[Paths & Playback Events](/stream-api/reference/paths)**: Complete SSE payload contracts, parameters, and proxy options.
- **[Subtitles & Media Downloads](/stream-api/reference/media-data)**: REST endpoints for subtitle extraction and direct downloads.
- **[Operations & Health](/stream-api/reference/operations)**: Cluster monitoring, probe IDs, and debug routes.
- **[API Keys & Authentication](/stream-api/authentication)**: Key management, SQLite database, and rate limiting.
- **[Self-Hosting Guide](/stream-api/deployment/self-hosting)**: Docker containerization, PM2, and Nginx reverse proxy setup.