mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-14 22:47:26 -05:00
142 lines
3.6 KiB
Markdown
142 lines
3.6 KiB
Markdown
# Subtitles & Media Downloads
|
|
|
|
<p class="page-description">REST API reference for retrieving subtitle tracks and direct media download packages for movies and television series.</p>
|
|
|
|
## Subtitle Endpoints
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
### 1. Movie Subtitles
|
|
|
|
```http
|
|
GET /subtitles/movie/:id HTTP/1.1
|
|
Host: your-api.example.com
|
|
```
|
|
|
|
#### Path Parameters
|
|
| Parameter | Type | Required | Description |
|
|
| :--- | :--- | :--- | :--- |
|
|
| `id` | `integer` | Required | Numeric TMDB Movie ID (e.g. `155`) |
|
|
|
|
#### Example Request & Response
|
|
```bash
|
|
curl https://your-api.example.com/subtitles/movie/155
|
|
```
|
|
|
|
```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"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 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.
|