MKPlayer - v1.46.0

MKPlayer is an HTML5 video player SDK used for playing back HLS and DASH adaptive bitrate streams without using browser plugins.

Our main goal is to provide a simple, abstract API that allows you to quickly get video playback of MediaKind streams running on your web page.

---

Prerequisite

Please reach out to MediaKind team as a player (mandatory) and analytics (optional) license subscription is required and respective domains must be whitelisted on which our player is expected to run on.

---

Setup

Getting Started

Step 1: Get the latest release of MKPlayer.

You can checkout the latest version of MKPlayer from npmjs.com using the following command:

npm i @mediakind/mkplayer
Copy

Step 2: Include JavaScript and CSS files in the head of your page.

After getting hold of the latest version of MKPlayer from NPM, you need to include mkplayer.js and mkplayer-ui.css in the <head> of your HTML page as below:

<head>
    <title>My Video Player</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!-- MKPlayer JavaScript and CSS -->
    <script  type="text/javascript"  src="./node_modules/@mediakind/mkplayer/mkplayer.js"></script>
    <link  rel="stylesheet"  href="./node_modules/@mediakind/mkplayer/mkplayer-ui.css">
</head>
Copy

Step 3: Add a HTML <div> for your video container.

As the next step you need to define a HTML <div> in your HTML page <body>. This is going to be your video container used by the player for playback.

<body>
    <div id="video-container"></div>
</body>
Copy

Step 4: Player initialization.

Now, inside your JavaScript source, we can initialize the player and configure the player for your needs as below:

// 1. Grab the video container
const videoContainer = document.getElementById("video-container");

// 2. Prepare the player configuration
const playerConfig = {
    key: "PLAYER_LICENSE_HERE",
    playback: {
        muted: true,
        autoplay: true
    },
    // Subscribe to player events
    events: {
        [mkplayer.MKPlayerEvent.Error]: (event) => {
            console.log("Encountered player error: ", JSON.stringify(event));
        },
        [mkplayer.MKPlayerEvent.TimeChanged]: (event) => {
            console.log("Current player position: ", event.time);
        }
    }
};

// 3. Initialize the player with video container and player configuration
let player = new mkplayer.MKPlayer(videoContainer, playerConfig);
Copy

Please see MKPlayerConfig for more details.

From this point onwards, we are all set to use the many player APIs and handle and respond to the many player events.

Optionally you can dynamically subscribe to player events in addition to the ones subscribed in player configuration as below:

player.on(mkplayer.MKPlayerEvent.SourceLoaded, (event) => {
    console.log("Source loaded successfully!");
});

player.on(mkplayer.MKPlayerEvent.Ready, (event) => {
    console.log("Player is ready for playback!");
});
Copy

Step 5: Start playback.

At this step, we have a player which is properly initialized and ready for use. All we need to do now is prepare a source configuration object as below:

const sourceConfig = {
    title: "Title for your source",
    description: "Brief description of your source",
    poster: "https://my-cdn.com/mysource/poster.png",
    hls: "https://my-cdn.com/mysource/hls/index.m3u8",
    dash: "https://my-cdn.com/mysource/dash/manifest.mpd"
};
Copy

When attempting to setup playback for DRM protected content, we need to pass in a MKDrmConfig as one of the properties to the source configuration above as below:

const sourceConfig = {
    title: "Title for your source",
    description: "Brief description of your source",
    poster: "https://my-cdn.com/mysource/poster.png",
    hls: "https://my-cdn.com/mysource/hls/index.m3u8",
    dash: "https://my-cdn.com/mysource/dash/manifest.mpd",
    // when your source is DRM protected
    drm: {
        widevine: {
            LA_URL: "License server URL",
            headers: { // custom headers if available
                "X-CustomHeader1": "Custom header value",
                "X-CustomHeader2": "Custom header value",
            }
        },
        playready: {
            LA_URL: "License server URL",
            headers: { // custom headers if available
                "X-CustomHeader1": "Custom header value",
                "X-CustomHeader2": "Custom header value",
            }
        },
        // FairPlay DRM applies only to HLS sources on apple devices
        fairplay: {
            LA_URL: "License server URL",
            certificateURL: "Certificate URL",
            headers: { // custom headers if available
                "X-CustomHeader1": "Custom header value",
                "X-CustomHeader2": "Custom header value",
            }
        }
    }
};
Copy

