mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-17 07:57:23 -05:00
fixed syntax issues
This commit is contained in:
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user