documentation/stream-api/reference/paths.md

Paths & Playback Events

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

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.

---

1. Movie Stream Endpoint: GET /movie (or /api/movie)

Establishes an SSE event stream for a movie.

GET /movie?id=155 HTTP/1.1
Host: your-api.example.com
Accept: text/event-stream

Query Parameters

Parameter	Type	Required	Description	Example
id	integer	Required	Numeric TMDB Movie ID	155 (The Dark Knight)

---

2. Television Stream Endpoint: GET /tv (or /api/tv)

Establishes an SSE event stream for a television series episode.

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.

data: {
  "type": "meta",
  "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"
    }
  ]
}

Event 2..N: source (Emitted Progressively)

Emitted as each provider scraper successfully resolves and passes two-phase verification.

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",
  "server": "vidlink-cf",
  "quality": "1080p",
  "type": "hls",
  "headers": {
    "User-Agent": "Mozilla/5.0 ...",
    "Referer": "https://vidlink.pro/"
  }
}

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.

data: {
  "type": "done",
  "total": 5
}

---

The Universal Reverse Proxy: GET /api

The /api route handles media proxying, M3U8 rewriting, segment stripping, and TMDB queries.

1. Media Proxying: /api?url=:encoded_url

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:

{
  "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"}