KVS Documentation

KVS Flash / HTML5 Video Player v5.x

Contents

1. General info

Kernel Team Video Player is developed for extensive monetization of your online websites. Player supports huge amount of advertising in different places and on different events, such as pre-roll, post-roll ads, advertising on pause / stop, advertising in controlbar and JavaScript API for HTML-based advertising.

Player works in two modes: local mode and "embed" mode. Local mode is the default mode when you use player on your own website. Embed mode is enabled when your player is being used from third-party websites using embed code. In this mode there is no ability for your so-called embedders to disable or change your advertising. So when somebody uses embed codes on your videos - your advertising will be always displayed as configured. Moreover you have the only place to control player behavior in embed mode, so if you change anything in your embed configuration, this change will be automatically propagated to all third-party websites that are referring to your embed code.

Kernel Team Video Player can be used for free without any limitations.

2. Installation

Consider the following steps to install Kernel Team Video Player:

  • Unpack archive into /%DOMAIN_ROOT%/kt_player folder. If you want to install player into a different folder, make sure you update player .htaccess file with your new value.
  • In /%DOMAIN_ROOT%/kt_player/.htaccess file change %DOMAIN% token with your domain name.
  • Copy crossdomain.xml file into your domain root folder. If you are going to use images or videos from other domains (and subdomains), you should copy this file to every such domain (subdomain).

Important! Any SWF files, which are used via player API should be implemented using ActionScript3.

3. Including player into your HTML code

Player can be embeded into your HTML page using kt_player.js script. Here is code example (assuming that you copied player files into /kt_player folder):

<!-- include JavaScript -->
<script type="text/javascript" src="/kt_player/kt_player.js"></script>

<!-- define hidden container for player, id="kt_player" identifies it -->
<div id="kt_player" style="visibility: hidden">
    <a href="http://adobe.com/go/getflashplayer">This page requires Adobe Flash Player</a>
</div>

<!-- use player insertion code -->
<script type="text/javascript">
    // configure initialization variables (we used only 2 for simplicity)
    var flashvars = {
        video_url: 'http://domain.com/kt_player/demo/demo_video.mp4',
        preview_url: 'http://domain.com/kt_player/demo/demo_preview.jpg'
    };

    // configure HTML object parameters
    var params = {allowfullscreen: 'true', allowscriptaccess: 'always'};

    // call player javascript
    // 'kt_player' - player container identifier
    // '/kt_player/kt_player.swf' - player file URL
    // '600' - player width
    // '400' - player height
    // flashvars - the list of all initialization variables created above
    // params - the list of all HTML object parameters created above
    var player_obj = kt_player('kt_player', '/kt_player/kt_player.swf', '600', '400', flashvars, params);

    // use player_obj to configure events handling (see JavaScript API section)
</script>

After the page display DIV container with id="kt_player" will contain player. In most cases you will only need to change initialization variables (flashvars object) and player size (600х400).

4. Flash vs HTML5 mode

Kernel Team Video Player supports basic HTML5 mode to make sure that your videos can be played by mobile devices. Player uses the following approach to define which mode should be used for the current browser:

Mode Description Conditions
Flash Default. Works for most desktop devices. Browser supports Flash.
HTML5 video Browser bundled player with only JavaScript advertising support (using player JS API). Works for most of mobile devices. (a) Browser doesn't support Flash.
(b) Video is encoded in MP4 format (h264 codec).
(c) Browser supports playing MP4 format.
Native video Plain link to MP4 file. Works for most of mobile devices. (a) Browser doesn't support Flash.
(b) Video is encoded in MP4 format.
(c) Browser doesn't support playing MP4 format.

Important! HTML5 / Native modes will be used only with MP4 files. All modern mobile devices do support MP4 format.

5. Player initialization variables

Player initialization variables (FlashVars) can be used to specify player behavior and advertising. The table below lists all supported variables:

