Kaltura InPlayer HTML5 Plugins

From HTML5 Video
Jump to: navigation, search


This document will guide the creation of html5 plugins.

Which side of the player?

An overview of onPage vs inside player plugins

The first question you have to ask when developing a player plugin is whether your plugin should be on loaded inside the player as a native plugin OR on the hosting page side communicating through the kdp and kWidget API.

Kaltura OnPage Plugins are loaded for both flash and HTML5 players and only have to be written once. On-page plugins are loaded on the same page of the player and they interact with the player with the Kaltura kdp api.

Kaltura HTML5 iframe plugins run inside the iframe side of player and have lower level access to the video tag and internal html5 events. Any plugins written as an iframe plugin will have to be written twice once for the html5 player and once for the swf player (see Creating KDP3 Flash plugins). In-Player plugins are good for visual plugins, skins, and ads where the plugin needs to control the playback sequence or modify the streaming functionality (e.g. peer 2 peer plugins).

On-Page plugins are good for anayltics or secondary interaction widgets such as searching transcripts, synced html content (slides, commentary, etc). A great example (and blue-print) for On-Page plugins is the Video Details Block On-Page player plugin.

This document covers iframe side plugins.


Getting Started - Developing iFrame (aka In-Player) Plugins

You will want to take a look at the External Resources plugin. The external resource support outlines how you include javascript resources from your uiConf plugin configuration lines. Specifically for an iframe html5 plugins we want to look at the iframeHTML5Js1 attribute:

<Plugin id="fooBar" width="0%" height="0%" includeInLayout="false" loadingPolicy="onDemand" 
        iframeHTML5Js1="myfooBarHtml5IframePlugin.js"
/>

This will cause the player to load your plugin during player build out. You can use a relative path to the player embed or an absolute url. We recommend using an absolute url once your done with testing.

Plugin Skeleton

Note this covers plugin support as of version 1.6.7 of the html5 library

First check that your myfooBarHtml5IframePlugin.js file is loading by putting an alert or console log call there. Once you confirm the plugin is loading your ready to start adding player build out bindings.

Here is an outline of a simple plugin with code comments

// Be sure to scope your plugin with the mw and $ jQuery to avoid global leakage.
( function( mw, $ ) {
 
	mw.bindHelper('Kaltura_CheckConfig', function( event, embedPlayer, callback ){
		// You will now want to check if your plugin is active.
		// ( For example a flashvar or uiVar may disable your plugin )
		if( !embedPlayer.isPluginEnabled( 'fooBar' ) ){
			// plugin is not enabled issue callback to continue player build out
			callback();
			return ;
		}
 
		// fooBar plugin ~is active~ you must decide if you need to block 
		// player build out or request any additional resources. 
		// You can request them with normal jQuery.getScript calls.		
		new mw.fooBar( embedPlayer, callback );
	});
 
	// Depending on the size of your plugin you may want to 
	// issue a separate request instead of having be part of the initial pay load. 
	// in practice this is not such a big concern with external plugins, 
	// since they are generally enabled if the plugin line is included. 
	mw.fooBar = function( embedPlayer, callback ){
		this.init( embedPlayer, callback );
	};
	mw.fooBar.prototype = {
		// A namespce for all player bindings, enables easy enabling / disabling
		// of the plugin in a given player session. 
		bindPostfix: '.fooBar',
		/**
		* @constructor 
		* @param {object} embedPlayer Base player object
		* @param {function} callback Function to call to finish player build out
		*/
		init: function( embedPlayer, callback){
			this.embedPlayer = embedPlayer;
			this.addPlayerBindings();
			// continue player build out ( without blocking )
			// if we needed some info before player build out ( like a pre-roll ad ) 
			// we could get that before we issue the callback, but be sure to include
			// a time out to ensure the player is built even if your plugin can't get
			// its resources. 
			callback();
		},
		/**
		* Remove player bindings
		*/
		destroy: function(){
			// remove any old pluing binding:
			this.embedPlayer.unbindHelper( this.bindPostfix );
		}
		/**
		* Add player bindings
		*/
		addPlayerBindings: function(){
			// remove any old bindings
			this.destroy();
 
			// Add bindings: 
			this.embedPlayer.bindHelper( 'onPlay', function(){
				// add some overlay text to the interface:
				this.embedPlayer.getInterface().append( 
					$('<div />')
					.css({
					   'position': 'absolute',
					   'top' : '10px',
					   'right' : '10px'
					})
					.text( 'hello world' );
				);
			});
			// write the evaluated configuration option to the console: 
			// where < plugin id="fooBar" myPluginAttr="{mediaProxy.entry.id}" 
			mw.log( "fooBar:: " + this.getConfig( 'myPluginAttr' ) );
			// will log to the console ( in debug mode ) 
			// fooBar:: 0_dsafda
			// ( where 0_dsafda is the entry id of the current entry )
		},
		/**
		* Get a configuration option by attribute name
		*/
		getConfig:function( attrName ){
			return this.embedPlayer.getKalturaConfig( 'fooBar', attrName );
		}
	}
 
})( window.mw, jQuery );