Documentation

Player API

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.

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

For our Video Advertisement 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/10.1.1/js/rmp.min.js"></script>
<!-- Player container element -->
<div id="rmp"></div>
<!-- Set up player configuration options -->
<script>

  // Your streaming source - in this example HLS
  const src = {
    hls: 'https://your-hls-url.m3u8'
  };
  // Your player settings
  const settings = {
    licenseKey: 'your-license-key',
    src,
    width: 640,
    height: 360,
    contentMetadata: {
      poster: [
        'https://your-poster-url.jpg'
      ]
    }
  };

  const elementID = 'rmp';
  const rmp = new RadiantMP(elementID);

  rmp.on('playing', () => {
    console.log('player has received playing event');
    // Set a custom quality
    rmp.quality = 0;
  });

  // Player initialisation
  async function initRmpPlayer() {
    try {
      await rmp.init(settings);  
      console.log('player ready');
      // Player is ready - we can start making API calls
      console.log(rmp.streamType);
    } catch (error) {
      console.error('Radiant Media Player failed to initialize', error);
    }
  }
  initRmpPlayer();

</script>

General player API events

Events are registered with the on method applied to the player instance rmp. They are unregistered with the off method. Example:

const rmp = new RadiantMP(elementID);
rmp.on('eventA', callbackA);
await rmp.init(settings);

You can register multiple events for the same callback, example:

const rmp = new RadiantMP(elementID);
rmp.on('eventA eventB eventC', callbackA);
await rmp.init(settings);

You can access the name of the event being fired:

function callbackA (event) {
  console.log(event.type); // name of the event being fired
}
const rmp = new RadiantMP(elementID);
rmp.on('eventA eventB eventC', callbackA);
await rmp.init(settings);

You can unregister an event with the off method:

const rmp = new RadiantMP(elementID);
rmp.off('eventA', callbackA);
await rmp.init(settings);

You can unregister multiple events for the same callback as well:

const rmp = new RadiantMP(elementID);
rmp.off('eventA eventB eventC', callbackA);
await rmp.init(settings);

You can also register an event where the callback is only executed once:

const rmp = new RadiantMP(elementID);
rmp.one('eventA', callbackA);
await rmp.init(settings);

As with the on method you can register multiple events for the same callback with the one method.

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

General player events

ready

Fires when the player is ready to receive calls from the API and is appended to DOM

play

Fires when a play request is made (either through a user interaction, an API call or autoplay)

playing

Fires when playback is ready to start after having been paused or delayed due to lack of media data. For buffer information use buffernotstalledanymore event instead.

pause

Fires when player has been paused

timeupdate

Fires when the current playback position changed as part of normal playback

ended

Fires when playback has stopped because the end of the media resource was reached

loadstart

Fires when player begins looking for media data, as part of the resource selection algorithm

loadedmetadata

Fires when player has just determined the duration and dimensions of the media resource and the text tracks are ready

durationchange

Fires when the media duration has just been updated

loadeddata

Fires when player can render the media data at the current playback position for the first time

progress

Fires when player is fetching media data

canplay

Fires when player can resume playback of the media data, but estimates that if playback were to be started now, the media resource could not be rendered at the current playback rate up to its end without having to stop for further buffering of content

canplaythrough

Fires when player estimates that if playback were to be started now, the media resource could be rendered at the current playback rate all the way to its end without having to stop for further buffering

waiting

Fires when playback has stopped because the next frame is not available, but the player expects that frame to become available in due course - for buffer information use bufferstalled event instead

seeking

Fires when the player starts seeking to a new position in the media

seeked

Fires when the player is finished seeking to a new position in the media

stopcompleted

Fires when stop API method has completed

loop

Fires when a loop event happens (on-demand video finishes and automatically restarts)

firstframe

Fires when first frame of content or pre-roll ad (whichever comes first) is shown in the player

htmlmediaelementappendedtodom

Fires when the HTML5 media element (video or audio tag) has been appended to DOM after init has been called on player. This event fires before ready event. The HTML5 media element can be accessed through the htmlMediaElement getter.

API getter|setter

