> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://mediakind.ferndocs.com/mkio/reference/player-sdk/setup/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mediakind.ferndocs.com/_mcp/server.

# Installation and setup

Install MKPlayer, add it to an HTML page, and create an initialised player instance before loading media.

## 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

* Terminal window

```bash
npm i @mediakind/mkplayer

```

### Include the scripts in your page

```html
<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

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

```

### Create a player instance

```javascript
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:

```javascript
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.