mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-09 20:17:20 -05:00
72 lines
2.3 KiB
Markdown
72 lines
2.3 KiB
Markdown
# 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. |