InterludePlayer

eko Core

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.

new InterludePlayer(el, [options])
constructor

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.engines : Array.<string>
property

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
property

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
property

If true, playback will begin muted.

Default: false
Example 

// playerOptions.json
{
    "muted": true
}

options.mutedAutoplayEnabled : boolean
property

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
property

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
property

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
property

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
property

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
property

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 to boxing (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
property

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
property

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
property

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
property

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
property

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
property

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
property

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
property

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
staticpropertyreadonly

The InterludePlayer’s version string.

Example 

console.log(`The player version is ${InterludePlayer.version}`);

InterludePlayer.ivdVersion : object
staticpropertyreadonly

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
staticpropertyreadonly

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
staticpropertyreadonly

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
propertyreadonly

The player’s version.

Example 

console.log(`The player version is ${player.version}`);

player.options : object
propertyreadonly

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
property

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
property

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
propertyreadonly

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
propertyreadonly

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
propertyreadonly

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
propertyreadonly

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
propertyreadonly

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
propertyreadonly

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
propertyreadonly

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
propertyreadonly

Indicates whether the video is currently paused.

See: play, pause
Example 

function togglePlayPause() {
    if (player.paused) {
        player.play();
    } else {
        player.pause();
    }
}

player.duration : number
propertyreadonly

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
property

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
propertyreadonly

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
propertyreadonly

The current node being played back. If playlist is empty, value is null.

Example 

console.log(player.currentNode.id);

player.currentNodeId : string
property

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
property

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
propertyreadonly

The time offest (in seconds) of current node relative to playlist start. If playlist is empty, value is 0.

See: currentNode

player.currentNodeDuration : number
propertyreadonly

The current node duration in seconds. If playlist is empty, value is 0.

See: currentNode

player.currentNodeTime : number
propertyreadonly

The current node elapsed time in seconds since node start. If playlist is empty, value is 0.

See: currentNode

player.currentNodeRemainingTime : number
propertyreadonly

The current node remaining time in seconds until node end. If playlist is empty, value is 0.

See: currentNode

player.engine : string
propertyreadonly

A string representation of the currently selected video playback engine.

See: engines, supportedEngines

player.isFullscreen : boolean
propertyreadonly

Is the player currently in fullscreen mode?

See: requestFullscreen, exitFullscreen, fullscreenchange
Example 

if (player.isFullscreen) {
    player.exitFullscreen();
}

player.initedPlugins : object
propertyreadonly

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
propertyreadonlydeprecated

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
propertyreadonly

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])
staticmethod

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
staticmethod

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
staticmethod

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>
staticmethod

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
    Example 
    const engines = InterludePlayer.supportedEngines();
engines.forEach(engineName => {
  console.log(`Current environment supports engine "${engineName}"`);
});

player.addReduxMiddleware : object
property

Param Type Description
the object dynamic middleware object

player.on(evt, listener)
method

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).

See: once, off, trigger

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)
method

Semi-alias of on.
It will add a listener that will be automatically removed after its first execution.

See: on, off, trigger

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)
method

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.

See: on, once, trigger

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)
method

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.

See: on, once, off

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()
method

Begins video playback.

See: pause
Example 

player.play();

player.pause()
method

Pauses video playback.

See: play, paused, pause
Example 

player.pause();

player.isFullscreenSupported() ⇒ boolean
method

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])
method

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()
method

Takes the player out of full-screen mode.

See: requestFullscreen, fullscreenchange
Example 

player.exitFullscreen();

player.initPlugin(name, [options]) ⇒ boolean
method

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
method

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)
method

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])
method

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)
method

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”
event

Triggered when the time indicated by the player’s currentTime attribute has changed.
During playback, timeupdate is triggered every ~250 milliseconds.

See: currentTime

“durationchange”
event

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”
event

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”
event

Triggered when the value of isAudioLocked changes.

See: isAudioLocked, mutedAutoplayEnabled

“loadeddata”
event

Triggered when the first frame of the media has finished loading.

“playing”
event

Triggered when the media begins to play (either for the first time, after having been paused/waiting, or after restarting).

See: play

“waiting”
event

Triggered when the requested operation (such as playback) is delayed pending the completion of another operation (such as a seek/buffering).

“canplay”
event

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”
event

Triggered when player cannot buffer any media until a user interaction/gesture is performed.

“play”
event

Triggered when play is called.

See: play

“pause”
event

Triggered when playback is paused (following a pause call).

See: pause, paused

“ended”
event

Triggered when playlist playback completes.

See: playlistcritical

“fullscreenchange”
event

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”
event

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”
event

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”
event

Triggered when a seek operation begins.

See: currentTime

“seeked”
event

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”
event

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”
event

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”
event

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.

See: playlist, ended

Param Type Description
node Node The node that’s currently playing. See currentNode.
index number The node’s playlist index (0 based).

“error”
event

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”
event

Triggered when an error of severity warning occurred.

Param Type Description
err Error Error object.

“playlistreset”
event

Triggered following a playlist.reset() call.

See: playlist

“playlistpush”
event

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”
event

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”
event

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”
event

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”
event

Triggered when QoE score is updated.

See: qoe, score

Param Type Description
score number The new score.

“qoestatus”
event

Triggered when QoE status is updated.

See: qoe, status

Param Type Description
status string The new status.

Objects

avTracksObj : object
property

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
property

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
property

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
callback

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;
            }
        };
    }
}
Rate this page:
☆ ☆ ☆ ☆ ☆
X
Tell us more!