Please see MKSourceConfig for more details.

Now with the above source config we are all set to start playback as below:

player.load(sourceConfig)
.then(() => {
    // you can also get notified when subscribed to `SourceLoaded` event, `Error` event to know if in case load failed.
    console.log("Source loaded successfully!");
});
Copy

Step 6: Stop playback.

To stop the current playback session:

player.unload()
.then(() => {
    // you can also get notified when subscribed to `SourceUnloaded` event.
    console.log("Source unloaded successfully!");
})
.catch((error) => {
    console.error("Source unload failed with error: ", error);
});
Copy

Step 7: Destroy player instance and release resources.

Finally to destroy the player instance and release all held resources, you can call destroy(). You must create a new instance of the player after a call to destroy().

player.destroy();

// It is recommended to wait for `Destroy` event notification after a call to `destroy()`.
Copy

---

Additional requirements for Apple devices (for Mac, iPhone, iPad)

For overcoming platform-specific limitations (to support secureUrl and customHeaders addition through setHttpHeaders), below additional steps need to be followed:

1. Download serviceWorker.js file
   Click here to download the file.
2. Place the file at the root of domain
   The serviceWorker.js file is expected to be added at the root of domain where webApp is hosted

Ex: https://yourdomain.com/serviceWorker.js
Copy

3. Enable native_hls_parsing
   MKPlayerSDK enables native_hls_parsing by default if not set, but explicitly setting it ensures consistent behaviour. This to be done during MKPlayer initialization.

let player = new mkplayer.MKPlayer(
    videoContainer, 
    {
        ...playerConfig,                // rest of playerConfig
        tweaks: {
            ...playerConfig.tweaks,     // rest of playerConfig.tweaks
            native_hls_parsing: true
        }
    }
);
Copy

Note: If you continue to experience issues related to secureUrl and setHttpHeaders on Apple devices even after completing the steps above, ensure that you're using latest version of MKPlayer Web SDK.
If issue persists even after updating to latest version then please contact MKPlayer Web SDK team.

---

Support Matrix and Error Codes

Supported Platforms

Note: We support the codecs (video and audio) that the individual platforms support. Codec support varies across platforms, but H.264/AVC video and AAC audio tend to be supported by all major vendors.

On Desktop Browsers

Browser	Supported	Supported stream formats
Chrome	Last three major versions	DASH/HLS/SMOOTH
Edge	Last three major versions (Chromium based)	DASH/HLS/SMOOTH
Safari	Last three major versions	HLS/DASH1
Firefox2	Last three major versions	DASH/HLS/SMOOTH
Opera2	Last three major versions	DASH/HLS/SMOOTH

Chromium (on ChromeOS): Not yet evaluated.
Internet Explorer is not supported.

¹ HLS is officially supported on Safari using native playback capabilities

² Limited support from MediaKind

On Mobile Devices

Mobile Browser	Supported	Supported stream formats
Chrome on Android	Android 8+, Android 4.4 - 7.x	DASH/HLS/SMOOTH
Edge	Android 8+	DASH/HLS/SMOOTH
Safari 10+	iOS 15+, iOS 11+	HLS/DASH

On Smart TVs

Smart TV	Supported	Supported stream formats
Samsung	Tizen 2.4+ (2016)	DASH/HLS/SMOOTH
LG	webOS 3.0+ (2016)	DASH/HLS/SMOOTH
Vizio	2020+	DASH/HLS/SMOOTH
Hisense (VIDAA U)	2018+	DASH/HLS/SMOOTH
Multiple Brands	TiVo OS	DASH/HLS

Hisense: Due to significant device fragmentation within the Hisense platform, we do not have access to all devices for testing purposes and thus cannot guarantee there won't be edge cases for this platform. However, some devices (specifically Android TV and Roku-based devices) may have higher levels of compatibility than others.