Unless stated otherwise the following getters|setters must be queried after the ready API event has fired or when init method has resolved.

ready getter (Boolean)

const ready = rmp.ready;

The player is ready or not.

playerVersion getter (String)

const playerVersion = rmp.playerVersion;

The current player version (MAJOR.MINOR.PATCH as in Semantic Versioning). Example: '10.1.0'.

htmlMediaElement getter (HTMLMediaElement)

const htmlMediaElement = rmp.htmlMediaElement;

This getter returns a HTMLMediaElement, the HTML5 video (or audio) tag used by Radiant Media Player. This method can be queried when the htmlmediaelementappendedtodom event fires.

paused getter|setter (Boolean)

const paused = rmp.paused;
rmp.paused = true;

get|set the state of the player either paused or playing.
For paused getter: true means the content on stage is currently paused.

currentTime getter (Number)

const currentTime = rmp.currentTime;

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.

currentTimeBeforeSeek getter (Number)

const currentTimeBeforeSeek = rmp.currentTimeBeforeSeek;

This getter returns a Number expressed in milliseconds representing the current playback position in the media content before seeking. This method should be invoked when seeking event fires. -1 is returned in case the value is not available.

duration getter (Number)

const duration = rmp.duration;

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.

streamType getter (String)

const streamType = rmp.streamType;

This getter returns a String representing the currently loaded streaming protocol: 'hls', 'dash', 'mp4', 'webm', 'm4a', 'mp3', 'ogg', 'outstream', 'nosupport'.

loopConfiguration getter|setter (Boolean)

const loopConfiguration = rmp.loopConfiguration;
rmp.loopConfiguration = true;

get|set the player loop mode.

controls getter|setter (Boolean)

const controls = rmp.controls;
rmp.controls = false;

get|set the player controls are available or not.
For the controls getter: true means the player controls are available.

controlsVisible getter|setter (Boolean)

const controlsVisible = rmp.controlsVisible;
rmp.controlsVisible = false;

get|set the player controls are currently visible or hidden.
For the controlsVisible getter: true means the player controls are currently visible.

waitingUI getter|setter (Boolean)

const waitingUI = rmp.waitingUI;
rmp.waitingUI = true;

get|set player waiting mode.
For waitingUI getter: true means the player is in waiting mode.

contentMetadataConfiguration getter|setter (ContentMetadata)

const contentMetadata = rmp.contentMetadataConfiguration;
rmp.contentMetadataConfiguration = {
  title,
  description,
  poster
};

get|set ContentMetadata Object representing the current content metadata. See here for the contentMetadata setting. The contentMetadataConfiguration setter can be useful when using the setSrc API method, to update content metadata as source changes.

appNameConfiguration getter (String)

const appName = rmp.appNameConfiguration;

This getter returns a String with the current appName set for the player.

preloadConfiguration getter (String)

const preload = rmp.preloadConfiguration;

This getter returns a String representing the preload mode used for player start up.

bandwidthEstimate getter (Number)

const bandwidthEstimate = rmp.bandwidthEstimate;

This getter returns a Number representing the real-time available device bandwidth captured by the player in bps. -1 is returned if this information is not available.

ratio getter (Ratio)

const ratio = rmp.ratio;

This getter returns a Ratio Object representing the current player and media ratio. Example:

{ 
  player: 1.7777777778,
  media: 1.7777777778
}

Player API methods

Unless stated otherwise the following API methods must be queried when init method has resolved or after the ready API event has fired

All Promise-based API methods may reject to a WarningData Object - a corresponding 'warning' event will fire when a Promise rejects. The only Promise-based API methods that may reject to a fatal error (ErrorData Object) is the init method (in case player initialisation failed - see below)

init(settings) Promise.<|ErrorData>

With await in an async function

try {
  await rmp.init(settings);
} catch (error) {
  console.log(error.code);
  console.log(error.message);
  console.error('Radiant Media Player failed to initialize', error);
}

Or with then/catch

rmp.init(settings).then(() => {
  console.log('player successfully initialised');
}).catch(error => {
  console.log(error.code);
  console.log(error.message);
  console.error('Radiant Media Player failed to initialize', error);
});

