This commit is contained in:
2026-11-15 17:34:41 -08:00
parent bc7c89b528
commit 46152a464d
37 changed files with 1413 additions and 3919 deletions

View File

@@ -1,112 +0,0 @@
# API Keys & Authentication
<p class="page-description">Managing API keys, rate limits, SQLite database synchronization, and authorization headers in Stream API.</p>
## Overview
Stream API includes a key management and rate-limiting system backed by SQLite. When enabled, client apps must supply an authenticated key to establish SSE streams or request proxied media.
---
## Key Tiers
- **`pk_` (Partner Key)**: For high-volume frontends. Default: 1,000 req/min.
- **`sk_` (Standard Key)**: For private self-hosters and internal client apps. Default: 500 req/min.
- **`pub_` (Public Key)**: For public trial access or open community frontends. Default: 10 req/min.
---
## Creating Keys
Generate keys using the CLI tool in the Stream API directory:
```bash
node add-key.mjs standard 500 my-desktop-client
node add-key.mjs partner 1000 partner-frontend
node add-key.mjs public 10 public-guest
```
### Output Example
```
Generated Key: sk_8f14b2d39a7e4c5b10e9f8a7b6c5d4e3
Type: standard
Limit: 500 req/min
Client: my-desktop-client
Status: Active
```
---
## Database Export & Sync
For automated deployments, export the database to JSON:
```bash
node export-db.mjs
```
This dumps active keys to `db.json`:
```json
{
"keys": [
{
"key": "sk_8f14b2d39a7e4c5b10e9f8a7b6c5d4e3",
"type": "standard",
"limit": 500,
"client": "my-desktop-client",
"active": 1,
"created_at": "2026-11-14T12:00:00Z"
}
]
}
```
To sync edits from `db.json` back into SQLite:
```bash
node update-db.mjs
```
---
## Client Authorization
Clients can send their key via headers or query parameters:
### Authorization Header
```http
GET /movie?id=155 HTTP/1.1
Host: api.vyla.cc
Authorization: Bearer sk_8f14b2d39a7e4c5b10e9f8a7b6c5d4e3
```
### Custom Header
```http
X-API-Key: sk_8f14b2d39a7e4c5b10e9f8a7b6c5d4e3
```
### Query Parameter
Used for browser `EventSource` and native `<video>` elements that do not support custom request headers:
```http
GET /movie?id=155&key=sk_8f14b2d39a7e4c5b10e9f8a7b6c5d4e3 HTTP/1.1
```
---
## Rate Limit Responses
Responses include standard rate-limiting headers:
```http
HTTP/1.1 200 OK
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 498
X-RateLimit-Reset: 1731614460
```
When a quota is exceeded, Stream API returns HTTP `429`:
```json
{
"error": "Rate limit exceeded. Please retry in 32 seconds.",
"retry_after": 32
}
```

View File

@@ -13,11 +13,13 @@ Stream API can be self-hosted on any Linux VPS, home server, or container enviro
Configure environment variables via a `.env` file in the project root:
- `PORT` *(number, optional)* — Bind port. Default: `7860`.
- `WORKER_COUNT` *(number, optional)* — Number of cluster workers. Default: `1`.
- `TMDB_API_KEY` *(string, recommended)* — TMDB v3 API key for metadata lookups.
- `WORKER_COUNT` *(number, optional)* — Number of cluster workers. Default: available CPU count.
- `ENABLE_DEBUG_ROUTE` *(boolean, optional)* — Enables `/debug/:source`. Keep `false` in production.
- `FALLBACK_BASE` *(string, optional)* — Secondary Stream API URL for failover redirects.
- `IS_HF` *(boolean, optional)* — Enables HuggingFace Spaces compatibility.
- `PROXY_STREAMS` *(boolean, optional)* — Enable local media stream proxying. Default: `true`.
- `PROXY_URL` *(string, optional)* — Base URL of an external proxy server if offloading stream bandwidth.
- `ENABLE_DEBUG_ROUTE` *(boolean, optional)* — Enables `/api/debug/:id`. Keep `false` in production.
- `GA_MEASUREMENT_ID` *(string, optional)* — Google Analytics measurement ID for request metrics.
- `GA_API_SECRET` *(string, optional)* — Google Analytics measurement protocol API secret.
---
@@ -25,20 +27,12 @@ Configure environment variables via a `.env` file in the project root:
### Dockerfile
```dockerfile
FROM node:20-alpine
FROM node:22-slim
WORKDIR /app
RUN apk add --no-cache python3 make g++
COPY package*.json ./
RUN npm ci --omit=dev
COPY package.json .
RUN npm install
COPY . .
ENV PORT=7860
EXPOSE 7860
CMD ["node", "server.js"]
```
@@ -57,6 +51,7 @@ services:
- PORT=7860
- TMDB_API_KEY=your_tmdb_api_key_here
- WORKER_COUNT=4
- PROXY_STREAMS=true
- ENABLE_DEBUG_ROUTE=false
volumes:
- ./data:/app/data
@@ -80,7 +75,7 @@ docker compose up -d
```bash
git clone https://gitlab.com/vyla-entertainment/stream-api.git /opt/stream-api
cd /opt/stream-api
npm ci --omit=dev
npm install --omit=dev
```
### 2. Service File: `/etc/systemd/system/stream-api.service`
@@ -100,6 +95,7 @@ Environment=NODE_ENV=production
Environment=PORT=7860
Environment=TMDB_API_KEY=your_tmdb_api_key_here
Environment=WORKER_COUNT=4
Environment=PROXY_STREAMS=true
NoNewPrivileges=true
PrivateTmp=true

