The first step to integrating the Vividas Player into a web site is to download the Vividas Player SDK. This can be found at the following location.

After downloading, extract the files using your favourite archive program to a convienient location and continue to the next sections.

	<!-- start player javascript support files -->
	<script type="text/javascript" src="scripts/core/api.js"></script> 
	<script type="text/javascript" src="scripts/core/java.js"></script>
	<!-- end player javascript support files --> 

	<!-- start player object tag -->
	<script type="text/javascript">startPlayerObjectTag("vivPlayer", 704, 430);</script>
		<param name="sdkVersion" value="current"/>
		<param name="backgroundImage" value="images/screen_bg_click.jpeg"/>
		<param name="mediaURL" value="http://www.crash-test-department.com/sdkmedia/3001_Widescreen_Ultra_915.viv"/>
		<div class="noplugin"><p><a href="http://player.vividas.com/download.php?noplugin=true">Click to install</a>&nbsp;</p></div>
	</object>
	<!-- end player object tag -->

	Note
	Change the mediaURL value to contain the URL of your media file.

	Note
	The Vividas Player can be configured to automatically commence playback when the web page is loaded. This is enabled by adding the following parameter (<param>) to the object tag.

	<param name="autoplay" value="true"/>

If you intend to deploy using the SIMPLIFIED method;

	<!-- start player object tag -->
	<object id="vivPlayer" 
			type="application/x-vividas-player;version=4.0" 
			codebase="http://player.vividas.com/download.php#Version=4,0,0,0"
			width="704" 
			height="430">
		<param name="sdkVersion" value="current"/>
		<param name="backgroundImage" value="http://update.vividas.com/sdk/images/screen_bg_click.jpeg"/>
		<param name="mediaURL" value="http://www.crash-test-department.com/sdkmedia/3001_Widescreen_Ultra_915.viv"/>
		<param name="playerEvents" value="false"/>
		<div class="noplugin"><p><a href="http://player.vividas.com/download.php?noplugin=true">Click to install</a>&nbsp;</p></div>
	</object>
	<!-- end player object tag -->	

	Note
	To further customise the player see the Customising the Vividas Player section of this document.

	Note
	The Vividas Player can be configured to automatically commence playback when the web page is loaded. This is enabled by adding the following <param> to the object tag.

	<param name="autoplay" value="true"/>

A standard HTML <object> tag is used to embed the Vividas Player onto a web page. The opening HTML element for the <object> tag is created dynamically by the startPlayerObjectTag(id,width,height,localApplet) javascript function.

The default behaviour of the startPlayerObjectTag function is to write the <object> tag for the installed Vividas Player plugin. However, if the browser is Internet Explorer on Windows and the player plugin is not installed, the startPlayerObjectTag function will write the <object> tag for the Vividas Player Java applet. This allows the Vividas Player to play video without requiring plugin installation for users of Internet Explorer on Windows.

The original HTML is as follows;

	<!-- start player object tag -->
	<script type="text/javascript">startPlayerObjectTag("vivPlayer", 704, 430);</script>
		<param name="sdkVersion" value="current"/>
		<param name="backgroundImage" value="images/screen_bg_click.jpeg"/>
		<param name="mediaURL" value="http://www.crash-test-department.com/sdkmedia/3001_Widescreen_Ultra_915.viv"/>
		<div class="noplugin"><p><a href="http://player.vividas.com/download.php?noplugin=true">Click to install</a>&nbsp;</p></div>
	</object>
	<!-- end player object tag -->

If the user has installed the Vividas Player then on Windows (IE8) it results in the following object tag being written.

<!-- start player object tag -->
<script type="text/javascript">startPlayerObjectTag("vivPlayer", 704, 430);</script>
<object id="vivPlayer" name="vivPlayer" codeBase="http://player.vividas.com/download.php#Version=4,0,0,0" width="704" height="430" type="application/x-vividas-player;version=4.0">
	<param name="sdkVersion" value="current" />
	<param name="backgroundImage" value="images/screen_bg_click.jpeg" />
	<param name="mediaURL" value="http://www.crash-test-department.com/sdkmedia/3001_Widescreen_Ultra_915.viv" />
