StreamKit SDK API Reference

Install

StreamKit SDK ships as a single UMD bundle plus a stylesheet. Drop both into your page — no build step, no package manager required.

<link rel="stylesheet" href="dist/skplayer.min.css">
<script src="dist/skplayer.min.js"></script>

hls.js and dash.js are not bundled — they're fetched from a CDN on demand, only when the source you give StreamKit SDK actually needs that engine (.m3u8 → hls.js, .mpd → dash.js). Native MP4/native HLS (Safari) needs neither.

Quick Start

Video

<div id="player"></div>

<script>
  new SKPlayer({
    containerId: "player",
    mediaType:   "video",
    src:         "https://example.com/stream.m3u8",
    backupsrc:   "https://backup-cdn.example.com/stream.m3u8",
    autoplay:    1,
    muted:       1,
    poster:      "https://example.com/poster.jpg",
  });
</script>

Audio

new SKPlayer({
  containerId: "player",
  mediaType:   "audio",
  src:         "https://example.com/stream.mp3",
});

containerId must point to an element already in the DOM — the constructor throws if it isn't found. See Audio Mode for what's different when mediaType: "audio".

Config Options

Everything below is a top-level key on the object passed to new SKPlayer({...}). Defaults shown are what applies when the key is omitted entirely.

Query-String Overrides

Useful for demos and support links — appending these to the page's own URL overrides matching config keys at runtime, taking priority over whatever the embedding code passed in.

Instance Methods

Called on the object returned by new SKPlayer(...).

Quality control (via player.core.stream)

Not exposed on the top-level instance — reach through player.core.stream:

L-Band (via player.core.lband)

Static Methods

Events

Custom DOM events, dispatched on the media element unless noted otherwise. Listen with document.getElementById("player").querySelector("video").addEventListener(...), or use the container-level ones directly on your containerId element.

Multi-DRM

One drm config block covers Widevine, PlayReady, FairPlay, and ClearKey.

Widevine · DASH

drm: {
  widevine: { licenseUrl: "https://your-license-server.com/widevine" }
}

Multi-DRM (Widevine + PlayReady) · DASH

drm: {
  widevine:  { licenseUrl: "https://.../AcquireLicense", headers: { "X-AxDRM-Message": token } },
  playready: { licenseUrl: "https://.../AcquireLicense", headers: { "X-AxDRM-Message": token } },
}

ClearKey · DASH

drm: {
  clearkey: { keys: { "4060a865887842679cbf91ae5bae1e72": "fc35340837310cc0fb53de97e22a69e0" } }
}

Widevine · HLS (via hls.js EME)

drm: {
  widevine: { licenseUrl: "https://your-license-server.com/widevine" }
}

Try any of these live on the Live Demo's DRM tab.

IMA Ads — Pre/Mid/Post-roll

Google IMA SDK integration. An empty ads: {} does nothing — at least one of preroll/midroll/postroll must be set.

// Preroll only
ads: { preroll: "https://pubads.g.doubleclick.net/gampad/ads?..." }

// Postroll only
ads: { postroll: "https://pubads.g.doubleclick.net/gampad/ads?..." }

// Midroll — multiple cue points, one shared tag
ads: { midroll: { times: [30, 90, 180], tag: "..." } }

// Midroll — per-cue tags
ads: { midrolls: [ { time: 30, tag: "..." }, { time: 90, tag: "..." } ] }

// All three together
ads: {
  preroll:  "...",
  midroll:  { times: [30, 90, 180], tag: "..." },
  postroll: "...",
}

Midrolls are VOD-only — they're automatically cancelled if the stream turns out to be live. A 8-second internal timeout guards every ad request; if the ad manager never responds, content plays through uninterrupted rather than hanging.

L-Band Display Ads

A squeeze-back display-ad format (Google Ad Manager/GPT) — the video shrinks into a corner and opens two ad slots, left vertical + bottom horizontal.

lband: {
  adUnit:    "/1234567/YourNetwork/Video",
  thickness: 100,
  refresh:   60,
}

GPT requests each slot at its computed exact size plus common IAB fallback sizes (300×250, 728×90, 160×600, etc.), since real ad inventory is bought at standard sizes. See it live on the Live Demo's L-Band tab.

CMCD

Common Media Client Data (CTA-5004) — attaches session/QoS data to every manifest and segment request so your CDN can make smarter delivery decisions.

// auto-generated session ID
cmcd: true

// or customize fields
cmcd: { sessionId: "my-session-id", contentId: "my-content-id" }

Delivered as hls.js's native cmcd option for HLS, dash.js's streaming.cmcd for DASH, and appended as a CMCD= query parameter for native/Safari HLS playback where no per-request hook exists.

GA4 Analytics

Push standard playback events straight into your own GA4 property. Zero overhead when not configured — no measurement ID, no tracking calls at all.

analytics: {
  ga4MeasurementId: "G-XXXXXXXXXX",
  debug: false  // true = tag every hit for GA4 DebugView
}

Reuses the host page's existing gtag if present, otherwise lazy-loads one. Events tracked automatically: init, play, video_start, resume, pause, seek, buffering_start/buffering_end, video_complete, error, fullscreen_enter/fullscreen_exit, volume_change, mute/unmute, plus ad-lifecycle events (ad_request, ad_loaded, ad_start, ad_complete, ad_skip, ad_failed). Each hit carries an anonymous per-device ID (localStorage-persisted), a per-viewing session ID, domain, browser/OS, and screen size — no PII.

License Protection

Domain-locked license keys, checked server-side against the embedding domain.

licenseKey: "avp_your_key_here"

When active: fails open on any network error/timeout, always bypasses localhost, and only stops playback on an explicit "not licensed" response from the server — shown as a clear, non-recoverable message rather than a generic error.

Playlist

An array of per-track configs — each item takes the same keys as a single-source player config.

player = new SKPlayer({
  containerId: "player",
  mediaType:   "video",
  autoplay: 1, muted: 1,
  playlist: [
    { title: "Track 1", src: "https://.../a.m3u8", mediaType: "video" },
    { title: "Track 2", src: "https://.../b.mpd",  mediaType: "video" },
  ],
  autoplayNext: true,
  loop: false,
});

player.nextTrack();
player.goToTrack(1);

Extra fields like title pass through harmlessly — StreamKit SDK only reads src/mediaType/autoplay/muted/etc. from each item; anything else is yours to use for your own UI (track titles, thumbnails).

Audio Mode

mediaType: "audio" reuses the entire control bar, seek bar, volume, and settings UI — same engine, same reliability, just no video canvas.

• • The control bar never auto-hides (video mode hides it after 3s of inactivity)
• • No touch-to-reveal-controls mobile behavior — the bar is always visible
• • No right-click context menu (video-only feature)
• • All streaming engines, DRM, ads, CMCD, and analytics work identically to video mode