View File

@@ -37,22 +37,21 @@ Instead of waiting 20 seconds for all 60 scrapers to finish:
## 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)
- `GET /movie?id=:id` — Progressive movie source resolution via SSE. [Docs](../reference/paths.md)
- `GET /tv?id=:id&season=:s&episode=:e` — Progressive TV episode source resolution via SSE. [Docs](../reference/paths.md)
- `GET /api?url=:url` — Universal HLS and video chunk reverse proxy. [Docs](../reference/paths.md)
- `GET /subtitles/movie/:id` — Multi-language subtitle tracks for movies. [Docs](../reference/media-data.md)
- `GET /subtitles/tv/:id/:s/:e` — Subtitle tracks for TV episodes. [Docs](../reference/media-data.md)
- `GET /downloads/movie/:id` — Direct media download packages for movies. [Docs](../reference/media-data.md)
- `GET /downloads/tv/:id/:s/:e` — Direct media download packages for TV. [Docs](../reference/media-data.md)
- `GET /health` — Cluster status, cache metrics, and scraper health. [Docs](../reference/operations.md)
- `GET /api/test/:id?source=:key` — Direct test harness for individual scrapers. [Docs](../reference/operations.md)
---
## 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.
- **[Paths & Playback Events](../reference/paths.md)**: Complete SSE payload contracts, parameters, and proxy options.
- **[Subtitles & Media Downloads](../reference/media-data.md)**: REST endpoints for subtitle extraction and direct downloads.
- **[Operations & Health](../reference/operations.md)**: Cluster monitoring, probe IDs, and debug routes.
- **[Self-Hosting Guide](../deployment/self-hosting.md)**: Docker containerization, systemd, and Nginx reverse proxy setup.

View File