Start player initialisation. Input must be a RadiantMediaPlayerSettings Object - check the complete list of player settings with default values. Returns a Promise that resolves if initialization was successful or rejects to an ErrorData Object. This method should not reject often, but when it happens it could be due to: invalid license key|cannot find container element (or PARENT)|no playback support. Note that this method rejects to an ErrorData Object and not a WarningData Object - this is the only API method in our player that can reject to an ErrorData Object. You could also need to monitor the error API event to intercept network or decoding errors. Example as follows:

rmp.on('error', () => {
  // get last error data 
  const error = rmp.errorData;
  console.log(error.code); // the error number
  console.log(error.message); // the error message
  console.log(error.event); // the native DOM error or library-specific event if available
});

getStreamMode() Promise.<string|WarningData>

rmp.getStreamMode().then(streamMode => {
  console.log(streamMode);
}).catch(warning => {
  console.warn(warning);
});
// or with await in an async function
try {
  const streamMode = await rmp.getStreamMode();
} catch (warning) {
  console.warn(warning);
}

Returns a Promise that resolves to the current player stream mode ('livedvr'|'voddvr'|'live'|'vod') or rejects to an WarningData Object. Can be queried before ready event.

play() Promise.<|WarningData>

rmp.play().then(() => {
  console.log('play was successful');
}).catch(warning => {
  // something went wrong and the play request was not successful
  console.warn(warning);
});

Returns a Promise that resolves if play request was successful or rejects to a WarningData Object.
On most devices, a play request must be initiated by a user interaction (touchend, click)
Do not use play method to force or emulate autoplay - instead use autoplay setting as described here.

pause()

rmp.pause();

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

stop() Promise.<|WarningData>

rmp.stop().then(() => {
  console.log('stop was successful');
}).catch(warning => {
  // something went wrong and the stop request was not successful
  console.warn(warning);
});

Returns a Promise that resolves if stop request was successful or rejects to a WarningData Object. If a video advertisement is on stage the player will first discard the advertisement and then reach the stop state. stopcompleted event will also fire when stop method has completed.

seekTo(ms) Promise.<|WarningData>

rmp.seekTo(5000).then(() => {
  console.log('seekTo was successful');
}).catch(warning => {
  // something went wrong and the seekTo request was not successful
  console.warn(warning);
});

Returns a Promise that resolves if seekTo request was successful or rejects to a WarningData Object. This method will cause the player to seek to the value indicated as input parameter. Input parameter 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. seeking event will fire when seekTo method starts and seeked event will fire when seekTo method ends. See dvrSeekTo API method for seeking in a DVR stream.

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.

fastForward()

rmp.fastForward();

Calling this method will set the player in fast-forward mode. Note that there are 3 fast-forward speeds. So calling fastForward() twice will cause the player to enter x2 fast-forward mode. Call play() to exit fast-forward mode. Also note that fastForward UI is only available with our TV player, but the fastForward API can be used with the general player as well.

fastRewind()

rmp.fastRewind();

Calling this method will set the player in fast-rewind mode. Note that there are 3 fast-rewind speeds. So calling fastRewind() twice will cause the player to enter x2 fast-rewind mode. Call play() to exit fast-rewind mode. Also note that fastRewind UI is only available with our TV player, but the fastRewind API can be used with the general player as well.

Environment detection API

environment getter (Environment)

const environment = rmp.environment;

This getter returns an Environment 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:

const environment = rmp.environment;
const isMobile = environment.isMobile;
const isAndroid = environment.isAndroid[0];
const isIos = environment.isIos[0];
const isMacosSafari = environment.isMacosSafari[0];

See a full example of output here. Note that this method can be used before calling init on player.

Volume API

Volume API events

volumechange

Fires when the player changes its volume

Volume API getter|setter

volume getter|setter (Number)

const volume = rmp.volume;
rmp.volume = 0.5;