</object>
<!-- end player object tag -->

If the user has not installed the Vividas Player then for IE8 it inserts the following code.

	Note
	This version of the <object> tag is only written if Java is detected in the browser.

<!-- start player object tag -->
<script type="text/javascript">startPlayerObjectTag("vivPlayer", 704, 430);</script>
<object id="vivPlayer" name="vivPlayer" width="704" height="430" type="application/x-java-applet">
	<param name="code" value="PlayerApplet.class" />
	<param name="archive" value="http://player.vividas.com/download.php?java=true&version=4.0.0.0" />
	<param name="MAYSCRIPT" value="true" />
	<param name="java_arguments" value="-Dsun.java2d.d3d=false" />
	<param name="userAgentJava" value="Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; .NET4.0E)" />
	<param name="sdkVersion" value="current" />
	<param name="backgroundImage" value="images/screen_bg_click.jpeg" />
	<param name="mediaURL" value="http://www.crash-test-department.com/sdkmedia/3001_Widescreen_Ultra_915.viv" />
</object>
<!-- end player object tag -->

The startPlayerObjectTag function contains a number of parameters to initialise the player object:

The following code is the <object> tag declaration from the index_simplified.html sample web page.

	<!-- start player object tag -->
	<object id="vivPlayer" 
			type="application/x-vividas-player;version=4.0" 
			codebase="http://player.vividas.com/download.php#Version=4,0,0,0"
			width="704" 
			height="430">
		<param name="sdkVersion" value="current"/>
		<param name="backgroundImage" value="images/screen_bg_click.jpeg"/>
		<param name="mediaURL" value="http://www.crash-test-department.com/sdkmedia/3001_Widescreen_Ultra_915.viv"/>
		<param name="playerEvents" value="false"/>
		<div class="noplugin"><p><a href="http://player.vividas.com/download.php?noplugin=true">Click to install</a>&nbsp;</p></div>
	</object>
	<!-- end player object tag -->

The tag contains a number of attributes to initialise the player object:

If the player events are required using the SIMPLIFIED deployment method, then the scripts/core/api.js script (see this section for downloading) must be included in the header of the web page. The <param> playerEvents will need to be modified as follows to enable player events;

<param name="playerEvents" value="true"/> 

The Vividas Player controls can be either within the player window controlled via a "skin" or alternatively they can be placed within javascript and controlled from the browser via javascript.

By default the Vividas Player has a skin enabled. This is the prefered method of controlling the Vividas Player. Alternatively, if the control is preferred via javascript, the javascript object methods playClip() and terminate() can be used to start and stop playback respectively. The Initialisation Property "skin" should be set to "none" and the following code copied into an appropriate place on your web page.

<a href = "javascript:document.getElementById('vivPlayer').playClip();">Play</a> 
<a href = "javascript:document.getElementById('vivPlayer').terminate();">Stop</a>

	Note
	The 'vivplayer' element ID refers to the default object which is the Vividas Player. If there is more than one Vividas Player in the web page, then the object id will require changing, along with any javascript references to that object.

The player can be configured via javascript calls, or via additional <param> tags inserted into the HTML code to embed the Vividas Player. The Vividas Player's Initialisation Properties and Loaded and Running Properties can be set using a <param> tag within the <object> tag.

Some of the player properties are defined as Initialisation Properties and can only be set using <param> tags in the HTML. This is because the player uses the param object properties whilst initialising. Two notable params tags include the splash screen and background image.

The complete list of player properties is given in the Player Properties section of this guide.

The Vividas Player <param> values can contain a custom option to modify the param's value.

If ',url' (note the comma) is appended to the parameter's name, the parameter's value will have the current page's base path prepended to it.

For example, the following code will allow the player to load a file for the 'endRedirectURL' parameter from a location relative to the web page.

<param name="endRedirectURL,url" value="redirect.html"/> 

