bigscreen-player 5.0.1 → 5.2.0

package/README.md

@@ -8,248 +8,45 @@
 
 *Bigscreen Player* is an open source project developed by the BBC to simplify video and audio playback on a wide range of 'bigscreen' devices (TVs, set-top boxes, games consoles, and streaming devices).
 
-## Getting Started
+For documentation on using this library, please see our [Getting Started guide](https://bbc.github.io/bigscreen-player/api/tutorial-Getting%20Started.html).
 
-`$ npm install`
+## Running Locally
 
-### Initialisation
-
-A playback session can be initialised by simply calling the `init()` function with some initial data.
-
-
-The player will render itself into a supplied parent element, and playback will begin as soon as enough data has buffered.
-
-```javascript
-import { BigscreenPlayer, MediaKinds, WindowTypes } from 'bigscreen-player'
-
-// configure the media player that will be used before loading
-// see below for further details of ths config
-
-// options are: msestrategy, nativestrategy, hybridstrategy
-window.bigscreenPlayer.playbackStrategy = 'msestrategy'
-
-const bigscreenPlayer = BigscreenPlayer()
-const playbackElement = document.createElement('div')
-const body = document.getElementByTagName('body')[0]
-
-playbackElement.id = 'BigscreenPlayback'
-body.appendChild(playbackElement)
-
-const minimalData = {
-  media: {
-    type: 'application/dash+xml',
-    urls: [
-      {
-        url: 'https://example.com/video.mpd'
-      }
-    ]
-  }
-}
-
-const optionalData = {
-  initialPlaybackTime: 0, // Time (in seconds) to begin playback from
-  media: {
-    type: 'application/dash+xml',
-    kind: MediaKinds.VIDEO, // Can be VIDEO, or AUDIO
-    urls: [
-      // Multiple urls offer the ability to fail-over to another CDN if required
-      {
-        url: 'https://example.com/video.mpd',
-        cdn: 'origin' // For Debug Tool reference
-      }, {
-        url: 'https://failover.example.com/video.mpd',
-        cdn: 'failover'
-      }
-    ],
-    captions: [{
-      url: 'https://example.com/captions/$segment$', // $segment$ required for replacement for live subtitle segments
-      segmentLength: 3.84, // Required to calculate live subtitle segment to fetch & live subtitle URL.
-      cdn: 'origin' // Displayed by Debug Tool
-    }, {
-      url: 'https://failover.example.com/captions/$segment$',
-      segmentLength: 3.84,
-      cdn: 'failover'
-    }
-    ],
-    captionsUrl: 'https://example.com/imsc-doc.xml', // NB This parameter is being deprecated in favour of the captions array shown above.
-    subtitlesRequestTimeout: 5000, // Optional override for the XHR timeout on sidecar loaded subtitles
-    subtitleCustomisation: {
-      size: 0.75,
-      lineHeight: 1.10,
-      fontFamily: 'Arial',
-      backgroundColour: 'black' // (css colour, hex)
-    },
-    playerSettings: { // This currently can be used to customise settings for the msestrategy. It is a pass through of all the dash.js player settings.
-      failoverSort: failoverSort, // Post failover custom sorting algorithm
-      failoverResetTime: 60000,
-      streaming: {
-        bufferToKeep: 8
-      }
-    }
-  }
-}
-
-// STATIC for VOD content, GROWING/SLIDING for LIVE content
-const windowType = WindowTypes.STATIC
-const enableSubtitles = false
-
-bigscreenPlayer.init(playbackElement, optionalData, windowType, enableSubtitles)
-```
-
-### Configuration
-
-Bigscreen Player has some global configuration that is needed before initialisation. A *playback strategy* may be configured, or defaulted to the native Html5 strategy:
-
-```javascript
-window.bigscreenPlayer.playbackStrategy = 'msestrategy' // OR 'nativestrategy' OR 'hybridstrategy'
+Install dependencies:
+```bash
+$ npm install
 ```
 
-See the [configuration](https://github.com/bbc/bigscreen-player/wiki/Playback-Strategy) wiki page for further details on these strategies.
-
-### Reacting to state changes
-
-State changes which are emitted from the player can be acted upon to by registering a callback. The callback will receive all of the following state changes as the `state` property of the event:
-- `MediaState.STOPPED`
-- `MediaState.PAUSED`
-- `MediaState.PLAYING`
-- `MediaState.WAITING`
-- `MediaState.ENDED`
-- `MediaState.FATAL_ERROR`
-
-State changes may be registered for before initialisation and will automatically be cleared upon `tearDown()` of the player.
-
-```javascript
-const bigscreenPlayer = BigscreenPlayer()
-
-// The token is only required in the case where the function is anonymous, a reference to the function can be stored and used to unregister otherwise.
-var stateChangeToken = bigscreenPlayer.registerForStateChanges(function (event) {
-  if(event.state == MediaState.PLAYING) {
-    console.log('Playing')
-    // handle playing event
-  }
-})
-
-bigscreenPlayer.unregisterForStateChanges(stateChangeToken)
-```
-
-### Reacting to time updates
-
-Time updates are emitted multiple times a second. Your application can register to receive these updates. The emitted object contains the `currentTime` and `endOfStream` properties.
-
-Time updates may be registered for before initialisation and will automatically be cleared upon `tearDown()` of the player.
-
-```javascript
-var bigscreenPlayer = BigscreenPlayer();
-
-// The token is only required in the case where the function is anonymous, a reference to the function can be stored and used to unregister otherwise.
-var timeUpdateToken = bigscreenPlayer.registerForTimeUpdates(function (event) {
-    console.log('Current Time: ' + event.currentTime);
-});
-
-bigscreenPlayer.unRegisterForTimeUpdates(timeUpdateToken);
+You can run Bigscreen Player locally in a dev environment by running:
+```bash
+$ npm run start
 ```
 
-### Reacting to subtitles being turned on/off
-
-This is emitted on every `setSubtitlesEnabled` call. The emitted object contains an `enabled` property.
-
-This may be registered for before initialisation and will automatically be cleared upon `tearDown()` of the player.
-
-```javascript
-var bigscreenPlayer = BigscreenPlayer();
-
-// The token is only required in the case where the function is anonymous, a reference to the function can be stored and used to unregister otherwise.
-var subtitleChangeToken = bigscreenPlayer.registerForSubtitleChanges(function (event) {
-    console.log('Subttiles enabled: ' + event.enabled);
-});
-
-bigscreenPlayer.unregisterForSubtitleChanges(subtitleChangeToken);
-```
-
-### Creating a plugin
-
-Plugins can be created to extend the functionality of the Bigscreen Player by adhering to an interface which propagates non state change events from the player. For example, when an error is raised or cleared.
-
-The full interface is as follows:
-- `onError`
-- `onFatalError`
-- `onErrorCleared`
-- `onErrorHandled`
-- `onBuffering`
-- `onBufferingCleared`
-- `onScreenCapabilityDetermined`
-
-An example plugin may look like:
-
-```javascript
-function ExamplePlugin (appName) {
-
-  var name = appName;
-
-  function onFatalError (evt) {
-    console.log('A fatal error has occured in the app: ' + name);
-  }
-
-  function onErrorHandled (evt) {
-    console.log('The ' + name + ' app is handling a playback error');
-  }
-
-  return {
-    onFatalError: onFatalError,
-    onErrorHandled: onErrorHandled
-  };
-}
-```
-
-```javascript
-var bigscreenPlayer = BigscreenPlayer();
-
-var examplePlugin = ExamplePlugin('myApp');
-
-bigscreenPlayer.registerPlugin(examplePlugin);
-
-// initialise bigscreenPlayer - see above
-
-// you should unregister your plugins as part of your playback cleanup
-
-// calling with no argument will unregister all plugins
-bigscreenPlayer.unregisterPlugin(examplePlugin);
-
-```
+This will open a web page at `localhost:8080`.
 
 ## Testing
 
 The project is unit tested using [Jest](https://jestjs.io/). To run the tests:
-
-`$ npm test`
-
+```bash
+$ npm test
+```
 This project currently has unit test coverage but no integration test suite. This is on our Roadmap to address.
 
-### Mocking media playback
-
-When writing tests for your application it may be useful to use the mocking functions provided. This creates a fake player with mocking hook functions to simulate real world scenarios.
-
-See [here](https://github.com/bbc/bigscreen-player/wiki/Mocking-Bigscreen-Player) for example usage.
-
 ## Releasing
 
 1. Create a PR.
-2. Label the PR with one of these labels:
-    - `semver prerelease`
-    - `semver patch`
-    - `semver minor`
-    - `semver major`
-
+2. Label the PR with one of these labels; `semver prerelease`, `semver patch`, `semver minor` or `semver major`
 3. Get a review from the core team.
 4. If the PR checks are green. The core team can merge to master.
 5. Automation takes care of the package versioning.
 6. Publishing to NPM is handled with our [GitHub Actions CI integration](https://github.com/bbc/bigscreen-player/blob/master/.github/workflows/npm-publish.yml).
 
+## Documentation
 
-
-## API Reference
-
-The API is documented [here](https://github.com/bbc/bigscreen-player/wiki/API-Reference).
+Bigscreen Player uses JSDocs to autogenerate API documentation. To regenerate the documentation run:
+```bash
+$ npm run docs
+```
 
 ## Contributing
 

package/dist/esm/{imscsubtitles-dcaea2e6.js → imscsubtitles-3d139d9a.js}

@@ -1,5 +1,5 @@
 import { fromXML, generateISD, renderHTML } from 'smp-imsc';
-import { b as TimeUtils, L as LoadUrl, a as DebugTool, P as Plugins, U as Utils, D as DOMHelpers } from './main-dea9f359.js';
+import { b as TimeUtils, L as LoadUrl, a as DebugTool, P as Plugins, U as Utils, D as DOMHelpers } from './main-fd918769.js';
 
 function IMSCSubtitles (mediaPlayer, autoStart, parentElement, mediaSources, defaultStyleOpts) {
   const SEGMENTS_TO_KEEP = 3;

package/dist/esm/{legacysubtitles-87c46bcc.js → legacysubtitles-bd87e09b.js}

@@ -1,4 +1,4 @@
-import { D as DOMHelpers, a as DebugTool, P as Plugins, L as LoadUrl, T as TransportControlPosition } from './main-dea9f359.js';
+import { D as DOMHelpers, a as DebugTool, P as Plugins, L as LoadUrl, T as TransportControlPosition } from './main-fd918769.js';
 
 /**
 * Safely checks if an attribute exists on an element.

package/dist/esm/{main-dea9f359.js → main-fd918769.js}

@@ -13,9 +13,17 @@ const MediaState = {
   FATAL_ERROR: 6
 };
 
+/**
+ * Enums for WindowTypes
+ * @readonly
+ * @enum {string}
+ */
 const WindowTypes = {
+  /** Media with a duration */
   STATIC: 'staticWindow',
+  /** Media with a start time but without a duration until an indeterminate time in the future */
   GROWING: 'growingWindow',
+  /** Media with a rewind window that progresses through a media timeline */
   SLIDING: 'slidingWindow'
 };
 
@@ -236,11 +244,14 @@ var Plugins = {
     onBufferingCleared: (evt) => callOnAllPlugins('onBufferingCleared', evt),
     onScreenCapabilityDetermined: (tvInfo) => callOnAllPlugins('onScreenCapabilityDetermined', tvInfo),
     onPlayerInfoUpdated: (evt) => callOnAllPlugins('onPlayerInfoUpdated', evt),
+    onManifestLoaded: (manifest) => callOnAllPlugins('onManifestLoaded', manifest),
+    onQualityChangedRendered: (evt) => callOnAllPlugins('onQualityChangedRendered', evt),
     onSubtitlesLoadError: (evt) => callOnAllPlugins('onSubtitlesLoadError', evt),
     onSubtitlesTimeout: (evt) => callOnAllPlugins('onSubtitlesTimeout', evt),
     onSubtitlesXMLError: (evt) => callOnAllPlugins('onSubtitlesXMLError', evt),
     onSubtitlesTransformError: (evt) => callOnAllPlugins('onSubtitlesTransformError', evt),
-    onSubtitlesRenderError: (evt) => callOnAllPlugins('onSubtitlesRenderError', evt)
+    onSubtitlesRenderError: (evt) => callOnAllPlugins('onSubtitlesRenderError', evt),
+    onSubtitlesDynamicLoadError: (evt) => callOnAllPlugins('onSubtitlesDynamicLoadError', evt)
   }
 };
 
@@ -835,21 +846,7 @@ if (instance === undefined) {
 
 var DebugTool$1 = instance;
 
-function PlaybackSpinner () {
-  const spinnerContainer = document.createElement('div');
-  spinnerContainer.id = 'loadingSpinner';
-  spinnerContainer.className = 'loadingSpinner loadingSpinner--large ';
-
-  const spinner = document.createElement('div');
-  spinner.className = 'loadingSpinner__spinner';
-
-  spinnerContainer.appendChild(spinner);
-
-  return spinnerContainer
-}
-
 function LiveGlitchCurtain (parentElement) {
-  let spinner = new PlaybackSpinner();
   let curtain = document.createElement('div');
 
   curtain.id = 'liveGlitchCurtain';
@@ -861,8 +858,6 @@ function LiveGlitchCurtain (parentElement) {
   curtain.style.bottom = 0;
   curtain.style.backgroundColor = '#3c3c3c';
 
-  curtain.appendChild(spinner);
-
   return {
     showCurtain: () => {
       curtain.style.display = 'block';
@@ -871,15 +866,10 @@ function LiveGlitchCurtain (parentElement) {
 
     hideCurtain: () => {
       curtain.style.display = 'none';
-      DOMHelpers.safeRemoveElement(spinner);
     },
 
     tearDown: () => {
       DOMHelpers.safeRemoveElement(curtain);
-
-      if (spinner) {
-        spinner = undefined;
-      }
     }
   }
 }
@@ -5683,12 +5673,12 @@ function StrategyPicker (windowType, isUHD) {
         return resolve(NativeStrategy)
       }
 
-      return import('./msestrategy-f7df73a1.js').then(({default: MSEStrategy}) => resolve(MSEStrategy))
+      return import('./msestrategy-af831822.js').then(({default: MSEStrategy}) => resolve(MSEStrategy))
         .catch(() => {
           reject({error: 'strategyDynamicLoadError'});
         })
     } else if (window.bigscreenPlayer.playbackStrategy === PlaybackStrategy.MSE) {
-      return import('./msestrategy-f7df73a1.js').then(({default: MSEStrategy}) => resolve(MSEStrategy))
+      return import('./msestrategy-af831822.js').then(({default: MSEStrategy}) => resolve(MSEStrategy))
         .catch(() => {
           reject({error: 'strategyDynamicLoadError'});
         })
@@ -6068,7 +6058,7 @@ function CallCallbacks (callbacks, data) {
   callbacks.forEach((callback) => DeferExceptions(() => callback(data)));
 }
 
-var version = "5.0.1";
+var version = "5.2.0";
 
 var sourceList;
 var source;
@@ -7254,14 +7244,18 @@ function Subtitles (mediaPlayer, autoStart, playbackElement, defaultStyleOpts, m
   let subtitlesContainer;
 
   if (useLegacySubs) {
-    import('./legacysubtitles-87c46bcc.js').then(({default: LegacySubtitles}) => {
+    import('./legacysubtitles-bd87e09b.js').then(({default: LegacySubtitles}) => {
       subtitlesContainer = LegacySubtitles(mediaPlayer, autoStart, playbackElement, mediaSources, defaultStyleOpts);
       callback(subtitlesEnabled);
+    }).catch(() => {
+      Plugins.interface.onSubtitlesDynamicLoadError();
     });
   } else {
-    import('./imscsubtitles-dcaea2e6.js').then(({default: IMSCSubtitles}) => {
+    import('./imscsubtitles-3d139d9a.js').then(({default: IMSCSubtitles}) => {
       subtitlesContainer = IMSCSubtitles(mediaPlayer, autoStart, playbackElement, mediaSources, defaultStyleOpts);
       callback(subtitlesEnabled);
+    }).catch(() => {
+      Plugins.interface.onSubtitlesDynamicLoadError();
     });
   }
 
@@ -7332,6 +7326,10 @@ function Subtitles (mediaPlayer, autoStart, playbackElement, defaultStyleOpts, m
   }
 }
 
+/**
+ * @module bigscreenplayer/bigscreenplayer
+ */
+
 function BigscreenPlayer () {
   let stateChangeCallbacks = [];
   let timeUpdateCallbacks = [];
@@ -7489,7 +7487,19 @@ function BigscreenPlayer () {
     return subtitles ? subtitles.available() : false
   }
 
-  return {
+  return /** @alias module:bigscreenplayer/bigscreenplayer */{
+
+    /**
+     * Call first to initialise bigscreen player for playback.
+     * @function
+     * @name init
+     * @param {HTMLDivElement} playbackElement - The Div element where content elements should be rendered
+     * @param {BigscreenPlayerData} bigscreenPlayerData
+     * @param {WindowTypes} newWindowType
+     * @param {boolean} enableSubtitles - Enable subtitles on initialisation
+     * @param {TALDevice} newDevice - An optional TAL device object
+     * @param {InitCallbacks} callbacks
+     */
     init: (newPlaybackElement, bigscreenPlayerData, newWindowType, enableSubtitles, callbacks) => {
       playbackElement = newPlaybackElement;
       Chronicle.init();
@@ -7526,6 +7536,11 @@ function BigscreenPlayer () {
       mediaSources.init(bigscreenPlayerData.media, serverDate, windowType, getLiveSupport(), mediaSourceCallbacks);
     },
 
+    /**
+     * Should be called at the end of all playback sessions. Resets state and clears any UI.
+     * @function
+     * @name tearDown
+     */
     tearDown: function () {
       if (subtitles) {
         subtitles.tearDown();
@@ -7555,11 +7570,22 @@ function BigscreenPlayer () {
       Chronicle.tearDown();
     },
 
+    /**
+     * Pass a function to call whenever the player transitions state.
+     * @see {@link module:models/mediastate}
+     * @function
+     * @param {Function} callback
+     */
     registerForStateChanges: (callback) => {
       stateChangeCallbacks.push(callback);
       return callback
     },
 
+    /**
+     * Unregisters a previously registered callback.
+     * @function
+     * @param {Function} callback
+     */
     unregisterForStateChanges: (callback) => {
       const indexOf = stateChangeCallbacks.indexOf(callback);
       if (indexOf !== -1) {
@@ -7567,11 +7593,21 @@ function BigscreenPlayer () {
       }
     },
 
+    /**
+     * Pass a function to call whenever the player issues a time update.
+     * @function
+     * @param {Function} callback
+     */
     registerForTimeUpdates: (callback) => {
       timeUpdateCallbacks.push(callback);
       return callback
     },
 
+    /**
+     * Unregisters a previously registered callback.
+     * @function
+     * @param {Function} callback
+     */
     unregisterForTimeUpdates: (callback) => {
       const indexOf = timeUpdateCallbacks.indexOf(callback);
 
@@ -7580,11 +7616,21 @@ function BigscreenPlayer () {
       }
     },
 
+    /**
+     * Pass a function to be called whenever subtitles are enabled or disabled.
+     * @function
+     * @param {Function} callback
+     */
     registerForSubtitleChanges: (callback) => {
       subtitleCallbacks.push(callback);
       return callback
     },
 
+    /**
+     * Unregisters a previously registered callback for changes to subtitles.
+     * @function
+     * @param {Function} callback
+     */
     unregisterForSubtitleChanges: (callback) => {
       const indexOf = subtitleCallbacks.indexOf(callback);
       if (indexOf !== -1) {
@@ -7592,6 +7638,11 @@ function BigscreenPlayer () {
       }
     },
 
+    /**
+     * Sets the current time of the media asset.
+     * @function
+     * @param {Number} time - In seconds
+     */
     setCurrentTime: function (time) {
       DebugTool$1.apicall('setCurrentTime');
       if (playerComponent) {
@@ -7609,15 +7660,46 @@ function BigscreenPlayer () {
     },
 
     getPlaybackRate: () => playerComponent && playerComponent.getPlaybackRate(),
+
+    /**
+     * Returns the media asset's current time in seconds.
+     * @function
+     */
     getCurrentTime: () => playerComponent && playerComponent.getCurrentTime() || 0,
+
+    /**
+     * Returns the current media kind.
+     * 'audio' or 'video'
+     * @function
+     */
     getMediaKind: () => mediaKind,
+
+    /**
+     * Returns the current window type.
+     * @see {@link module:bigscreenplayer/models/windowtypes}
+     * @function
+     */
     getWindowType: () => windowType,
+
+    /**
+     * Returns an object including the current start and end times.
+     * @function
+     * @returns {Object} {start: Number, end: Number}
+     */
     getSeekableRange: () => playerComponent ? playerComponent.getSeekableRange() : {},
 
+    /**
+    * @function
+    * @returns {boolean} Returns true if media is initialised and playing a live stream within a tolerance of the end of the seekable range (10 seconds).
+    */
     isPlayingAtLiveEdge: function () {
       return !!playerComponent && windowType !== WindowTypes.STATIC && Math.abs(this.getSeekableRange().end - this.getCurrentTime()) < END_OF_STREAM_TOLERANCE
     },
 
+    /**
+     * @function
+     * @return {Object} An object of the shape {windowStartTime: Number, windowEndTime: Number, initialPlaybackTime: Number, serverDate: Date}
+     */
     getLiveWindowData: () => {
       if (windowType === WindowTypes.STATIC) {
         return {}
@@ -7631,15 +7713,39 @@ function BigscreenPlayer () {
       }
     },
 
+    /**
+     * @function
+     * @returns the duration of the media asset.
+     */
     getDuration: () => playerComponent && playerComponent.getDuration(),
+
+    /**
+     * @function
+     * @returns if the player is paused.
+     */
     isPaused: () => playerComponent ? playerComponent.isPaused() : true,
+
+    /**
+     * @function
+     * @returns if the media asset has ended.
+     */
     isEnded: () => playerComponent ? playerComponent.isEnded() : false,
 
+    /**
+     * Play the media assest from the current point in time.
+     * @function
+     */
     play: () => {
       DebugTool$1.apicall('play');
       playerComponent.play();
     },
-
+    /**
+     * Pause the media asset.
+     * @function
+     * @param {*} opts
+     * @param {boolean} opts.userPause
+     * @param {boolean} opts.disableAutoResume
+     */
     pause: (opts) => {
       DebugTool$1.apicall('pause');
       pauseTrigger = opts && opts.userPause === false ? PauseTriggers.APP : PauseTriggers.USER;
@@ -7660,8 +7766,23 @@ function BigscreenPlayer () {
       resizer.clear(playbackElement);
     },
 
+    /**
+     * Set whether or not subtitles should be enabled.
+     * @function
+     * @param {boolean} value
+     */
     setSubtitlesEnabled: setSubtitlesEnabled,
+
+    /**
+     * @function
+     * @return if subtitles are currently enabled.
+     */
     isSubtitlesEnabled: isSubtitlesEnabled,
+
+    /**
+     * @function
+     * @return Returns whether or not subtitles are currently enabled.
+     */
     isSubtitlesAvailable: isSubtitlesAvailable,
 
     areSubtitlesCustomisable: () => {
@@ -7686,45 +7807,132 @@ function BigscreenPlayer () {
       }
     },
 
+    /**
+     *
+     * An enum may be used to set the on-screen position of any transport controls
+     * (work in progress to remove this - UI concern).
+     * @function
+     * @param {*} position
+     */
     setTransportControlsPosition: (position) => {
       if (subtitles) {
         subtitles.setPosition(position);
       }
     },
 
+    /**
+     * @function
+     * @return Returns whether the current media asset is seekable.
+     */
     canSeek: function () {
       return windowType === WindowTypes.STATIC || DynamicWindowUtils.canSeek(getWindowStartTime(), getWindowEndTime(), getLiveSupport(), this.getSeekableRange())
     },
 
+    /**
+     * @function
+     * @return Returns whether the current media asset is pausable.
+     */
     canPause: () => {
       return windowType === WindowTypes.STATIC || DynamicWindowUtils.canPause(getWindowStartTime(), getWindowEndTime(), getLiveSupport())
     },
 
+    /**
+     * Return a mock for in place testing.
+     * @function
+     * @param {*} opts
+     */
     mock: function (opts) { MockBigscreenPlayer.mock(this, opts); },
+
+    /**
+     * Unmock the player.
+     * @function
+     */
     unmock: function () { MockBigscreenPlayer.unmock(this); },
+
+    /**
+     * Return a mock for unit tests.
+     * @function
+     * @param {*} opts
+     */
     mockJasmine: function (opts) { MockBigscreenPlayer.mockJasmine(this, opts); },
 
+    /**
+     * Register a plugin for extended events.
+     * @function
+     * @param {*} plugin
+     */
     registerPlugin: (plugin) => Plugins.registerPlugin(plugin),
+
+    /**
+     * Unregister a previously registered plugin.
+     * @function
+     * @param {*} plugin
+     */
     unregisterPlugin: (plugin) => Plugins.unregisterPlugin(plugin),
+
+    /**
+     * Returns an object with a number of functions related to the ability to transition state
+     * given the current state and the playback strategy in use.
+     * @function
+     */
     transitions: () => playerComponent ? playerComponent.transitions() : {},
+
+    /**
+     * @function
+     * @return The media element currently being used.
+     */
     getPlayerElement: () => playerComponent && playerComponent.getPlayerElement(),
 
+    /**
+     * @function
+     * @param {Number} epochTime - Unix Epoch based time in milliseconds.
+     * @return the time in seconds within the current sliding window.
+     */
     convertEpochMsToVideoTimeSeconds: (epochTime) => {
       return getWindowStartTime() ? Math.floor((epochTime - getWindowStartTime()) / 1000) : undefined
     },
 
+    /**
+     * @function
+     * @return The runtime version of the library.
+     */
     getFrameworkVersion: () => {
       return version
     },
 
+    /**
+     * @function
+     * @param {Number} time - Seconds
+     * @return the time in milliseconds within the current sliding window.
+     */
     convertVideoTimeSecondsToEpochMs: convertVideoTimeSecondsToEpochMs,
+
+    /**
+     * Toggle the visibility of the debug tool overlay.
+     * @function
+     */
     toggleDebug: toggleDebug,
+
+    /**
+     * @function
+     * @return {Object} - Key value pairs of available log levels
+     */
     getLogLevels: () => DebugTool$1.logLevels,
+
+    /**
+     * @function
+     * @param logLevel -  log level to display @see getLogLevels
+     */
     setLogLevel: DebugTool$1.setLogLevel,
     getDebugLogs: () => Chronicle.retrieve()
   }
 }
 
+/**
+ * @function
+ * @param {TALDevice} device
+ * @return the live support of the device.
+ */
 function getLiveSupport () {
   return PlayerComponent.getLiveSupport()
 }

package/dist/esm/main.js

@@ -1 +1 @@
-export { B as BigscreenPlayer, c as LiveSupport, d as MediaKinds, M as MediaState, f as MockBigscreenPlayer, g as PauseTriggers, h as PlaybackStrategy, i as TransferFormat, T as TransportControlPosition, W as WindowTypes } from './main-dea9f359.js';
+export { B as BigscreenPlayer, c as LiveSupport, d as MediaKinds, M as MediaState, f as MockBigscreenPlayer, g as PauseTriggers, h as PlaybackStrategy, i as TransferFormat, T as TransportControlPosition, W as WindowTypes } from './main-fd918769.js';

package/dist/esm/{msestrategy-f7df73a1.js → msestrategy-af831822.js}

@@ -1,4 +1,4 @@
-import { D as DOMHelpers, W as WindowTypes, c as LiveSupport, M as MediaState, a as DebugTool, d as MediaKinds, P as Plugins, U as Utils, b as TimeUtils, e as DynamicWindowUtils } from './main-dea9f359.js';
+import { D as DOMHelpers, W as WindowTypes, c as LiveSupport, M as MediaState, a as DebugTool, P as Plugins, d as MediaKinds, U as Utils, b as TimeUtils, e as DynamicWindowUtils } from './main-fd918769.js';
 import { MediaPlayer } from 'dashjs/index_mediaplayerOnly';
 
 function filter (manifest, representationOptions) {
@@ -259,9 +259,15 @@ function MSEStrategy (mediaSources, windowType, mediaKind, playbackElement, isUH
 
       ManifestModifier.filter(manifest, representationOptions);
       ManifestModifier.generateBaseUrls(manifest, mediaSources.availableSources());
+
+      emitManifestInfo(manifest);
     }
   }
 
+  function emitManifestInfo (manifest) {
+    Plugins.interface.onManifestLoaded(manifest);
+  }
+
   function onManifestValidityChange (event) {
     DebugTool.info('Manifest validity changed. Duration is: ' + event.newDuration);
   }
@@ -325,6 +331,7 @@ function MSEStrategy (mediaSources, windowType, mediaKind, playbackElement, isUH
     }
 
     emitPlayerInfo();
+    Plugins.interface.onQualityChangedRendered(event);
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigscreen-player",
-  "version": "5.0.1",
+  "version": "5.2.0",
   "description": "Simplified media playback for bigscreen devices.",
   "main": "dist/esm/main.js",
   "browser": "dist/esm/main.js",
@@ -15,6 +15,7 @@
   ],
   "scripts": {
     "prepare": "[ ! -d dist/ ] && npm run build || exit 0",
+    "docs": "npx jsdoc -c jsdoc.conf.json",
     "build": "rollup -c rollup.config.js",
     "start": "rollup -c rollup.dev.config.js -w",
     "test": "jest",
@@ -37,6 +38,7 @@
     "@rollup/plugin-json": "^4.1.0",
     "@rollup/plugin-node-resolve": "^13.0.4",
     "babel-jest": "^27.0.6",
+    "clean-jsdoc-theme": "^3.2.7",
     "eslint": "^7.2.0",
     "eslint-plugin-es5": "1.3.1",
     "eslint-plugin-jest": "^24.4.0",
@@ -45,6 +47,7 @@
     "eslint-plugin-standard": "4.0.0",
     "husky": "^4.2.5",
     "jest": "^27.0.6",
+    "jsdoc": "^3.6.4",
     "rollup": "^2.54.0",
     "rollup-plugin-livereload": "^2.0.5",
     "rollup-plugin-polyfill-node": "^0.7.0",