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.
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>
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.
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.
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 }
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
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.
volumechange
Fires when the player changes its volume
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.
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
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.
resize
Fires when player is actually resizing
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.
An example of implementation of the buffer API can be viewed here.
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)
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.
An example of implementation of the quality API can be viewed here.
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
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).
An example of Audio tracks API implementation can be viewed here.
audiotrackchanging
Fires when an audio track switch is requested
audiotrackchanged
Fires when an audio track switch completes
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 data can be delivered by the player with JavaScript. We provide the following analytics-oriented API methods:
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.
<!-- 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>
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>
An example of implementation of the src API can be viewed here.
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
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.
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.
destroycompleted
Fires when the player has finished destroying its
instance (using the destroy
method)
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.
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).
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
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.
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).
shakainstancecreated
Fires when the Shaka player instance has been created
manifestparsed
Fires when player has finished parsing the MPEG-DASH manifest
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.
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.
©2015-2025 Radiant Media Player. All Rights Reserved.