Variable name Description
scaling You can use this variable to specify non-default scaling algorithm. By default player will keep video aspect ratio, which produces black areas either horizontally or vertically. If you specify fill value for this parameter - video will be stretched into the whole player area ignoring aspect ratio. If you want your video to keep aspect ratio while occupying the whole player area you can specify crop value for this variable: in this case video will be cropped either horizontally (from left and right) or vertically (from top and bottom).
license_code License code (optional).
video_url FLV / MP4 video file URL.
preview_frame Video frame (in seconds) which will be displayed before video playback is started.
preview_url Preview image URL which will be displayed before video playback is started.
flv_stream Should be set to false if web server does not support streaming.
autoplay If this variable is set to true - video playback will be started automatically after player initialization.
logo_src Custom logo URL (jpg, png) which will be displayed on top of video.
logo_position Custom logo position (should be specified in square brackets like [x,y]). Related to top-left player corner.
logo_url Logo click URL.
video_click_url Video playback area click URL. If not specified (by default) video playback will be paused as clicked on playback area.
bt Video buffer time in seconds (the default is 5 seconds).
skin Supports 2 skins: 1 - black (default), 2 - white.
hide_controlbar Configures controlbar behavior: 0 - display always (by default), 1 - hide automatically if user is not active, 2 - never display controlbar.
mlogo Text string to be displayed on controlbar.
mlogo_link Controlbar text click URL (for text specified with mlogo variable).
embed Enables embed code display inside the player if specified as 1. Embed code is not displayed by default. The HTML code to display should be provided using JavaScript API (described later).
permalink_url URL to your website where this video is displayed. If specified, player will display small icon which allows copy this URL.
urls_in_same_window The global variable to force all clicks from within the player to be opened in the same browser window. Specify 1 in order to enable it. By default all clicks will be opened in separate windows.
prtext Can be used to periodically display small portions of text in random player corners. You can use this feature to protect your content from display grabbers (for example display user's IP).
prtime Interval in seconds to display text configured in prtext variable.
related Related plugin URL to display related videos after playback is finished. We provide related.swf plugin and its source code in related.fla.
related_data Related plugin configuration XML file URL. The file lists related videos in the predefined format. The example of such file is provided as related.xml.
timeline_screens_url Timeline screenshots configuration XML file URL. The file lists timeline screenshots. The example of such file is provided as key.xml.
timeline_screens_interval Interval to display timeline screenshots (in seconds).
video_url_text Main video stream title. It will be displayed only if video_alt_url variable is specified (see below).
video_alt_url
video_alt_url_text
video_alt_url_redirect
This set of variables can be used to enable the dropdown list of different video streams (for example, 480p, 720p HD). If video_alt_url variable is specified, player will display dropdown list with 2 elements in controlbar: (1) the first element plays video stream specified by video_url variable and is rendered with title specified in video_url_text variable; (2) the second element is rendered with title specified in video_alt_url_text variable and either plays video stream configured in video_alt_url variable, or redirects user to the URL configured in video_alt_url variable if video_alt_url_redirect is set to 1. The example will be described later.
video_alt_url2
video_alt_url2_text
video_alt_url2_redirect
Can be used in the same way as previous variable set in order to display additional dropdown list item.
video_alt_url3
video_alt_url3_text
video_alt_url3_redirect
Can be used in the same way as previous variable set in order to display additional dropdown list item.
video_alt_url4
video_alt_url4_text
video_alt_url4_redirect
Can be used in the same way as previous variable set in order to display additional dropdown list item.
adv_pre_src Pre-roll advertising URL (video - flv, swf, or image - jpg, png). Pre-roll advertising is displayed before video playback is started.
adv_pre_duration Pre-roll advertising duration in seconds (applicable for images).
adv_pre_url Pre-roll advertising click URL.
adv_post_src Post-roll advertising URL (video - flv, swf, or image - jpg, png). Post-roll advertising is displayed after video playback is finished.
adv_post_duration Post-roll advertising duration in seconds (applicable for images).
adv_post_url Post-roll advertising click URL.
adv_pause_src Advertising-on-pause URL (image - jpg, png). Advertising-on-pause is displayed if user pauses video playback.
adv_pause_url Advertising-on-pause click URL.
adv_stop_src Advertising-on-stop URL (image - jpg, png). Advertising-on-stop is displayed if user stops video playback.
adv_stop_url Advertising-on-stop click URL.
sec Provides ability to limit video playback duration. If this variable is used user will be able to see only first N seconds, which is specified by this variable. Important! This variable works correctly only without streaming support (see flv_stream variable).

Lets look into the small example of alternative video streams configuration. Suppose we need to display the following items in dropdown list:

  • 360p - displays video stream with 360 pixel height.
  • 480p - displays video stream with 480 pixel height.
  • 720p HD - redirects user to signup / payment page, as HD video is only available for premium members.

Initialization variables for this usecase are the following:

  • video_url = http://domain.com/videos/my_video_360.mp4 (will be initially selected and played)
  • video_url_text = 360p
  • video_alt_url = http://domain.com/videos/my_video_480.mp4 (will be played if users switches to this item)
  • video_alt_url_text = 480p
  • video_alt_url2 = http://domain.com/signup.php (will be redirected to this URL if users switches to this item)
  • video_alt_url2_text = 720p HD
  • video_alt_url2_redirect = 1

Important! Player can use files (images / video) from third-party domains and sub-domains only if their document root contains crossdomain.xml security policy file. This file is bundled with player installation archive and should be copied to any domains and sub-domains which content you will be using.

Player configuration in "embed" mode is being provided by embed.xml file located in the same folder as player.

6. JavaScript API

JavaScript API can be used to pass embed code which will be displayed inside player (if embed initialization variable is set to 1). In order to specify embed code you should define the following JavaScript function:

function getEmbed() {
    return '%EMBED_CODE_GOES_HERE%';
}

In this function you should replace %EMBED_CODE_GOES_HERE% with embed code you want to be used. There can be several embed code concepts:

  • Classic embed code is supported only by Flash and does not provide ability to use JavaScript API: <object id="kt_player" name="kt_player" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,0,0" width="600" height="400">
        <param name="allowscriptaccess" value="always"/>
        <param name="allowFullScreen" value="true"/>
        <param name="movie" value="http://%YOUR_DOMAIN_HERE%/kt_player/kt_player.swf"/>
        <param name="flashvars" value="video_url=%VIDEO_URL%&amp;preview_url=%PREVIEW_IMAGE_URL%"/>
        <embed src="http://%YOUR_DOMAIN_HERE%/kt_player/kt_player.swf?video_url=%VIDEO_URL%&amp;preview_url=%PREVIEW_IMAGE_URL%" width="600" height="400" allowfullscreen="true" allowscriptaccess="always" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer"/>
    </object>
  • Iframe embed code is an iframe element, which refers to a video player page on your site. Iframe embed code will work in all modes and also fully supports JavaScript API. Using this type of embed code assumes that your site has functionality, which can display player based on the video ID passed. <iframe width="600" height="400" src="http://%YOUR_DOMAIN_HERE%/embed/%VIDEO_ID%" frameborder="0" allowfullscreen webkitallowfullscreen mozallowfullscreen oallowfullscreen msallowfullscreen></iframe>

Important! If you don't declare getEmbed() function or don't return any value from it, player will generate embed code automatically based on initialization variables passed to it. In this case embed code will have the same size as configured at the current page. You can use getEmbed() function in order to give users embed code with another data (another size for example).

Kernel Team Player also supports many JavaScript callbacks. You can use them as you need:

var player_obj = kt_player('kt_player', '/kt_player/kt_player.swf', '600', '400', flashvars, params);
player_obj.listen('ktVideoStarted', function() {alert('Video started');});
player_obj.listen('ktVideoPaused', function() {alert('Video paused');});
player_obj.listen('ktVideoStopped', function() {alert('Video stopped');});
player_obj.listen('ktVideoScrolled', function(time) {alert('Video scrolled to ' + time + ' seconds');});
player_obj.listen('ktVideoProgress', function(time) {alert('Video played to ' + time + ' seconds');});
player_obj.listen('ktVideoFinished', function() {alert('Video finished');});
player_obj.listen('ktFullScreenActivated', function() {alert('Player goes to full screen mode');});
player_obj.listen('ktFullScreenDeactivated', function() {alert('Player goes to normal mode');});
player_obj.listen('ktPreRollStarted', function() {alert('Configured pre-roll ad started');});
player_obj.listen('ktPreRollFinished', function() {alert('Configured pre-roll ad finished');});
player_obj.listen('ktPostRollStarted', function() {alert('Configured post-roll ad started');});
player_obj.listen('ktPostRollFinished', function() {alert('Configured post-roll ad finished');});

player_obj.listen('ktVideoFormatChanging', function(format) {
    alert('Video format is attempted to be changed to: ' + format);
    // this can be used to show user HTML content on video format change
    // return 'true' (as string) if you want player to cancel default behavior
});

If you need to initialize events handling from the outside code, you can define kt_player_loaded function, which will be called after player initialization:

function kt_player_loaded(player_obj) {
    // configure events handling
    player_obj.listen(...);
}

When initialized, player will change its DIV-container styles so that it is possible to easily display HTML layers above player (e.g. ads, floating banners, additional menus):

container styles {
    width: 600px;
    height: 400px;
    position: relative;
    overflow: hidden;
}

Additional player control API:

// get player DIV-container
player_obj.container();

// start playback
player_obj.play();

// pause playback
player_obj.pause();

7. Player files list

Here is the list of all files bundled with player and their description:

Filename Description
.htaccess Contains redirection rules, which switch player into "embed" mode for all requests from third-party domains.
btn_play.jpg Main play button which is displayed in HTML5 mode on top of player.
embed.php PHP code used to enable "embed" mode for third-party domains. Works together with .htaccess.
embed.xml "Embed" mode configuration. Modify this file to configure your player behavior in "embed" mode.
example.html Player usage example.
expressInstall.swf Flash update component from Adobe.
kt_player.js JavaScript to embed player into HTML.
kt_player.swf Player itself.
demo/crossdomain.xml This file should be copied into document root of all domains (and sub-domains) which store any data used by player.
demo/key.xml Timeline screenshots configuration example. This file should be used for timeline_screens_url initialization variable.
demo/keyX.jpg Example timeline screenshots.
demo/related.fla Source code / template for related plugin.
demo/related.swf Demo related plugin. This file should be used for related initialization variable.