# Paths & Playback Events

API reference for Stream API endpoints, Server-Sent Events contracts, and proxy query parameters.

## Progressive Playback Endpoints 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. --- ### 1. Movie Stream: `GET /movie` Establishes an SSE stream for a movie. ```http GET /movie?id=155 HTTP/1.1 Host: api.vyla.cc 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. --- ### 2. TV Series Stream: `GET /tv` Establishes an SSE stream for a television series episode. ```http GET /tv?id=1396&season=1&episode=1 HTTP/1.1 Host: api.vyla.cc Accept: text/event-stream ``` **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`). - `sources` *(string, optional)* — Comma-separated list of source keys to query. --- ## SSE Event Lifecycle Connections return `Content-Type: text/event-stream` and emit events in sequence: ### Event 1: `meta` Sent immediately with title metadata and subtitle tracks while scrapers are still running. ```json data: { "type": "meta", "meta": { "title": "The Dark Knight", "year": 2008, "tmdb_id": 155, "imdb_id": "tt0468569", "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://api.vyla.cc/api?url=https%3A%2F%2Fsubtitles.org%2Fen.vtt", "type": "vtt", "source": "opensubtitles" } ] } ``` ### Event 2..N: `source` Emitted progressively as each provider scraper completes verification. ```json data: { "type": "source", "source": "vidlink", "label": "VidLink", "url": "https://api.vyla.cc/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/" } } ``` ### Event Final: `done` Emitted when all enabled scrapers have finished or timed out. The server closes the SSE connection immediately after. ```json data: { "type": "done", "total": 5 } ``` --- ## Media Reverse Proxy: `GET /api` 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` 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 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: ```json { "sources": [ { "key": "vidlink", "label": "VidLink", "timeout": 12000 }, { "key": "vixsrc", "label": "VixSrc", "timeout": 10000 }, { "key": "cinecat", "label": "CineCat", "timeout": 15000 } ] } ``` --- ## 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. - `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.