Web quick start

OGPlayer for the web plays HLS through hls.js (with Safari’s native HLS as fallback) and MPEG-DASH through dash.js, and renders its UI as a framework-agnostic <og-player> custom element — it works identically in plain HTML, React, Vue or Angular.

Option A · npm

npm install ogplayer

<og-player style="width:100%;aspect-ratio:16/9"></og-player>

<script type="module">
  import { OGPlayer } from "ogplayer";

  const player = new OGPlayer({ licenseKey: "OGP2…" }); // omit → watermarked trial
  document.querySelector("og-player").player = player;

  player.addListener({
    onStateChanged: (s) => console.log(s),
    onError: (e) => console.warn(e.code, e.message),
  });

  player.load({
    url: "https://example.com/stream.m3u8",
    title: "My movie",
    sideloadedSubtitles: [
      { url: "/subs/en.vtt", language: "en", label: "English", isDefault: true },
    ],
  });
</script>

Option B · script tag (no build step)

<script src="https://unpkg.com/ogplayer@<version>/dist/ogplayer.global.js"></script>
<og-player id="pl" style="width:100%;aspect-ratio:16/9"></og-player>
<script>
  const player = new OGPlayerSDK.OGPlayer({ licenseKey: "OGP2…" });
  document.getElementById("pl").player = player;
  player.load({ url: "https://example.com/stream.m3u8" });
</script>

The global build is served straight from the npm package, so any npm CDN works — swap unpkg.com for cdn.jsdelivr.net/npm if you prefer. Pin an exact <version> (for example 1.6.0) rather than a range.

DASH

Pass an .mpd URL — or mimeType: "application/dash+xml" for an extensionless manifest URL — and the player hands the item to its DASH engine, dash.js: the same API, events, menus, live/DVR handling and DRM config as HLS.

player.load({ url: "https://example.com/manifest.mpd", title: "My movie" });

DASH plays on Chrome, Edge and Firefox (desktop and Android), and on Samsung Tizen and LG webOS through the smart-TV bundle. Safari has no DASH path: serve Safari, and the WebKit browsers on iPhone and iPad, the HLS rendition (CMAF lets one packaging feed both).

dash.js ships inside the ogplayer package — nothing extra to install — and loads only when a DASH item plays:

• npm / ES modules — nothing to do. The bundle imports the engine as a separate chunk (dist/ogplayer.dash-*.js, next to ogplayer.js) on the first DASH item; bundlers pick it up as a lazy chunk.

• Script tag — add the engine file with a second tag from the same folder:

  <script src="https://unpkg.com/ogplayer@<version>/dist/ogplayer.global.js"></script>
  <script src="https://unpkg.com/ogplayer@<version>/dist/ogplayer.dash.global.js"></script>

• Your own dash.js build — pass the module as new OGPlayer({ dashjs }), or put a dashjs global on the page; the player uses it instead of the shipped engine.

HLS-only apps change nothing: without a DASH item the engine is never requested. A DASH item on a script-tag page without the engine file fails with 3001 SOURCE_UNSUPPORTED and a message naming the file to add.

DRM

One DrmConfig covers all three browser DRM systems — the SDK engages whichever the visitor’s browser supports (Chrome/Firefox/Android → Widevine, Edge → PlayReady, Safari → FairPlay):

player.load({
  url: "https://example.com/protected.m3u8",
  drm: {
    widevine:  { licenseUrl: "https://drm.example.com/widevine" },
    playready: { licenseUrl: "https://drm.example.com/playready" },
    fairplay:  {
      licenseUrl: "https://drm.example.com/fairplay",
      certificateUrl: "https://drm.example.com/fairplay.cer",
    },
    tokenProvider: async ({ renewal }) => ({ "X-DRM-Token": await freshToken() }),
  },
});

DASH items take the same config — Widevine and PlayReady, the same token provider and renewal events; see DASH on the web.

Localisation

Every word of the chrome — control labels, menu rows, screen-reader text, ad and error copy — comes from config.strings, a partial map merged over the English defaults. <og-player lang="nl"> (or config.locale) names language-coded tracks in the same language. See Localisation.

Engine options

Everything the constructor accepts is optional:

const player = new OGPlayer({
  licenseKey: "OGP2…",          // omit → watermarked trial
  // Autoplay policy: when the browser blocks autoplay-with-audio, retry
  // muted instead of staying paused. You get onMutedAutoplayFallback (and a
  // MutedAutoplayFallback analytics event) to show an unmute affordance.
  fallbackToMutedAutoplay: true,
  // Extra hls.js configuration, merged under the SDK-managed keys —
  // buffer targets, ABR tuning, anything hls.js accepts.
  hlsConfig: { maxBufferLength: 60 },
});
player.setLooping(true);        // seamless per-item looping (isLooping reads it)

Browser support

Evergreen Chrome / Edge / Firefox / Safari 16+ (desktop & mobile). Every API used (MSE, custom elements, shadow DOM, WebCrypto, Fullscreen) has been baseline for years; no polyfills. DASH plays on Chrome, Edge and Firefox on desktop and Android; serve Safari and iPhone/iPad browsers the HLS rendition.

Complete examples

Every guide in these docs has a matching page in the open-source web demos — npm install && npm start and lift code from there.