If ',preload' is appended to a parameter name, the file described by the parameter's value is downloaded and cached on the user's system during the player initialisation stage. ',preload' automatically implies ',url' and will automatically convert a relative URL to an absolute URL, if required.

For example, the following code will preload and cache a file for the 'skin' parameter, so that it can be reused by the player without additional downloads.

<param name="skin,preload" value="customskin.jpeg"/> 

The Vividas Player <object> tag is written in part by the javascript function startPlayerObjectTag . Part of what is written is the 'codebase' parameter that instructs the browser to install the plugin from a player.vividas.com URL. The player.vividas.com webserver responds with a platform and browser specific plugin installation package (eg .xpi for Firefox, .dmg for Safari on Mac) to allow the browser to install and/or run the Vividas Player.

	Note
	The player.vividas.com and update.vividas.com domain names MUST resolve to a valid IP address and be reachable from the deployed network for the Vividas Player to operate correctly.

If plugin installation is blocked in the browser a standalone installer is available (.exe on Windows, .dmg on MacOS). The standalone installer can be downloaded from http://player.vividas.com/download.php?installer=true. The web browser will require restarting to complete standalone installation.

	Note
	The download of the Vividas Player installer intelligently selects which package to download, depending on the browser and operating system that downloads it. If redistributing this package across multiple workstations, then the correct package should be selected and downloaded for the particular workstation. Contact Vividas if further help is required.

For the web browser to install the Vividas Player plugin, they require installation (administrator) privileges. If installation privileges are not available, the user's system administrator can deploy the Vividas Player plugin using the standalone installer.

Plugin installation is a once only process. After installation, the player automatically downloads updates from update.vividas.com. To request a specific player version update for use in a web page, the sdkVersion <param> tag can be used to lock the player version.

To lock the Vividas Player version to a particular version of the SDK, replace the sdkVersion <param> tag with the following. Be sure to alter the value to the version number required.

<param name="sdkVersion" value="4.0.5"/> 

The Vividas Player will resize to almost any space that is allocated to it on a web page. To fit the allocated size, the Vividas Player allocates a fixed size for the "skin" (if displayed) and resizes the video to maintain aspect ratio. The height for the default "skin" is 30 pixels.

To maintain aspect ratio the Vividas Player adds black bars or "dead space" either to the sides or to the top and bottom of the media. These are generally not desirable as they are poor usage of screen real estate.

To prevent black bars from being displayed, the optimal player dimensions should be calculated. The optimal player dimensions are the native size of the footage plus the size required for any skin (if displayed). This will provide the optimal player dimensions.

The quickest way of obtaining the native player size is to enter the following javascript code into URL bar of a browsers window and press enter, while the required media is playing. It will display an alert with the native width and height of the media.

javascript:alert("w: "+getPlayerObject().getProperty("frameWidth")+"h: "+getPlayerObject().getProperty("frameHeight"));

Alternatively to get the native size of the footage from a web page can be achieved by creating a test page with the Vividas Player and adding the following code to the <BODY> section.

<h2><a href="javascript:NativeDimensions();">Get Native Video dimensions</a></h2>

Next, add the following code to the <HEAD> section of the web page. Be sure to change the MediaURL to the media you are putting into your page and make sure the player is playing prior to clicking the link.

<script type="text/javascript">
	<!--
	function NativeDimensions()
	{
		var text = 'The native dimensions are width:' + 
			 getPlayerObject("vivPlayer").getPropertyInt("frameWidth") + 
			 ' height:' + 
			 getPlayerObject("vivPlayer").getPropertyInt("frameHeight") ;
		alert(text) ;
	}
	-->
</script>

To learn more about the Vividas Player and its capabilities see the Further Information about the Vividas Player section of this document.

The Vividas Player has 5 distinct states when present on a web page. These are as follows;

	Note
	VivRights is another Vividas Product. It provides conditional viewing of .viv files, by requiring that the Vividas Player to obtain permission to decode a piece of media. Please contact Vividas for more information on this product.

	Important
	The following section is written for web developers, and it is assumed that the reader has a reasonable knowledge of HTML, Document Object Models (DOMs) and javascript.