get|set the current player volume (between 0 and 1).
For volume getter: -1 is returned if current player volume is not available.
An example of implementation of the mute/volume API can be viewed here.
Do not use the volume setter to set initial player volume when ready event fires - instead use initialVolume player setting.
On iOS, volume cannot be set|get through JavaScript (OS-level limitation). You can use mute getter|setter as an alternative.

mute getter|setter (Boolean)

const mute = rmp.mute;
rmp.mute = true;

get|set the current player muted state.
For mute getter: true means the player is currently muted.

Fullscreen API

Fullscreen API events

enterfullscreen

Fires when the player enters fullscreen mode

exitfullscreen

Fires when the player enters exitfullscreen mode

warning

with code 17000|17001 will fire when a fullscreen error is detected

Fullscreen API methods

getFullscreen()

rmp.getFullscreen();

This method returns a String representing the URI for the current player media source.

setFullscreen(fs) Promise.<|WarningData>

rmp.setFullscreen(true).then(() => {
  console.log('setFullscreen was successful');
}).catch(warning => {
  // something went wrong and the setFullscreen request was not successful
  console.warn(warning);
});

Returns a Promise that resolves if setFullscreen request was successful or rejects to a WarningData Object. This method will order the player to enter or exit fullscreen based on input parameter. Input parameter must be a Boolean. enterfullscreen, or exitfullscreen or warning API events will also fire when this method has completed.
The player may only enter fullscreen through the setFullscreen API method as a result of a direct user interaction. Modern browsers generally block entering full screen programmatically.

Sizing API

Sizing API event

resize

Fires when player is actually resizing

Sizing API methods

getPlayerSize() (PlayerSize)

const playerSize = rmp.getPlayerSize();

This method returns a PlayerSize Object with a width and a height property representing the current size of the player in pixels.

setPlayerSize({width, height})

rmp.setPlayerSize({width: 960, height: 540});

This method will dynamically resize the player to the input PlayerSize Object width and height properties. This method will have no effect with autoHeightMode and iframeMode settings or when player is in fullscreen.

resize()

rmp.resize();

This method will force the player to resize itself based on its new context dimension.

Buffer API

An example of implementation of the buffer API can be viewed here.

Buffer API events

bufferstalled

Fires when current buffer is empty - media playback is stopped until enough buffer has been downloaded to resume playback

buffernotstalledanymore

Fires when player has resumed playback after a bufferstalled event (e.g. it exits buffering state)

Buffer API method

bufferAhead|bufferBehind getters

const bufferAhead = rmp.bufferAhead;
const bufferBehind = rmp.bufferBehind;

These getters return a Number expressed in milliseconds representing the current player buffer (ahead or behind). -1 is returned in case this value is not available.

Quality API

An example of implementation of the quality API can be viewed here.

Quality API events

qualitychanging

Fires when the player is starting to change quality - works for HLS, MPEG-DASH and progressive download in manual or automatic ABR mode

qualitychanged

Fires when the player has changed quality - works for HLS, MPEG-DASH and progressive download in manual or automatic ABR mode

abrstatuschanged

Fires when the player changes from automatic quality selection to manual quality selection or the other way around - query abrAutoMode getter to know current status

Quality API methods

quality getter|setter (Number)

const quality = rmp.quality;
rmp.quality = 0;

get|set the current rendition for the player. Input parameter for setter must be a Number. For HLS and MPEG-DASH streaming, index at 0 will cause the player to play the lowest quality rendition. This method has no effect if called when a linear ad is playing or if input index is out of bound. See qualities getter to read information about available renditions and to determine which rendition is currently active. For HLS and MPEG-DASH streaming, rmp.quality = -1; will restore the player to its automatic ABR mode.

qualities getter (Array.<Quality>)

rmp.qualities;

This getter returns an Array.<Quality> representing the available renditions for the current streaming source. Each Quality item has the following properties:

{
  active: true, // Boolean: if the current audio track active or not
  audioCodec: "mp4a.40.2", // String: the audio codec name when available
  bitrate: 727221, // Number: the bandwidth in bps required to the play the current rendition
  height: 360, // Number: the height in px of the rendition (not available for audio-only feed)
  id: 0, // Number: the bitrate id
  videoCodec: "avc1.4d401e", // String: the video codec name when available (not available for audio-only feed)
  width: 640 // Number: the width in px of the rendition (not available for audio-only feed)
}

