vyla-entertainment/documentation
2
0
Fork 0
mirror of https://gitlab.com/vyla-entertainment/documentation.git synced 2026-11-14 22:47:26 -05:00
Code Issues Packages Projects Releases Wiki Activity

fixed syntax issues

Browse Source
This commit is contained in:
alwaysmesmerizingyou
2026-11-14 19:05:02 -08:00
parent 2cec85a8f3
commit 36b2b33ecc
29 changed files with 842 additions and 977 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
stream-api/reference/media-data.md
View File

@@ -4,25 +4,22 @@
## Subtitle Endpoints
Stream API provides dedicated REST endpoints to fetch subtitle tracks independently from video streams. Subtitles are discovered and parsed into web-standard `.vtt` or `.srt` formats.
Retrieve subtitle tracks independently from video streams in `.vtt` or `.srt` formats.
---
### 1. Movie Subtitles
### 1. Movie Subtitles: `GET /subtitles/movie/:id`
```http
GET /subtitles/movie/:id HTTP/1.1
Host: your-api.example.com
GET /subtitles/movie/155 HTTP/1.1
Host: api.vyla.cc
```
#### Path Parameters
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `id` | `integer` | Required | Numeric TMDB Movie ID (e.g. `155`) |
**Parameters:**
- `id` *(number, required)* — TMDB Movie ID (e.g. `155`).
#### Example Request & Response
```bash
curl https://your-api.example.com/subtitles/movie/155
curl https://api.vyla.cc/subtitles/movie/155
```
```json
@@ -30,21 +27,15 @@ curl https://your-api.example.com/subtitles/movie/155
"subtitles": [
{
"label": "English",
"file": "https://your-api.example.com/api?url=https%3A%2F%2Fsubtitles.org%2Fen.vtt",
"file": "https://api.vyla.cc/api?url=https%3A%2F%2Fsubtitles.org%2Fen.vtt",
"type": "vtt",
"source": "opensubtitles"
},
{
"label": "Spanish",
"file": "https://your-api.example.com/api?url=https%3A%2F%2Fsubtitles.org%2Fes.vtt",
"file": "https://api.vyla.cc/api?url=https%3A%2F%2Fsubtitles.org%2Fes.vtt",
"type": "vtt",
"source": "opensubtitles"
},
{
"label": "French",
"file": "https://your-api.example.com/api?url=https%3A%2F%2Fsubtitles.org%2Ffr.srt",
"type": "srt",
"source": "subdl"
}
]
}
@@ -52,41 +43,37 @@ curl https://your-api.example.com/subtitles/movie/155
---
### 2. Television Episode Subtitles
### 2. Television Episode Subtitles: `GET /subtitles/tv/:id/:season/:episode`
```http
GET /subtitles/tv/:id/:season/:episode HTTP/1.1
Host: your-api.example.com
GET /subtitles/tv/1396/1/1 HTTP/1.1
Host: api.vyla.cc
```
#### Path Parameters
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `id` | `integer` | Required | Numeric TMDB TV Series ID (e.g. `1396`) |
| `season` | `integer` | Required | Season number (e.g. `1`) |
| `episode` | `integer` | Required | Episode number (e.g. `1`) |
**Parameters:**
- `id` *(number, required)* — TMDB Series ID (e.g. `1396`).
- `season` *(number, required)* — Season number (e.g. `1`).
- `episode` *(number, required)* — Episode number (e.g. `1`).
#### Example Request
```bash
curl https://your-api.example.com/subtitles/tv/1396/1/1
curl https://api.vyla.cc/subtitles/tv/1396/1/1
```
---
## Download Endpoints
## Direct Download Endpoints
Stream API resolves high-speed direct media download packages and torrent/debrid links. Download lookups are separated from playback streams to allow offline caching or background download managers.
Fetch direct video files and torrent/debrid download packages.
---
### 1. Movie Downloads
### 1. Movie Downloads: `GET /downloads/movie/:id`
```http
GET /downloads/movie/:id HTTP/1.1
Host: your-api.example.com
GET /downloads/movie/155 HTTP/1.1
Host: api.vyla.cc
```
#### Example Response
```json
{
"downloads": [
@@ -95,14 +82,14 @@ Host: your-api.example.com
"size": 2450882194,
"type": "mkv",
"active": true,
"url": "https://fast-cdn.example.com/download/the-dark-knight-1080p.mkv"
"url": "https://cdn.example.com/download/the-dark-knight-1080p.mkv"
},
{
"quality": "720p",
"size": 1150428190,
"type": "mkv",
"active": true,
"url": "https://fast-cdn.example.com/download/the-dark-knight-720p.mkv"
"url": "https://cdn.example.com/download/the-dark-knight-720p.mkv"
}
]
}
@@ -110,14 +97,13 @@ Host: your-api.example.com
---
### 2. Television Episode Downloads
### 2. Television Episode Downloads: `GET /downloads/tv/:id/:season/:episode`
```http
GET /downloads/tv/:id/:season/:episode HTTP/1.1
Host: your-api.example.com
GET /downloads/tv/1396/1/1 HTTP/1.1
Host: api.vyla.cc
```
#### Example Response
```json
{
"downloads": [
@@ -126,7 +112,7 @@ Host: your-api.example.com
"size": 1420882194,
"type": "mkv",
"active": true,
"url": "https://fast-cdn.example.com/download/breaking-bad-s01e01-1080p.mkv"
"url": "https://cdn.example.com/download/breaking-bad-s01e01-1080p.mkv"
}
]
}
@@ -134,8 +120,8 @@ Host: your-api.example.com
---
## Best Practices for Clients
## Client Integration Notes
1. **Do Not Block Initial Playback**: Initiate subtitle and download queries asynchronously. The video player should start playback immediately on the first candidate stream, and subtitles should be attached dynamically as they arrive.
2. **CORS Handling**: Subtitle files proxied through `/api?url=...` are served with `Access-Control-Allow-Origin: *`, ensuring HTML5 `<track>` elements load cleanly in cross-origin browser contexts.
3. **Format Support**: While most modern players prefer `.vtt`, some tracks are returned in `.srt`. If your player strictly requires WebVTT, convert SRT timestamps (`00:01:20,500` -> `00:01:20.500`) client-side before loading.
- **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.

66
stream-api/reference/operations.md
View File

@@ -2,23 +2,22 @@
<p class="page-description">Monitoring, cluster diagnostics, live health probing, and testing endpoints in Stream API.</p>
## The Health Check Endpoint: `GET /health`
## Health Check: `GET /health`
Stream API provides an automated health probe endpoint that executes live responsiveness checks across all registered scraper modules.
Runs responsiveness checks across registered scraper modules.
```http
GET /health HTTP/1.1
Host: your-api.example.com
Host: api.vyla.cc
```
### Response Status Codes
- **`200 OK`**: All active provider sources passed their health probes.
- **`207 Multi-Status`**: One or more providers failed their probes (degraded state), but the API gateway remains functional.
### Status Codes
- `200 OK`: All active scrapers passed their health probes.
- `207 Multi-Status`: One or more providers failed (degraded state), but the gateway is functional.
### Example Response Payload
### 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,
@@ -33,33 +32,31 @@ Host: your-api.example.com
}
```
#### Response Fields
| Field | Type | Description |
| :--- | :--- | :--- |
| `status` | `string` | Overall system state (`"ok"` or `"degraded"`). |
| `timestamp` | `string` | ISO 8601 timestamp of probe completion. |
| `tmdb` | `boolean` | `true` if `TMDB_API_KEY` is configured and valid in the environment. |
| `cache` | `integer` | Current number of active cached titles in the primary LRU cache. |
| `probe_id` | `integer` | The standard TMDB ID used to probe source responsiveness. |
| `sources` | `object` | Dictionary of per-source availability (`ok`) and roundtrip latency in milliseconds (`ms`). |
**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`
To test an individual scraper directly without querying all 60 providers:
Tests a single scraper directly without triggering all other providers:
```http
GET /test/vidlink?id=155 HTTP/1.1
```
For television episodes, pass season and episode query parameters:
For television episodes, include season and episode:
```http
GET /test/vixsrc?id=1396&s=1&e=1 HTTP/1.1
```
### Response
Returns the raw resolved candidate object directly from the provider scraper:
Returns the raw candidate stream resolved by that scraper:
```json
{
@@ -75,33 +72,28 @@ Returns the raw resolved candidate object directly from the provider scraper:
## Deep Debug Route: `GET /debug/:source`
When `ENABLE_DEBUG_ROUTE=true` is set in your environment variables, Stream API exposes a comprehensive diagnostic route:
Exposes diagnostic internals when `ENABLE_DEBUG_ROUTE=true` is set:
```http
GET /debug/vidlink?id=155 HTTP/1.1
```
### Diagnostic Output Includes:
1. **Raw Scraper Payload**: Unmodified JSON or HTML received from the upstream host.
2. **Extraction Timings**: Milliseconds spent parsing DOM, solving tokens, and resolving URLs.
3. **Phase 1 Verification**: Status code, response headers, and latency of the `HEAD` request.
4. **Phase 2 Verification**: First 500 bytes of the master M3U8 playlist and test chunk fetch status.
5. **Rewritten URLs**: Preview of how chunk URIs will be rewritten by the proxy.
**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.
:::callout-warning
**Security Note**: Keep `ENABLE_DEBUG_ROUTE=false` in public production environments to avoid leaking internal scraper tokens or upstream endpoints.
Keep `ENABLE_DEBUG_ROUTE=false` in production to prevent leaking upstream tokens or credentials.
:::
---
## Cluster & Cache Architecture
### Primary Supervisor & Worker Pool Architecture
- **Central In-Memory Cache**: Holds up to 1,500 verified title entries in a shared LRU table with a 5-minute TTL.
- **Periodic Pruner**: Runs every 30 seconds to clean expired keys and enforce memory ceilings.
- **Worker Lifecycle Supervisor**: Spawns and supervises $N$ worker processes matching CPU core count, automatically restarting terminated workers.
- **IPC Message Dispatcher**: Routes `cache:get` and `cache:set` messages between worker threads and the primary process.
1. **IPC Cache Synchronization**: When a worker resolves a title, it sends a `cache:set` message to the primary process. When another worker receives a request for the same title, it sends a `cache:get` message and receives an instant `cache:hit` without re-scraping upstream hosts.
2. **Cache Pruning**: The primary process evicts stale items older than 300,000ms (5 minutes). If total cache size exceeds 1,500 items, the oldest entries are evicted immediately.
3. **Worker Auto-Restart**: If a worker process exits unexpectedly or exceeds memory limits, the primary cluster supervisor automatically spawns a replacement worker.
- **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.

102
stream-api/reference/paths.md
View File

@@ -1,55 +1,51 @@
# Paths & Playback Events
<p class="page-description">Detailed API reference for Stream API streaming endpoints, Server-Sent Events contracts, and proxy query parameters.</p>
<p class="page-description">API reference for Stream API endpoints, Server-Sent Events contracts, and proxy query parameters.</p>
## Progressive Playback Endpoints
Stream API uses Server-Sent Events (SSE) to deliver real-time discovery events directly to player clients. This eliminates long HTTP timeouts and allows players to begin buffering the moment the first candidate resolves.
Stream API uses Server-Sent Events (SSE) so players can start buffering as soon as the first candidate source is verified.
---
### 1. Movie Stream Endpoint: `GET /movie` (or `/api/movie`)
### 1. Movie Stream: `GET /movie`
Establishes an SSE event stream for a movie.
Establishes an SSE stream for a movie.
```http
GET /movie?id=155 HTTP/1.1
Host: your-api.example.com
Host: api.vyla.cc
Accept: text/event-stream
```
#### Query Parameters
| Parameter | Type | Required | Description | Example |
| :--- | :--- | :--- | :--- | :--- |
| `id` | `integer` | Required | Numeric TMDB Movie ID | `155` (The Dark Knight) |
**Parameters:**
- `id` *(number, required)* — Numeric TMDB Movie ID (e.g. `155` for The Dark Knight).
---
### 2. Television Stream Endpoint: `GET /tv` (or `/api/tv`)
### 2. TV Series Stream: `GET /tv`
Establishes an SSE event stream for a television series episode.
Establishes an SSE stream for a television series episode.
```http
GET /tv?id=1396&season=1&episode=1 HTTP/1.1
Host: your-api.example.com
Host: api.vyla.cc
Accept: text/event-stream
```
#### Query Parameters
| Parameter | Type | Required | Description | Example |
| :--- | :--- | :--- | :--- | :--- |
| `id` | `integer` | Required | Numeric TMDB TV Series ID | `1396` (Breaking Bad) |
| `season` | `integer` | Required | Season number | `1` |
| `episode` | `integer` | Required | Episode number | `1` |
**Parameters:**
- `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`).
---
## Server-Sent Events (SSE) Contract
## SSE Event Lifecycle
Connections to `/movie` and `/tv` return `Content-Type: text/event-stream` and emit events sequentially:
Connections return `Content-Type: text/event-stream` and emit events in sequence:
### Event 1: `meta` (Emitted Immediately)
Delivers title metadata and parsed subtitle tracks while scrapers are still running.
### Event 1: `meta`
Sent immediately with title metadata and subtitle tracks while scrapers are still running.
```json
data: {
@@ -59,13 +55,13 @@ data: {
"year": 2008,
"tmdb_id": 155,
"imdb_id": "tt0468569",
"poster": "https://image.tmdb.org/t/p/w500/...",
"backdrop": "https://image.tmdb.org/t/p/original/..."
"poster": "https://image.tmdb.org/t/p/w500/sample.jpg",
"backdrop": "https://image.tmdb.org/t/p/original/sample.jpg"
},
"subtitles": [
{
"label": "English",
"file": "https://your-api.example.com/api?url=...",
"file": "https://api.vyla.cc/api?url=https%3A%2F%2Fsubtitles.org%2Fen.vtt",
"type": "vtt",
"source": "opensubtitles"
}
@@ -73,15 +69,15 @@ data: {
}
```
### Event 2..N: `source` (Emitted Progressively)
Emitted as each provider scraper successfully resolves and passes two-phase verification.
### Event 2..N: `source`
Emitted progressively as each provider scraper completes two-phase verification.
```json
data: {
"type": "source",
"source": "vidlink",
"label": "VidLink Primary",
"url": "https://your-api.example.com/api?url=https%3A%2F%2Fupstream.cdn%2Fmaster.m3u8&vl=1",
"url": "https://api.vyla.cc/api?url=https%3A%2F%2Fupstream.cdn%2Fmaster.m3u8&vl=1",
"server": "vidlink-cf",
"quality": "1080p",
"type": "hls",
@@ -92,8 +88,8 @@ data: {
}
```
### Event Final: `done` (Stream Closes)
Emitted when all enabled scrapers have finished resolving or reached their maximum timeout. The server closes the SSE connection immediately after.
### Event Final: `done`
Emitted when all enabled scrapers have finished or timed out. The server closes the SSE connection immediately after.
```json
data: {
@@ -104,34 +100,30 @@ data: {
---
## The Universal Reverse Proxy: `GET /api`
## Media Reverse Proxy: `GET /api`
The `/api` route handles media proxying, M3U8 rewriting, segment stripping, and TMDB queries.
### 1. Media Proxying: `/api?url=:encoded_url`
The `/api` route handles media proxying, M3U8 playlist rewriting, header spoofing, and byte stripping.
```http
GET /api?url=https%3A%2F%2Fcdn.example.com%2Fvideo.m3u8&proxyHeaders=%7B%22Referer%22%3A%22https%3A%2F%2Fsite.com%22%7D HTTP/1.1
GET /api?url=https%3A%2F%2Fcdn.example.com%2Fvideo.m3u8&vl=1 HTTP/1.1
```
#### Query Parameters
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `url` (or `proxy`) | `string` | Required | URL-encoded destination target. |
| `proxyHeaders` | `string` | Optional | URL-encoded JSON dictionary of custom headers to forward upstream. |
| `<source_flag>` | `string` | Optional | Provider flag matching `proxyParam` (e.g. `&vl=1`, `&vx=1`) to apply source-specific referer rules. |
| `tt` | `string` | Optional | Forces the 120-byte image de-masking routine on MPEG-TS video chunks. |
**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.
#### Proxy Behaviors
- **M3U8 Playlists**: Rewrites all `.ts` chunk lines and AES `#EXT-X-KEY` URIs so that player requests route through the proxy with permissive CORS headers.
- **Obfuscated Chunks**: If chunks begin with PNG (`0x89`), JPEG (`0xFF`), or null (`0x00`) fake headers, Stream API automatically slices off the leading 120 bytes.
- **Range Seeking**: Forwards `Range: bytes=start-end` headers to upstream servers and returns HTTP `206 Partial Content`, enabling smooth scrubbing in MP4/MKV media.
**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.
- **Range Seeking**: Forwards `Range: bytes=start-end` headers and returns HTTP `206 Partial Content` for video seeking.
---
### 2. Active Sources Listing: `/api?sources_meta=1`
## Active Sources Listing: `GET /api?sources_meta=1`
Returns the list of active streaming sources currently loaded into the instance:
Returns all provider scrapers currently loaded into the instance:
```json
{
@@ -145,12 +137,10 @@ Returns the list of active streaming sources currently loaded into the instance:
---
## HTTP Status Codes & Error Responses
## HTTP Status Codes
| Status Code | Description | Example Payload |
| :--- | :--- | :--- |
| **`200 OK`** | Request succeeded or SSE stream opened | `text/event-stream` or JSON payload |
| **`206 Partial Content`** | Byte-range media response for video scrubbing | Binary video stream chunk |
| **`400 Bad Request`** | Missing required parameters or invalid TMDB ID | `{"error": "missing id", "route": "/movie?id=:tmdb_id"}` |
| **`404 Not Found`** | Unknown route | `{"error": "not found"}` |
| **`502 Bad Gateway`** | Upstream provider connection failed or timed out | `{"error": "upstream connection timeout"}` |
- `200 OK` — Request succeeded or SSE stream opened.
- `206 Partial Content` — Byte-range media response for video scrubbing.
- `400 Bad Request` — Missing parameters or invalid ID (`{"error": "missing id"}`).
- `404 Not Found` — Unknown route (`{"error": "not found"}`).
- `502 Bad Gateway` — Upstream provider connection failed or timed out.