huge doc rewrite

2026-11-13 05:57:22 -05:00 · 2026-10-07 20:03:38 -07:00
parent d6ec1f93b8
commit c28308c389
47 changed files with 3185 additions and 6304 deletions
--- a/stream-api/reference/media-data.md
+++ b/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.
--- a/stream-api/reference/operations.md
+++ b/stream-api/reference/operations.md
@@ -0,0 +1,37 @@
+# Health, testing, and safe operations
+
+<p class="page-description">Observe SDK providers and diagnose a Stream API deployment without making debug data public.</p>
+
+## Health
+
+`GET /health` (or `/api/health`) probes active providers and returns a JSON summary. It includes a status, timestamp, TMDB-key presence, cache size, and a map of provider keys to `{ ok, ms }` results.
+
+Health is a signal, not a promise of playback. Provider behavior can differ by title, client network, and the moment of the request. Use it for observability and source selection—not as a guarantee that a viewer will receive a stream.
+
+## Test one provider
+
+`GET /test/:id?source=:providerKey` resolves a single provider for a movie. Add `season` and `episode` (or `s` and `e`) for TV.
+
+```bash
+curl "http://localhost:7860/test/155?source=provider-key"
+curl "http://localhost:7860/test/1396?season=1&episode=1&source=provider-key"
+```
+
+Use source keys reported by the running deployment. A test result reports whether resolution and verification succeeded; clients should inspect the result body rather than relying only on a transport success.
+
+## Debug route
+
+`GET /debug/:id?source=:providerKey` offers detailed candidate and request traces, but it is only available when `ENABLE_DEBUG_ROUTE=true`.
+
+:::callout-warning
+Do not enable the debug route on a public deployment. It can expose upstream request data, raw candidates, and headers. Enable it temporarily in a controlled environment, then disable it again.
+:::
+
+## Production checklist
+
+- Set `TMDB_API_KEY` when metadata-dependent sources are required.
+- Keep `ENABLE_DEBUG_ROUTE=false` outside controlled troubleshooting.
+- Use TLS and enforce your own access policy before making the service remotely reachable.
+- Monitor health trends and playback failures separately.
+- Run updates and provider changes through your normal deployment process.
+- Build player fallbacks instead of assuming a specific provider is always available.
--- a/stream-api/reference/paths.md
+++ b/stream-api/reference/paths.md
@@ -0,0 +1,72 @@
+# 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.