@@ -4,11 +4,35 @@
## Subtitle Endpoints
Retrieve subtitle tracks independently from video streams in `.vtt` or `.srt` formats.
Retrieve subtitle tracks independently from video streams in `.vtt` or `.srt` formats. Both `/subtitles` and `/api/subtitles` paths are supported.
---
### 1. Movie Subtitles: `GET /subtitles/movie/:id`
### Subtitle Directory: `GET /subtitles`
Returns available subtitle route templates:
```http
GET /subtitles HTTP/1.1
Host: api.vyla.cc
```
```json
{
"routes": {
"movie": "/subtitles/movie/:id",
"tv": "/subtitles/tv/:id/:s/:e"
},
"examples": {
"movie": "/subtitles/movie/155",
"tv": "/subtitles/tv/1396/1/1"
}
}
```
---
### Movie Subtitles: `GET /subtitles/movie/:id`
```http
GET /subtitles/movie/155 HTTP/1.1
@@ -23,27 +47,25 @@ curl https://api.vyla.cc/subtitles/movie/155
```
```json
{
"subtitles": [
{
"label": "English",
"file": "https://api.vyla.cc/api?url=https%3A%2F%2Fsubtitles.org%2Fen.vtt",
"type": "vtt",
"source": "opensubtitles"
},
{
"label": "Spanish",
"file": "https://api.vyla.cc/api?url=https%3A%2F%2Fsubtitles.org%2Fes.vtt",
"type": "vtt",
"source": "opensubtitles"
}
]
}
[
{
"label": "English",
"file": "https://api.vyla.cc/api?url=https%3A%2F%2Fsubtitles.org%2Fen.vtt",
"type": "vtt",
"source": "opensubtitles"
},
{
"label": "Spanish",
"file": "https://api.vyla.cc/api?url=https%3A%2F%2Fsubtitles.org%2Fes.vtt",
"type": "vtt",
"source": "opensubtitles"
}
]
```
---
### 2. Television Episode Subtitles: `GET /subtitles/tv/:id/:season/:episode`
### Television Episode Subtitles: `GET /subtitles/tv/:id/:season/:episode`
```http
GET /subtitles/tv/1396/1/1 HTTP/1.1
@@ -63,11 +85,33 @@ curl https://api.vyla.cc/subtitles/tv/1396/1/1
## Direct Download Endpoints
Fetch direct video files and torrent/debrid download packages.
Fetch direct video files and stream packages for offline playback. Both `/downloads` and `/api/downloads` paths are supported.
---
### 1. Movie Downloads: `GET /downloads/movie/:id`
### Download Directory: `GET /downloads`
```http
GET /downloads HTTP/1.1
Host: api.vyla.cc
```
```json
{
"routes": {
"movie": "/downloads/movie/:id",
"tv": "/downloads/tv/:id/:s/:e"
},
"examples": {
"movie": "/downloads/movie/155",
"tv": "/downloads/tv/1396/1/1"
}
}
```
---
### Movie Downloads: `GET /downloads/movie/:id`
```http
GET /downloads/movie/155 HTTP/1.1
@@ -75,29 +119,27 @@ Host: api.vyla.cc
```
```json
{
"downloads": [
{
"quality": "1080p",
"size": 2450882194,
"type": "mkv",
"active": true,
"url": "https://cdn.example.com/download/the-dark-knight-1080p.mkv"
},
{
"quality": "720p",
"size": 1150428190,
"type": "mkv",
"active": true,
"url": "https://cdn.example.com/download/the-dark-knight-720p.mkv"
}
]
}
[
{
"quality": "1080p",
"size": 2450882194,
"type": "mkv",
"active": true,
"url": "https://cdn.example.com/download/the-dark-knight-1080p.mkv"
},
{
"quality": "720p",
"size": 1150428190,
"type": "mkv",
"active": true,
"url": "https://cdn.example.com/download/the-dark-knight-720p.mkv"
}
]
```
---
### 2. Television Episode Downloads: `GET /downloads/tv/:id/:season/:episode`
### Television Episode Downloads: `GET /downloads/tv/:id/:season/:episode`
```http
GET /downloads/tv/1396/1/1 HTTP/1.1
@@ -105,17 +147,15 @@ Host: api.vyla.cc
```
```json
{
"downloads": [
{
"quality": "1080p",
"size": 1420882194,
"type": "mkv",
"active": true,
"url": "https://cdn.example.com/download/breaking-bad-s01e01-1080p.mkv"
}
]
}
[
{
"quality": "1080p",
"size": 1420882194,
"type": "mkv",
"active": true,
"url": "https://cdn.example.com/download/breaking-bad-s01e01-1080p.mkv"
}
]
```
---
@@ -124,4 +164,3 @@ Host: api.vyla.cc
- **Non-blocking Loading**: Fetch subtitles in the background while video playback begins immediately on the first candidate stream.
- **CORS Permissive**: Subtitle tracks proxied through `/api?url=...` include `Access-Control-Allow-Origin: *`, allowing HTML5 `<track>` elements to render in any browser context.
- **Format Conversion**: If your web player requires WebVTT, convert SRT commas to dots (`00:01:20,500` -> `00:01:20.500`) client-side before loading.

View File

@@ -4,7 +4,7 @@
## Health Check: `GET /health`
Runs responsiveness checks across registered scraper modules.
Runs responsiveness checks across registered scraper modules. Both `/health` and `/api/health` are supported.
```http
GET /health HTTP/1.1
@@ -18,82 +18,110 @@ Host: api.vyla.cc
### Response Payload
```json
{
"note": "This is a health check endpoint. This is extremely unreliable, be sure to test sources directly.",
"status": "ok",
"timestamp": "2026-11-14T20:30:00.000Z",
"tmdb": true,
"cache": 142,
"probe_id": 155,
"timestamp": "2026-11-15T12:00:00.000Z",
"sources": {
"vidlink": { "ok": true, "ms": 420 },
"vixsrc": { "ok": true, "ms": 610 },
"cinecat": { "ok": true, "ms": 890 },
"movy": { "ok": false, "ms": null }
"vidlink": { "ok": true, "latency": 350 },
"vixsrc": { "ok": true, "latency": 480 },
"cinecat": { "ok": false, "latency": 15000 }
}
}
```
**Key Fields:**
- `status`: Overall state (`"ok"` or `"degraded"`).
- `timestamp`: ISO 8601 probe timestamp.
- `tmdb`: True if `TMDB_API_KEY` is configured and responding.
- `cache`: Current number of active cached titles in LRU memory.
- `probe_id`: The TMDB ID used for the probe query.
- `sources`: Dictionary of per-source availability (`ok`) and roundtrip latency in milliseconds (`ms`).
---
## Direct Source Testing: `GET /test/:source`
## Test Directory: `GET /test`
Tests a single scraper directly without triggering all other providers:
Calling `GET /test` or `GET /api/test` returns auto-generated test URLs for every registered source:
```http
GET /test/vidlink?id=155 HTTP/1.1
GET /test HTTP/1.1
Host: api.vyla.cc
```
For television episodes, include season and episode:
```http
GET /test/vixsrc?id=1396&s=1&e=1 HTTP/1.1
```
### Response
Returns the raw candidate stream resolved by that scraper:
```json
{
"source": "vidlink",
"url": "https://upstream.example.com/playlist.m3u8",
"quality": "1080p",
"type": "hls",
"server": "vidlink-cf"
"vidlink": {
"movie": "/api/test/155?source=vidlink",
"tv": "/api/test/1396?season=1&episode=1&source=vidlink"
},
"vixsrc": {
"movie": "/api/test/155?source=vixsrc",
"tv": "/api/test/1396?season=1&episode=1&source=vixsrc"
}
}
```
---
## Deep Debug Route: `GET /debug/:source`
## Direct Source Testing: `GET /test/:tmdb_id`
Exposes diagnostic internals when `ENABLE_DEBUG_ROUTE=true` is set:
Tests a single scraper directly without triggering all other providers. Supports `/test/:id` and `/api/test/:id`.
### Movie Test
```http
GET /debug/vidlink?id=155 HTTP/1.1
GET /api/test/155?source=vidlink HTTP/1.1
Host: api.vyla.cc
```
**Output details:**
- Raw HTML or JSON received from upstream hosts.
- Time spent solving tokens and parsing DOM.
- Status code and headers from Phase 1 verification (`HEAD` check).
- First 500 bytes of the master M3U8 manifest.
- Preview of rewritten segment URLs.
**Parameters:**
- `tmdb_id` *(path, required)* — Numeric TMDB ID (e.g. `155`).
- `source` *(query, required)* — Source key to test (e.g. `vidlink`).
### TV Episode Test
```http
GET /api/test/1396?season=1&episode=1&source=vidlink HTTP/1.1
Host: api.vyla.cc
```
**Parameters:**
- `tmdb_id` *(path, required)* — Numeric TMDB Series ID (e.g. `1396`).
- `source` *(query, required)* — Source key to test (e.g. `vidlink`).
- `season` or `s` *(query, required)* — Season number (e.g. `1`).
- `episode` or `e` *(query, required)* — Episode number (e.g. `1`).
### Response Example
```json
{
"source": "vidlink",
"ok": true,
"stream": {
"url": "https://api.vyla.cc/api?url=https%3A%2F%2Fupstream.example.com%2Fmaster.m3u8",
"quality": "1080p",
"type": "hls",
"server": "vidlink-cf"
}
}
```
---
## Deep Debug Route: `GET /debug/:tmdb_id`
Exposes diagnostic internals when `ENABLE_DEBUG_ROUTE=true` is enabled in `.env`:
```http
GET /api/debug/155?source=vidlink HTTP/1.1
Host: api.vyla.cc
```
**Diagnostics Returned:**
- Raw HTML and JSON payloads from upstream providers.
- Resolution latency and DOM parsing metrics.
- Upstream HTTP status codes and headers from probe checks.
- First 500 bytes of upstream playlist manifests.
- Rewritten proxy segment URLs.
:::callout-warning
Keep `ENABLE_DEBUG_ROUTE=false` in production to prevent leaking upstream tokens or credentials.
Keep `ENABLE_DEBUG_ROUTE=false` in production to prevent leaking upstream tokens and API keys.
:::
---
## Cluster & Cache Architecture
- **In-Memory Cache**: Up to 1,500 verified titles stored in an LRU cache with a 5-minute TTL.
- **Cache Pruner**: Runs every 30 seconds to evict expired keys.
- **Worker Lifecycle**: The supervisor process maintains workers matching CPU core count, automatically replacing crashed processes.
- **IPC Messaging**: Workers coordinate via `cache:get` and `cache:set` messages, allowing instant cache hits across worker boundaries without an external database.
- **In-Memory Cache**: Up to 1,500 entries stored in primary process memory with a 5-minute TTL (`CACHE_TTL`).
- **Pruning Timer**: Runs automatically every 30 seconds to purge expired entries and maintain cache boundaries.
- **Worker Management**: Cluster primary supervises worker processes, automatically respawning workers on process exit.
- **IPC Synchronization**: Workers communicate through `cache:get`, `cache:set`, and `cache:push` IPC messages for fast cross-process cache hits.

