The InterludePlayer class is the core interface for Eko‘s interactive video experiences. InterludePlayer provides the basic functionality you’d expect from any video player (play, pause, volume, etc.) as well as unique features that work out of the box, such as dynamic video stream generation, real-time stream switching, and adaptive streaming.
The basic idea behind interactive video is creating a continuous video stream out of smaller chunks of video known as nodes.
InterludePlayer allows playing back nodes in sequence via the playlist array. The playlist array allows you to dynamically push nodes for playback during playback, essentially creating a video stream on the fly. Nodes must be registered with the repository before you can push them into the playlist.
Adaptive bitrate and cross platform support come standard with InterludePlayer.
Our encoding process creates multiple representations for each source video enabling it to be played across different platforms, devices and network conditions. Each video node is represented by an IVD (Interlude Video Descriptor) file, which is a JSON-based format that describes all the different representations.
InterludePlayer offers a simple but comprehensive plugin system, allowing you to extend the player’s functionality with reusable code.
You can use pre-existing plugins or write your own using the InterludePlayer.registerPlugin() and player.initPlugin() methods. The plugin system also supports interdependencies between plugins.
- Table of Contents
- Constructor
- Properties
- versionspro
- ivdVersionspro
- environmentspro
- registeredPluginsspro
- versionpro
- optionspro
- volumep
- mutedp
- isAudioLockedpro
- videoWidthpro
- videoHeightpro
- isAutoplayExpectedpro
- containerWidthpro
- containerHeightpro
- containerpro
- pausedpro
- durationpro
- currentTimep
- bufferedpro
- currentNodepro
- currentNodeIdp
- currentNodeIndexp
- currentNodeTimeOffsetpro
- currentNodeDurationpro
- currentNodeTimepro
- currentNodeRemainingTimepro
- enginepro
- isFullscreenpro
- initedPluginspro
currentChannelprodep- reduxStorepro
- Methods
- Events
- timeupdatee
- durationchangee
- volumechangee
- audiolockedchangee
- loadeddatae
- playinge
- waitinge
- canplaye
- requiresuseractione
- playe
- pausee
- endede
- fullscreenchangee
- switchede
- switchinge
- seekinge
- seekede
- nodestarte
- nodeende
- playlistcriticale
- errore
- warninge
- playlistresete
- playlistpushe
- plugininite
- containerresizee
- resizee
- qoescoree
- qoestatuse
new InterludePlayer(el, [options])
Constructs an InterludePlayer instance.
Returns: InterludePlayer
- A player instance.
Param | Type | Description |
---|---|---|
el | Element | string |
The container element to be used by player, or a DOM selector string for the container element. |
[options] | object |
Optional configuration object for player initialization. See options. |
Example
const player = new InterludePlayer('#playerContainer', {
autoplay: true,
scaling: 'boxing',
plugins: {
audio: {
// ...
}
}
});
// ...
player.play();
Constructor Options
options : object
The second argument of the InterludePlayer constructor.
- options :
object
- .engines :
Array.<string>
- .autoplay :
boolean
- .muted :
boolean
- .mutedAutoplayEnabled :
boolean
- .forceAudioLocked :
boolean
- .minCanplayBuffer :
number
- .initialBitrate :
number
- .ivdMediaBaseUrl :
object
|string
- .scaling :
string
- .panAndScanMinVisibleWidth :
number
- .panAndScanMinVisibleHeight :
number
- .fullscreenOrientation :
string
- .fullscreenOptions :
object
- .containerStyle :
object
- .plugins :
object
- .envOptions :
object
- .env :
string
- .engines :
options.engines : Array.<string>
Array of strings, engines to choose from, sorted by descending priority.
Currently available engines:
msevid
jabba
rancor
Default: ['msevid', 'jabba', 'rancor']
See: supportedEngines, engine
options.autoplay : boolean
If true, will attempt to automatically begin playback as soon as video content is ready.
Note that not all platforms/browsers/devices support autoplay.
Default: false
See: mutedAutoplayEnabled
Example
// playerOptions.json
{
"autoplay": true
}
options.muted : boolean
If true, playback will begin muted.
Default: false
Example
// playerOptions.json
{
"muted": true
}
options.mutedAutoplayEnabled : boolean
On some devices/browsers, autoplay is not supported unless audio is muted.
Setting this to true (default), enables the muted autoplay feature (will autoplay without audio until audio playback is unlocked by user gesture).
A false setting would mean that we would only autoplay if current environment supports autoplaying with unmuted audio.
Note that when autoplay is set to false, this setting would still apply - calling play without user gesture will start muted playback if audio is locked.
Default: true
See: autoplay, isAudioLocked, forceAudioLocked
Example
// playerOptions.json
{
"autoplay": true,
"mutedAutoplayEnabled": false
}
options.forceAudioLocked : boolean
If true, player would force the audio locked experience (i.e. require user interaction prior to audio playback), even if the current environment would allow us to start audio playback without a user interaction.
Setting this to true
would cause isAudioLocked to initially return true on all platforms/environments, until a user interaction is detected on the page.
Default: false
See: mutedAutoplayEnabled, isAudioLocked
Example
// playerOptions.json
{
"forceAudioLocked": true
}
options.minCanplayBuffer : number
Minimum media buffered (in seconds) afterwhich player will trigger the canplay event.
If autoplay was set to true, playback will only begin once minCanplayBuffer
seconds were buffered.
In the event that playlist does not contain minCanplayBuffer
seconds, the canplay event will be triggered once the entire playlist is fully buffered.
Default: 3
See: canplay, buffered
Example
// playerOptions.json
{
"minCanplayBuffer": 15
}
options.initialBitrate : number
The initial bitrate value (prior to first actual measurement of network bandwidth) in bits-per-second.
This will affect the chosen reprensentation for the first node in the playlist.
The default value is dynamic - it’s a best guess derived from the available APIs on current environment.
Example
// playerOptions.json
{
"initialBitrate": 3500000 // 3.5 Mbps
}
options.ivdMediaBaseUrl : object
| string
Base url (protocol + host) to be forced for all IVD media files.
If a string is given, that value is set for all media URLs.
Also supports map objects of the form {cdnName1: baseUrl1, cdnName2: baseUrl2}
.
When a map object is given, the player will choose the fastest CDN and its base url will be set for all subsequent videos.
Default: null
Example
// playerOptions.json
{
"ivdMediaBaseUrl": {
"cf": "//d1w2zhnqcy4l8f.cloudfront.net",
"fastly": "https://storageinterludefm.global.ssl.fastly.net"
}
}
options.scaling : string
The video scaling method used to scale the video within its container. Supported values are:
panAndScan
- Default. Will zoom and crop video to fill dimensions while maintaining aspect ratio.
If too much of the frame would be cropped, will fallback toboxing
(configurable, see panAndScanMinVisibleWidth and panAndScanMinVisibleHeight).boxing
- Fits within dimensions while maintaining aspect ratio (letterboxing / pillarboxing).
Default: "panAndScan"
Example
// playerOptions.json
{
"scaling": "boxing"
}
options.panAndScanMinVisibleWidth : number
The minimum visible percentage of video width (number in the range [0, 1]).
When scaling is set to panAndScan
, this value controls at which point the fallback to boxing
occurs.
For example, with default value 0.7
(70%), player will fallback to boxing
if more than 30% of the video frame width would be cropped by panAndScan
.
Default: 0.7
options.panAndScanMinVisibleHeight : number
The minimum visible percentage of video height (number in the range [0, 1]).
When scaling is set to panAndScan
, this value controls at which point the fallback to boxing
occurs.
For example, with default value 0.7
(70%), player will fallback to boxing
if more than 30% of the video frame height would be cropped by panAndScan
.
Default: 0.7
options.fullscreenOrientation : string
Will lock orientation when entering fullscreen via player.requestFullscreen.
See Screen Orientation API spec for supported values: https://www.w3.org/TR/screen-orientation/#orientationlocktype-enum.
To disable orientation locking, set to a falsey value.
Note: only applies to devices/browsers that support the Fullscreen API and the Screen Orientation API.
Default: "landscape"
Example
// playerOptions.json
{
"fullscreenOrientation": "portrait"
}
options.fullscreenOptions : object
A default FullscreenOptions object which will be passed on to the Element.requestFullscreen() call when invoking player.requestFullscreen().
Default: { navigationUI: "hide" }
Example
// playerOptions.json
{
"fullscreenOptions": {
"navigationUI": "show"
}
}
options.containerStyle : object
A map of CSS style attributes to be applied to the player container DOM element.
The player container element is the DOM element provided as the first argument to the InterludePlayer constructor.
Default: {'background-color': 'black', 'background-repeat': 'no-repeat', 'background-position': 'center', 'background-image': 'none'}
options.plugins : object
A map of plugins to initialize.
Keys are plugin names, values are options objects to pass to the plugin.
This object is the same as you would use for the initPlugin method (using the map object variant).
Default: null
Example
// playerOptions.json
{
"plugins": {
"subtitles": {},
"audio": {
"sounds": [{
"id": "soundtrack",
"src": [
"http://mydomain.com/song.ogg",
"http://mydomain.com/song.mp3"
],
"volume": 1.0,
"loop": true,
"fadeInDuration": 3
}]
}
}
}
options.envOptions : object
The envOptions
object contains environment-specific overrides for player options.
At runtime, the player looks for an envOptions
object whose key is InterludePlayer.environment.name‘s value.
You can also force the environment using the top-level env option.
Default: null
See: env, InterludePlayer.environment.name
Example
// playerOptions.json
{
// Common options for all environments
///////////////////////////////////////
"minCanplayBuffer": 10,
"initialBitrate": 3500000,
// Env specific overrides
///////////////////////////
"envOptions": {
"ios": {
"initialBitrate": 1000000
},
"android": {
"initialBitrate": 2000000
},
"myCustomEnv": {
"initialBitrate": 4500000
}
}
}
options.env : string
Force a specific envOptions to be used.
If no value given, the value of InterludePlayer.environment.name will be used.
See: envOptions
Example
// playerOptions.json
{
// Common options for all environments
///////////////////////////////////////
"minCanplayBuffer": 10,
"initialBitrate": 3500000,
// Env specific overrides
///////////////////////////
"env": "myCustomEnv",
"envOptions": {
"ios": {
"initialBitrate": 1000000
},
"android": {
"initialBitrate": 2000000
},
// This object will be used, since "env" value was given
"myCustomEnv": {
"initialBitrate": 4500000
}
}
}
Properties
InterludePlayer.version : string
The InterludePlayer’s version string.
Example
console.log(`The player version is ${InterludePlayer.version}`);
InterludePlayer.ivdVersion : object
The minimum and the latest IVD version that InterludePlayer supports. Returns an object that includes minimum
and latest
properties, their value is a string.
Example
console.log(`The minimum supported IVD version is ${InterludePlayer.ivdVersion.minimum}`);
console.log(`The latest supported IVD version is ${InterludePlayer.ivdVersion.latest}`);
InterludePlayer.environment : object
An object which contains information about the current environment, such as browser, os and more.
Param | Type | Description |
---|---|---|
name | string |
The environment name. Current values are “desktop”, “ios”, “android” or “windows” (for non-desktop Windows devices). |
queryParams | object |
An object that contains all the query string params parsed from the page’s URL. Note that the values are also parsed so they can have different types (e.g. string, array, boolean, number). |
isTouchEnabled | boolean |
True if touch events are supported on current environment, false otherwise. |
browser | object |
An object containing information about the current browser. |
browser.name | string |
Browser name. |
browser.version | string |
Browser full version string. |
browser.major | string |
Browser major version string. |
os | object |
An object containing information about the current operating system. |
os.name | string |
Operating system’s name. |
os.version | string |
Operating system’s full version string. |
Example
const env = InterludePlayer.environment;
console.log(`You are using ${env.browser.name} on ${env.os.name}`);
InterludePlayer.registeredPlugins : object
Returns all the plugins that were registered, names and versions.
This is a superset of initedPlugins.
See: registerPlugin, initedPlugins
Example
console.log(InterludePlayer.registeredPlugins); // {audio: '0.0.6', canvas: '0.0.4', ...}
player.version : string
The player’s version.
Example
console.log(`The player version is ${player.version}`);
player.options : object
An object containing read-only properties of the options used to initiate the player instance.
The values are either the defaults defined by options, or values overridden by the 2nd constructor argument.
For a list of available properties, see options.
See: options
Example
console.log(`The player instance is using "${player.options.scaling}" scaling.`);
player.volume : number
The audio volume, from 0.0 (silent) to 1.0 (loudest).
Setting this value will change the volume and cause a volumechange event to be triggered.
See: volumechange
Example
player.volume = 0.5;
console.log(player.volume); // 0.5
player.muted : boolean
True if the audio is muted, and false otherwise.
See: volumechange
Example
player.muted = true; // Will mute the audio
player.muted = false; // Will unmute the audio
if (!player.muted && player.volume > 0) {
// Do something
}
player.isAudioLocked : boolean
On some devices/browsers, user gesture is required in order to unlock audio playback.
This property would be true if audio playback is currently locked and requires a user gesture.
See: audiolockedchange, mutedAutoplayEnabled
Example
player.once('playing', function() {
if (player.isAudioLocked) {
// Show muted overlay button
}
player.once('audiolockedchange', function() {
if (!player.isAudioLocked) {
// Hide muted overlay button
}
});
});
player.videoWidth : number
The intrinsic width of the video in pixels. Returns 0 if this data is not yet available.
See: resize
Example
console.log(`Video dimensions: ${player.videoWidth}x${player.videoHeight}`);
player.videoHeight : number
The intrinsic height of the video in pixels. Returns 0 if this data is not yet available.
See: resize
Example
console.log(`Video dimensions: ${player.videoWidth}x${player.videoHeight}`);
player.isAutoplayExpected : boolean
Will be true
if autoplay option was set and current environment potentially supports autoplay.
If autoplay option is not set, or if the current environment does not support autoplay, the value will be false
.
Note that a true
value does not necessarily mean player will autoplay, as some environments may not allow it.
However, a value of false
necessarily means that the player will not autoplay.
See: autoplay, mutedAutoplayEnabled
player.containerWidth : number
The width (in pixels) of player container element.
See: container, containerresize
Example
console.log(`Player container size is: ${player.containerWidth}x${player.containerHeight}`);
player.containerHeight : number
The height (in pixels) of player container element.
See: container, containerresize
Example
console.log(`Player container size is: ${player.containerWidth}x${player.containerHeight}`);
player.container : Element
The DOM element that contains the player.
See: containerWidth, containerHeight
Example
// Resize the player container to 1920x1080
player.container.style.width = '1920px';
player.container.style.height = '1080px';
player.paused : boolean
Indicates whether the video is currently paused.
function togglePlayPause() {
if (player.paused) {
player.play();
} else {
player.pause();
}
}
player.duration : number
The duration of the playlist in seconds, or 0 if empty.
See: durationchange, currentTime
Example
// Return the normalized current time (Number between 0.0 to 1.0)
function normalizedCurrentTime() {
return player.currentTime / player.duration;
}
player.currentTime : number
The current playback time, in seconds. Setting this value seeks the video to the new time.
See: timeupdate, duration
Example
player.currentTime = 0; // Seek to start of playlist
player.buffered : number
The number of seconds of media buffered out of playlist’s duration.
This number will always be equal or greater than currentTime, and will never be greater than duration.
See: currentTime, duration
Example
let bufferAhead = player.buffered - player.currentTime;
console.log(`There are ${bufferAhead} seconds buffered ahead of current playback position.`);
let playlistIsFullyLoaded = player.duration === player.buffered;
if (playlistIsFullyLoaded) {
console.log('Playlist is fully loaded/buffered.');
} else {
console.log('Playlist is not yet fully loaded/buffered.');
}
player.currentNode : Node
The current node being played back. If playlist is empty, value is null
.
Example
console.log(player.currentNode.id);
player.currentNodeId : string
The current node’s unique ID. If playlist is empty, value is an empty string.
See: currentNode
Example
if (player.currentNodeId === 'node_myNodeId') {
// Do something
}
player.currentNodeIndex : number
The current node’s playlist index (zero based). Setting this value seeks the media to the requested playlist index.
See: currentNode
Example
player.currentNodeIndex = 3; // Seeks to 4th node in playlist
player.currentNodeTimeOffset : number
The time offest (in seconds) of current node relative to playlist start. If playlist is empty, value is 0.
See: currentNode
player.currentNodeDuration : number
The current node duration in seconds. If playlist is empty, value is 0.
See: currentNode
player.currentNodeTime : number
The current node elapsed time in seconds since node start. If playlist is empty, value is 0.
See: currentNode
player.currentNodeRemainingTime : number
The current node remaining time in seconds until node end. If playlist is empty, value is 0.
See: currentNode
player.engine : string
A string representation of the currently selected video playback engine.
See: engines, supportedEngines
player.isFullscreen : boolean
Is the player currently in fullscreen mode?
See: requestFullscreen, exitFullscreen, fullscreenchange
Example
if (player.isFullscreen) {
player.exitFullscreen();
}
player.initedPlugins : object
Returns all the plugins that were initialized, names and versions.
This is a subset of registeredPlugins.
See: initPlugin, registeredPlugins, plugininit, pluginInited
Example
console.log(player.initiedPlugins); // {control: '0.0.1', decision: '0.0.2', ...}
player.currentChannel : number
number
A readonly alias for the current node’s current video channel (certain special nodes, known as parallel nodes, contain more than one video channel).
This API is being deprecated and will be removed in an upcoming version, please use player.currentNode.currentVideoTrackIndex instead.
player.reduxStore : object
A Redux store instance, containing the state of the player and some plugins.
This may be used for binding React components to player/plugins state, and is used to power the UI plugin.
See: Redux, playerReduxState
Methods
InterludePlayer.registerPlugin(name, fn, [options])
Statically registers a plugin for later use with InterludePlayer instances.
See: initPlugin
Param | Type | Description |
---|---|---|
name | string |
The plugin’s name. |
fn | pluginInitFunction |
The plugin initialization function. It will be executed whenever an InterludePlayer instance initializes this plugin. |
[options] | object | boolean |
An optional options object. If a boolean is given, it will apply to the autoInit option. |
[options.autoInit] | boolean |
If true, plugin will be initialized automatically whenever a new player instance is created. Default: false . |
[options.version] | string |
The version of the plugin. Default: '0.0.0' . |
[options.deps] | Array.<string> | Array.<object> |
An array of plugin dependencies (other plugins that must be initialized before initializing this plugin). Default: [] (empty array). Each item in the array can either be a string (plugin name), or an object. |
[options.deps[].name] | string |
Required. The name of the plugin this plugin depends on. |
[options.deps[].version] | string |
Optional. Default 0.0.0 . The minimum required version of the plugin (a semver string). |
[options.deps[].optional] | boolean | string |
Optional. Default false . Whether or not this is an optional dependency.Possible values: false - Default. The dependency is manadatory - plugin initialization will fail if dependency is not found.true - Dependency is optional - initializing this plugin will not fail if dependency was not found.'orderonly' - Dependency is optional - dependency will be initialized first, but only if explicitly requested on the same call to initPlugin. |
[options.redux] | object |
Optional. An options object for plugins that wish to participate in the redux state. |
[options.redux.reducer] | function |
Required. A redux reducer function to be registered with the reduxStore. The state given as the first argument to the reducer is a part of the global state, under its own namespace (i.e. player.reduxStore.getState().myPluginName). The reducer is only resposible for its part of the global state. Make sure to follow redux’s best practices when implementing a reducer. |
Example
InterludePlugin.registerPlugin('myPlugin', function(ctx, options) {...}, {
autoInit: false,
version: '1.0.3',
deps: [
'anotherPlugin',
{
name: 'yetAnotherPlugin',
version: '2.0.0',
optional: false
}
]
});
...
player.initPlugin('myPlugin', {});
InterludePlayer.isSupported() ⇒ boolean
Checks whether InterludePlayer is supported on current environment and returns a boolean value.
Returns: boolean
- True if InterludePlayer is supported on current environment, false otherwise.
Example
if (!InterludePlayer.isSupported()) {
console.log('Oh no! InterluePlayer is not supported on current env...');
}
InterludePlayer.isDeviceSupported() ⇒ boolean
Checks whether InterludePlayer is supported on current device.
This is slightly different from isSupported, since the player might be supported on device, but not on current environment/browser.
Returns: boolean
- True if InterludePlayer is supported on current device, false otherwise.
Example
if (InterludePlayer.isSupported()) {
const player = new InterludePlayer('#playerContainer');
// ...
} else if (InterludePlayer.isDeviceSupported()) {
alert('Download Chrome!');
}
InterludePlayer.supportedEngines() ⇒ Array.<string>
Checks which video playback engines are supported on current environment.
Returns: Array.<string>
- Array of supported engine names. An empty array means that InterludePlayer is not supported on current environment.
Possible values include:
msevid
jabba
rancor
See: engines, engine
Exampleconst engines = InterludePlayer.supportedEngines(); engines.forEach(engineName => { console.log(`Current environment supports engine "${engineName}"`); });
player.addReduxMiddleware : object
Param | Type | Description |
---|---|---|
the | object |
dynamic middleware object |
player.on(evt, listener)
Adds a listener function to the specified event.
The listener will not be added if it is a duplicate.
If the listener returns true then it will be removed after it is called.
If you pass a regular expression as the event name then the listener will be added to all events that match it.
To add a listener for a specific event you can use its name (i.e. 'nodestart'
), or you can use the events object (i.e. player.events.nodestart
).
Param | Type | Description |
---|---|---|
evt | string | RegExp |
Name of the event to attach the listener to. |
listener | function |
Method to be called when the event is triggered. If the function returns true, then it will be removed after calling. |
Example
player.on('nodestart', (node, index) => {
console.log(`Node "${node.id}" at playlist index ${index} started.`);
});
player.on(player.events.nodeend, (node, index) => {
console.log(`Node "${node.id}" at playlist index ${index} ended.`);
});
player.once(evt, listener)
Semi-alias of on.
It will add a listener that will be automatically removed after its first execution.
Param | Type | Description |
---|---|---|
evt | string | RegExp |
Name of the event to attach the listener to. |
listener | function |
Method to be called when the event is triggered. |
player.off(evt, listener)
Removes a listener function from the specified event.
When passed a regular expression as the event name, it will remove the listener from all events that match it.
Param | Type | Description |
---|---|---|
evt | string | RegExp |
Name of the event to remove the listener from. |
listener | function |
Method to remove from the event. |
player.trigger(evt)
Triggers an event of your choice.
When triggered, every listener attached to that event will be executed.
If you pass the optional arguments, they will be passed to every listener upon execution.
You can trigger and listen to your own custom events.
Param | Type | Description |
---|---|---|
evt | string | RegExp |
Name of the event to emit and execute listeners for. |
[…args] | * |
Optional arguments to be passed to each listener. |
Example
player.on('myproject.myevent', function(firstArg, secondArg) {
console.log('This is an handler function to my event!', firstArg, secondArg);
});
player.trigger('myproject.myevent', firstArg, secondArg);
player.play()
Begins video playback.
See: pause
Example
player.play();
player.pause()
Pauses video playback.
See: play, paused, pause
Example
player.pause();
player.isFullscreenSupported() ⇒ boolean
Returns whether or not the full-screen API is supported on current environment.
Will return false
if player is embedded in an iframe (or iframe hierarchy) which is missing the allowfullscreen
attribute.
Returns: boolean
- True if fullscreen is supported on current environment, false otherwise.
See: requestFullscreen
Example
if (player.isFullscreenSupported()) {
myFullscreenBtn.show();
} else {
myFullscreenBtn.hide();
}
player.requestFullscreen([options])
Asynchronously requests that the player be made full-screen.
It’s not guaranteed that the player will be put into full-screen mode.
Note that on some browsers/devices, this will not work unless call stack originated with user interaction.
See: isFullscreenSupported, exitFullscreen, fullscreenchange
Param | Type | Description |
---|---|---|
[options] | object |
Optional. A FullscreenOptions object that will be passed on to Element.requestFullscreen(). If not given, fullscreenOptions will be used. |
Example
if (player.isFullscreenSupported()) {
player.requestFullscreen();
}
player.exitFullscreen()
Takes the player out of full-screen mode.
See: requestFullscreen, fullscreenchange
Example
player.exitFullscreen();
player.initPlugin(name, [options]) ⇒ boolean
Initializes a plugin that was previously statically registered.
There are two ways to invoke this function.
The simple form accepts 2 arguments, name
and options
.
Another way, is to pass a single map object, with plugin names as keys, and options objects as values (this allows initializing several plugins with a single call).
Returns: boolean
- True if successfully initialized, false otherwise.
See: registerPlugin, registeredPlugins, initedPlugins, plugininit, pluginInited
Param | Type | Description |
---|---|---|
name | string | object |
Plugin’s name (string) or a map object with plugin names as keys and options as values. |
[options] | object |
Optional configuration object to pass to plugin initialization function (only applies if first argument was a string). |
Example
player.initPlugin('myPlugin', {});
// OR
player.initPlugin({myPlugin: {}});
player.pluginInited(name) ⇒ Promise
Returns a promise that resolves once a plugin has been successfully initialized.
Also supports multiple arguments.
Returns: Promise
- A promise that resolves once plugin has been successfully initialized.
See: initPlugin, initedPlugins, plugininit
Param | Type | Description |
---|---|---|
name | string |
Plugin’s name. |
[…name] | string |
Optional. Additional plugin names. |
Example
player.pluginInited('myPlugin', 'myOtherPlugin').then(function() {
// We will only execute this after 'myPlugin' and 'myOtherPlugin' have been initialized
doSomething();
});
player.append(node)
Appends a node to the end of stream.
This is similar to the playlist.push method.
Param | Type | Description |
---|---|---|
node | string | Node |
Node object or node id (which was previously added to repository). |
Example
player.append('myNodeId');
player.seek(node, [offset])
Immediately seek to given node. By default, seeks to the beginning of the node (unless an offset
argument was given).
In practice, this will push the node to the playlist, and seek to it (i.e. via currentTime setter).
Param | Type | Description |
---|---|---|
node | string | Node |
Node object or node id (which was previously added to repository). |
[offset] | number |
Optional offset (in seconds) from beginning of node. If a negative value is given, it will be used as offset from end of node. This will fail if requested offset is too close to end of node (allow at least 2 seconds before end of node, see playlistcritical). |
Example
player.seek('myNodeId'); // Will push 'myNodeId' into playlist and seek to it
player.seek('myNodeId', 10); // Will push 'myNodeId' into playlist and seek to 10 seconds within the node
player.seek('myNodeId', -10); // Will push 'myNodeId' into playlist and seek to 10 seconds before the end of the node
player.switch(value)
Immediately switch to another audio/video track on the current parallel node.
The method accepts either a avTracksObj object, a numeric index to switch to (may throw error if out of range), or the special string values next
or prev
.
Param | Type | Description |
---|---|---|
value | avTracksObj | number | string |
An object describing which audio and video tracks to switch to. A numeric value would switch both audio and video tracks and must be in the range [0, Math.max(player.currentNode.audioTracksCount, player.currentNode.videoTracksCount) ]. Special string values next and prev are also accepted. |
Example
player.on('switching', function() { console.log('Starting channel switching'); })
player.on('switched', function() { console.log('Completed channel switch'); })
player.switch('next');
Events
“timeupdate”
Triggered when the time indicated by the player’s currentTime attribute has changed.
During playback, timeupdate
is triggered every ~250 milliseconds.
See: currentTime
“durationchange”
Triggered when the total playlist duration has changed (i.e. due to a node being pushed to the playlist).
See: duration
Param | Type | Description |
---|---|---|
newDuration | number |
The new duration in seconds. |
“volumechange”
Triggered when the audio volume changes (i.e. the volume is set or the muted property is changed).
See: volume
Param | Type | Description |
---|---|---|
volumeObj | object |
An object containing the current volume, muted and isAudioLocked state. |
volumeObj.volume | number |
The current volume. |
volumeObj.muted | boolean |
The muted state. |
volumeObj.isAudioLocked | boolean |
The isAudioLocked state. |
“audiolockedchange”
Triggered when the value of isAudioLocked changes.
See: isAudioLocked, mutedAutoplayEnabled
“loadeddata”
Triggered when the first frame of the media has finished loading.
“playing”
Triggered when the media begins to play (either for the first time, after having been paused/waiting, or after restarting).
See: play
“waiting”
Triggered when the requested operation (such as playback) is delayed pending the completion of another operation (such as a seek/buffering).
“canplay”
Triggered when player buffered enough media to begin playback.
Param | Type | Description |
---|---|---|
buffered | number |
The duration of buffered media in seconds. |
isAutoplayExpected | boolean |
Is the video expected to start automatically playing? See isAutoplayExpected. |
“requiresuseraction”
Triggered when player cannot buffer any media until a user interaction/gesture is performed.
“play”
Triggered when play is called.
See: play
“pause”
Triggered when playback is paused (following a pause call).
“ended”
Triggered when playlist playback completes.
See: playlistcritical
“fullscreenchange”
Triggered when the player is switched to/out-of fullscreen mode.
See: requestFullscreen, exitFullscreen
Param | Type | Description |
---|---|---|
isFullscreen | boolean |
True if we switched to fullscreen, false otherwise. |
“switched”
Triggered when a channel switch was completed.
See: switch
Param | Type | Description |
---|---|---|
previousTracks | avTracksObj |
The previous audio and video tracks |
currentTracks | avTracksObj |
The current audio and video tracks |
“switching”
Triggered when a channel switch was requested.
See: switch
Param | Type | Description |
---|---|---|
currentTracks | avTracksObj |
The current audio and video tracks |
requestedTracks | avTracksObj |
The requested audio and video tracks |
“seeking”
Triggered when a seek operation begins.
See: currentTime
“seeked”
Triggered when a seek operation completes.
If a seek was unsuccessful, an error event will be triggered instead.
See: currentTime
Param | Type | Description |
---|---|---|
currentTime | number |
Player’s currentTime after seek was completed. |
index | number |
Current node’s playlist index (0 based). |
currentNodeTimeOffset | number |
See currentNodeTimeOffset. |
“nodestart”
Triggered when node playback has started.
See: Node
Param | Type | Description |
---|---|---|
node | Node |
The node that’s currently playing. See currentNode. |
index | number |
The node’s playlist index (0 based). |
“nodeend”
Triggered when node playback has completed.
See: Node
Param | Type | Description |
---|---|---|
node | Node |
The node that just ended. |
index | number |
The node’s playlist index (0 based). |
“playlistcritical”
Triggered when playback reached a critical point and no next node has been pushed to playlist.
If no node is pushed in response to playlistcritical
, the ended event will be triggered once current node’s playback is complete.
Param | Type | Description |
---|---|---|
node | Node |
The node that’s currently playing. See currentNode. |
index | number |
The node’s playlist index (0 based). |
“error”
Triggered when an error occurred.
If no listeners were attached to the error
event, error will be thrown instead.
Param | Type | Description |
---|---|---|
err | Error | string |
Error object or message. |
“warning”
Triggered when an error of severity warning occurred.
Param | Type | Description |
---|---|---|
err | Error |
Error object. |
“playlistreset”
Triggered following a playlist.reset() call.
See: playlist
“playlistpush”
Triggered when playlist.push() was called.
If multiple nodes were pushed, each node will trigger this event.
See: playlist
Param | Type | Description |
---|---|---|
node | Node |
The node that was pushed to playlist. |
index | number |
The node’s playlist index (0 based). |
“plugininit”
Triggered when a plugin was successfully initialized, following a initPlugin call.
You can also register an event handler for a specific plugin’s initialization, by appending its name to the event name.
See: initPlugin
Param | Type | Description |
---|---|---|
name | string |
The plugin’s name. |
version | string |
The plugin’s version. |
Example
player.on('plugininit', function(name, version) {
if (name === 'myPlugin') {
doSomethin();
}
});
// OR
player.on('plugininitmyPlugin', function(name, version) {
doSomething();
});
“containerresize”
Triggered when player container element is resized.
See: container, containerWidth, containerHeight
Param | Type | Description |
---|---|---|
width | number |
The new containerWidth (in pixels). |
height | number |
The new containerHeight (in pixels). |
“resize”
Triggered when one or both of the videoWidth and videoHeight attributes have just been updated.
See: videoWidth, videoHeight
Param | Type | Description |
---|---|---|
width | number |
The new videoWidth (in pixels). |
height | number |
The new videoHeight (in pixels). |
“qoescore”
Triggered when QoE score is updated.
Param | Type | Description |
---|---|---|
score | number |
The new score. |
“qoestatus”
Triggered when QoE status is updated.
Param | Type | Description |
---|---|---|
status | string |
The new status. |
Objects
avTracksObj : object
The argument to the switch method.
An object consisting of audio
and video
properties.
See: switch
Param | Type | Description |
---|---|---|
[avTracksObj.audio] | number | string |
Optional. 0-based index of audio track to switch to. Should be in the range [0, player.currentNode.audioTracksCount - 1]. Special string values 'prev' and 'next' are also accepted. If omitted, switch will retain current audio track. |
[avTracksObj.audio] | number | string |
Optional. 0-based index of video track to switch to. Should be in the range [0, player.currentNode.videoTracksCount - 1]. Special string values 'prev' and 'next' are also accepted. If omitted, switch will retain current video track. |
Example
{
audio: 0,
video: 3
}
environmentReduxState : object
Environment redux state sub-object (i.e. player.reduxStore.getState().environment).
See: reduxStore
Example
// player.reduxStore.getState().environment
{
// The environment name.
// Current values are "desktop", "ios", "android" or "windows" (for non-desktop Windows devices).
"name": "desktop",
// An object that contains all the query string params parsed from the page’s URL.
// Note that the values are also parsed so they can have different types
// (e.g. string, array, boolean, number).
"queryParams": {
"autoplay": true,
"debug": "events"
},
// True if touch events are supported on current environment, false otherwise.
"isTouchEnabled": false,
// An object containing information about the current browser.
"browser": {
"name": "Chrome",
"version": "80.0.3987.116",
"major": "80"
},
// An object containing information about the current operating system.
"os": {
"name": "Windows",
"version": "10"
}
}
playerReduxState : object
Player’s redux state sub-object (i.e. player.reduxStore.getState().player).
See: reduxStore
Example
// player.reduxStore.getState().player
{
// Audio Props
//////////////////////////////////////////////////////
volume: 1.0,
muted: false,
// Playback State Props
//////////////////////////////////////////////////////
isPlaying: false,
isPaused: true,
isSeeking: false,
isWaiting: false,
isEnded: false,
isFullscreen: false,
isAudioLocked: true,
// Current Node Related Props
//////////////////////////////////////////////////////
currentNodeId: '',
currentVideoTrackIndex: 0,
currentAudioTrackIndex: 0,
isCurrentNodeParallel: false,
currentNodeTime: 0,
currentNodeDuration: 0,
currentNodeProgress: 0,
currentNodeRemainingTime: 0,
// Container Dimensions (px)
//////////////////////////////////////////////////////
containerWidth: 0,
containerHeight: 0,
// Video content positioning relative to container (%)
//////////////////////////////////////////////////////
videoLeftPercent: 0,
videoTopPercent: 0,
videoWidthPercent: 100,
videoHeightPercent: 100
}
Callbacks
pluginInitFunction : function
Plugin initialization function (second argument of registerPlugin).
Param | Type | Description |
---|---|---|
ctx | object |
Contains a reference to the player instance and other goodies. |
[options] | object |
An optional configuration object for the plugin initialization. |
Example
function myPlugin(ctx, options) {
options = options || {};
if (options.exposeOnInstance) {
ctx.player.myPlugin = {
doSomething: function() {
console.log('Done...!');
},
dispose: function() {
delete ctx.player.myPlugin;
}
};
}
}