fixed syntax issues

This commit is contained in:
2026-11-14 19:05:02 -08:00
parent 2cec85a8f3
commit 36b2b33ecc
29 changed files with 842 additions and 977 deletions

View File

@@ -1,71 +1,38 @@
# Building a Custom Player
<p class="page-description">Architectural principles, format handling, and engineering guidelines for building resilient video players backed by Vyla infrastructure.</p>
<p class="page-description">Architectural principles, format handling, and engineering guidelines for building video players backed by Vyla infrastructure.</p>
## Overview
In the Vyla ecosystem, you are never locked into an official frontend. Vyla provides the discovery, resolution, and proxy layers; your application owns the player experience. Whether you are building a custom web portal, desktop client, or mobile app, this guide covers the core engineering patterns required for a robust player.
Vyla handles discovery, scraping, and proxying; your app owns the player. Whether building a web player, desktop shell, or mobile UI, this guide outlines the core playback patterns.
---
## Integration Boundaries
## Integration Paths
Choose your integration point based on your architecture:
| Architecture | Integration Point | Data Flow | Best For |
| :--- | :--- | :--- | :--- |
| **Node.js Backend** | **Vyla SDK Directly** | `sdk.getStream()` in-process | Applications with full backend control, custom authentication, and server-side session tracking. |
| **Browser / Mobile** | **Stream API Gateway** | SSE `/movie` or `/tv` over HTTP | Web applications, smart TV frontends, or lightweight mobile clients requiring an HTTP/SSE source feed. |
- **Node.js Backends**: Use the Vyla SDK directly in-process via `sdk.getStream()`. Ideal for custom authentication and server-side tracking.
- **Web / Mobile / TV**: Connect to the Stream API gateway via HTTP/SSE (`/movie` or `/tv`). Ideal for frontend players requiring a live streaming feed.
---
## Playback Formats: HLS vs Direct Video
## Playback Formats
Resolved candidate streams come in two primary container types:
1. **HLS Streams (`type: "hls"`)**:
- Master M3U8 playlists containing multiple bitrate/resolution variants.
- Proxied through Stream API (`/api?url=...`), which automatically rewrites chunk URLs and AES-128 encryption key URIs.
- Requires native HLS support (Safari on macOS/iOS) or a JavaScript HLS MSE library such as [HLS.js](https://github.com/video-dev/hls.js/) in modern browsers.
2. **Direct Media Files (`type: "mp4"`)**:
- Progressive MP4 or MKV streams.
- Proxied with HTTP Range header forwarding (`206 Partial Content`), allowing smooth scrubbing and seeking.
- Directly assignable to the HTML5 `<video>` element `src` attribute.
- **HLS Streams (`type: "hls"`)**: Adaptive master playlists (`.m3u8`). Proxied via Stream API (`/api?url=...`), which rewrites chunk URIs and AES encryption keys with permissive CORS headers. Handled via HLS.js or native Safari.
- **Direct Video (`type: "mp4"`)**: Direct MP4 or MKV files. Proxied with HTTP Range forwarding (`206 Partial Content`) for scrubbing.
---
## Resilient Player Architecture
## Player Guidelines
Upstream streaming hosts are dynamic: network latencies fluctuate, upstream proxies fail, and geo-restrictions vary. A production-ready Vyla player must adhere to five design rules:
### 1. Start on the First Candidate
Never wait for all providers to finish. Stream API emits verified sources over Server-Sent Events (SSE). The moment the first `source` event arrives (typically within 3 to 8 seconds):
- Initialize your player immediately.
- Store any subsequent incoming `source` events in a priority fallback array.
### 2. Maintain a Fallback Priority Array
If the active stream stalls, encounters an unrecoverable network error, or buffer-underruns:
- Catch the error event (e.g. `Hls.Events.ERROR` with fatal flag).
- Pop the next candidate from your fallback queue.
- Re-attach the media source without disrupting the user's viewing session.
### 3. Decouple Subtitles from Video Playback
Subtitles are retrieved independently from the video stream. Never block initial video buffering waiting for subtitle tracks to download. Load the video stream immediately and inject subtitle tracks (`<track kind="subtitles">`) asynchronously once resolved.
### 4. Implement a Client-Side Timeout
Always set a client-side watchdog timer (typically 15 to 20 seconds). If no viable candidate emits a valid video stream before the timer expires, render an informative empty state allowing the user to retry or switch servers.
### 5. Clean Up on Title Switch
When a viewer selects a new movie or episode:
- Call `eventSource.close()` on the active SSE connection.
- Invoke `hls.destroy()` or `video.removeAttribute('src')`.
- Clear pending retry timers and abort in-flight fetch requests.
1. **Start on First Source**: Begin playback as soon as the first `source` event arrives (3–8s). Queue later events as fallbacks.
2. **Auto-Failover**: If the current stream fails, catch fatal playback errors and immediately switch to the next queued source.
3. **Async Subtitles**: Fetch subtitles in the background without blocking video buffering.
4. **Watchdog Timer**: If no working source resolves within 15–20s, show an empty state with a retry option.
5. **Clean Teardown**: When switching media, close the SSE connection and destroy the HLS instance before opening a new stream.
---
## Reference Implementation: Minimal Web Player
Below is a complete, copyable implementation using native HTML5 and HLS.js:
## Minimal Web Player Example
```html
<!DOCTYPE html>
@@ -84,7 +51,7 @@ Below is a complete, copyable implementation using native HTML5 and HLS.js:
<div id="status" class="status">Connecting to Stream API...</div>
<script>
const API_BASE = "https://your-stream-api.example.com";
const API_BASE = "https://api.vyla.cc";
const TMDB_ID = 155;
const video = document.getElementById("vyla-video");
@@ -137,7 +104,6 @@ Below is a complete, copyable implementation using native HTML5 and HLS.js:
hlsInstance.on(Hls.Events.ERROR, (event, errorData) => {
if (errorData.fatal) {
console.warn("HLS fatal error encountered. Switching to fallback candidate...");
hlsInstance.destroy();
isPlaying = false;
if (fallbackSources.length > 0) playCandidate(fallbackSources.shift());
@@ -167,11 +133,3 @@ Below is a complete, copyable implementation using native HTML5 and HLS.js:
</body>
</html>
```
---
### Next Steps
- Explore the complete [Client Integration Guide](/guides/integrations) for React, Vue, and ExoPlayer examples.
- Review error classification in the [Error Handling Guide](/guides/error-handling).
- Review the SSE event protocol in [Paths & Playback Events](/stream-api/reference/paths).