boss-web-player-sdk

v1.1.12

Published

a day ago

Unified high-performance OTT web video player SDK supporting adaptive HLS/DASH streaming, secure token-based DRM protection, dynamic watermarking, captioning, and premium UI components.

0High
0Medium
0Low

umass

video-player hls dash drm webvtt subtitles chromecast airplay chapters adaptive-streaming analytics firebase sdk react

@goboss/web-video-player-sdk

A unified, high-performance OTT web video player SDK for adaptive streaming — HLS/DASH, token-based DRM, dynamic watermarking, captions, chapters, casting, and premium UI controls.

Heads up: the high-level <BossVideoPlayer> component is tenant-gated. It validates a GoBOSS player key against the GoBOSS API before playback starts, and resolves its feature set (subtitles, DRM, chromecast, etc.) from your plan. You need a player key from the GoBOSS dashboard to use it. For a generic, ungated player use the headless core entry.

Features

Adaptive streaming — HLS (bundled hls.js) and DASH (bundled dashjs) with automatic quality switching
DRM — token-based authorization, FairPlay / Widevine, dynamic watermarking
Rich controls — quality, playback speed, subtitles, PiP, fullscreen, chapters/key-moments
Casting — Chromecast and AirPlay
Server-side ads (SSAI) — AWS MediaTailor ad-break tracking and skip-ad flow
Analytics — onAnalyticsEvent callback + optional Firebase Analytics provider
Framework-agnostic — React component, a vanilla createPlayer() mount, and a zero-React headless core

Installation

npm install @goboss/web-video-player-sdk

Peer dependencies

| Package | Required? | Notes | |---|---|---| | react, react-dom (^18 or ^19) | Required for the React component & createPlayer | Not needed if you only use the headless /core entry | | firebase (>=10) | Optional | Only needed for Firebase Analytics. Install it only if you pass firebaseConfig; the SDK installs and runs fine without it. |

DASH works out of the box. dashjs is bundled into the SDK (lazily, like hls.js) — you do not need to install it separately. The DASH engine is only fetched by the browser when a .mpd stream actually plays, so HLS-only apps never download it.

# Only if you use Firebase analytics:
npm install firebase

CSS — required, import once

The player stylesheet must be imported separately. The SDK ships CSS as a standalone file so your bundler can handle it correctly (critical for SSR frameworks like Next.js). Forgetting this import will result in a broken, unstyled player.

import '@goboss/web-video-player-sdk/css';

Import it once at your app entry point (e.g. main.tsx, _app.tsx, layout.tsx) and it applies globally — you do not need to import it in every file that uses <BossVideoPlayer>.

Quick start (React)

import { BossVideoPlayer } from '@goboss/web-video-player-sdk';
import '@goboss/web-video-player-sdk/css';

export default function App() {
  return (
    <BossVideoPlayer
      playerKey="bsp_your_player_key"          // from the GoBOSS dashboard (required)
      src="https://cdn.example.com/video.m3u8" // HLS (.m3u8) or DASH (.mpd)
      title="My Video"
      themeColor="#6366f1"
      autoplay
      muted
    />
  );
}

The component shows a loading spinner while it validates the player key, then renders the player. If the key is invalid or the API is unreachable, it renders an error state instead.

Next.js

The SDK works in Next.js (both Pages Router and App Router). The player is entirely client-side — it uses browser APIs (HTMLVideoElement, window, navigator) that do not exist on the server.

App Router — mark any file that imports the player as a Client Component:

// app/watch/page.tsx
'use client';

import { BossVideoPlayer } from '@goboss/web-video-player-sdk';

export default function WatchPage() {
  return (
    <BossVideoPlayer
      playerKey="bsp_your_player_key"
      src="https://cdn.example.com/video.m3u8"
      autoplay
      muted
    />
  );
}

Import the CSS in your root layout so it loads once for the whole app:

// app/layout.tsx
import '@goboss/web-video-player-sdk/css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <html><body>{children}</body></html>;
}

Pages Router — import the CSS in _app.tsx (or _app.js):

