Paths and playback events

The complete Stream API playback contract, unified for movies and TV episodes.

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:

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.

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

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

{ "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 contains a practical player pattern; error handling covers fallback behavior.