boss-web-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 your GoBOSS player key before playback starts, and resolves its feature set (subtitles, DRM, chromecast, etc.) from your plan. Obtain a player key from the GoBOSS dashboard and supply it from your app config (never commit real keys). 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
• Episodic playback — Skip Intro and an auto-advancing Next Episode chip, for series content
• Analytics — first-party session/event telemetry, plus an onAnalyticsEvent callback
• Framework-agnostic — React component, a vanilla createPlayer() mount, and a zero-React headless core

Installation

npm install boss-web-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 |

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.

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 'boss-web-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 'boss-web-player-sdk';
import 'boss-web-player-sdk/css';

export default function App() {
  return (
    <BossVideoPlayer
      playerKey={process.env.NEXT_PUBLIC_PLAYER_KEY!} // from your app config / env (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 'boss-web-player-sdk';

export default function WatchPage() {
  return (
    <BossVideoPlayer
      playerKey={process.env.NEXT_PUBLIC_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 'boss-web-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 'boss-web-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;                 // from your GoBOSS dashboard — supply via app config/env
  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;               // API base override: reverse proxy path, or the staging host
  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;

  // ── Series / episodic ─────────────────────────────────────
  introStartTime?: number;           // Content-relative intro start, in seconds
  introEndTime?: number;             // Content-relative intro end, in seconds — Skip Intro seeks here
  hasNextEpisode?: boolean;          // Whether another episode is available to auto-advance into
  outroStartTime?: number;           // Content-relative outro/credits start, in seconds — reveals the Next Episode chip
  nextEpisodeLabel?: string;         // Label on the Next Episode chip. Default 'Next Episode'
  nextEpisodeAutoAdvanceSeconds?: number; // Seconds before auto-advancing once the chip is shown. Default 5
  onNextEpisode?: () => void;        // Called on chip click, or when the auto-advance timer fires

  // ── 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 ──────────────────────────────────────────
  drmConfig?: DRMConfig;             // DRM license / token configuration

  // ── Callbacks ─────────────────────────────────────────────
  onAnalyticsEvent?: (event: AnalyticsEvent) => void;   // Every analytics event
  onKeyMomentsLoaded?: (keyMoments: Chapter[]) => void; // When chapters parse from the stream
  onTimeUpdate?: (currentTime: number) => void;         // Every timeupdate — use to persist watch progress

  // ── Resume playback ───────────────────────────────────────
  initialTime?: number;               // Seek to this position (seconds) once the video is ready
}

Skip Intro / Next Episode (series)

Both are driven entirely by props — the SDK owns the timing, the chip UI, and the seek/auto-advance behavior. All times are content-relative (the original episode timeline), so they stay correct even if the stream has spliced ad breaks.

<BossVideoPlayer
  playerKey={playerKey}
  src="https://cdn.example.com/episode-04.m3u8"
  introStartTime={0}
  introEndTime={78}                 // Skip Intro shows between 0s–78s, seeks to 78s on click
  hasNextEpisode={true}
  outroStartTime={1230}             // Next Episode chip appears once playback reaches 1230s
  nextEpisodeLabel="S2 · E5"        // optional — defaults to "Next Episode"
  nextEpisodeAutoAdvanceSeconds={5} // optional — auto-advances 5s after the chip appears
  onNextEpisode={() => loadNextEpisode()}
/>

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 'boss-web-player-sdk';
import 'boss-web-player-sdk/css';

const player = createPlayer(document.getElementById('player')!, {
  playerKey, // from your app config / env
  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 'boss-web-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, 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 — optional override for GoBOSS API calls. Use it for a same-origin reverse proxy during local development, or to point a non-production build at the staging API (apiBaseUrl="https://dev-api.go-boss.com"). Omit it in production, where the default is the production API host.
• 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={playerKey}
  src="https://master.example.com/index.m3u8"
  apiBaseUrl="/api-proxy"
  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={playerKey}
  src="https://cdn.example.com/video.m3u8"
  onAnalyticsEvent={(e) => console.log(e.eventType, e)}
/>

To forward events anywhere else — your own warehouse, a third-party analytics product — use onAnalyticsEvent and send them on from there. The SDK reports session and event telemetry to the GoBOSS backend on its own; onAnalyticsEvent is purely additive and does not replace it.

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 'boss-web-player-sdk';

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

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

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

// Types
import type {
  AnalyticsEvent, AnalyticsCallback, Chapter, KeyMoment, SubtitleTrack,
  VideoQuality, ThumbnailConfig, DRMConfig, PlayerSDKOptions,
  FeatureFlags, SubtitleStyle,
} from 'boss-web-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 (boss-web-player-sdk/css). react and react-dom are externalized (see peer dependencies); hls.js and dashjs are bundled (lazily).

License

MIT — see LICENSE.