// pages/_app.tsx
import '@goboss/web-video-player-sdk/css';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

No 'use client' directive is needed in the Pages Router — all pages are client-rendered by default.

`<BossVideoPlayer>` props

interface BossVideoPlayerProps {
  // ── Required ──────────────────────────────────────────────
  playerKey: string;                 // GoBOSS player key — gates playback & features
  src: string;                       // HLS (.m3u8) or DASH (.mpd) URL

  // ── Identity / theming ────────────────────────────────────
  title?: string;                    // Title shown in the player UI
  watermark?: string;                // Watermark text stamped on the video
  themeColor?: string;               // Accent color (hex). Default '#6366f1'
  licenseKey?: string;               // Required by DRM-enabled plans (presence-checked)

  // ── Networking ────────────────────────────────────────────
  apiBaseUrl?: string;               // Override the GoBOSS API base URL (see note below)
  proxyDomains?: string;             // CORS proxy map, "host=/path,host2=/path2" (see CORS)

  // ── Ads (AWS MediaTailor SSAI) ────────────────────────────
  adTrackingUrl?: string;            // Ad-break tracking URL
  overlayAdUrl?: string;             // Overlay ad tracking URL
  enableSkipAd?: boolean;
  skipAdAfterSeconds?: number;

  // ── Behavior / UI ─────────────────────────────────────────
  autoplay?: boolean;                // Default false
  muted?: boolean;                   // Default false (use with autoplay — browsers block unmuted autoplay)
  autoFullscreen?: boolean;
  enableControls?: boolean;          // Default true
  chaptersDisplayMode?: 'strip' | 'panel';   // Default 'strip'
  volumeControlType?: 'slider' | 'button';    // Default 'slider'
  subtitleStyle?: { size?: 'small'|'medium'|'large'; background?: 'none'|'dim'|'solid'; color?: string };

  // ── Integrations ──────────────────────────────────────────
  firebaseConfig?: FirebaseConfig;   // Enables Firebase Analytics (lazy-loads `firebase`)
  drmConfig?: DRMConfig;             // DRM license / token configuration

  // ── Callbacks ─────────────────────────────────────────────
  onAnalyticsEvent?: (event: AnalyticsEvent) => void;   // Every analytics event
  onKeyMomentsLoaded?: (keyMoments: Chapter[]) => void; // When chapters parse from the stream
}

Feature availability (subtitles, chromecast, DRM, multiple resolutions, etc.) is resolved from your plan by the GoBOSS API at init — it is not toggled by individual props on this component.

Use without JSX — `createPlayer()`

For Vue, Angular, Svelte, or vanilla JS. Renders the same gated <BossVideoPlayer> into any element.

import { createPlayer } from '@goboss/web-video-player-sdk';
import '@goboss/web-video-player-sdk/css';

const player = createPlayer(document.getElementById('player')!, {
  playerKey: 'bsp_your_player_key',
  src: 'https://cdn.example.com/video.m3u8',
  autoplay: true,
  muted: true,
});

player.update({ src: 'https://cdn.example.com/other.m3u8' }); // re-render with new props
player.destroy();                                             // unmount & release resources

Headless core (no React)

Import from the /core subpath for a zero-React, zero-UI player and modules. This entry is not player-key gated — you drive everything yourself.

import { VideoPlayerSDK } from '@goboss/web-video-player-sdk/core';

const player = new VideoPlayerSDK({
  container: document.getElementById('player')!,
  src: 'https://cdn.example.com/video.m3u8',
  autoplay: false,
  muted: false,
});

// Playback
player.play();
player.pause();
player.seek(30);
player.setVolume(0.8);
player.setMute(false);
player.setPlaybackRate(1.5);
player.setQuality(qualityId);     // id from a `qualitylevels` event entry

// Events (EventEmitter-style)
player.on('play', () => {});
player.on('qualitychange', (q) => {});
player.on('subtitlesloaded', (tracks) => {});

player.destroy();                 // clean up

