huge rewrite

This commit is contained in:
2026-11-14 18:21:12 -08:00
parent f465d1ec0d
commit 2cec85a8f3
69 changed files with 11479 additions and 1576 deletions

View File

@@ -1,37 +1,177 @@
# Build a player
# Building a Custom Player
<p class="page-description">Design a resilient Vyla playback experience around your own product and infrastructure.</p>
<p class="page-description">Architectural principles, format handling, and engineering guidelines for building resilient video players backed by Vyla infrastructure.</p>
## Your player, your rules
## Overview
Vyla supplies the integration layer; your application owns the player experience. That includes design, authentication, title discovery, parental controls, analytics, playback policy, and fallback behavior.
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.
For a local managed experience, Vyla Home starts its bundled player service. For a custom product, choose one of two boundaries:
---
| Integration | Best for |
| --- | --- |
| **SDK directly** | Node.js products that already have a backend and want complete control |
| **Stream API** | browser or mobile clients that need an HTTP/SSE source feed |
## Integration Boundaries
## Build for changing conditions
Choose your integration point based on your architecture:
Provider results vary by title and network. A dependable player should:
| 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. |
1. Begin playback as soon as it has a usable candidate.
2. Keep later candidates as fallbacks.
3. Keep subtitles independent from first playback.
4. Report a helpful unavailable state when no candidates resolve.
5. Destroy playback and abort in-flight work when the viewer changes titles.
---
The SDK returns provider results directly; Stream API emits `meta`, `source`, and `done` events. Both models benefit from the same fallback strategy.
## Playback Formats: HLS vs Direct Video
## Playback formats
Resolved candidate streams come in two primary container types:
Candidates may be HLS manifests or direct media files. Let the result metadata and your player capabilities guide how a candidate is loaded; do not assume every URL has the same format or availability. HLS-capable web players normally use HLS.js where native HLS is unavailable, while direct media can be assigned to a video element.
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.
## Continue building
---
- Embed provider resolution with [SDK quickstart](/sdk/vyla-sdk/quickstart).
- Learn the optional HTTP event contract in [Paths and playback events](/stream-api/reference/paths).
- Use the [client integration guide](/guides/integrations) for a browser-oriented example.
- Review [error handling](/guides/error-handling) before shipping a player.
## Resilient Player Architecture
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.
---
## Reference Implementation: Minimal Web Player
Below is a complete, copyable implementation using native HTML5 and HLS.js:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Vyla Custom Player</title>
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<style>
video { width: 100%; max-width: 960px; height: auto; background: #000; border-radius: 8px; }
.status { font-family: sans-serif; margin-top: 8px; color: #666; }
</style>
</head>
<body>
<video id="vyla-video" controls playsinline></video>
<div id="status" class="status">Connecting to Stream API...</div>
<script>
const API_BASE = "https://your-stream-api.example.com";
const TMDB_ID = 155;
const video = document.getElementById("vyla-video");
const statusEl = document.getElementById("status");
const fallbackSources = [];
let isPlaying = false;
let hlsInstance = null;
const eventSource = new EventSource(`${API_BASE}/movie?id=${TMDB_ID}`);
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.type === "meta") {
statusEl.textContent = `Found: ${data.meta.title} (${data.meta.year})`;
if (data.subtitles) loadSubtitles(data.subtitles);
}
else if (data.type === "source") {
if (!isPlaying) {
playCandidate(data);
} else {
fallbackSources.push(data);
}
}
else if (data.type === "done") {
eventSource.close();
if (!isPlaying && fallbackSources.length === 0) {
statusEl.textContent = "No compatible streaming sources found.";
}
}
};
eventSource.onerror = () => {
eventSource.close();
if (!isPlaying) statusEl.textContent = "Error connecting to Stream API.";
};
function playCandidate(candidate) {
isPlaying = true;
statusEl.textContent = `Streaming from provider: ${candidate.source} (${candidate.quality})`;
if (candidate.type === "hls") {
if (Hls.isSupported()) {
if (hlsInstance) hlsInstance.destroy();
hlsInstance = new Hls({ maxBufferLength: 30 });
hlsInstance.loadSource(candidate.url);
hlsInstance.attachMedia(video);
hlsInstance.on(Hls.Events.MANIFEST_PARSED, () => video.play());
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());
}
});
} else if (video.canPlayType("application/vnd.apple.mpegurl")) {
video.src = candidate.url;
video.play();
}
} else {
video.src = candidate.url;
video.play();
}
}
function loadSubtitles(subtitles) {
subtitles.forEach((sub) => {
const track = document.createElement("track");
track.kind = "subtitles";
track.label = sub.label;
track.srclang = sub.label.slice(0, 2).toLowerCase();
track.src = sub.file;
video.appendChild(track);
});
}
</script>
</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).