mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-14 22:47:26 -05:00
59 lines
3.5 KiB
Markdown
59 lines
3.5 KiB
Markdown
# Stream API Overview
|
|
|
|
<p class="page-description">A self-hosted Node.js HTTP and Server-Sent Events (SSE) streaming gateway for progressive source discovery, HLS proxying, and subtitle extraction.</p>
|
|
|
|
<img class="vyla-banner" src="/src/assets/images/devices.webp" alt="Vyla Stream API infrastructure across client devices" loading="lazy" decoding="async" fetchpriority="low" />
|
|
|
|
## 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.
|