On Consoles

Console	Supported	Supported stream formats
Xbox	One, Series S, Series X	DASH/HLS/SMOOTH
PlayStation	4, 5	DASH/HLS/SMOOTH
Comcast	X1	DASH/HLS/SMOOTH

---

DRM Support

On Desktop Devices

Scroll sideways to view all columns

On Mobile Devices

Scroll sideways to view all columns

On Smart TVs & Consoles

Scroll sideways to view all columns

✅ supported | ☓ not supported | - restricted by the platform

---

Error Codes

Refer MKErrorCodes for more details regarding error codes.

---

Features

Player Analytics

Analytics comes pre-integrated in the player and can be used to track playback activity. You can enable analytics by configuring analytics license key during mkplayer setup.
For a minimal setup, only analytics license key needs to be specified in analytics configuration. This is sufficient to enable basic playback tracking.

let player = new mkplayer.MKPlayer(
    videoContainer, 
    {
        ...playerConfig,    // rest of playerConfig
        key: "PLAYER_LICENSE_HERE",
        analytics: {
            key: "ANALYTICS_LICENSE_HERE"
        }
    }
);
Copy

To enrich analytics data, custom data can be used to provide additional information about user, session or content being played. This custom data can be supplied during player initialization (through playerConfig) or associated with individual sources (through sourceConfig).
Refer MKAnalyticsConfig for more details.

---

Http Signing Requests and Widevine License Encryption

Prerequisites - Please refer to the quick start guide to configure and set up MKPlayer.

MKPlayer Web SDK supports Http request signing using Key Sign Service (KSS) and Widevine license encryption for supported MediaKind registered sources. These features can be enabled through playerConfig.

Http Signing Requests

Http signing generates signatures for playback Http requests to help secure access to content. To enable Http signing, set enableSecureUrl to true in playerConfig and provide kssUrl through registered.environmentConfig.kssUrl in MKEnvironmentConfig.

let player = new mkplayer.MKPlayer(
    videoContainer, 
    {
        ...playerConfig,    // rest of playerConfig
        enableSecureUrl: true
    }
);

const sourceConfig = {
    title: "Title for your source",
    assetType: "Your asset type",
    registered: {
        mediaId: "Media ID",
        environmentConfig: {
            serverUrl: "Server URL",
            authToken: "STS Authentication Token",
            ownerUid: "azuki",
            kssUrl: "KSS URL"
        }
    }
};

player.load(sourceConfig)
    .then(() => {
        console.log("Source loaded successfully!");
    });
Copy

Refer MKRegisteredSource and MKEnvironmentConfig for more details.

Widevine License Encryption

Widevine license encryption is supported through the same Key Sign Service (KSS). To enable this feature, set enableWidevineEncryption to true in playerConfig during MKPlayer initialization.

let player = new mkplayer.MKPlayer(
    videoContainer, 
    {
        ...playerConfig,    // rest of playerConfig
        enableWidevineEncryption: true
    }
);
Copy

A KSS URL is required for widevine license encryption. Configure kssUrl same way as shown for Http request signing.
Refer MKEnvironmentConfig for more details.

Note: Enabling widevineEncryption and secureUrl from client-side does not guarantee encrypted widevine DRM key and KSS feature, alignment with backend is required.

---

Adobe Primetime support

Prerequisites - Please refer to the quick start guide to configure and set up MKPlayer.

MKPlayer Web SDK supports Adobe Primetime integration to enable Adobe Primetime authentication for content playback. This feature can be configured and passed as part of MKRegisteredSource config.
Refer MKAdobePrimetimeConfig and MKRegisteredSource for more details

---

DAI (SSAI/CSAI) support

Prerequisites - Please refer to the quick start guide to configure and set up MKPlayer.

Events

The DAI events can be listened through events emitted by MKPlayer Web SDK along with other events. You can register event listeners to track ad playback lifecycle events.

