Radiant Media Player

API Documentation



API documentation sections


Introduction

Radiant Media Player provides a complete JavaScript API to programmatically control the player, allowing for custom applications to be built on top of the player.

When working with the player API we recommend that you self-host the player files or use a specific version of the cloud player (example for current version: https://cdn.radiantmediatechs.com/rmp/4.1.3/js/rmp.min.js).

As a start point you may review our implementation example here:

Player API demo

For our ads API please visit this link.


Set up

A basic example of player API usage will look like:

<!-- Include Radiant Media Player JavaScript file in your <body> or <head> -->
<script src="https://cdn.radiantmediatechs.com/rmp/4.1.3/js/rmp.min.js"></script>
<!-- Set up your wrapper div with its unique id -->
<div id="rmpPlayer"></div>
<!-- Set up player configuration options -->
<script>
// First we specify bitrates to feed to the player
var bitrates = {
  hls: 'https://dqwp3xzzbfhtw.cloudfront.net/vod/smil:bbb.smil/playlist.m3u8'
};
// Then we set our player settings
var settings = {
  licenseKey: 'your-license-key',
  bitrates: bitrates,
  delayToFade: 3000,
  width: 640,
  height: 360,
  poster: 'https://www.radiantmediaplayer.com/images/poster-rmp-showcase.jpg'
};
// Reference to the wrapper div (unique id)
var elementID = 'rmpPlayer';
// Object creation
var rmp = new RadiantMP(elementID);
// Reference to the player container which will receive API events
var rmpContainer = document.getElementById(elementID);
rmpContainer.addEventListener('ready', function() {
  console.log('player ready');
  // we can call API methods now that player is ready
  rmp.setVolume(0.5);
});
rmpContainer.addEventListener('play', function() {
  console.log('player has received play event');
});
// Player initialisation only after API events are registered
rmp.init(settings);
</script>

Player API events

Below is a list of events that are dispatched by Radiant Media Player.

You must attach your listener to the player container before calling the player init method - otherwise you may miss some!

Events are registered with the native JavaScript addEventListener method applied to the player div wrapper: rmpContainer as defined above. They are unregistered with the removeEventListener method. You must use named function to use the removeEventListener method, anonymous functions will not be removed.

All events fired by the player API are non-bubbling events.

General player events

  • ready the player is ready to receive calls from the API and is appended to DOM
  • play the play event fires when the player starts or resumes playback
  • pause the pause event fires when the player has paused playback
  • timeupdate the timeupdate event fires when the current playback position changes
  • ended the ended event fires when playback for the current content has ended
  • error this event fires when a fatal error is encountered and the player cannot recover from it. Those errors are most of the time network errors when trying to access the content(403, 404 ...). Various internal mechanisms are in place to avoid fatal error but they can still happen. Those errors can also be fatal playback or DRM errors
  • loadstart fires when the player starts looking for the specified media
  • loadedmetadata fires when the player has loaded meta data for the video
  • durationchange the player has received metadata information about content duration
  • loadeddata fires when the player has loaded the current frame of the media
  • progress fires when the player is downloading media data
  • canplay fires when the player can start playing the media
  • canplaythrough fires when the player can play through the video without stopping for buffering
  • waiting fires when media stops because it needs to buffer the next frame
  • playing fires when media is playing after having been paused or stopped for buffering
  • seeking fires when the player starts moving to a new position in the media
  • seeked fires when the player is finished moving to a new position in the media
  • stalled fires when the player is trying to get media data, but data is not available
  • suspend fires when the player is intentionally not getting media data
  • abort fires when the loading of content is aborted - this event occurs when media data download has been aborted - not because of an error
  • ratechange fires when the playing speed of the video is changed
  • volumechange fires when the player changes its volume
  • enterfullscreen fires when the player enters fullscreen mode
  • exitfullscreen fires when the player enters exitfullscreen mode
  • fullscreenerror fires when an error has occurred while trying to enter or exit fullscreen
  • srcchanged fires when the player has finished changing its source media URL (using the setSrc method) - if an error occurs while changing source media the error event shall fire
  • destroycompleted fires when the player has finished destroying its instance (using the destroy method)
  • destroyerror fires when the player has not been able to properly dispose of its instance
  • startuptimeavailable fires when startup time analytics data is available
  • resize fires when player is resizing

HLS (MSE-based) specific events

  • hlsinstancecreated fires when the hls.js instance has been created
  • hlsmanifestloaded fires when the player has finished loading the main HLS manifest
  • hlsmanifestparsed fires when the player has finished parsing the main HLS manifest
  • hlslevelloaded fires when the player has finished loading a level
  • hlsfragmentloaded fires when the player has finished loading a fragment
  • hlsfragmentbeingplayedchanged fires when the fragment being rendered within the player changes
  • hlsabradaptationchange fires when the player changes bitrate (fires in auto mode only)
  • hlsid3tagparsingcompleted fires when parsing id3 metadata has completed. You can get id3 metadata with the getHlsId3TagSamples method. See our HLS ID3 metadata documentation page for more information.
  • hlsprogramdatetimeavailable data from the #EXT-X-PROGRAM-DATE-TIME tag has been updated and is available - use getHlsEpochProgramDateTime and getHlsRawProgramDateTime methods to access the program-date-time value
  • hlserror fires when an fatal error is encountered while streaming HLS content. The difference with the generic error event is that hlserror will send error details along the event. When a fatal error occurs both the hlserror and error fire. Example:
    rmpContainer.addEventListener('hlserror', function(event) {
      console.log('hlserror');
      console.log(event.detail);
      console.log(event.detail.type); 
    });
    event.detail is an Object with the following properties holding details about the error:
    • type - the error type (String)
    • details - further details about the error (String)
  • hlswarning fires when a warning is raised while streaming HLS content. Note that it is not uncommon for the player to fire a couple of hlswarning events during playback but that does not indicate that the player actually has an issue with playing the content. Serious issues are reported with the above hlserror event. Example:
    rmpContainer.addEventListener('hlswarning', function(event) {
      console.log('hlswarning');
      console.log(event.detail);
      console.log(event.detail.type); 
    });

The above events will not fire when native HLS is used by the player (e.g. on iOS & macOS Safari)

DASH specific events

  • dashinstancecreated fires when the Shaka player instance has been created
  • dashabradaptationchange fires when the player changes bitrate (fires in auto mode only)
  • dashtrackschanged fires when the list of tracks changes - for example, this will happen when changing periods or when track restrictions change

Player API getters

The following getters must be queried after the ready event has fired.

General player getters

getReady()
rmp.getReady();

This getter returns a Boolean indicating if the player is ready or not.

getPlayerVersion()
rmp.getPlayerVersion();

This getter returns a String representing the current player version (MAJOR.MINOR.PATCH as in Semantic Versioning). null is returned if version is not available.

getPaused()
rmp.getPaused();

This getter returns a Boolean representing the state of the media content either paused or playing. true means the content on stage is currently paused. null is returned in case the value is not available.

getCurrentTime()
rmp.getCurrentTime();

This getter returns a Number expressed in milliseconds representing the current playback position in the media content. -1 is returned in case the value is not available.

getDuration()
rmp.getDuration();

This getter returns a Number expressed in milliseconds representing the total duration of the media content. -1 is returned in case the value is not available. Note that on some mobile devices the duration may only be available after a successful play event.

getPlayerMode()
rmp.getPlayerMode();

This getter returns a String representing the mode in which the player is rendered: 'html5', 'flash' or 'nosupport'. null is returned in case the value is not available.

getStreamType()
rmp.getStreamType();

This getter returns a String representing the currently loaded streaming protocol: 'hls', 'dash', 'mp4', 'webm', 'm4a' or 'mp3'. null is returned in case the value is not available.

getBufferLength(type)
rmp.getBufferLength('ahead');
rmp.getBufferLength('behind');

This getter returns a Number expressed in milliseconds representing the current player buffer. It takes an input String parameter which must either be 'ahead' (this would return the buffer ahead value) or 'behind' (this would return the buffer behind value, also known as back-buffer). null is returned in case this value is not available. This works for HLS, DASH or progressive download.

getLoop()
rmp.getLoop();

This getter returns a Boolean stating if the player is in loop mode or not. true means the player automatically jumps back to start and continue playback when content completes. null is returned in case this value is not available.

getControls()
rmp.getControls();

This getter returns a Boolean stating if the player controls are currenlty shown or hidden. true means the player controls are visible. null is returned in case this value is not available.

getAdUI()
rmp.getAdUI();

This getter returns a Boolean stating if the player advertisement UI is currenlty shown or hidden. true means the advertisement UI is visible. null is returned in case this value is not available.

getWaitingUI()
rmp.getWaitingUI();

This getter returns a Boolean stating if the player is in waiting mode while displaying its waiting UI. true means the player is in waiting mode. null is returned in case this value is not available.

getFullscreen()
rmp.getFullscreen();

This getter returns a Boolean representing the current state of the player. true means the player is in fullscreen mode. null is returned in case this value is not available.

getVolume()
rmp.getVolume();

This getter returns a Number representing the current player volume (between 0 and 1). -1 is returned if this value is not available.

getMute()
rmp.getMute();

This getter returns a Boolean stating if the player is currently muted or not. true means player is muted. null is returned in case this value is not available.

getPlaybackRate()
rmp.getPlaybackRate();

This getter returns a Number representing the current playback rate. null is returned if this value is not available.

getContentTitle()
rmp.getContentTitle();

This getter returns a String representing the content title. null is returned if this value is not available.

getContentDescription()
rmp.getContentDescription();

This getter returns a String representing the content description. null is returned if this value is not available.

getPoster()
rmp.getPoster();

This getter returns a String representing the path or URL to the player poster frame. null is returned if this value is not available.

getSrc()
rmp.getSrc();

This getter returns a String representing the path or URL to the current player media source. null is returned if this value is not available.
An example of implementation of the src API can be viewed here.

getPlayerWidth()
rmp.getPlayerWidth();

This getter returns a Number representing the current width in pixels of the player. Returns -1 if not available.

getPlayerHeight()
rmp.getPlayerHeight();

This getter returns a Number representing the current height in pixels of the player. Returns -1 if not available.

getEnvironment()
rmp.getEnvironment();

This getter returns an Object representing the current environment (e.g. feature detection & type of device) in which Radiant Media Player is rendered. Example to detect a mobile device:

var env = rmp.getEnvironment();
var isMobile = env.isMobile;

This is an advanced getter which is mainly used by the player internally and provided as indication as you may see it in some of our code examples. Further documentation is not provided for this getter.
Getter added with version 4.0.2

getFramework()
rmp.getFramework();

This getter returns an Object representing the internal player framework. This framework is written with native JavaScript (e.g. it does not depend on a third party library like jQuery or Lodash). Example to add a class to an HTML element:

var rmpFW = rmp.getFramework();
rmpFW.addClass(element, 'custom-class');;

This is an advanced getter which is mainly used by the player internally and provided as indication as you may see it in some of our code examples. Further documentation is not provided for this getter.
Getter added with version 4.0.4

getBitrates()
rmp.getBitrates();

This getter returns an Array representing the available renditions for the current media source. This getter is only available for HLS (MSE) and DASH. null is returned if this value is not available. Each element of the returned Array is an Object. The width, height, bitrate properties of this object can be accessed to get the related values for each rendition.

getCurrentBitrateIndex()
rmp.getCurrentBitrateIndex();

This getter returns a Number representing the index of the currently playing rendition. This getter works for HLS (MSE) and DASH. null is returned if this value is not available. Index starts at 0 for the lower rendition. Use this in conjunction with the getBitrates getter to get data about the currently playing rendition for HLS and DASH.

getAbrAutoMode()
rmp.getAbrAutoMode();

This getter returns a Boolean stating if the player is in ABR auto mode (true) or not (false). null is returned if this information is not available. This getter works for all available streaming protocols.

getContentID()
rmp.getContentID();

This getter returns a String with the current contentID set for the player (or the content displayed). null is returned if this information is not available.

getLogo()
rmp.getLogo();

This getter returns an Object with the current player logo information. This Object holds two properties. The img property is a String representing the URL to the logo image. The loc property is a String representing the link to open when the logo is interacted with. null is returned if this logo information are not available. Example of returned value when available:

{
  img: 'url-logo-image',
  loc: 'link-to-open-when-logo-is-clicked'
}

Player API methods

The following methods must be called after the ready event has fired.

play()
rmp.play();

When invoked, this method will cause the player to start playback or resume it if it was paused.
On mobile devices this method must be called within a user interaction callback (click, touchstart ...) to start initial playback. Practically the user interaction registration should happen after the ready event has fired.

pause()
rmp.pause();

When invoked, this method will cause the player to pause playback.

stop()
rmp.stop();

When invoked, this method will cause the player to pause playback returning its playhead to 0 (for on-demand content) and show the current poster.
Note that if a linear ad is present on stage, this stop method will have no effect. You must first call the stopAds method, wait for the adalladscompleted event to fire and then call stop.

seekTo(ms)
rmp.seekTo(5000);

When invoked, this method will cause the player to seek to the value indicated as parameter. Parameter value is a Number expressed in milliseconds. Note that milliseconds accurate seeking is not guaranteed as it depends on the browser implementation of the HTML5 media currentTime property. Most of the time you can expect a 100 ms precision with modern browsers. This method will have no effect if an ad is playing on stage or with a live stream.

Example for starting the player at a specific timestamp:

<script src="https://cdn.radiantmediatechs.com/rmp/4.1.3/js/rmp.min.js"></script>
<div id="rmpPlayer"></div>
<script>
var bitrates = {
  hls: 'https://dqwp3xzzbfhtw.cloudfront.net/vod/smil:bbb.smil/playlist.m3u8',
};
var settings = {
  bitrates: bitrates,
  licenseKey: 'your-license-key',
  delayToFade: 3000,
  width: 640,
  height: 360,
  poster: 'https://www.radiantmediaplayer.com/images/poster-rmp-showcase.jpg',
};
var elementID = 'rmpPlayer';
var rmp = new RadiantMP(elementID);
// Our container to receive API events
var rmpContainer = document.getElementById(elementID);
// When the player reaches the playing event we order a seek
// Note that it is important to wait for the playing event 
// to properly seek into content that has not been started yet
var onPlayingSeekTo = function() {
  // Remove listener to clear the player
  rmpContainer.removeEventListener('playing', onPlayingSeekTo);
  rmp.seekTo(30000);
};
rmpContainer.addEventListener('playing', onPlayingSeekTo);
rmp.init(settings);
</script>
setVolume(volume)
rmp.setVolume(0.8);

When invoked, this method will change the volume level of the player audio track. Parameter value is a Number ranging from 0 to 1.
An example of implementation of the mute/volume API can be viewed here.

setMute(muted)
rmp.setMute(true);

When invoked, this method will cause the player to enter or exit mute mode based on the input parameter. Parameter should be a Boolean with true meaning the mute mode should be engaged and false the mute mode should be disengaged.
An example of implementation of the mute/volume API can be viewed here.

setLoop(loop)
rmp.setLoop(true);

When invoked, this method will change the player loop mode. Parameter value is a Boolean. When set to true it will enabled loop mode. When set to false it will disable it.

setLogo(logo)
rmp.setLogo({
  img: 'url-logo-image',
  loc: 'link-to-open-when-logo-is-clicked'
});

When invoked, this method will update the player logo information. Note that player must be initialised with the logo setting for this method to have affect. Parameter value is an Object holding two properties. The img property is a String representing the new URL to the logo image. The loc property is a String representing the new link to open when the logo is interacted with.

resize()
rmp.resize();

When invoked, this method will force the player to resize itself based on its new context dimension.

setPlayerSize(width, height)
rmp.setPlayerSize(960, 540);

When invoked, this method will dynamically resize the player to the provided width and height parameters. The player will call the API resize method automatically once the new width and height are set. The width and height parameters must be Number representing pixels.

setContentTitle(title)
rmp.setContentTitle('Hello RMP!');

When invoked, this method update the current content title. Input must be a String.

setContentDescription(description)
rmp.setContentTitle('This is a good day today.');

When invoked, this method update the current content description. Input must be a String.

showCaptions(lng)
rmp.showCaptions('en');

When invoked, this method will display closed captions for the queried language. The language parameter must be a 2 digit ISO 639-1 (two-letter) String. This is currently only supported for externally loaded WebVTT files (i.e. not for in-manifest HLS or DASH captions).

hideCaptions()
rmp.hideCaptions();

When invoked, this method will hide closed captions. This is currently only supported for externally loaded WebVTT files (i.e. not for in-manifest HLS or DASH captions).

setPoster(posterUrl)
rmp.setPoster('https://www.radiantmediaplayer.com/images/poster-rmp-showcase.jpg');

This methods takes a URL String parameter and updates the player with this new poster.

showPoster()
rmp.showPoster();

This methods causes the current player poster to be displayed on stage.

hidePoster()
rmp.hidePoster();

This methods causes the current player poster to be hidden from the stage.

setControls(controls)
rmp.setControls(false);

This method hides (input parameter set to false) or shows (input parameter set to true) the player controls (including modules, logo, ad UI ...). Input parameter must be a boolean.

setAdUI(adUI)
rmp.setAdUI(false);

This method hides (input parameter set to false) or shows (input parameter set to true) the advertisement UI - overriding the default player controls. Input parameter must be a boolean.

setWaitingUI(adUI)
rmp.setWaitingUI(true);

This method hides (input parameter set to false) or shows (input parameter set to true) the player waiting UI. Note that the player may internally still decides to hide or show the waiting UI. Input parameter must be a boolean.

setPlaybackRate(rate)
rmp.setPlaybackRate(2);

When invoked, this method will order the player to modify its playback rate to the Number set as input parameter. Decent values for playback rate ranges from 0.25 to 4 and can be increment by 0.1. Values outside this range are not supported as they can cause playback issues in some browsers.

setFullscreen(fs)
rmp.setFullscreen(true);

When invoked, this method will order the player to enter or exit fullscreen. Input parameter must be a Boolean If in fullscreen mode the player will exit fullscreen mode (input parameter is false). If in window mode the player will enter fullscreen mode (input parameter is true).

setBitrate(index)
rmp.setBitrate(0);

This method allows to set the current bitrate for the player based on an index value. Input parameter must be a Number. Index at 0 will cause the player to play the lowest bitrate available. This method has no effect when called when a linear ad is playing on stage or if input index is out of bound.
For HLS and DASH setting index to -1 will restore the player to its 'auto' ABR mode.
This method is available HLS, DASH and progressive download.
An example of implementation of the bitrate API can be viewed here.

setSrc(newSource)
rmp.setSrc('https://dqwp3xzzbfhtw.cloudfront.net/vod/smil:bbb-long.smil/playlist.m3u8');

This method updates the current player media source with the provided String input paramater. The player will clear its current buffer, load the new media source and updates its UI (including bitrate informations, audio-tracks and in-manifest text tracks) after the change has completed. When this happens the srcchanged event fires. This method works for HLS, DASH and progressive download.
An example of implementation of the src API can be viewed here.

destroy()
rmp.destroy();

This method destroys the current player instance, removing listeners and emptying player buffer. The player container is thus ready for removal from DOM when destroycompleted event fires.
An example of implementation of the destroy API can be viewed here.

isWebView()
rmp.isWebView();

This method returns a boolean stating if the player is currently used in an Android or iOS WebView or not.

isStandalone()
rmp.isStandalone();

This method returns a boolean stating if the player is currently used in an Android or iOS standalone web-application or not.


HLS (MSE) specific methods

getHlsId3TagSamples()
rmp.getHlsId3TagSamples();

This getter returns an Object representing the current ID3 timed metadata in an HLS stream. It is updated when the hlsid3tagparsingcompleted event fires. null is returned if this value is not available. See our HLS ID3 metadata documentation page for more information and a usage example.

getHlsManifestData()
rmp.getHlsManifestData();

This getter returns an Array representing the HLS manifest data. It can be queried when the hlsmanifestloaded event fires. null is returned if this value is not available. It holds information about each level found in the manifest. Each item of this Array is made of an Object with information about a specific level as follows:

{
  url: [ 'http://levelURL.com', 'http://levelURLfailover.com' ], level URL
  bitrate: 246440, level bitrate
  name: "240", level name
  codecs: "mp4a.40.5,avc1.42000d", used codecs
  width: 320, video width
  height: 136 video height
}
getHlsLevelData()
rmp.getHlsLevelData();

This getter returns an Object representing the currently loaded level. It can be queried when the hlslevelloaded event fires. null is returned if this value is not available. The returned Object is as follows:

{
  version: 3, HLS version
  type: 'VOD', playlist type
  startSN: 0, start sequence number
  endSN: 50, end sequence number
  totalduration: 510, level total duration
  targetduration: 10, level fragment target duration
  fragments: Array(51), array of fragments info
  live: false is this level a live playlist or not
}
getHlsFragmentData()
rmp.getHlsFragmentData();

This getter returns an Object representing the currently loaded fragment. It can be queried when the hlsfragmentloaded event fires. null is returned if this value is not available. The returned Object is as follows:

{
  duration: 10, fragment duration
  level: 3, level identifier
  sn: 35, fragment sequence number
  start: 30, fragment start offset
  url: 'http://fragURL.com' fragment URL
}
getHlsFragmentBeingPlayedData()
rmp.getHlsFragmentBeingPlayedData();

This getter returns an Object representing the fragment currently being rendered by the player. This is generally used in conjunction with the hlsfragmentbeingplayedchanged event. null is returned if this value is not available. The returned Object is of the same format as with the getHlsFragmentData method.

getHlsEpochProgramDateTime()
rmp.getHlsEpochProgramDateTime();

This getter returns a Number representing the #EXT-X-PROGRAM-DATE-TIME in universal (epoch) milliseconds time. It can be queried when the hlsprogramdatetimeavailable event fires. null is returned if this information is not available.

getHlsRawProgramDateTime()
rmp.getHlsRawProgramDateTime();

This getter returns a Date representing the #EXT-X-PROGRAM-DATE-TIME as a Date object. It can be queried when the hlsprogramdatetimeavailable event fires. null is returned if this information is not available.

hlsStartLoad()
rmp.hlsStartLoad();

This method allows to start/restart the playlist/fragment loading process. This method should only be queried after the hlsmanifestparsed event has fired.

hlsStopLoad()
rmp.hlsStopLoad();

This method allows to stop the playlist/fragment loading process. This can be useful to better manage the HLS loading mechanism and to save bandwidth when the loading of new fragments is not needed anymore. When the playlist/fragment loading process has been stopped it can be resumed with the hlsStartLoad method. When hlsStopLoad is requested be mindful to always call hlsStartLoad when the viewer requests playback again so as to resume the fragment loading process - otherwise the player may stop working as expected due to the lack of new fragments for rendering.


Accessing hls.js or Shaka Player instances

Some advanced use-cases may require access to the hls.js or Shaka Player instances that Radiant Media Player uses to respectively decode HLS & DASH streaming.

It is possible to access those instances as shown below. It is assumed here that the player instance is created as in the example at the top of this page through
var rmp = new RadiantMP(elementID);

  • When hlsinstancecreated player event fires the hls.js instance can be accessed as rmp.hlsJS. The hls.js instance corresponds to var hls = new Hls(config); as described here.
  • When dashinstancecreated player event fires Shaka Player instance can be accessed as rmp.shakaPlayer. The Shaka Player instance corresponds to var player = new shaka.Player(video); as described here.

API usage examples

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.