mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-14 22:47:26 -05:00
huge rewrite
This commit is contained in:
@@ -1,54 +1,141 @@
|
||||
# Subtitles and downloads
|
||||
# Subtitles & Media Downloads
|
||||
|
||||
<p class="page-description">Unified media-data paths for movies and TV episodes.</p>
|
||||
<p class="page-description">REST API reference for retrieving subtitle tracks and direct media download packages for movies and television series.</p>
|
||||
|
||||
## Subtitle paths
|
||||
## Subtitle Endpoints
|
||||
|
||||
| Media | Path |
|
||||
| --- | --- |
|
||||
| Movie | `GET /subtitles/movie/:id` |
|
||||
| TV episode | `GET /subtitles/tv/:id/:season/:episode` |
|
||||
Stream API provides dedicated REST endpoints to fetch subtitle tracks independently from video streams. Subtitles are discovered and parsed into web-standard `.vtt` or `.srt` formats.
|
||||
|
||||
The same routes are available under `/api/subtitles`. A successful response is a JSON array of tracks; a missing result returns `404` with an error object.
|
||||
---
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"label": "English",
|
||||
"file": "https://example.invalid/subtitles/en.vtt",
|
||||
"type": "vtt",
|
||||
"source": "v1"
|
||||
}
|
||||
]
|
||||
### 1. Movie Subtitles
|
||||
|
||||
```http
|
||||
GET /subtitles/movie/:id HTTP/1.1
|
||||
Host: your-api.example.com
|
||||
```
|
||||
|
||||
`file` is the track URL, `type` is normally `vtt` or `srt`, and `source` identifies the subtitle backend. Prefer the tracks included in the playback `meta` event when you are already opening a playback stream; use these paths when subtitles are fetched separately.
|
||||
#### Path Parameters
|
||||
| Parameter | Type | Required | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | `integer` | Required | Numeric TMDB Movie ID (e.g. `155`) |
|
||||
|
||||
## Download paths
|
||||
|
||||
| Media | Path |
|
||||
| --- | --- |
|
||||
| Movie | `GET /downloads/movie/:id` |
|
||||
| TV episode | `GET /downloads/tv/:id/:season/:episode` |
|
||||
|
||||
The `/api/downloads` prefix is also supported. A successful response is an array; an empty array simply means no candidates were found.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"url": "https://example.invalid/file.mp4",
|
||||
"quality": "1080p",
|
||||
"size": "2.14 GB",
|
||||
"format": "MP4"
|
||||
}
|
||||
]
|
||||
#### Example Request & Response
|
||||
```bash
|
||||
curl https://your-api.example.com/subtitles/movie/155
|
||||
```
|
||||
|
||||
Download URLs are provider results, not durable Vyla-hosted files. Display quality and size as informational fields, and handle expired or unavailable links in your client.
|
||||
```json
|
||||
{
|
||||
"subtitles": [
|
||||
{
|
||||
"label": "English",
|
||||
"file": "https://your-api.example.com/api?url=https%3A%2F%2Fsubtitles.org%2Fen.vtt",
|
||||
"type": "vtt",
|
||||
"source": "opensubtitles"
|
||||
},
|
||||
{
|
||||
"label": "Spanish",
|
||||
"file": "https://your-api.example.com/api?url=https%3A%2F%2Fsubtitles.org%2Fes.vtt",
|
||||
"type": "vtt",
|
||||
"source": "opensubtitles"
|
||||
},
|
||||
{
|
||||
"label": "French",
|
||||
"file": "https://your-api.example.com/api?url=https%3A%2F%2Fsubtitles.org%2Ffr.srt",
|
||||
"type": "srt",
|
||||
"source": "subdl"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Request and response rules
|
||||
---
|
||||
|
||||
- IDs are TMDB IDs; TV paths additionally require season and episode numbers.
|
||||
- Both families return JSON, unlike the SSE playback paths.
|
||||
- Handle `404` for missing subtitles and `500` for an upstream or resolver failure.
|
||||
- Do not block first playback on either call. Fetch them in parallel or after the player has started.
|
||||
### 2. Television Episode Subtitles
|
||||
|
||||
```http
|
||||
GET /subtitles/tv/:id/:season/:episode HTTP/1.1
|
||||
Host: your-api.example.com
|
||||
```
|
||||
|
||||
#### Path Parameters
|
||||
| Parameter | Type | Required | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | `integer` | Required | Numeric TMDB TV Series ID (e.g. `1396`) |
|
||||
| `season` | `integer` | Required | Season number (e.g. `1`) |
|
||||
| `episode` | `integer` | Required | Episode number (e.g. `1`) |
|
||||
|
||||
#### Example Request
|
||||
```bash
|
||||
curl https://your-api.example.com/subtitles/tv/1396/1/1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Download Endpoints
|
||||
|
||||
Stream API resolves high-speed direct media download packages and torrent/debrid links. Download lookups are separated from playback streams to allow offline caching or background download managers.
|
||||
|
||||
---
|
||||
|
||||
### 1. Movie Downloads
|
||||
|
||||
```http
|
||||
GET /downloads/movie/:id HTTP/1.1
|
||||
Host: your-api.example.com
|
||||
```
|
||||
|
||||
#### Example Response
|
||||
```json
|
||||
{
|
||||
"downloads": [
|
||||
{
|
||||
"quality": "1080p",
|
||||
"size": 2450882194,
|
||||
"type": "mkv",
|
||||
"active": true,
|
||||
"url": "https://fast-cdn.example.com/download/the-dark-knight-1080p.mkv"
|
||||
},
|
||||
{
|
||||
"quality": "720p",
|
||||
"size": 1150428190,
|
||||
"type": "mkv",
|
||||
"active": true,
|
||||
"url": "https://fast-cdn.example.com/download/the-dark-knight-720p.mkv"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Television Episode Downloads
|
||||
|
||||
```http
|
||||
GET /downloads/tv/:id/:season/:episode HTTP/1.1
|
||||
Host: your-api.example.com
|
||||
```
|
||||
|
||||
#### Example Response
|
||||
```json
|
||||
{
|
||||
"downloads": [
|
||||
{
|
||||
"quality": "1080p",
|
||||
"size": 1420882194,
|
||||
"type": "mkv",
|
||||
"active": true,
|
||||
"url": "https://fast-cdn.example.com/download/breaking-bad-s01e01-1080p.mkv"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices for Clients
|
||||
|
||||
1. **Do Not Block Initial Playback**: Initiate subtitle and download queries asynchronously. The video player should start playback immediately on the first candidate stream, and subtitles should be attached dynamically as they arrive.
|
||||
2. **CORS Handling**: Subtitle files proxied through `/api?url=...` are served with `Access-Control-Allow-Origin: *`, ensuring HTML5 `<track>` elements load cleanly in cross-origin browser contexts.
|
||||
3. **Format Support**: While most modern players prefer `.vtt`, some tracks are returned in `.srt`. If your player strictly requires WebVTT, convert SRT timestamps (`00:01:20,500` -> `00:01:20.500`) client-side before loading.
|
||||
|
||||
Reference in New Issue
Block a user