documentation/stream-api/overview/index.md

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 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
• GET /tv?id=:id&season=:s&episode=:e — Progressive TV episode source resolution via SSE. Docs
• GET /api?url=:url — Universal HLS and video chunk reverse proxy. Docs
• GET /subtitles/movie/:id — Multi-language subtitle tracks for movies. Docs
• GET /subtitles/tv/:id/:s/:e — Subtitle tracks for TV episodes. Docs
• GET /downloads/movie/:id — Direct media download packages for movies. Docs
• GET /downloads/tv/:id/:s/:e — Direct media download packages for TV. Docs
• GET /health — Cluster status, cache metrics, and scraper health. Docs
• GET /test/:source — Direct test harness for individual scrapers. Docs

---

Documentation Sections

• Paths & Playback Events: Complete SSE payload contracts, parameters, and proxy options.
• Subtitles & Media Downloads: REST endpoints for subtitle extraction and direct downloads.
• Operations & Health: Cluster monitoring, probe IDs, and debug routes.
• API Keys & Authentication: Key management, SQLite database, and rate limiting.
• Self-Hosting Guide: Docker containerization, PM2, and Nginx reverse proxy setup.