# 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

```
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](https://docs.mediakind.com/mkio/reference/player-sdk/playback) 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`.

1. Download `serviceWorker.js` from the MKPlayer SDK resources.
2. Place the file at the root of the domain where your web app is hosted, for example `https://yourdomain.com/serviceWorker.js`.
3. 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.