View File

@@ -4,7 +4,7 @@
## Progressive Playback Endpoints
Stream API uses Server-Sent Events (SSE) so players can start buffering as soon as the first candidate source is verified.
Stream API uses Server-Sent Events (SSE) so players can start buffering as soon as the first candidate source is verified. Both root paths (`/movie`, `/tv`) and prefixed paths (`/api/movie`, `/api/tv`) are supported.
---
@@ -20,6 +20,7 @@ Accept: text/event-stream
**Parameters:**
- `id` *(number, required)* — Numeric TMDB Movie ID (e.g. `155` for The Dark Knight).
- `sources` *(string, optional)* — Comma-separated list of source keys to query (e.g. `?sources=vidlink,vixsrc`). Omit to query all active sources.
---
@@ -37,6 +38,7 @@ Accept: text/event-stream
- `id` *(number, required)* — Numeric TMDB TV Series ID (e.g. `1396` for Breaking Bad).
- `season` *(number, required)* — Season number (e.g. `1`).
- `episode` *(number, required)* — Episode number (e.g. `1`).
- `sources` *(string, optional)* — Comma-separated list of source keys to query.
---
@@ -70,13 +72,13 @@ data: {
```
### Event 2..N: `source`
Emitted progressively as each provider scraper completes two-phase verification.
Emitted progressively as each provider scraper completes verification.
```json
data: {
"type": "source",
"source": "vidlink",
"label": "VidLink Primary",
"label": "VidLink",
"url": "https://api.vyla.cc/api?url=https%3A%2F%2Fupstream.cdn%2Fmaster.m3u8&vl=1",
"server": "vidlink-cf",
"quality": "1080p",
@@ -102,28 +104,27 @@ data: {
## Media Reverse Proxy: `GET /api`
The `/api` route handles media proxying, M3U8 playlist rewriting, header spoofing, and byte stripping.
The `/api` route handles media proxying, M3U8 playlist rewriting, header forwarding, and byte stripping.
```http
GET /api?url=https%3A%2F%2Fcdn.example.com%2Fvideo.m3u8&vl=1 HTTP/1.1
```
**Parameters:**
- `url` *(string, required)* — URL-encoded target URL to fetch.
- `proxyHeaders` *(string, optional)* — URL-encoded JSON object of custom headers to forward.
- `<source_flag>` *(string, optional)* — Source flag matching configuration (e.g. `&vl=1`, `&vx=1`) to apply source-specific referer rules.
- `tt` *(string, optional)* — Forces the 120-byte image header stripping routine on MPEG-TS video chunks.
- `url` or `proxy` *(string, required)* — URL-encoded target URL to fetch.
- `proxyHeaders` *(string, optional)* — URL-encoded JSON string of custom headers to forward.
- `tt` *(string, optional)* — Forces the 120-byte image header stripping routine on obfuscated video chunks.
**Proxy Features:**
- **M3U8 Rewriting**: Rewrites all `.ts` chunk URIs and `#EXT-X-KEY` AES encryption endpoints to route through the proxy with CORS headers (`Access-Control-Allow-Origin: *`).
- **Obfuscation Stripping**: Slices off the 120-byte image header if chunks start with PNG (`0x89`), JPEG (`0xFF`), or null (`0x00`) bytes.
- **Obfuscation Stripping**: Slices off the 120-byte fake image header if chunks begin with PNG (`0x89`), JPEG (`0xFF`), or null (`0x00`) bytes.
- **Range Seeking**: Forwards `Range: bytes=start-end` headers and returns HTTP `206 Partial Content` for video seeking.
---
## Active Sources Listing: `GET /api?sources_meta=1`
Returns all provider scrapers currently loaded into the instance:
Returns all provider scrapers currently loaded:
```json
{
@@ -137,6 +138,16 @@ Returns all provider scrapers currently loaded into the instance:
---
## TMDB Proxy Helpers
Stream API provides server-side cached TMDB proxy routes:
- **Movie Metadata**: `GET /api?tmdb_movie=1&id=155&append_to_response=credits,videos`
- **TV Series Metadata**: `GET /api?tmdb_tv=1&id=1396`
- **TV Season Metadata**: `GET /api?tmdb_season=1&id=1396&s=1`
---
## HTTP Status Codes
- `200 OK` — Request succeeded or SSE stream opened.