documentation/stream-api/reference/paths.md

# Paths & Playback Events

<p class="page-description">Detailed API reference for Stream API streaming 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.

---

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

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
```

#### 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.

```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": {
    "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.

```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",
  "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.

```json
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`

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