This API allows you to embed and control your Media player (audio and video) on your website with a simple JavaScript interface.
The API requires to be loaded in a browser with JavaScript enabled. Nearly all modern browsers support this feature, including Internet Explorer 9+.
Currently the API allow you to select a specific version in url if you want. Latest version will be used unless specified.
Resource:
https://player.cdn.mdstrm.com/lightning_player/<VERSION>/api.js
Examples:
- Using latest:
https://player.cdn.mdstrm.com/lightning_player/api.js - Using v0.0.128:
https://player.cdn.mdstrm.com/lightning_player/v0.0.128/api.js
There are many ways to load the player API. You should choose the one that best fits your particular implementation needs.
Player will be rendered where the script is placed unless combined with data-container attribute. You can attach a playerloaded event to the script to know when it has been loaded. NOTE: The event structure has a detail property which corresponds to the player API instance.
<!doctype html>
<html>
<body>
<script
src="https://player.cdn.mdstrm.com/lightning_player/api.js"
data-type="media"
data-id="5f7f563e34cd7e08221af329"
data-app-name="appName"
id="playerScript"
></script>
<script type="text/javascript">
document.getElementById('playerScript').addEventListener('playerloaded', ({ detail: player }) => {
/**
* Here you can use player api
*/
console.log('*** player loaded', player)
})
</script>
</body>
</html>Player will be rendered where the script is placed unless combined with data-container attribute. You can attach a data-loaded attribute referencing the name of a global (window scope) function to be called when loaded.
<!doctype html>
<html>
<head>
<script type="text/javascript">
function playerLoaded (player) {
/**
* Here you can use player api
*/
console.log('*** player loaded', player)
}
</script>
</head>
<body>
<script
src="https://player.cdn.mdstrm.com/lightning_player/api.js"
data-type="media"
data-id="5f7f563e34cd7e08221af329"
data-app-name="appName"
id="playerScript"
data-loaded="playerLoaded"
></script>
</body>
</html>Using the data-container attribute when loading script tag you can inform where the content should be rendered, thus eliminating the need to place the script itself inside the page body. You will need to use either the playerloaded event or the data-loaded attribute to know when the player has been loaded.
<!doctype html>
<html>
<head>
<script type="text/javascript">
function playerLoaded (player) {
/**
* Here you can use player api
*/
console.log('*** player loaded', player)
}
</script>
<script
src="https://player.cdn.mdstrm.com/lightning_player/api.js"
data-container="player-div"
data-type="media"
data-id="5f7f563e34cd7e08221af329"
data-app-name="appName"
id="playerScript"
data-loaded="playerLoaded"
></script>
</head>
<body>
<div id="player-div"></div>
</body>
</html>A loadMSPlayer function will be attached to the window scope when no data-id attribute exists on the script tag. This allows for the API to be instantiated manually when needed. The loadMSPlayer function returns a Promise that will resolve with the player API instance. NOTE: Options passed as second parameter for this function are the same supported as tag attributes when loading with the script tag directly, but they are camelCased instead of dash-cased. For example, the equivalence for data-ads-map would be adsMap.
<!doctype html>
<html>
<head>
<script src="https://player.cdn.mdstrm.com/lightning_player/api.js"></script>
</head>
<body>
<div id="player-div"></div>
<script>
loadMSPlayer('player-div', {
type: 'media',
id: '5f7f563e34cd7e08221af329',
volume: 0,
appName: 'appName'
}).then(player => {
/**
* Here you can use player api
*/
console.log('** player loaded', player)
}).catch(console.error)
</script>
</body>
</html>You can specify many attributes when loading the script. Those attributes will be taken into account when constructing the player. If the value of the attribute looks like $value it will be read from window[value] when loading.
| Name | loadMSPlayer option | Mandatory | Type | Description |
|---|---|---|---|---|
| src | N/A | Yes | String | Source of player javascript file. |
| data-type | type | Yes | String | Content type. Possible values: media, live, dvr, episode. |
| data-id | id | Yes | String | Id of content to load. |
| data-width | N/A | No | String | Embed width, it can be any unit css this set the style on div. |
| data-height | N/A | No | String | Embed height, it can be any unit css this set the style on div. |
| data-autoplay | autoplay | No | Boolean | Enable / Disable autoplay. Defaults to Platform player config. |
| data-volume | volume | No | Number | Sets initial volume (from 0 to 1). |
| data-container | N/A | No | String | DOM element id to search for and insert player in. The player will load where the script is places unless provided. When using the loadMSPlayer function, container id is passed as the first parameter. |
| data-player | player | No | String | Platform player id to be used. Correct default player will be inferred from content passed if not provided. |
| data-dnt | dnt | No | Boolean | Disable analytics tracking. Default: false. |
| data-access-token | accessToken | No | String | Content playback access token. |
| data-app-name | appName | No | String | Custom name for app player. Default: lightning-player. |
| data-app-version | appVersion | No | String | Useful to identify you app version. Default: Current lightning player version. |
| data-app-type | appType | No | String | Type of player app. Default: web-app. |
| data-start-pos | startPos | No | Number | Position in seconds from where to start playing. Default: 0. |
| data-ads-map | adsMap | No | String | Custom ad VAST tag URL. |
| data-google-ima-ppid | googleImaPpid | No | String | Sets the Publisher provided identifier (PPID). |
| data-customer | customer | No | String | Customer id you are playing for analytics and continue playback. |
| data-distributor | distributor | No | String | Distributor id for analytics. |
| data-custom-* | custom | No | String or Object | Customs variables for ads. Note that data-custom-example=1 would be equivalent to {custom: {example: 1}} when using loadMSPlayer function |
| data-view | view | No | String | Override the view to be used. Setting this option to none will render a player with no view elements. |
| data-render-as | renderAs | No | String | Inform the player what type of content you want to handle when using none view. Possible values are video or audio |
| data-detect-adblocker | detectAdblocker | No | Boolean | Enable / Disable adblock detector. Default: false. |
| data-without-cookies | withoutCookies | No | Boolean | Enable / Disable Mediastream cookies. |
| data-ref | ref | No | String | Send custom referrer for analytics. Default: location.hostname. |
| data-listener-id | listenerId | No | String | Send Apple Id For Advertising (IDFA) or Google Advertising Id (GAID) |
DVR (Digital Video Recorder) allows users to watch live content with the ability to pause, rewind, and seek through the content.
Note: DVR functionality is only available for video content (data-view="video").
To enable DVR functionality, set the data-type attribute to "dvr" when loading the player:
<script
src="https://player.cdn.mdstrm.com/lightning_player/api.js"
data-type="dvr"
data-id="your-live-content-id"
data-app-name="appName"
></script>| Parameter | Description | Example |
|---|---|---|
| data-type="dvr" | Enables DVR functionality | data-type="dvr" |
| data-start | Start time in date format (optional) | data-start="2024-01-15T10:00:00Z" |
| data-end | End time in date format (optional) | data-end="2024-01-15T12:00:00Z" |
Live DVR with default window:
<script
src="https://player.cdn.mdstrm.com/lightning_player/api.js"
data-type="dvr"
data-view="video"
data-id="your-live-content-id"
data-app-name="appName"
></script>DVR starting from specific time:
<script
src="https://player.cdn.mdstrm.com/lightning_player/api.js"
data-type="dvr"
data-view="video"
data-id="your-live-content-id"
data-start="2024-01-15T10:00:00Z"
data-app-name="appName"
></script>DVR with start and end (VOD-like):
<script
src="https://player.cdn.mdstrm.com/lightning_player/api.js"
data-type="dvr"
data-view="video"
data-id="your-live-content-id"
data-start="2024-01-15T10:00:00Z"
data-end="2024-01-15T12:00:00Z"
data-app-name="appName"
></script>Once loaded, you can read and write attributes using the HTML5 compatible API exposed by the player.
<!doctype html>
<html>
<head>
<script src="https://player.cdn.mdstrm.com/lightning_player/api.js"></script>
</head>
<body>
<div id="player-div"></div>
<script>
loadMSPlayer('player-div', {
type: 'media',
id: '5f7f563e34cd7e08221af329',
volume: 0,
appName: 'appName'
}).then(player => {
player.volume = 1 // set volume to 100%
console.log(player.status) // will log player status
}).catch(console.error)
</script>
</body>
</html>Custom API attributes are non standard properties that are exposed by the API and are not part of the HTML 5 standard or have been overloaded.
| Property | Description | Type | Readonly |
|---|---|---|---|
| fullscreen | Gets / Sets fullscreen state. Only on player views that support fullscreen. | Boolean | No |
| playerType | Gets player type. | String | Yes |
| fps | Gets detected frames per seconds. Only available when using Hls.js. | Number | Yes |
| status | Gets current playback status. | String | Yes |
| bandwidth | Gets detected bandwidth. Only available when using Hls.js. | Number | Yes |
| level | Gets current level. Only available when using Hls.js. | Number | No |
| nextlevel | Gets the next level to be used. Only available when using Hls.js. | Number | Yes |
| autoLevelEnabled | Will be true if using automatic level switching. Only available when using Hls.js. | Boolean | Yes |
| levels | Gets available levels. Only available when using Hls.js. | Array | Yes |
| edge | Gets detected current edge server being used. Only available when using Hls.js. | String | Yes |
| bitrate | Gets detected bitrate. Only available when using Hls.js. | Number | Yes |
| droppedFrames | Shows dropped frames count. | Number | Yes |
| type | Gets current player type. Can be one of audio, video. | String | Yes |
| sourceType | Gets detected source type. (Ex: hls or mp4). | String | Yes |
| isLive | Gets if content being played is live. | Boolean | Yes |
| isDVR | Gets if content being played is DVR. | Boolean | Yes |
| hasAdblocker | Gets if an ad blocker was detected When "Adblocker Detector" option is enabled. | Boolean | Yes |
| ad.info | Gets current playing ad information when applicable. Available information is: clickThroughUrl, contentType, currentTime, duration, podIndex, remainingTime, skippable, isLinear. | Object | Yes |
| ad.cuePoints | Gets the cue point list representing a time-schedule of ad breaks. Note that individual ads in the ad break are not included in the schedule. | Array | Yes |
| videoWidth | Gets video width. | Number | Yes |
| videoHeight | Gets video height. | Number | Yes |
| metadata | Provides current content metadata, such as title, thumbnail, etc | Object | Yes |
These HTML 5 standard attributes are accessible through the API.
| Property | Description | Type | Readonly |
|---|---|---|---|
| volume | Gets / Sets volume (from 0 to 1). | Number | No |
| src | Gets / Sets current video/audio URL source. | String | No |
| currentTime | Gets / Sets playback current time in seconds. | Number | No |
| paused | Gets if player paused status. | Boolean | Yes |
| duration | Gets video/audio duration in seconds. | Number | Yes |
| autoplay | Gets autoplay settings. | Boolean | Yes |
| ended | Get if video/audio has ended. | Boolean | Yes |
| readyState | Gets player readyState. | Number | Yes |
| seekable | Returns a TimeRanges object representing the seekable parts of the audio/video. | Object | Yes |
| textTracks | returns a TextTrackList object listing all of the TextTrack objects representing the media element's text tracks. For more information refer to the TextTrackList API section | TextTrackList | Yes |
The native API is wrapped to provide a seamless integration, supporting the following features:
- Accessing TextTrack object by index (Ex: api.textTracks[0]), by the getTrackById method (Ex: api.textTracks.getTrackById('someTrackId')), or by the addtrack event emitted by the TextTrackList and texttrackaddtrack event emitted by the global API emitter. TextTrack objects behave as described in the TextTrack API section
- Event emitter is exposed by addEventListener and removeEventListener methods, and can also be accessed by the onchange, onaddtrack and onremovetrack setters.
- Emits change, addtrack and removetrack as an alternative to the events texttrackchange, texttrackaddtrack and texttrackremovetrak described in the TextTrackList Events section.
Every text track available during playback is managed by its corresponding TextTrack reference, adhering to the HTML5 standard.
| Property | Description | Type | Readonly |
|---|---|---|---|
| id | A string which identifies the track, if it has one. If it doesn't have an ID, then this value is an empty string. | String | Yes |
| kind | Returns a string indicating what kind of text track the TextTrack describes. | String | Yes |
| label | A human-readable string which contains the text track's label, if one is present; otherwise, this is an empty string. | String | Yes |
| language | A string which specifies the text language in which the text track's contents is written. For example, this can be en-US for United States English or pt-BR for Brazilian Portuguese. | String | Yes |
| mode | A string specifying the track's current mode, which must be one of the permitted values. Changing this property's value changes the track's current mode to match. | String | No |
TextTrack.mode is used to control whether a track is being shown or not. Supported values are:
- disabled - The text track is currently disabled. Even though the track does exist, nothing will happen with it.
- hidden - The track is active, but nothing is displayed. This feature is NOT fully supported by the Player.
- showing - The text track is currently enabled and is visible.
NOTE: When track is set in showing mode, any other track that was previously showing will be changed to disabled.
| Method | Description |
|---|---|
| play | Request for the current media to start playing. Returns a promise that will resolve when playing request is successful or reject otherwise. |
| pause | Request for the currently playing media to be paused. |
| load | Load new content dynamically. |
| addToPlaylist | Add new content to playlist queue. |
| destroy | Destroys current player API instance. |
| on | Adds an event listener. |
| once | Adds an event listener that will fire only once. |
| off | Removes an event listener. |
| ad.skip | When an ad is playing, and it's flagged as skippable, it can be skipped by calling this method. |
| Option | Required | Description |
|---|---|---|
| type | Yes | Media type. Possible values: media, episode, live, dvr |
| id | Yes | Media, episode or live id. |
| Option | Required | Description |
|---|---|---|
| type | Yes | Media type. Possible values: media, episode |
| id | Yes | Media or episode id. |
Events are triggered to inform when things change. To listen to an event you can use either the on or once methods, and you use the off method to remove an event listener. The event listeners will behave exactly like the native event listener does.
// will call onReady function every time the event is fired
player.on('ready', onReady)
function onReady () {
console.log('player ready')
// Removes the onReady event handler
player.off('ready', onReady)
}
// Will fire once and never again
player.once('canplay', function onCanPlay () {
player.play()
})Custom events are non standard events that are fired by the player API and are not part of the HTML 5 standard or have been overloaded.
| Event name | Description |
|---|---|
| loaded | Fires when the API has finished loading everything it needs to initialize. |
| sourcechange | Fires when a new source is passed to the player. |
| error | Fires when an error is detected. |
| ready | Fires when player API is ready to be used. |
| buffering | Fires when player has no buffer ahead to continue playing and is requesting some. |
| programdatetime | Fires when live manifests inform program date time. |
| adblockerDetected | Fires when Adblocker detection is enabled and an adblocker is detected. |
| share | Fires when social share button is clicked. |
| levelchange | Fires when the level (quality) change has been requested. |
| levelchanged | Fires when the level (quality) has changed. |
| metadataloading | Fires before a load request is send to the server when loading new content |
| metadataloaded | Fires when content metadata has been loaded |
| metadatachanged | Fires when content metadata changes |
These HTML 5 standard events are proxied through the event emitter.
| Event name | Description |
|---|---|
| abort | Fires when the loading of an audio/video is aborted |
| canplay | Fires when the browser can start playing the audio/video |
| canplaythrough | Fires when the browser can play through the audio/video without stopping for buffering |
| durationchange | Fires when the duration of the audio/video is changed |
| emptied | Fires when the current playlist is empty |
| ended | Fires when the current playlist has ended |
| loadeddata | Fires when the browser has loaded the current frame of the audio/video |
| loadedmetadata | Fires when the browser has loaded meta data for the audio/video |
| loadstart | Fires when the browser starts looking for the audio/video |
| pause | Fires when the audio/video has been paused |
| play | Fires when the audio/video has been started or is no longer paused |
| playing | Fires when the audio/video is playing after having been paused or stopped for buffering |
| progress | Fires when the browser is downloading the audio/video |
| ratechange | Fires when the playing speed of the audio/video is changed |
| seeked | Fires when the user is finished moving/skipping to a new position in the audio/video |
| seeking | Fires when the user starts moving/skipping to a new position in the audio/video |
| stalled | Fires when the browser is trying to get media data, but data is not available |
| suspend | Fires when the browser is intentionally not getting media data |
| timeupdate | Fires when the current playback position has changed |
| volumechange | Fires when the volume has been changed |
| waiting | Fires when the video stops because it needs to buffer the next frame |
TextTrackList events are prefixed with texttrack and re-emitted from the event emitter for ease of use, even though they can be used by accessing the api.textTracks event listener directly as well.
| Event name | Description |
|---|---|
| change | The change event is fired when a text track is made active or inactive, or a TextTrackList is otherwise changed. |
| addtrack | The addtrack event is fired when a track is added to a TextTrackList. The event payload will contain a track property corresponding to the TextTrack to which the event refers. |
| removetrack | The removetrack event is fired when a track is removed from a TextTrackList. The event payload will contain a track property corresponding to the TextTrack to which the event refers. |
These events are fired for Ad playback life cycle.
| Event name | Description |
|---|---|
| adsAdBreakReady | Fired when an ad rule or a VMAP ad break would have played if autoPlayAdBreaks is false |
| adsAdMetadata | Fired when an ads list is loaded |
| adsAllAdsCompleted | Fired when the ads manager is done playing all the ads |
| adsClick | Fired when the ad is clicked |
| adsComplete | Fired when the ad completes playing |
| adsContentPauseRequested | Fired when content should be paused. This usually happens right before an ad is about to cover the content |
| adsContentResumeRequested | Fired when content should be resumed. This usually happens when an ad finishes or collapses |
| adsDurationChange | Fired when the ad's duration changes |
| adsFirstQuartile | Fired when the ad playhead crosses first quartile |
| adsImpression | Fired when the impression URL has been pinged |
| adsLinearChanged | Fired when the displayed ad changes from linear to nonlinear, or vice versa |
| adsLoaded | Fired when ad data is available |
| adsLog | Fired when a non-fatal error is encountered. The user need not take any action since the SDK will continue with the same or next ad playback depending on the error situation |
| adsMidpoint | Fired when the ad playhead crosses midpoint |
| adsPaused | Fired when the ad is paused |
| adsResumed | Fired when the ad is resumed |
| adsSkippableStateChanged | Fired when the displayed ads skippable state is changed |
| adsSkipped | Fired when the ad is skipped by the user |
| adsStarted | Fired when the ad starts playing |
| adsThirdQuartile | Fired when the ad playhead crosses third quartile |
| adsTimeUpdate | Fired while ad is playing to indicate current time position has changed. |
| adsUserClose | Fired when the ad is closed by the user |
| adsVolumeChanged | Fired when the ad volume has been changed |
| adsVolumeMuted | Fired when the ad volume has been muted |
| adsError | Fired when an error occurred while the ad was loading or playing |
| adsAdBuffering | Fired when the ad has stalled playback to buffer |
| adsAdProgress | Fired when the ad's current time value changes. Calling getAdData() on this event will return an AdProgressData object |
| adsInteraction | Fired when an ad triggers the interaction callback. Ad interactions contain an interaction ID string in the ad data |
| adsVideoClicked | Fires when the non-clickthrough portion of a video ad is clicked. |
| adsVideoIconClicked | Fires when a user clicks a video icon. |