# Paths and playback events

<p class="page-description">The complete Stream API playback contract, unified for movies and TV episodes.</p>

## Playback paths

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

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

```bash
curl -N "http://localhost:7860/movie?id=155"
curl -N "http://localhost:7860/tv?id=1396&season=1&episode=1"
```

## Event contract

Playback routes use `text/event-stream`, not a single JSON document. Read each `data: ` line as JSON.

### `meta`

Sent before source resolution completes. It can include TMDB metadata and an array of subtitle tracks.

```json
{
  "type": "meta",
  "meta": { "id": 155, "title": "The Dark Knight" },
  "subtitles": [{ "label": "English", "file": "https://…", "type": "vtt", "source": "v1" }]
}
```

### `source`

One event for each candidate that passes the service's verification pipeline.

```json
{
  "type": "source",
  "source": {
    "source": "provider-key",
    "label": "Provider name",
    "url": "http://localhost:7860/api?url=…"
  }
}
```

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.

```json
{ "type": "done", "total": 3 }
```

`total: 0` means no playable sources were produced for that request. The SSE connection itself can still be successful.

## Client rules

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 [integration guide](/guides/integrations) contains a practical player pattern; [error handling](/guides/error-handling) covers fallback behavior.