Kaltura HTML5 Configuration

From HTML5 Video
Jump to: navigation, search


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

Contents

Getting additional HTML5 Library Support

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

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

If you are 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://cdnapi.kaltura.com/p/{partnerId}/sp/{partnerId}00/embedIframeJs/uiconf_id/{uiConfId}/partner_id/{partnerId} is the version of the library that kaltura.com SaaS offering points to. This is the url you will get from the KMC, when enable html5 on preview and embed. If your a kaltura customer you should use this url. You can control what version of the html5 library it points to via uiConf
  • https version of the production url looks like this: https://www.kaltura.com/p/{partnerId}/sp/{partnerId}00/embedIframeJs/uiconf_id/{uiConfId}/partner_id/{partnerId}
  • http://player.kaltura.com/mwEmbedLoader.php is a community version of the html5 library; it should not be used if your a customer of kaltura.
  • 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://player.kaltura.com/mwEmbedLoader.php" type="text/javascript">
<script type="text/javascript">
              // mw.setConfig calls go here
</script>
<!-- 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 ( service = "adminUser", action="login" )
  2. Select the uiConf service and then "update"
  3. Enter the uiconf id of the player you wish to update.
  4. Then set uiConf:html5Url (string): to the version you want i.e: /html5/html5lib/v1.7.0.4/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:

Player Studio: key: EmbedPlayer.EnableIpadHTMLControls
value: false
Inline JavaScript: mw.setConfig('EmbedPlayer.EnableIpadHTMLControls', false);
UiConf XML: <var key="EmbedPlayer.EnableIpadHTMLControls" value="false"/>
 

Hybrid HTML controls, native fullscreen mode on iPad

If you would like html controls but native fullscreen ( no address bar at the top of the screen ) you can set the following option:

Player Studio: key: EmbedPlayer.EnableIpadNativeFullscreen
value: true
Inline JavaScript: mw.setConfig('EmbedPlayer.EnableIpadNativeFullscreen', true);
UiConf XML: <var key="EmbedPlayer.EnableIpadNativeFullscreen" value="true"/>
 

This will native fullscreen, while retaining html controls while in player. Note you can't enter fullscreen until you start playback.

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.

Player Studio: key: Kaltura.LeadWithHTML5
value: true
Inline JavaScript: mw.setConfig('Kaltura.LeadWithHTML5', true);
UiConf XML: <var key="Kaltura.LeadWithHTML5" value="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:

Player Studio: key: EmbedPlayer.UseFlashOnAndroid
value: false
Inline JavaScript: mw.setConfig('EmbedPlayer.UseFlashOnAndroid', false);
UiConf XML: <var key="EmbedPlayer.UseFlashOnAndroid" value="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:

Player Studio: key: Kaltura.ForceFlashOnDesktop
value: true
Inline JavaScript: mw.setConfig('Kaltura.ForceFlashOnDesktop', true);
UiConf XML: <var key="Kaltura.ForceFlashOnDesktop" value="true"/>
 

Force flash for IE10

On Windows 8, Modern UI IE10, Flash is integrated, but would only load for domains listed on Microsoft's Compatibility View (CV) list, in the Flash section. As a result, we currently load our HTML5 player by default on Modern UI IE10 (On desktop IE10, our fallback mechanism is able to identify Flash support). To force Flash on Modern UI IE10, users can set:

Player Studio: key: Kaltura.ForceFlashOnIE10
value: true
Inline JavaScript: mw.setConfig('Kaltura.ForceFlashOnIE10', true);
UiConf XML: <var key="Kaltura.ForceFlashOnIE10" value="true"/>
 

For more information about IE10 and Kaltura see the Kaltura IE10 knowledge page

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. See example page. 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>
 
</div>
<script type="text/javascript">
	window['doPlayCallback'] = function( playerId ){
		console.log( 'kwidget doPlayCallback ' + playerId );
	};
	kWidget.embed({
		'targetId': 'myVideoTarget',
		'wid': '_243342',
		'uiconf_id' : '2877502',
		'entry_id' : '0_uka1msg4',
		'flashvars':{
			'externalInterfaceDisabled' : false,
			'autoPlay' : true
		},
		'readyCallback': function( playerId ){
			console.log( "kWidget player ready: " + playerId );
			var kdp = document.getElementById( playerId );
			kdp.addJsListener( 'doPlay', 'doPlayCallback');
		}
	});
</script>

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.12.40/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.

Player Studio: key: EmbedPlayer.WebKitPlaysInline
value: true
Inline JavaScript: mw.setConfig('EmbedPlayer.WebKitPlaysInline', true);
UiConf XML: <var key="EmbedPlayer.WebKitPlaysInline" value="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 )

Player Studio: key: EmbedPlayer.WebKitAllowAirplay
value: true
Inline JavaScript: mw.setConfig('EmbedPlayer.WebKitAllowAirplay', true);
UiConf XML: <var key="EmbedPlayer.WebKitAllowAirplay" 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:

Player Studio: key: EmbedPlayer.FullScreenZIndex
value: Number
Inline JavaScript: mw.setConfig('EmbedPlayer.FullScreenZIndex', Number);
UiConf XML: <var key="EmbedPlayer.FullScreenZIndex" value="Number"/>
 

Directly play m3u8 live stream sources