The active property of each rendition can be queried in order to know which rendition is currently played in the player.

For progressive download only the active and id properties of a rendition object will be available.

For native HLS (default on iOS and macOS Safari) this method will return

[{
  active: false,
  audioCodec: '',
  bitrate: -1,
  height: -1,
  id: -1,
  videoCodec: '',
  width: -1
}]

abrAutoMode getter (Boolean)

rmp.abrAutoMode;

This getter returns a Boolean stating if the player is in ABR auto mode (true) or not (false).

Audio tracks API

An example of Audio tracks API implementation can be viewed here.

Audio tracks API events

audiotrackchanging

Fires when an audio track switch is requested

audiotrackchanged

Fires when an audio track switch completes

Audio tracks API methods

audioTracks getter (Array.<AudioTrack>)

const audioTracks = rmp.audioTracks;

This getter returns an Array.<AudioTrack> representing the loaded audio tracks for the current HLS or MPEG-DASH stream. Each AudioTrack item has the following properties:

{
  active: true, // Boolean: if the current audio track active or not
  id: 0, // Number: the audio track id
  language: "en" // String: language code for the audio track
}

The id property from the AudioTrack item can be used with the audioTrack setter to select a specific audio track.

audioTrack getter|setter (Number)

const audioTrack = rmp.audioTrack;
rmp.audioTrack = 1;

get|set the current HLS or MPEG-DASH audio track being read by the player.
For audioTrack getter: returns Number, the id of the active audio track.
For audioTrack setter: Number input represents the id of the audio track within the available audio tracks (see audioTracks getter).

Analytics API

Analytics data can be delivered by the player with JavaScript. We provide the following analytics-oriented API methods:

Analytics API getters

timeViewed getter

rmp.timeViewed

This getter returns a Number expressed in milliseconds that represents the cumulative time viewed for the current player instance. Returns 0 if not available. This number can exceed content duration if the same part of content is viewed multiple times for a given player session.

percentViewed getter

rmp.percentViewed

This methods returns a Number expressed in % that represents the cumulative percent viewed for the current player instance (example: 20 for 20%). This is calculated against content duration. It will only return valid values for on-demand content as for live/DVR content the duration is unknown. Returns 0 if not available. This number CAN exceed 100 if the same part of content is viewed multiple times for a given player session.

currentTimeInPercent getter

rmp.currentTimeInPercent

This getter returns a Number expressed in % that represents the current percent viewed for the current player instance (example: 20 for 20%). This is calculated against content duration. It will only return valid values for on-demand content as for live/DVR content the duration is unknown. Returns -1 if not available. This number CANNOT exceed 100.

timeReady getter

rmp.timeReady

This getter returns a Number expressed in milliseconds that represents the time for the player to be ready, i.e. fully appended to DOM, ready to receive user interaction (or autoplay if required) and API calls. It is computed from the moment init player method is called on player. Returns -1 if not available.

startUpTime getter

rmp.startUpTime

This getter returns a Number expressed in milliseconds that represents the time needed for the player to display the first frame of content (or pre-roll ad when available) after the viewer has requested playback through an initial user interaction (or when autoplay is successful). Returns -1 if not available. This method should be queried when the firstframe player event fires.

Analytics API usage example: computing time to load player library

<!-- Here we start our timer to compute time to load rmp.min.js -->
<script>
  let timeAfterLoad;
  const timeBeforeLoad = Date.now();
