huge doc rewrite

stream-api/reference/media-data.md

@@ -0,0 +1,54 @@
+# Subtitles and downloads
+
+<p class="page-description">Unified media-data paths for movies and TV episodes.</p>
+
+## Subtitle paths
+
+| Media | Path |
+| --- | --- |
+| Movie | `GET /subtitles/movie/:id` |
+| TV episode | `GET /subtitles/tv/:id/:season/:episode` |
+
+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"
+  }
+]
+```
+
+`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.
+
+## 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"
+  }
+]
+```
+
+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.
+
+## 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.