Emitted events: play, pause, ended, timeupdate, seeking, buffering, volumechange, ratechange, pipchange, error, qualitylevels, qualitychange, subtitlesloaded, audiotracksloaded, audiotrackchange, keymomentsloaded, chaptersloaded, adbreaksloaded, adbreakchange.

The /core entry also exposes the individual modules: AnalyticsModule, FirebaseAnalyticsProvider, SubtitlesModule, ThumbnailsModule, KeyMomentsModule, ChaptersModule, CastingModule, DRMModule, and BasePlayerPlugin.

CORS & proxying

The player fetches the manifest and media segments from the browser, so those origins must send CORS headers. Two tools help:

apiBaseUrl — point the SDK's GoBOSS API calls at your own reverse proxy (useful to avoid CORS on the API in development).
proxyDomains — a comma-separated "<host>=/<proxyPath>" map. Any stream URL whose host matches is rewritten to <proxyPath><pathname><search>, and applied to the manifest and every segment/key request. Back each <proxyPath> with a same-origin dev proxy.

<BossVideoPlayer
  playerKey="bsp_..."
  src="https://master.example.com/index.m3u8"
  apiBaseUrl="/boss-api"
  proxyDomains="segments.example.com=/seg-proxy,master.example.com=/mt-proxy"
/>

Proxying is a development convenience. For production, configure CORS on the content origin (S3 / CloudFront / MediaTailor) — you cannot proxy every viewer's traffic.

DRM

const drmConfig = {
  authToken: 'bearer-token',          // sent with license/segment requests
  watermarkText: 'Your Brand',
  fairplayLicenseUrl: 'https://...',  // Safari / Apple
  widevineServiceUrl: 'https://...',  // Chrome / Android
};

licenseKey is a separate, plan-level gate: when your resolved plan has DRM enabled, a non-empty licenseKey must be provided or the player shows a "Playback restricted" overlay.

Analytics

Every player event flows through onAnalyticsEvent:

<BossVideoPlayer
  playerKey="bsp_..."
  src="https://cdn.example.com/video.m3u8"
  onAnalyticsEvent={(e) => console.log(e.eventType, e)}
/>

To also forward events to Firebase Analytics (GA4), pass a firebaseConfig (and install firebase). Firebase is loaded lazily — omit the config and the firebase package is never required.

Keyboard shortcuts

| Key | Action | |---|---| | Space / K | Play / Pause | | J / ← | Seek back 10s | | L / → | Seek forward 10s | | ↑ / ↓ | Volume ±10% | | M | Mute toggle | | F | Fullscreen toggle | | P | Picture-in-Picture toggle | | C | Subtitles toggle |

Exports

// React component (gated, drop-in)
import { BossVideoPlayer, type BossVideoPlayerProps } from '@goboss/web-video-player-sdk';

// Framework-agnostic mount
import { createPlayer, type PlayerProps, type PlayerInstance } from '@goboss/web-video-player-sdk';

// Lower-level React UI / headless core
import { WebVideoPlayer, VideoPlayerSDK } from '@goboss/web-video-player-sdk';

// Optional Firebase analytics
import { FirebaseAnalyticsProvider, type FirebaseConfig } from '@goboss/web-video-player-sdk';

// Advanced: raw SDK API calls
import { initSdk, startSession, sendHeartbeat, endSession } from '@goboss/web-video-player-sdk';

// Types
import type {
  AnalyticsEvent, AnalyticsCallback, Chapter, KeyMoment, SubtitleTrack,
  VideoQuality, ThumbnailConfig, DRMConfig, PlayerSDKOptions,
  FeatureFlags, SubtitleStyle,
} from '@goboss/web-video-player-sdk';

Browser support

| Browser | Version | |---|---| | Chrome / Edge | 90+ | | Firefox | 88+ | | Safari (incl. iOS) | 14+ | | Android Chrome | 90+ |

Module formats

Ships ES Module (dist/index.js) and CommonJS (dist/index.cjs) builds with bundled TypeScript definitions and an extracted stylesheet (@goboss/web-video-player-sdk/css). react, react-dom, and firebase are externalized (see peer dependencies); hls.js and dashjs are bundled (lazily).

License

MIT — see LICENSE.