</script>
<script src="https://cdn.radiantmediatechs.com/rmp/10.1.1/js/rmp.min.js"></script>
<div id="rmp"></div>
<script>
  const src = {
    hls: 'https://your-hls-url.m3u8'
  };
  const settings = {
    licenseKey: 'your-license-key',
    src,
    width: 640,
    height: 360,
    contentMetadata: {
      poster: [
        'https://your-poster-url.jpg'
      ]
    }
  };  
  const elementID = 'rmp';
  const rmp = new RadiantMP(elementID);
  // We wire our events before calling init
  rmp.on('ready', () => {
    // ready event fires this is when the timer for timeReady getter stops
    const timeToLoad = timeAfterLoad - timeBeforeLoad;
    const timeToReady = rmp.timeReady;
    const totalReadyTime = timeToLoad + timeToReady;
    // print our data to console
    console.log('timeToLoad is ' + timeToLoad + ' ms');
    console.log('timeToReady is ' + timeToReady + ' ms');
    console.log('totalReadyTime is ' + totalReadyTime + ' ms');
  });
  // Here we also print the player start-up time
  rmp.on('firstframe', () => {
    const startupTime = rmp.startUpTime;
    console.log('startupTime is ' + startupTime + ' ms');
  });
  // Here we stop our timer to compute time to load rmp.min.js
  // In this case we also add the time it took to create Radiant Media Player instance and to wire our app logic
  timeAfterLoad =  Date.now();
  // init is called this is when the timer for timeReady getter starts
  // Initialization ... and done!
  async function initRmpPlayer() {
    try {
      await rmp.init(settings);
    } catch(error) {
      console.error('Radiant Media Player failed to initialize', error);
    }
  }
  initRmpPlayer();
</script>

3rd-party analytics service integration

By default, Radiant Media Player integrates with Google Analytics, Mux Data, MediaMelon, Bitmovin Analytics and Matomo Analytics. For MediaMelon integration please contact MediaMelon directly as this integration is not public. With that being said, you could also want to build your own custom analytics solution or support other analytics services that we currently do not support. Assuming your analytics service can send and receive information through JavaScript, all player API events and methods can be tracked. In the example below we show how to retrieve commonly needed analytics information through the player API.

<script src="https://cdn.radiantmediatechs.com/rmp/10.1.1/js/rmp.min.js"></script>
<div id="rmp"></div>
<script>
  const src = {
    hls: 'https://your-hls-url.m3u8'
  };
  const settings = {
    licenseKey: 'your-license-key',
    src,
    width: 640,
    height: 360,
    ads: true,
    adTagUrl: 'https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml', 
    contentMetadata: {
      poster: [
        'https://your-poster-url.jpg'
      ]
    }
  };
  const elementID = 'rmp';
  const rmp = new RadiantMP(elementID);

  // We attached our listeners to be notified of player events
  rmp.on('ready', () => {
    // player is ready
    // TODO: send data to your custom analytics service
  }); 

  rmp.on('error', () => {
    // player has encountered a fatal error preventing playback
    // TODO: send data to your custom analytics service
  });

  rmp.on('bufferstalled', () => {
    // current buffer is empty - media playback is stopped until enough buffer has been downloaded to resume playback
    // TODO: send data to your custom analytics service
  });

  rmp.on('buffernotstalledanymore', () => {
    // player has resumed playback after a bufferstalled event (e.g. it exits buffering state)
    // TODO: send data to your custom analytics service
  });

  rmp.on('ended', () => {
    // player has ended content
    // TODO: send data to your custom analytics service
  });

  rmp.on('timeupdate', () => {
    // player has moved its playhead
    const currentTime = rmp.currentTime; // current playback position in milliseconds
    if (currentTime > XX) {
      const fullscreen = rmp.getFullscreen(); // current fullscreen state of the player
      const volume = rmp.volume; // current player volume 
      // TODO: send data to your custom analytics service
    }
  });

  rmp.on('adimpression', () => {
    // player has pinged the VAST impression URL
    // TODO: send data to your custom analytics service
  });

  // Initialization ... and done!
  async function initRmpPlayer() {
    try {
      await rmp.init(settings);
    } catch(error) {
      console.error('Radiant Media Player failed to initialize', error);
    }
  }
  initRmpPlayer();
</script>

Changing source API

An example of implementation of the src API can be viewed here.

src API events

srcchanging

Fires when the player starts changing its source media URI

srcchanged

Fires when the player has finished changing its source media URI

error

Fires when the player was not able to change source due to a fatal error when trying to load the new source - see error management page to get details about the error - upon an error event, the setSrc method can still be invoked with a new source to attempt recovery from the error

