@sitr.io/embed-sdk

Security-first video embed SDK with DRM support for HLS and DASH streaming.

Installation

npm install @sitr.io/embed-sdk

Usage

Script tag (UMD)

<div id="vg-player"></div>
<script src="https://unpkg.com/@sitr.io/embed-sdk@0/dist/vg.js"></script>
<script>
  VideoGuard.mountOnStart({
    el: "#vg-player",
    tenant: "<playback-grant>",
    videoId: "video-123",
    userId: "user-456",
  });
</script>

ES modules

import VideoGuard from "@sitr.io/embed-sdk";

VideoGuard.init({
  apiBaseUrl: "https://api.sitr.io",
});

const drmSecurity = await VideoGuard.detectDrmSecurityLevel();
console.log(drmSecurity.level);

const player = await VideoGuard.mount({
  el: "#vg-player",
  tenant: "<playback-grant>",
  videoId: "video-123",
  userId: "user-456",
});

Mount on DOM ready

await VideoGuard.mountOnStart({
  el: "#vg-player",
  tenant: "<playback-grant>",
  videoId: "video-123",
  userId: "user-456",
});

API

• VideoGuard.init(config) – Optional for custom runtimes. Use it to override apiBaseUrl, tenantToken (a short-lived playback grant), or legacy branding values.
• VideoGuard.mount(options) – Mount the player into a target element. Returns a Promise resolving to the player DOM element.
• VideoGuard.mountOnStart(options) – Same as mount, but waits for DOMContentLoaded before mounting.
• VideoGuard.detectDrmSecurityLevel() – Best-effort browser DRM probe returning hardware, software, supported-unknown, or unsupported.

DRM security probe

Browsers do not expose the "Use graphics acceleration when available" setting to web pages. The SDK therefore reports a best-effort DRM capability level based on EME robustness probing instead of trying to read the browser setting directly.

<script src="https://unpkg.com/@sitr.io/embed-sdk@0/dist/vg.js"></script>
<script>
  (async () => {
    const result = await VideoGuard.detectDrmSecurityLevel();
    console.log(result.level, result.keySystem, result.reason);

    if (result.level === "unsupported") {
      console.warn("DRM is not available in this browser.");
    }

    await VideoGuard.mountOnStart({
      el: "#vg-player",
      tenant: "<playback-grant>",
      videoId: "video-123",
      userId: "user-456",
    });
  })();
</script>

Returned levels:

• hardware: hardware-secure DRM robustness was granted.
• software: DRM is available, but only software-secure or baseline access succeeded.
• supported-unknown: DRM is available, but the browser does not expose a trustworthy hardware/software distinction.
• unsupported: no supported DRM key system could be acquired.

Required backend endpoints

Your API must implement:

• GET {apiBaseUrl}/playback/sdk-conf – Tenant-level embed defaults used by the short snippet flow
• GET {apiBaseUrl}/playback/videos/{id} – Video metadata and manifest paths
• GET {apiBaseUrl}/playback/config – DRM license URLs
• GET {apiBaseUrl}/playback/videos/{id}/token – Playback token

Notes

• The SDK stores a persistent vg_device_id in localStorage.
• The tenant option is a short-lived playback grant, not a tenant UUID or server-side API key.
• Supports HLS, DASH, and MP4 fallback with optional Widevine, PlayReady, and FairPlay DRM.
• strictRootTamperDetection has been removed. Watermark protection is now scoped to canvasWatermark, which verifies that the forensic canvas remains visible over the protected media without treating unrelated host-page DOM changes as attacks.
• When canvasWatermark.enabled is true, Picture-in-Picture and remote playback are disabled because those surfaces cannot carry the DOM watermark. The SDK continuously restores these browser hints because media engines may rewrite them during normal source changes. They remain available when canvas watermarking is disabled.