Installation and setup

This page covers how to install MKPlayer, include it in your HTML page, and create an initialised player instance ready for use.

Prerequisites

npm available in your project
A player license key from MediaKind
Your deployment domain added to the MediaKind license allowlist

The player will not start if your domain is not allowlisted. You will see a PLAYER_SETUP_MISSING_LICENSE_ALLOWLIST error. Contact MediaKind to add your domain before going further.

Install and initialise

Install the package

npm i @mediakind/mkplayer

Include the scripts in your page

Add mkplayer.js and mkplayer-ui.css to the <head> of your HTML page:

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

Add a video container element

Add a <div> to your page <body>. MKPlayer uses this element as the playback container:

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

Create a player instance

In your JavaScript, get the container, build a configuration object, and pass both to MKPlayer:

const videoContainer = document.getElementById("video-container");

const playerConfig = {
  key: "YOUR_PLAYER_LICENSE_KEY",
  playback: {
    muted: true,
    autoplay: true
  }
};

const player = new mkplayer.MKPlayer(videoContainer, playerConfig);

The player is now initialised and ready to load a source. See Loading and playing content for the next step.

Player configuration options

The MKPlayerConfig object controls how the player behaves. All properties are optional except where noted.

Property	Type	Description
`key`	`string`	Your player license key.
`playback`	`MKPlaybackConfig`	Playback options such as `autoplay` and `muted`.
`ui`	`boolean`	Enables the built-in player UI. Requires `mkplayer-ui.css` to be loaded. Default: `false`.
`events`	`MKPlayerEventConfig`	Map of player events to handler callbacks. You can also register handlers dynamically using `player.on()`.
`analytics`	`MKAnalyticsConfig \| false`	Analytics configuration. Set to `false` to disable analytics even if the analytics module is loaded.
`buffer`	`MKBufferConfig`	Buffer configuration.
`log`	`MKLogConfig`	Log level and output configuration.
`tweaks`	`MKTweaksConfig`	Advanced player tweaks. Use these only if you understand their effect on playback behaviour.

Additional requirements for Apple devices

Safari on Mac, iPhone, and iPad requires an extra step to support secure URLs and custom HTTP headers via setHttpHeaders.

Download serviceWorker.js from the MKPlayer SDK resources.
Place the file at the root of the domain where your web app is hosted — for example, https://yourdomain.com/serviceWorker.js.
Explicitly enable native_hls_parsing in your player configuration:

const playerConfig = {
  key: "YOUR_PLAYER_LICENSE_KEY",
  tweaks: {
    native_hls_parsing: true
  }
};

The SDK enables native_hls_parsing by default if the property is not set, but setting it explicitly ensures consistent behaviour across environments.