If you have a live stream such as from a Wowza server, you can directly embed it into the player, this is useful if your html5 player is only used for iOS, you can force a live stream url. All other metadata title etc will be pulled from your embed settings. For more detailed discussion see issue 160 thread.

mw.setConfig('EmbedPlayer.ReplaceSources',  [
	    {
	    	'type': 'application/vnd.apple.mpegurl',
	    	'src': 'http://path.to.livestream.com/playlist.m3u8'
	    }
]);
kWidget.embed({
		'targetId': 'myVideoTarget',
		'wid': '_243342',
		'uiconf_id' : '5677072',
		'entry_id' : '0_uka1msg4',
		'flashvars':{}
	});

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:

http://cdnbakmi.kaltura.com/p/243342/sp/24334200/playManifest/entryId/0_c0r624gh/flavorId/0_w3aolq8p/format/url/protocol/http/a.mp4

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

Select preferred bitrate for HLS and multi flavour HTML5

The html5 library supports the same flashvar as the flash player to select an initial stream. In the case of apple HLS, it will pass along a url parameter that will adjust the m3u8 output to preference the provided bitrate. In the case of multiple playable flavours for desktop html5, the preferred bitrate parameter will cause the player to select the flavour with the nearest bitrate

kWidget.embed({
		'targetId': 'myVideoTarget',
		'wid': '_243342',
		'uiconf_id' : '5677072',
		'entry_id' : '0_uka1msg4',
		'flashvars':{
			'mediaProxy.preferedFlavorBR': 2000 
		}
	});

would set the preferred bitrate to 2mbs

Midrolls fail / 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 and OSX Safari, fail to play video, while Chrome and Firefox work

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:

Player Studio: key: Kaltura.UseAppleAdaptive
value: false
Inline JavaScript: mw.setConfig('Kaltura.UseAppleAdaptive', false);
UiConf XML: <var key="Kaltura.UseAppleAdaptive" value="false"/>
 

Seeking is not very accurate on iOS

Seeking with HLS enabled is not very accurate on iOS, if your application requires accurate seeks its recommend that you disable apple adaptive:

Player Studio: key: Kaltura.UseAppleAdaptive
value: false
Inline JavaScript: mw.setConfig('Kaltura.UseAppleAdaptive', false);
UiConf XML: <var key="Kaltura.UseAppleAdaptive" value="false"/>
 

Enable HLS on Android

By default HLS is disabled on android because of many issues with android live streaming, such as browser crashes and aspect ratio issues. If you would like to force HLS usage on android where availabe you can set the following flag.

Player Studio: key: Kaltura.LeadHLSOnAndroid
value: true
Inline JavaScript: mw.setConfig('Kaltura.LeadHLSOnAndroid', true);
UiConf XML: <var key="Kaltura.LeadHLSOnAndroid" value="true"/>
 

This flag is available in HTML5 library version "v2.1.1.2" and above

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'

Latest version of jQuery supported? JavaScript conflicts?

Version 1.7 of the HTML5 library, has no client side jQuery inter-dependencies.

For 1.6.x versions of the html5 library we support up to jQuery from 1.7.2 down to jQuery 1.4.1

Player is not displayed and jQuery JavaScript conflicts?

Note this is deprecated in 1.7 version of the html5 library

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:

Player Studio: key: EmbedPlayer.EnableIframeApi
value: false
Inline JavaScript: mw.setConfig('EmbedPlayer.EnableIframeApi', false);
UiConf XML: <var key="EmbedPlayer.EnableIframeApi" value="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 behaviour 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.

Player Studio: key: LoadingSpinner.ImageUrl
value: {imageURL
Inline JavaScript: mw.setConfig('LoadingSpinner.ImageUrl', {imageURL);
UiConf XML: <var key="LoadingSpinner.ImageUrl" value="{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:

Player Studio: key: EmbedPlayer.AttributionButton
value: false
Inline JavaScript: mw.setConfig('EmbedPlayer.AttributionButton', false);
UiConf XML: <var key="EmbedPlayer.AttributionButton" value="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, or disabling browser ui to right click and save the video to disk.

Player Studio: key: EmbedPlayer.EnableRightClick
value: false
Inline JavaScript: mw.setConfig('EmbedPlayer.EnableRightClick', false);
UiConf XML: <var key="EmbedPlayer.EnableRightClick" value="false"/>
 

Remove options button

Note in version 1.7 the options menu is disabled by default and the share button will reflect the uiConf.

To remove the option button in 1.6.x version of the library:

Player Studio: key: EmbedPlayer.EnableOptionsMenu
value: false
Inline JavaScript: mw.setConfig('EmbedPlayer.EnableOptionsMenu', false);
UiConf XML: <var key="EmbedPlayer.EnableOptionsMenu" value="false"/>
 

Like all configuration you can also set this in the kaltura player studio under custom vars

Setting player "theme" from presets

Note jquery ui skin presets have been deprecated as of  version 1.7 

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', 'url of custom skin file' );

Loading Custom player CSS

NOTE as of 1.6.1 you should instead use 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.
mw.setConfig('Mw.CustomResourceIncludes',[
{
	'src' : 'http://mysite.com/custom.css'
}
]);
mw.setConfig('jQueryUISkin', 'redmond');
</script>

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">
    mw.setConfig({
        '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'
    });	
</script>