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

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.