documentation/player/index.html

<!doctype html>
<html lang="en" class="dark">

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Build a player — Vyla</title>
  <meta name="description"
    content="Design a resilient Vyla playback experience around your own product and infrastructure." />
  <meta name="keywords"
    content="Vyla player, media player, custom player, playback experience, HLS player, MP4 player, streaming player" />
  <link rel="canonical" href="https://vyla.cc/player.html" />

  <!-- Open Graph / Facebook -->
  <meta property="og:type" content="website" />
  <meta property="og:url" content="https://vyla.cc/player.html" />
  <meta property="og:title" content="Build a player — Vyla" />
  <meta property="og:description"
    content="Design a resilient Vyla playback experience around your own product and infrastructure." />
  <meta property="og:image" content="https://vyla.cc/assets/images/thumbnail.png" />
  <meta property="og:site_name" content="Vyla" />

  <!-- Twitter -->
  <meta property="twitter:card" content="summary_large_image" />
  <meta property="twitter:url" content="https://vyla.cc/player.html" />
  <meta property="twitter:title" content="Build a player — Vyla" />
  <meta property="twitter:description"
    content="Design a resilient Vyla playback experience around your own product and infrastructure." />
  <meta property="twitter:image" content="https://vyla.cc/assets/images/thumbnail.png" />
  <meta property="twitter:site" content="@vylaentertainment" />

  <!-- Additional SEO -->
  <meta name="robots" content="index, follow" />
  <meta name="author" content="Vyla" />

  <link rel="icon" href="/favicon.ico" />
  <link rel="stylesheet" href="/assets/base.css" />
  <link rel="stylesheet" href="/assets/highlight.css" />
  <link rel="stylesheet" href="/assets/mintlify-overrides.css" />

  <!-- JSON-LD Structured Data -->
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "SoftwareApplication",
    "name": "Build a player",
    "description": "Design a resilient Vyla playback experience around your own product and infrastructure.",
    "url": "https://vyla.cc/player.html",
    "applicationCategory": "MultimediaApplication",
    "operatingSystem": "Windows, macOS, Linux, Android, Android TV",
    "offers": {
      "@type": "Offer",
      "price": "0",
      "priceCurrency": "USD"
    }
  }
  </script>
</head>

<body>

  <div id="banner">
    <span>Vyla is self-hosted. Run Vyla Home, embed the SDK, or deploy Stream API on infrastructure you control. Rights
      holders can request source removal — <a href="/misc/dmca">DMCA policy</a>.</span>
    <button id="banner-close" onclick="dismissBanner()" aria-label="Dismiss">✕</button>
  </div>

  <header id="navbar">
    <div class="nav-top">
      <a class="brand" href="/"><img src="/assets/images/logo.png" alt="Vyla" id="brand-logo" loading="lazy"
          fetchpriority="low"></a>
      <button id="search-trigger" type="button" onclick="openSearch()" aria-label="Search"></button>
      <div class="links">
        <button id="theme-toggle" type="button" onclick="toggleThemeMenu(event)" aria-label="Theme"></button>
      </div>
    </div>
    <nav class="tabs">
      <a class="tab-link" href="/">Vyla</a>
      <a class="tab-link" href="/sdk">SDK</a>
      <a class="tab-link active" href="/stream-api/overview">Stream API</a>
      <a class="tab-link" href="/guides/integrations">Resources</a>
      <a class="tab-link" href="/misc/credit">Misc</a>
    </nav>
  </header>
  <div id="layout">
    <nav id="sidebar">
      <div class="group">
        <p class="group-title">Start here</p>
        <ul>
          <li><a class="active" href="/">Introduction</a></li>
          </li>
          <li><a class="" href="/architecture">Architecture</a></li>
        </ul>
      </div>
      <div class="group">
        <p class="group-title">Products</p>
        <ul>
          <li><a class="" href="/home">Home</a></li>
          <li><a class="" href="/go">Go</a></li>
          <li><a class="" href="/tv">Tv</a></li>
          <li><a class="active" href="/player">Player</a></li>
        </ul>
      </div>
      <div class="group">
        <p class="group-title">Concepts</p>
        <ul>
          <li><a class="" href="/concepts/providers">Providers</a></li>
        </ul>
      </div>
    </nav>
    <div id="content-col">
      <main class="prose">
        <h1>Build a player</h1>
        <p class="page-description">Design a resilient Vyla playback experience around your own product and
          infrastructure.</p>
        <h2 id="your-player-your-rules">Your player, your rules</h2>
        <p>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.</p>
        <p>For a local managed experience, Vyla Home starts its bundled player service. For a custom product, choose one
          of two boundaries:</p>
        <table>
          <thead>
            <tr>
              <th>Integration</th>
              <th>Best for</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><strong>SDK directly</strong></td>
              <td>Node.js products that already have a backend and want complete control</td>
            </tr>
            <tr>
              <td><strong>Stream API</strong></td>
              <td>browser or mobile clients that need an HTTP/SSE source feed</td>
            </tr>
          </tbody>
        </table>
        <h2 id="build-for-changing-conditions">Build for changing conditions</h2>
        <p>Provider results vary by title and network. A dependable player should:</p>
        <ol>
          <li>Begin playback as soon as it has a usable candidate.</li>
          <li>Keep later candidates as fallbacks.</li>
          <li>Keep subtitles independent from first playback.</li>
          <li>Report a helpful unavailable state when no candidates resolve.</li>
          <li>Destroy playback and abort in-flight work when the viewer changes titles.</li>
        </ol>
        <p>The SDK returns provider results directly; Stream API emits <code>meta</code>, <code>source</code>, and
          <code>done</code> events. Both models benefit from the same fallback strategy.
        </p>
        <h2 id="playback-formats">Playback formats</h2>
        <p>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.</p>
        <h2 id="continue-building">Continue building</h2>
        <ul>
          <li>Embed provider resolution with <a href="/sdk-quickstart">SDK quickstart</a>.</li>
          <li>Learn the optional HTTP event contract in <a href="/stream-api/paths">Paths and playback events</a>.
          </li>
          <li>Use the <a href="/guides/integrations">client integration guide</a> for a browser-oriented example.
          </li>
          <li>Review <a href="/guides/error-handling">error handling</a> before shipping a player.</li>
        </ul>
      </main>
      <aside id="toc">
        <p class="toc-title">On this page</p>
        <ul>
          <li><a href="#your-player-your-rules">Your player, your rules</a></li>
          <li><a href="#build-for-changing-conditions">Build for changing conditions</a></li>
          <li><a href="#playback-formats">Playback formats</a></li>
          <li><a href="#continue-building">Continue building</a></li>
        </ul>
      </aside>
    </div>
  </div>
  <footer id="site-footer">
    <a href="https://discord.gg/5eqRhKeywG" target="_blank" rel="noopener">Discord</a>
    <a href="https://gitlab.com/vyla-entertainment/" target="_blank" rel="noopener">GitLab</a>
  </footer>
  <script src="/assets/app.js"></script>
</body>

</html>