Kaltura HTML5 Configuration

From HTML5 Video
Revision as of 12:39, 1 May 2012 by Mdale (Talk | contribs)

Jump to: navigation, search

This document helps you navigate the common configuration options for the HTML5 library.


Getting additional HTML5 Library Support

If you're a Kaltura customer, email support@kaltura.com, For speedy resolution include:

  • A short description of the issue.
  • A public or password protected url that has displays the issue your having.

If you're a Kaltura community member we are generally very responsive to forum posts, again if possible include a test page and or example code that displays the issue your having.

HTML5 Library Version

NOTE the Kaltura HTML5 Release Notes page documents html5 library versions.

There are three options for loading the html5 library.

  • http://html5.kaltura.org/js version is updated frequently and includes newer features, capabilities.
  • http://www.kaltura.com/.../embedIframeJs/... is the version of the library that kaltura.com SaaS offering points to. Its updated less frequently and features are more tightly integrated with the KMC before being deployed and undergoes a more stringent QA process.
  • Host it your self If running onPrem or you want to do special customizations you may chose to host the open source kaltura html5 library on their own server. The html5 library is much simpler to deploy then a full onPrem or Community kaltura install, and can gives the developer fine grain control over update deployment process. We tag deployment versions, so its easy to check out a given stable version as a basis for self hosted copy of the library.

Both Kaltura hosted versions are tested before being updated and share the same code base. Also see our automated testing page on html5video.org.

To better understand the library differences, let us consider the life-cyle of a given plugin. A plugin can start off as a one-off integration for a particular client or as a community member led feature hosted completely outside of the kaltua system. If the plugin is generally useful, the plugin may be added as a plugin/ module to the kaltura HTML5 library. Once added as a plugin we also add automated testing and if all goes well we add it as an option to .org hosted version of the HTML5 library. If plugin is popular and a commonly requested feature, it will be further integrated into the Kaltura KMC version of the html5 library and made available in the KMC gui.

The resource loading framework for the HTML5 library makes it possible to have may plugins available for dynamically invocation without increasing core payload size. Furthermore because KMC player studio allows the setting of "custom vars" a given plugin can still "work" within the Kaltura system without being fully integrated into the KMC gui. So through the entire lifecycle of the plugin, it can be integrated in SaaS, onPrem, and Community hosted versions of the KMC platform via the .org hosted version of the library.

All configuration options should come after you include the kaltura script:

<!-- Kaltura html5 library include if copied from the KMC could also be http://www.kaltura.com/p/243342/sp/24334200/embedIframeJs/ ... ( note .org vs .com html5 js -->
<script src="http://html5.kaltura.org/js" type="text/javascript">
<script type="text/javascript">
              // mw.setConfig calls go here
<!-- Kaltura Object Embed Goes here -->
<object id="kaltura_player"> ...</object>

Controlling the HTML5 library version for .com uiConf urls

By default your per partner, per uiConf url will point to the latest Kaltura.com QA'ed release. Sometimes you may want to have more control over which version of the html5 library your players are using. To update:

  1. Login to the test me console.
  2. Select the uiConf service and then "update"
  3. Then set uiConf:html5Url (string): to the version you want i.e: /html5/html5lib/v1.6.0/mwEmbedLoader.php You can see all the valid versions listed on the Release Notes page ( for .com urls you should just use the path so that it works if you ever use https ). Once updated urls the uiConf will be redirect to that version.

HTML or Native player for IPad

The iPad has two modes of usage for HTML5, HTML controls or native player. There are tradeoff to either option:

Advantages of HTML controls:

  • On screen overlays ( like ad overlays )
  • Control over the playhead scrubber ( no ad skip)
  • Custom branded player and 'experience' ( watermarks, control bar logo, share option etc. )

Advantages of Native controls:

  • Smooth transition to true fullscreen ( no "new browser window" or address bar )
  • Consistent with iPhone experience ( native player )
  • Analytics and flavor selection work the same for both modes

To switch off html5 controls for iPad:

mw.setConfig('EmbedPlayer.EnableIpadHTMLControls', false );

Lead with HTML5

As of version 1.6.1 we now support leading with html5. A Kaltura player by default uses flash. With this property you can have the script use html5 first on browsers that support it, while falling back to flash on browsers such as IE8 that do not support the video tag.

mw.setConfig( 'KalturaSupport.LeadWithHTML5', true );
  • Note if you want fine grain control over which browsers use HTML5 or not, see the UserAgentPlayerRules plugin
  • Note this property is different form the "forceMobileHTML5" flag that will force the HTML5 player regardless of native browser support.

Lead with HTML5 on Android

As of version 1.6.0 by default we try to use 'flash' on android. To use HTML5 first on androids set:

mw.setConfig( 'EmbedPlayer.UseFlashOnAndroid', false );

Force flash for desktop browsers

