# Building a Custom Player
Architectural principles, format handling, and engineering guidelines for building video players backed by Vyla infrastructure.
## Overview 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 Paths - **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 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. --- ## Player Guidelines 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. --- ## Minimal Web Player Example ```html