mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-14 22:47:26 -05:00
huge rewrite
This commit is contained in:
@@ -1,72 +1,156 @@
|
||||
# Paths and playback events
|
||||
# Paths & Playback Events
|
||||
|
||||
<p class="page-description">The complete Stream API playback contract, unified for movies and TV episodes.</p>
|
||||
<p class="page-description">Detailed API reference for Stream API streaming endpoints, Server-Sent Events contracts, and proxy query parameters.</p>
|
||||
|
||||
## Playback paths
|
||||
## Progressive Playback Endpoints
|
||||
|
||||
The API supports both the short paths below and `/api`-prefixed equivalents. A movie needs only `id`; a TV episode also needs `season` and `episode`.
|
||||
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.
|
||||
|
||||
| Media | Path | Response |
|
||||
| --- | --- | --- |
|
||||
| Movie | `GET /movie?id=:id` | Server-Sent Events |
|
||||
| TV episode | `GET /tv?id=:id&season=:season&episode=:episode` | Server-Sent Events |
|
||||
---
|
||||
|
||||
`id` is a TMDB ID. For example:
|
||||
### 1. Movie Stream Endpoint: `GET /movie` (or `/api/movie`)
|
||||
|
||||
```bash
|
||||
curl -N "YOUR_API_URL/movie?id=155"
|
||||
curl -N "YOUR_API_URL/tv?id=1396&season=1&episode=1"
|
||||
Establishes an SSE event stream for a movie.
|
||||
|
||||
```http
|
||||
GET /movie?id=155 HTTP/1.1
|
||||
Host: your-api.example.com
|
||||
Accept: text/event-stream
|
||||
```
|
||||
|
||||
## Event contract
|
||||
#### Query Parameters
|
||||
| Parameter | Type | Required | Description | Example |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| `id` | `integer` | Required | Numeric TMDB Movie ID | `155` (The Dark Knight) |
|
||||
|
||||
Playback routes use `text/event-stream`, not a single JSON document. Read each `data: ` line as JSON.
|
||||
---
|
||||
|
||||
### `meta`
|
||||
### 2. Television Stream Endpoint: `GET /tv` (or `/api/tv`)
|
||||
|
||||
Sent before source resolution completes. It can include TMDB metadata and an array of subtitle tracks.
|
||||
Establishes an SSE event stream for a television series episode.
|
||||
|
||||
```http
|
||||
GET /tv?id=1396&season=1&episode=1 HTTP/1.1
|
||||
Host: your-api.example.com
|
||||
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` |
|
||||
|
||||
---
|
||||
|
||||
## Server-Sent Events (SSE) Contract
|
||||
|
||||
Connections to `/movie` and `/tv` return `Content-Type: text/event-stream` and emit events sequentially:
|
||||
|
||||
### Event 1: `meta` (Emitted Immediately)
|
||||
Delivers title metadata and parsed subtitle tracks while scrapers are still running.
|
||||
|
||||
```json
|
||||
{
|
||||
data: {
|
||||
"type": "meta",
|
||||
"meta": { "id": 155, "title": "The Dark Knight" },
|
||||
"subtitles": [{ "label": "English", "file": "https://…", "type": "vtt", "source": "v1" }]
|
||||
"meta": {
|
||||
"title": "The Dark Knight",
|
||||
"year": 2008,
|
||||
"tmdb_id": 155,
|
||||
"imdb_id": "tt0468569",
|
||||
"poster": "https://image.tmdb.org/t/p/w500/...",
|
||||
"backdrop": "https://image.tmdb.org/t/p/original/..."
|
||||
},
|
||||
"subtitles": [
|
||||
{
|
||||
"label": "English",
|
||||
"file": "https://your-api.example.com/api?url=...",
|
||||
"type": "vtt",
|
||||
"source": "opensubtitles"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### `source`
|
||||
|
||||
One event for each candidate that passes the service's verification pipeline.
|
||||
### Event 2..N: `source` (Emitted Progressively)
|
||||
Emitted as each provider scraper successfully resolves and passes two-phase verification.
|
||||
|
||||
```json
|
||||
{
|
||||
data: {
|
||||
"type": "source",
|
||||
"source": {
|
||||
"source": "provider-key",
|
||||
"label": "Provider name",
|
||||
"url": "YOUR_API_URL/api?url=…"
|
||||
"source": "vidlink",
|
||||
"label": "VidLink Primary",
|
||||
"url": "https://your-api.example.com/api?url=https%3A%2F%2Fupstream.cdn%2Fmaster.m3u8&vl=1",
|
||||
"server": "vidlink-cf",
|
||||
"quality": "1080p",
|
||||
"type": "hls",
|
||||
"headers": {
|
||||
"User-Agent": "Mozilla/5.0 ...",
|
||||
"Referer": "https://vidlink.pro/"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `url` is ready for a player. HLS sources may be wrapped by Vyla's proxy so manifest segments and keys can be fetched with the appropriate upstream headers. Some configured sources bypass proxying. Do not assume a filename extension alone determines playback behavior.
|
||||
|
||||
### `done`
|
||||
|
||||
Sent after the configured attempts are complete.
|
||||
### 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.
|
||||
|
||||
```json
|
||||
{ "type": "done", "total": 3 }
|
||||
data: {
|
||||
"type": "done",
|
||||
"total": 5
|
||||
}
|
||||
```
|
||||
|
||||
`total: 0` means no playable sources were produced for that request. The SSE connection itself can still be successful.
|
||||
---
|
||||
|
||||
## Client rules
|
||||
## The Universal Reverse Proxy: `GET /api`
|
||||
|
||||
1. Start playback as soon as the first `source` arrives.
|
||||
2. Queue every later source for manual switching or automatic fallback.
|
||||
3. Attach subtitle tracks from `meta` without blocking playback.
|
||||
4. Treat an empty result as a normal product state, not a malformed response.
|
||||
5. Abort the request when the viewer leaves the page or chooses another title.
|
||||
The `/api` route handles media proxying, M3U8 rewriting, segment stripping, and TMDB queries.
|
||||
|
||||
The [integration guide](/guides/integrations) contains a practical player pattern; [error handling](/guides/error-handling) covers fallback behavior.
|
||||
### 1. Media Proxying: `/api?url=:encoded_url`
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
#### 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. |
|
||||
|
||||
#### 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.
|
||||
|
||||
---
|
||||
|
||||
### 2. Active Sources Listing: `/api?sources_meta=1`
|
||||
|
||||
Returns the list of active streaming sources currently loaded into the instance:
|
||||
|
||||
```json
|
||||
{
|
||||
"sources": [
|
||||
{ "key": "vidlink", "label": "VidLink", "timeout": 12000 },
|
||||
{ "key": "vixsrc", "label": "VixSrc", "timeout": 10000 },
|
||||
{ "key": "cinecat", "label": "CineCat", "timeout": 15000 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## HTTP Status Codes & Error Responses
|
||||
|
||||
| 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"}` |
|
||||
|
||||
Reference in New Issue
Block a user