By default, the html5 library is invoked when there is no flash available. For some use cases you may want to force flash install request for desktop users, that don't yet have flash installed ( instead of using desktop html5 ). To force flash on desktop users this simply set:

mw.setConfig('Kaltura.ForceFlashOnDesktop', true );

Dynamically embed the player

As of 1.6.6 we recommend the kWidget.embed call. 

The best way to embed the hmtl5 library is with kWidget.embed. This is because your page will not have to wait until dom ready to check to rewrite object tags. Future versions of the kaltura KMC will use kWidget embed, but as of version 1.6.6 you can manually make use of kWidget.embed on your page for both dynamic and inline embed calls.

The following outlines how a kWidget embed might look on your page: you can pass to kWidget.embed:

<script src="{HTML5 library include}"></script> 
<div id="myVideoTarget" style="width:400px;height:330px;">
	<!--  SEO and video metadata go here -->
	<span property="dc:description" content="folgers coffee commercial"></span>
	<span property="media:title" content="FolgersCoffe.mpeg"></span>
	<span property="media:width" content="400"></span>
	<span property="media:height" content="300"></span>
<script type="text/javascript">
	window['doPlayCallback'] = function( playerId ){
		console.log( 'kwidget doPlayCallback ' + playerId );
		'targetId': 'myVideoTarget',
		'wid': '_243342',
		'uiconf_id' : '2877502',
		'entry_id' : '0_uka1msg4',
			'externalInterfaceDisabled' : false,
			'autoPlay' : true
		'readyCallback': function( playerId ){
			console.log( "kWidget player ready: " + playerId );
			var kdp = document.getElementById( playerId );
			kdp.addJsListener( 'doPlay', 'doPlayCallback');

Directly embed the iframe player

Note: Its highly recommended to use the javascript embed, which supports fullscreen and the api

Sometimes for sharing the player on remote sites where you don't have javascript or if you just want to load the player without any javascript on your page you can use the "iframe" url directly. It should be noted that this will degrade some feature like fullscreen support. For .com the mwEmbedFrame url currently looks like this:

If you want to have DOM element Overlay your flash object you can add a parameter to the url ?wmode=transparent Note wmode transparent inside an iframe is not compatible with all flash ui components per security models of some browsers ( so your mileage may vary )

<iframe src="http://cdnapi.kaltura.com/html5/html5lib/v1.6.6/mwEmbedFrame.php/wid/[WIDGET_ID]/uiconf_id/[UICONF_ID]/entry_id/[ENTRY_ID]/" width="480" height="271" frameborder="0" ></iframe>

where 1.6.6 is the library version of your choice. You can get your .com iframe embed code by pressing the share button inside the html5 player.

Embedding the HTML5 player in native apps

When embedding the player in native iPhone app, you can use the property webkit-playsinline to cause the player to render in a window isntead of taking up the full screen.

mw.setConfig( 'EmbedPlayer.WebKitPlaysInline', true );

Enabling Apple AirPlay

Air play allows playback of html5 video on apple tv via wireless device mirroring see for more info Should be set inside uiVars of the uiConf ( available as of 1.6.11 )

<var key="EmbedPlayer.WebKitPlaysInline" value="true">

Controlling z-index of player when fullscreen

You can control the z-index of the fullscreen html5 player ( for browsers that don't support native fullscreen ) with:

mw.setConfg('EmbedPlayer.FullScreenZIndex', {Number} );

Directly Grab Video Sources

Example page

Sometimes you need to integrate the kaltura videos into a native device player or you want an extremely light weight version of the player with no analytics or plugins. Here all you really want a stand alone small snippet of javascirpt to generate urls to the media. The stand alone kWidget.getSources javascript may be for you. This code gives you a list of flavors with urls, and is very similar to what the Kaltura HTML5 library does internally when building out the list of urls.

Note you don't even need that JS snippet, ( if referee, stream tokenization. or custom flavors are not set your account ). You can just modify a standard playManifest url to get at your video assets:

For example this iPhone flavor:


Could be your template where the items in bold are replaced with your partner, entryId and flavorId respectively.

Seeking is inaccurate on iOS / OSX Safari

If HLS is enabled, seeking only seeks to the nearest 10 seconds. See disable adaptive configuration to instead use progressive, which supports more accurate seeking by http ranged requests.

iPad and iPhone fail to play video, while desktop html5 works

When the player "works" and plays content on desktop browsers but fails on iPad with a pop up error like "this operation could not be completed", only plays audio or does not play at all, its likely a configuration issue with HLS ( http apple live streaming ). To resolve you will need to fix the adaptive streaming setup integration. To restore plaback on iPad ( without HLS ) while you fix the HLS setup, you can set the following configuration option on page or as uiConf var:

mw.setConfig("Kaltura.UseAppleAdaptive", false );

Player does not work ( no mobile sources error )

If the html5 player displays the message no mobile sources, be sure to check the content in the KMC and ensure the given piece of content has Mobile/HTML5 flavors. These include flavors tagged as 'iPad', 'iPhone', 'Ogg', 'WebM', '3gp'

Player is not displayed and jQuery JavaScript conflicts?

The library is designed to be as compatible as possible with client javascript. To save bandwidth, increase load speed and not break the sites in which the player is embed, we don't re-load jQuery and use what ever is available. Occasionally if the host site is using an old version of jQuery or some versions of jQuery mobile javascript conflicts can occur. A simple fix to this ( if your not using the kdp js api on the player ) is to disable the iframe api. This will tell the loader script to just insert an iframe, and not load the library javascipt code to support the iframe messaging api. You can set this option like so:

mw.setConfig('EmbedPlayer.EnableIframeApi', false );

Library is rewriting tags that I don't want rewritten

By default the player rewrites video tags to the html5 player interface at DOM ready time. This is a feature to make integration simple ie "just include this script" and video tags work in IE 8. This behavior may be undesirable ( say you have a page with multiple video players or you want the native video player to be displayed ) In which case simply set:

mw.setConfig( 'EmbedPlayer.RewriteSelector', false ) ;

Custom loading spinner

As of 1.6.1 you can set a custom loading spinner.

mw.setConfig( 'LoadingSpinner.ImageUrl', {imageURL} );

Note: As of 1.6.5, this functionality is supported by the UiConf watermark plugin.

By default, like the flash player the the HTML5 player displays an attribution logo. You may want to remove or disable that attribution. To disable the attribution set:

mw.setConfig('EmbedPlayer.AttributionButton', false);

To change the attribution to a custom logo, with custom link set:

mw.setConfig('EmbedPlayer.AttributionButton', {
		 	'title' : 'Title for your custom link',
		 	'href' : 'url to link to for your player icon',
			// Style icon to be applied
			'class' : 'kaltura-icon',
			// An icon image url 16x16 image url or data url )
			'iconurl' : "http://url.to.your/custom/icon.png"

Disable right click

You may want to disable users right clicking on video. For example to prevent showing controls on adds and skipping ad content.

mw.setConfig('EmbedPlayer.EnableRightClick', false );

Remove options button

The option button ( small gear in the lower right ) can be removed with:

mw.setConfig('EmbedPlayer.EnableOptionsMenu', false );

Setting player "theme" from presets

The player supports the following skin presets:

  • 'kdark' // the default dark theme
  • 'le-fogg' // a green dark theme
  • 'redmond' // a light blue theme
  • 'start' // a dark blue theme
  • 'sunny' // a light yellow theme
  • 'darkness' // a dark black and gray theme ( basis for kdark )

You can set the theme by setting:

mw.setConfig('jQueryUISkin', 'kdark');

Set a custom jQuery UI Skin file

The html5 library also supports full override of the jQuery ui skin. This allows the most flexibility in customizing the css of the player. Note if you change the height of the player please update 'EmbedPlayer.ControlsHeight' to the custom height ( by default its set to 31 pixels )

mw.setConfig('IframeCustomjQueryUISkinCss', true);

Loading Custom player CSS

NOTE as of 1.6.1 this feature has been superseded by the External Resources plugin

Loading the player in an iframe is a double edge sword, in that it protects your site from conflicting with the css of the player, while simultaneously making it difficult to do player style customizations. To provide some basic css customization support the library lets you load your own css file to come after all the player css. You should base your theme customization on jquery.ui theme conventions, and you may need to override some properties with !important in cases where they are preset via the base jQuery ui. To override css simply set HTML5PlayerCssUrl to the url hosting your css in KMC player studio under "additional parameters and plugins"

<script type="text/javascript">
// hard code the addition of some css files.
// this can be moved to the player studio once ready for production.
	'src' : 'http://mysite.com/custom.css'
mw.setConfig('jQueryUISkin', 'redmond');

Using OnPrem or Community edition for your Kaltura provider

NOTE: its recommended that onPrem customers host their own copy of the HTML5 library 

If your self hosting your own Kaltura platform, you need to tell the html5 library where to go to find the Kaltura service. ( This can't always be derived from the swf player url ). To use the html5 library with your onPrem or community edition simply set:

<script type="text/javascript">
        'Kaltura.ServiceUrl' : 'http://your.kaltura.install.domain.or.cdn.com',
        // Path to Kaltura service base usually /api_v3/index.php?service=
        'Kaltura.ServiceBase' : '/api_v3/index.php?service=',
	// Path that hosts your assets ( in late versions of onPrem, mediafiles 
        // are served via playManifest rather than directly pointing to the cdn, 
        // but the cdn url is still used for thumbnails )
        'Kaltura.CdnUrl' : 'http://kalty.cdn.sfr-sh.fr'