src API methods

getSrc()

const currentSource = rmp.getSrc();

This method returns a String representing the URI for the current player media source.

setSrc(newSourceObject) Promise.<|WarningOrErrorData>

const newSourceObject = {
  hls: 'https://your-hls-url.m3u8',
  dash: 'https://your-dash-url.mpd',
  mp4: [
    'https://your-mp4-sd-url.mp4',
    'https://your-mp4-hd-url.mp4'
  ]
};
async function initSrcChange() {
  try {
    await rmp.setSrc(newSourceObject);
  } catch (warningOrError) {
    // something went wrong with setSrc - it could be fatal error or warning
    if (warningOrError.code < 1000) {
      // this is a fatal error
      console.error(warningOrError);
    } else {
      // this is just a warning
      console.warn(warningOrError);
    }
  }
}
initSrcChange();

Returns a Promise that resolves if setSrc request was successful or rejects to a WarningOrErrorData Object. This method updates the current player media source with the provided SourceData Object input parameter. The player will clear its current buffer, load the new media source and updates its UI (including video, audio, text tracks). When source change starts the srcchanging API event fires. When source change completes the srcchanged event fires and setSrc resolves. This Promise may reject to a warning or an error. For early rejection a warning will fire (previous content will remain available in player), for late rejection an error will fire (previous content has already been discarded and new content is failing to load/play -> error message will be displayed in player UI).

Also see the srcChangeAutoplay player setting.

If you have advertisement enabled the player will reload ads each time setSrc is successful. If you do not want advertisement to be reloaded when calling setSrc, set adTagReloadOnEnded setting to false (you can also use loadAds API method to load a new set of advertisement when srcchanged API event fires).

The setSrc method can also be used for DRM use-case, see here for additional details

isChangingSrc()

rmp.isChangingSrc();

Since setSrc runs asynchronously you may want to check if it is running before usage. This method returns a Boolean stating if setSrc is currently running or not.

Destroy API

An example of implementation of the destroy API can be viewed here.

When you are done using the player on your page and want to release memory/CPU resources you can call the destroy API method.

While it is possible to use destroy to update an existing player instance with a new one, we generally recommend using setSrc or other API methods described in our documentation to update your player instance as it could be more efficient.

destroy API events

destroycompleted

Fires when the player has finished destroying its instance (using the destroy method)

destroy API methods

destroy() Promise.<|WarningData>

rmp.destroy().then(() => {
  console.log('destroy has completed');
}).catch(warning => {
  // something went wrong and the destroy request was not successful
  console.warn(warning);
});

Returns a Promise that resolves if destroy request was successful or rejects to an WarningData Object. 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 or when destroy resolves.

HLS API with hls.js (default)

The following HLS API events and methods are only available when streaming HLS content when the hlsEngine setting is set to 'hlsjs' (default). They do not apply to MPEG-DASH content or HLS content when the hlsEngine setting is set to 'shakaplayer' or when HLS content is displayed with native rendering (Apple or legacy devices).

Player API events

hlsjsinstancecreated

Fires when the hls.js instance has been created

manifestloaded

Fires when the player has finished loading the main HLS manifest

manifestparsed

Fires when player has finished parsing the main HLS manifest

levelloaded

Fires when the player has finished loading a level

fragmentloaded

Fires when the player has finished loading a fragment

fragmentbeingplayedchanged

Fires when the fragment being rendered within the player changes

The above events will not fire when native HLS is used by the player (e.g. on Apple Safari) - set forceMseHlsOnAppleDevices to true for support on Apple devices

API methods

hlsJSInstance getter (HLSJSInstance)

const hlsJSInstance = rmp.hlsJSInstance;

This getter returns HLSJSInstance representing the hls.js instance created by the player. This instance is available when the hlsjsinstancecreated event fires.

hlsManifestData getter (HLSManifestData)

const hlsManifestData = rmp.hlsManifestData;

This getter returns HLSManifestData representing the HLS manifest data. It can be queried when manifestloaded event fires. Example:

