npm package: @meisterplayer/plugin-shaka
Description: Meister plugin wrapping the Shaka player.
Author: Triple
Latest version: 5.3.0

# Shaka plugin for meister #
===========

This plugin allows basic media types to be played. They are directly put in the video element.

### Installation ###
-----

You can install this plugin through npm:

```
npm install @meisterplayer/plugin-shaka
```

and importing it

``` JavaScript
import Meister from 'meisterplayer';
import BaseMedia from '@meisterplayer/plugin-shaka'
```

or using a script tag:

``` html
<script src="Meister.js"></script>
<script src="Shaka.js"></script>
```


Getting started
-----------

Load the plugin by adding a `Shaka` configuration object to the Meister initialisation options. If you don't need to customize anything an empty object is enough.

Example:

``` JavaScript
var meisterPlayer = new Meister('#player', {
    Shaka: {}
});

meisterPlayer.setItem({
    src: 'https://example.com/secure/stream/manifest.mpd',
    type: 'mpd',
});

meisterPlayer.load();

```

### Configuration ###

Options are required unless marked as [optional].

* [optional] **dvrThreshold** :: *Number*  
    Content with a window longer than this threshold is considered as having a DVR window. This is measured in seconds. Defaults to 300 (5 minutes).
* [optional] **maxErrorCounts** :: *Object*  
    This object allows customization of the maximum amount of nonfatal errors before throwing a fatal error. It's possible to specify a default value as well as individual values for specific error codes. See the [docs](https://shaka-player-demo.appspot.com/docs/api/shaka.util.Error.html) for an overview of the various error codes.
    ```JavaScript
    var meisterPlayer = new Meister('#player', {
        Shaka: {
            maxErrorCounts: {
                default: 5,
                1003: 1,
            }
        },
    });
    ```
    * [optional] **default** :: *Number*  
        When no maximum has been set for a specific error code the player will use this value as the maximum number. Defaults to 3.
    * [optional] **<errorCode>** :: *Number*  
        By entering a maximum for a specific error code it's possible to finetune the experience based on your needs. This makes it possible to throw an error after 1 request timeout retry by while keeping the other maximums higher:
* [optional] **shakaConfig** :: *Object*  
    Through this option it is possible to set default values in the Shaka player configuration. This object is directly passed to the `configure` call of the Shaka instance. These options can be overridden on a per item basis by setting a `shakaConfig` property on the item. See the [docs](https://shaka-player-demo.appspot.com/docs/api/shaka.extern.html#.PlayerConfiguration) for information on the configuration object.  
    ```JavaScript
    var meisterPlayer = new Meister('#player', {
        Shaka: {
            shakaConfig: {
                manifest: {
                    availabilityWindowOverride: 200,
                },
            }
        },
    });
    ```

Item options
------------

The following options can be added per item

### startFromLive *[Boolean]* (default: false) ###

Start from the live edge this will bring the player as close as possible to the live edge.

``` JavaScript
meisterPlayer.setItem({
    src: 'https://example.com/secure/stream/manifest.mpd',
    startFromLive: true,
    type: 'mpd'
});
```

### startFromBeginning *[Boolean|Object]* (default: false) ###

Start from the beginning of the live stream. (VOD streams will always begin from the beginning).

``` JavaScript
meisterPlayer.setItem({
    src: 'https://example.com/secure/stream/manifest.mpd',
    startFromBeginning: true,
    type: 'mpd'
});
```

Or you can give an object with an offset to start from a offset

``` JavaScript
meisterPlayer.setItem({
    src: 'https://example.com/secure/stream/manifest.mpd',
    startFromBeginning: {
        offset: 10, // Start from the "beginning" with an offset of 10 seconds
    },
    type: 'mpd'
});
```

### shakaConfig *[Object]* (default: {}) ###

Through this option it is possible to set override default values in the Shaka player configuration on a per item basis. This object is directly passed to the `configure` call of the Shaka instance. See the [docs](https://shaka-player-demo.appspot.com/docs/api/shaka.extern.html#.PlayerConfiguration) for information on the configuration object.  
```JavaScript
meisterPlayer.setItem({
    src: 'https://example.com/secure/stream/manifest.mpd',
    shakaConfig: {
        manifest: {
            availabilityWindowOverride: 100,
        },
    }
    type: 'mpd'
});
```

### customFilters *[Array]* (default: []]) ###

While using Shaka for playback of DRM encrypted content there are two extra fields you can add to the Widevine or PlayReady config of the drmConfig object. These fields allow adding custom request and response filters as per the Shaka documentation.
```JavaScript
meisterPlayer.setItem({
    src: 'https://example.com/secure/stream/manifest.mpd',
    drmConfig: {
        widevine: {
            customRequestFilters: [(type, request) => {
                if (type === shaka.net.NetworkingEngine.RequestType.LICENSE) {
                    const originalBody = request.body;
                    const newBody = {
                        licenseChallenge: originalBody;
                    }
                    request.body = JSON.stringify(newBody);
                }
            }],
            customResponseFilters: [(type, response) => {
                if (type === shaka.net.NetworkingEngine.RequestType.LICENSE) {
                    const originalResponse = response.data;
                    const license = originalResponse.licenseKey;
                    response.data = license;
                }
            }],
        },
    }
    type: 'mpd'
});
```