player.on(mkplayer.MKPlayerEvent.AdMarker, (event) => {
    // Is called after the ad data is discovered
});
player.on(mkplayer.MKPlayerEvent.AdBreakStarted, (event) => {
    // Is called after the ad break started
});
player.on(mkplayer.MKPlayerEvent.AdStarted, (event) => {
    // Is called after the ad in an ad break started
});
player.on(mkplayer.MKPlayerEvent.AdQuartile, (event) => {
    // Is called during ad to indicate stages of ad playback
});
player.on(mkplayer.MKPlayerEvent.AdFinished, (event) => {
    // Is called after the ad in an ad break ends
});
player.on(mkplayer.MKPlayerEvent.AdBreakFinished, (event) => {
    // Is called after the ad break ends
});
Copy

Refer MKPlayerEvents for more details.

APIs

• skipAd(isCSAI: boolean): Promise - To skip the current CSAI/SSAI ad. Has no effect if no ad is active or if ad's end is out of seekableRange.
  Refer skipAd for more details.
• skipAdBreak(): void - To skip the current SSAI adBreak. Has no effect if no adBreak is active or if adBreak's end is out of seekableRange.
  Refer skipAdBreak for more details.

---

Google PAL SDK support

Google's PAL (Programmatic Access Library) can be used with MKPlayer Web SDK and can be enabled by setting enableGooglePal.
Refer Google PAL SDK doc for more details.

---

Pause Ads

MKPlayer Web SDK supports pause ads, which display an image overlay when user pauses playback. This feature is disabled by default and is not supported when MKPlayerConfig.ui is enabled.

Configuration and Container

Enable pauseAds by setting pauseAdEnabled to true and providing document-attached HTML div element through pauseAdView during player initialization process. The application is responsible for creating and managing container's layout and styling.

const pauseAdContainer = document.createElement("div");
pauseAdContainer.id = "pause-ad-container";
document.body.appendChild(pauseAdContainer);

let player = new mkplayer.MKPlayer(
    videoContainer, 
    {
        ...playerConfig,                    // rest of playerConfig
        ssaiAdConfig: {
            ...playerConfig.ssaiAdConfig,   // rest of playerConfig.ssaiAdConfig
            pauseAdEnabled: true,
            pauseAdView: pauseAdContainer
        }
    }
);
Copy

Requirements and Limitations

• Position pauseAd container above video elements and below playback controls. The displayed pauseAd image size depends on container dimensions, which are managed by app.
• Pause ads require #EXT-X-SESSION-DATA tag in HLS master manifest.
• Pause ads are displayed only for user initiated pauses.
• Pause ads are suppressed during ad breaks (both SSAI and CSAI) and Picture-in-Picture (PiP) mode.
• Pause ad feature is disabled when MKPlayerConfig.ui is enabled.

Events

MKPlayer Web SDK provides the following events to track the pause ad lifecycle and event listeners for them can be registered as shown below:

player.on(mkplayer.MKPlayerEvent.PauseAdShown, (event) => {
    // Is fired when the pause ad overlay is rendered
});
player.on(mkplayer.MKPlayerEvent.PauseAdDismissed, () => {
    // Is fired when the overlay is dismissed or playback resumes by dismissing pause ad overlay if active
});
player.on(mkplayer.MKPlayerEvent.PauseAdWarning, (event) => {
    // Is fired when image preloading fails or times out, or when the pause ad container is missing
});
Copy

APIs

• dismissPauseAd(): boolean - Dismisses the active pause ad overlay, fires the dismissal event and close beacon, and returns true if an overlay was dismissed. Otherwise, returns false.
  If any preloading or rendering of pause ad overlay was in progress then that is cleared and returns false (since ad was not active).
  Refer dismissPauseAd for more details.
• isPauseAdActive(): boolean — Returns true if a pause ad overlay is active; otherwise, returns false.
  Refer isPauseAdActive for more details.

Both methods return false when the pause ad feature is disabled.

Refer MKSsaiAdConfig, MKPauseAd for more details.

---

Low Latency

Prerequisites - Please refer to the quick start guide to configure and set up MKPlayer.