{
  levels: [ LevelObject ], // Array of levels/rendition data
  audioTracks: [ Object ], // Array of audio tracks data
  subtitles: [ Object ], // Array of subtitles data
  captions: [ Object ] // Array of captions data
}

A LevelObject should look like:

{
  url: 'http://levelURL.com', // level URL
  bitrate: 246440, // level bitrate in bps
  name: "240p", // level name
  codecs: "mp4a.40.5,avc1.42000d", // level codecs (video,audio)
  width: 320, // level width
  height: 180, // level height
}

hlsLevelData getter (HLSLevelData)

const hlsLevelData = rmp.hlsLevelData;

This getter returns HLSLevelData representing the currently loaded level. It can be queried when the levelloaded event fires. HLSLevelData 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
}

hlsFragmentData getter (HLSFragmentData)

const hlsFragmentData = rmp.hlsFragmentData;

This getter returns an HLSFragmentData representing the currently loaded fragment. It can be queried when the fragmentloaded event fires. HLSFragmentData 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
}

hlsFragmentBeingPlayedData getter (HLSFragmentData)

const hlsFragmentBeingPlayedData = rmp.hlsFragmentBeingPlayedData;

This getter returns an HLSFragmentData (see above) representing the fragment currently being rendered by the player. This is generally used in conjunction with the fragmentbeingplayedchanged event.

hlsSessionData getter (HLSSessionData)

const hlsSessionData = rmp.hlsSessionData;

This getter returns HLSSessionData representing the #EXT-X-SESSION-DATA read by the player in the HLS manifest. This is avilable with the manifestloaded event. Example:

{ 
  com.apple.hls.chapters: { 
    DATA-ID: "com.apple.hls.chapters", 
    URI: "https://www.rmp-streaming.com/media/hls/EXT-X-SESSION-DATA/chapters.json"
  },
  com.apple.hls.director: { 
    DATA-ID: "com.apple.hls.director", 
    VALUE: "Martin Director"
  }
}

hlsStartLoad()

rmp.hlsStartLoad();

This method allows to start/restart the playlist/fragment loading process. This method should only be queried after the manifestparsed 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.

MPEG-DASH API

The following API events and methods are only available when streaming MPEG-DASH content or HLS content when the hlsEngine setting is set to 'shakaplayer'. They do not apply to HLS content when the hlsEngine setting is set to 'hlsjs' (default) or when HLS content is displayed with native rendering (Apple and legacy devices).

Player API events

shakainstancecreated

Fires when the Shaka player instance has been created

manifestparsed

Fires when player has finished parsing the MPEG-DASH manifest

Player API methods

shakaPlayerInstance getter (ShakaPlayerInstance)

const shakaPlayerInstance = rmp.shakaPlayerInstance;

This getter returns an ShakaPlayerInstance representing the Shaka player instance created by the player. This instance is available when the shakainstancecreated event fires.

Accessing the HTMLMediaElement, hls.js or Shaka Player instances

Some advanced use-cases may require access to the HTMLMediaElement, hls.js or Shaka Player instances that Radiant Media Player dynamically creates when needed. The example below show how this can be achieved through our player API:

const elementID = 'rmp';
const rmp = new RadiantMP(elementID);
// We wire our events before calling init
rmp.one('hlsjsinstancecreated', () => {
  const hlsJSInstance = rmp.hlsJSInstance;
  console.log(hlsJSInstance);
});
rmp.one('shakainstancecreated', () => {
  const shakaPlayerInstance = rmp.shakaPlayerInstance;
  console.log(shakaPlayerInstance);
});
rmp.one('htmlmediaelementappendedtodom', () => {
  const videoTag = rmp.htmlMediaElement;
  console.log(videoTag);
});

async function initRmpPlayer() {
  try {
    await rmp.init(settings);
  } catch(error) {
    console.error('Radiant Media Player failed to initialize', error);
  }
}
initRmpPlayer();
  • hlsJSInstance corresponds to const hls = new Hls(config); as described here.
  • shakaPlayerInstance corresponds to const 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.

©2015-2025 Radiant Media Player. All Rights Reserved.