5.2 KiB
Stream API Overview
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 dedicated backend gateway for the Vyla ecosystem. While the Vyla SDK executes directly in Node.js environments, web browsers, mobile applications, and smart TVs require a standard HTTP/SSE bridge to communicate with upstream providers, circumvent browser CORS restrictions, and decrypt video streams.
Stream API wraps @vyla-entertainment/sdk in a high-concurrency, self-hostable service designed for maximum throughput and zero playback stutter.
Architectural Highlights
| Cluster Role | Process Type | Responsibilities & Functions |
|---|---|---|
| Primary Process | Node.js Cluster Master | Spawns and supervises worker processes across CPU cores, manages the shared 1,500-entry in-memory LRU cache (5-minute TTL), coordinates IPC messages (cache:get / cache:set), and executes cache cleanup every 30 seconds. |
| Inter-Process Channel | Node.js IPC | High-throughput bi-directional message pipe (process.send and cluster.on('message')) synchronizing cache entries across workers without Redis or external database overhead. |
| Worker Processes | Forked HTTP Workers (0..N) |
Runs native HTTP request routers (http.createServer), pushes progressive Server-Sent Events (SSE), executes universal reverse proxying with live M3U8/key rewriting, and strips 120-byte image obfuscation masks. |
1. Multi-Core Cluster Architecture
Stream API leverages Node's native cluster module to fork independent worker processes across available CPU cores. If one worker experiences a heavy upstream network timeout, other workers continue handling client requests without interruption.
2. Progressive Streaming over Server-Sent Events (SSE)
Rather than blocking HTTP requests for 20 seconds while 60 providers resolve, Stream API utilizes Server-Sent Events:
- Instant Metadata: Title info and subtitle tracks arrive in the first event (
type: "meta"). - Progressive Sources: As each provider scraper finishes verification, a
type: "source"event is pushed immediately. - Completion Signal: When all sources complete, a
type: "done"event closes the stream cleanly.
3. Shared In-Memory LRU Cache
All cluster workers communicate with a centralized in-memory cache managed by the primary process:
- Cache TTL: 5 minutes (300,000 ms).
- Capacity: 1,500 items max with LRU eviction.
- Cache Hit Latency: < 2 milliseconds for frequently requested titles.
4. Reverse Proxy & Chunk De-Obfuscator
- Transparently proxies HLS playlists (
/api?url=...), rewriting AES encryption keys and.tschunk URIs to inject permissive CORS headers. - Strips 120-byte fake image headers prepended to video chunks by ByteDance/TikTok-based content delivery networks.
- Supports HTTP Range headers (
206 Partial Content) for seeking large MP4 and MKV media containers.
Route Overview
| Route | Protocol | Primary Purpose | Reference |
|---|---|---|---|
/movie?id=:id |
GET (SSE) | Progressive movie source resolution | Paths Reference |
/tv?id=:id&season=:s&episode=:e |
GET (SSE) | Progressive TV episode source resolution | Paths Reference |
/subtitles/movie/:id |
GET (REST) | Multi-language subtitle tracks for movies | Media Data Reference |
/subtitles/tv/:id/:s/:e |
GET (REST) | Subtitle tracks for TV episodes | Media Data Reference |
/downloads/movie/:id |
GET (REST) | Direct media download packages for movies | Media Data Reference |
/downloads/tv/:id/:s/:e |
GET (REST) | Direct media download packages for TV | Media Data Reference |
/api?url=:url |
GET (Proxy) | Universal HLS & video chunk proxy | Paths Reference |
/health |
GET (REST) | Cluster status, cache size, source health | Operations Reference |
/test/:source |
GET (REST) | Direct test harness for individual sources | Operations Reference |
Stream API Documentation Index
- Paths & Playback Events: Complete SSE payload contracts, parameters, and proxy options.
- Subtitles & Media Downloads: REST endpoints for subtitle extraction and direct media files.
- Operations, Health & Testing: Cluster health monitoring, probe IDs, and debug routes.
- API Keys & Authentication: Key management, SQLite database, and partner keys.
- Production Self-Hosting Guide: Docker containerization, PM2, systemd, and Nginx reverse proxy configurations.