MKPlayer Web SDK supports low latency playback for live streams using LL-HLS and LL-DASH.
Low latency playback can be configured at source level using lowLatency in MKLiveConfigAtSourceLevel. You can configure target latency and catchup/fallback behaviour. Default target latency is 8 sec.
Note: Enabling lowLatency from MKPlayer Web SDK doesn't guarantee low latency playback, it enforces client-side only. Alignment with backend is required i.e., stream must be configured correctly.

Default Configuration

Set enableLowLatency to true to enable low latency playback for supported live streams.

const sourceConfig = {
    hls: "https://my-cdn.com/mysource/hls/index.m3u8",
    enableLowLatency: true
};
player.load(sourceConfig);
Copy

Manual Configuration

Manual lowlatency configs can be configured using lowLatency property in live

const sourceConfig = {
    hls: "https://my-cdn.com/mysource/hls/index.m3u8",
    enableLowLatency: true,
    live: {
        lowLatency: {
            targetLatency: 8,
            catchup: {
                playbackRateThreshold: 0.075,
                seekThreshold: 5,
                playbackRate: 1.08,
            },
            fallback: {
                playbackRateThreshold: 0.075,
                seekThreshold: 5,
                playbackRate: 0.95,
            }
        }
    }
};
player.load(sourceConfig);
Copy

The above same configuration approach applies to DASH live streams by using dash source URL.

APIs

• Use isLowLatencyPlayback to check whether active live stream is playing in low latency mode.
• Can also use player.lowlatency API to get current latency and target latency.

const currentLatency = player.lowlatency.getLatency();
const targetLatency = player.lowlatency.getTargetLatency();
Copy

These APIs return values in sec. Enabling low latency doesn't guarantee that it will work, stream must support LL-HLS or LL-DASH.
Refer MKLowLatencyAPI for more details.

---

Thumbnails

Prerequisites - Please refer to the quick start guide to configure and set up MKPlayer.

MKPlayer Web SDK supports both HLS Image Media Playlist and DASH Image Adaptation Set formats to display thumbnails.
DASH Image Adaptation Set processing is enabled by default in SDK.
HLS Image Media Playlist processing is disabled by default. Enable it by setting enableHlsImageMediaPlaylistSupport to true in playerConfig.
The getThumbnail(time) API returns thumbnail for specified playback time or null if no thumbnail available.

const thumbnail = player.getThumbnail(time);
Copy

The returned thumbnail provides the image URL and coordinates needed to extract the corresponding thumbnail from the sprite sheet.
Refer getThumbnail for more details.

---

MKPlayer Web Plugins

MKAnalytics Plugin

Analytics Plugin is a web plugin for MKPlayer Web SDK to enable and fetch playback analytics data.
Refer MKAnalytics Plugin

MKBrandbrigade Plugin

MKBrandbrigade Plugin is a web plugin for MKPlayer Web SDK to support augmented ads.
Refer MKBrandbrigade Plugin

MKConviva Plugin

MKConviva Plugin is a web plugin for MKPlayer Web SDK that adds support for Conviva analytics to collect variety of player, user and app specific metrics.
Refer MKConviva Plugin

MKCustomUI Plugin

MKCustomUI Plugin is a web plugin for MKPlayer Web SDK allows developers to implement a customizable playback UI using Bitmovin Player V3.
Refer MKCustomUI Plugin

MKFMTS Plugin

MKFMTS Plugin is a web plugin for MKPlayer Web SDK that adds Friend MTS ASiD watermarking support to provide advanced content security and anti-piracy features.
Refer MKFMTS Plugin

MKGeoComply Plugin

MKGeoComply Plugin is a web plugin for MKPlayer Web SDK that adds GeoComply BrowserGuard location verification support, gating playback of geo-restricted content behind a signed location JWT attached to the Azuki roll request.
Refer MKGeoComply Plugin

MKOMSDK Plugin

MKOMSDK Plugin is a web plugin for MKPlayer Web SDK to support AD Verification on streaming assets.
Refer MKOMSDK Plugin

---

Quick links

• MKPlayer Web RefApp
• Modules
• MKPlayerAPI
• MKPlayerEvents
• MKPlayerConfig
• MKSourceConfig
• CHANGELOG