The Vividas Player is a well featured video player that has two levels of interfaces to configure and control the player.

5.2.1. Simple Playback Control using api.js

The 'scripts/core/api.js' support file included with the Player SDK contains convenient functions for starting playback and controlling the player. The sample host page tests/index_tests.html provides examples for using the functions in api.js. The first step is to include the api.js file. This is done as follows;

<script type="text/javascript" src="scripts/core/api.js"></script>

The functions are used to control a single player object on the host page that has the id 'vivPlayer'

Once playback has commenced, the following methods are available for controlling playback

Function	Description
playPressed()	Start playing media.
stopPressed()	Stop the player
pausePressed()	Pause playback
resumePressed()	Resume playback
seekForward(milliseconds)	Skip forward by the offset in milliseconds
volumeIncreasePressed()	Increase the volume by 10%
volumeDecreasePressed()	Decrease the volume by 10%
fullscreenPressed()	Toggle the player between windowed and fullscreen playback

	Note
	This method and direct calls to the Vividas Player described in the section Vividas Player Javascript API are not mutually exclusive and can be combined on the same web page.

	Note
	This section is to be read in conjunction with the playlist documentation if you are planning on using playlist files. To read the playlist documentation, either read the file doc/sdk_playlist_guide.html from the Vividas Player SDK, or to view online, follow this link sdk_playlist_guide.html.

The Vividas Player object plays media streams in '.viv' format. The player accepts single media files, or multiple media files in a playlist. The media types and the properties used to configure the media are:

The Vividas Player component can generate events when initialisating and playing that are sent to predefined javascript methods within the host page. A default implementation is included for convienience in scripts/core/api.js, and can be included if needed. If the javascript methods do not exist, a javascript runtime error is likely to be generated. Vividas Player events are enabled by default and can be disabled by setting the 'playerEvents' parameter to 'false' in the player object parameters.

Events include the HTML 'id' of the player object as a parameter, to handle events from multiple players.

	Note
	Example implementations of these event handler functions are included in the 'scripts/optional/tests.js' source file.

For details of specific events see section Player Events

To be able to interface with the player or instruct it to perform a command, firstly its javascript object has to be retrieved from the HTML Document Object Model (DOM). This is achieved as follows;

<script type="text/javascript"> 
	var playerObject = document.getElementById('vivPlayer');
</script>

The player object's properties are then configured, and playback started using setProperty() and doCommand(). A property configured using setProperty() overrides the value set in the player's object <param> tags. For example:

function play() {
	var playerObject = document.getElementById('vivPlayer');
	playerObject.setProperty("mediaURL","http://video.vividas.com/content.viv");
	playerObject.setProperty("fullscreen", true);
	playerObject.doCommand("playClip"); // or playerObject.playClip();
	}

The player can be controlled during playback using doCommand(). Many commands include a player object helper method (eg pause)

function pause() {
	var playerObject = document.getElementById('vivPlayer');
	playerObject.doCommand("pause"); // or playerObject.pause();
	}

The player can be queried during playback for media properties or playback status using getProperty().

function getFrameRate() {
	var playerObject = document.getElementById('vivPlayer');
	return playerObject.getProperty("frameRate");
	}

The helper methods expose simple method names for common player commands.

The basic methods set and get player properties, and perform player commands. See Player Properties and Player Commands for a list of available names used by these methods.

The inialisation methods are used during player installation and upgrade, and enable monitoring of the player.

The following properties can only be set via the player object HTML <param> parameters

These properties configure the Vividas Player after it is loaded and prior to playing. All the writeable parameters can be set at run time, however only a few will be recognised by the player while playing. These parameter types are denoted as "cached". If the parameters are written to when the player is playing, then they are cached until the next time the player is restarted or the media changes in a playlist. If a parameter is read, then the last written parameter is returned.

The following properties can only be set or retrieved by the player object's setProperty() and getProperty() methods when the player is starting or playing a video. If the player is stopped, the properties return 'undefined'. Properties pertaining to playlists have been separated below.

Playing properties pertaining to playlists and playlist functionality.