Projekktor.com Documentation

Javascript API Functions - [player.getCanPlayNatively(mediaTypes:Array):Boolean]

operator — Mon, 22 Apr 2013 14:30:10 +0200

Javascript API Functions

The documentation as listed below applies to Projekktor V0.7.17 or higher.

Instantiation

projekktor(identifier:String, config:Object, onReady:Function):Object

projekktor is the central function to create or select player instances.

creating instances

To instantiate a player use identifier to provide information which element(s) you want the player to sit on. identifier is identical to jQuery selectors.

E.g: projekktor('#player_one'); will apply to a media-tag with the id attribute player_one, projekktor('video')); will projekktorize all video elements on page and so on. Optionally you can provide a config object like this: projekktor('#player_one',{enableFlashFallback:false});

The “onReady” function will be triggered once the player has been initialized. The function gets the player Object as argument.

Chaining multiple selectors by separating them with a colon, like e.g. “video,audio” or “div.player,div.second” does not work with IE6,7,8. Single selectors like “audio” or “video” work fine.

getting instances

To get an instance previously set up as described above you can simply use projekktor(); again. This time identifier is a jQuery object or the id of the player you want to fetch. E.g: projekktor('player_a').setStop(); or projekktor($('#player_a')).setStop();

To get all available instances, use “*” as identifier. In return you will get an array of Projekktor instances.

If you are planing to use the JS API to manipulate the players, you should set the id attribute for each media element to make your live easier. If no id attribute is set, a 8-string-random id will be applied. This makes it practically impossible to identify a specific player instance during runtime. Anyhow you can of course use projekktor('*'); to grab all available instances and iterate through them.

Setters

All setters return this in order to allow method cascading.

player.addListener(event:String, callback:Object):Void

Adds a function as callback listener for the event specified. Can be applied at any time.

player.removeListener(event:String, callback:Object):Boolean

Removes a previously added function from event listening. callback must be the same entity as used in corresponding addListener call. E.g:

WIN:

var ApiTest =  function(data) {console.log(data)};
playerInstance.addListener('*',ApiTest );
playerInstance.removeListener('*',ApiTest );

FAIL:

playerInstance.addListener('*',function(data) {console.log(data)});
playerInstance.removeListener('*',function(data) {console.log(data)});

Returns TRUE on success otherwise FALSE.

player.setFile(data:Mixed, type:String):Void

Applies a single media item or a playlist. This will overwrite all current media and playlist data scheduled within in the player.

data - Can either be an URL or a valid playlist OBJECT. If data is an URL and type is not a valid data exchange format (xml, json or jsonp), the URL is interpreted as URL pointing to a single audio- or video-file.

player.setItem(data:Mixed, index:Number, replace:Boolean):Void

Sets, adds, removes or replaces a playlist item.

Data can be an object following the projekktor item scheme, an URL string pointing to a valid media file or NULL. If data is NULL the item at index will be removed from schedule (remove). If data is an Object and or an URL and index is NULL a new item will be injected to schedule (add). index indicates the schedule index to be affected.

add

If index is out of range (less 1 or higher than the total length of the current schedule) a new item will be appended to the schedule otherwise a new item will be created on position provided.

If replace is true and an item already exists at index the new item will not be injected but will replace the already existing one - if any.

If calling this function affects the item currently playing back, the player will instantly stop and restart playback with the new data made available and without changing the “currentItem” pointer.

If setItem affects items after the currently playing one (items of an higher index than currentItem) no restart apply.

remove

If index is out of range (less 1 or higher than the total length of the current schedule) the last scheduled item will be removed. Otherwise the item at the index provided gets dumped.

replace has no effect while performing remove actions.

If calling this function affects the item currently playing back, the player will instantly stop and will move the currentItem pointer to the previous one.

If setItem affects an item after the currently playing one (items of an higher index than currentItem) no previous-action will happen.

player.setConfig(data:Object, destIndex:Mixed):Void

Was “setItemConfig” prior V0.9.0.

Allows to set or alter item config options during runtime. data must be an object containing one or more config parameters. Not all config options are available to be set dynamically to avoid the player to crash or react in a strange way (please refer: Configuration parameters).

destIndex can either be an integer describing the destination item´s position within schedule (itemIdx) or '*' which will apply data to all items currently scheduled. If destIndex is NULL the currently played item is manipulated.

Changes on current items only take immediate effect if the player state is IDLE.

player.setPlayerPoster(url:String):Void

Sets the poster for the player. This poster is shown up once the player has been instantiated, autoplay is FALSE and the user did not hit play so far.

This method is a shortcut for setItemConfig({poster:url},0);

player.setPlayhead(position:mixed):Void (> V0.7.16)

Move the play-head to the given position.

Position can be either in seconds (number) representing the absolute second to move the playhead to or a relative value prefixed with operators ”+” or ”-” indicating the direction to move the playhead to.

E.g. assumed the playhead is on second #15, ”+5” will move it to second #20 while ”-5” will move it to #10.

If the resulting position is beyond the point of loaded media data so far and the current media type does not allow random-seeking, the play-head will be moved to the highest possible position. This function has no result. You have to listen to player events in order to check what happens. Nothing will happen at all if player´s config-option “disallowSkip” is set to TRUE.

player.setVolume(vol:mixed):Void (> V0.7.16)

Sets the Volume of the player to a percent mark indicated by vol.

Volume can be either a numeric value representing the absolute volume to set, where 0 is equal to muted and 100 indicates full throttle. Volume can also be relative - prefixed with operators ”+” or ”-” indicating the relative amount to adjust the volume to. E.g. assumed current volume is 15%, ”+5” set it to 20%, ”-5” to 10% and so on. This function has no result. You have to listen to player events in order to check what happens. Nothing will happen at all if player´s config-option “fixedVolume” is set to TRUE.

player.setFullscreen(goFullscreen:Boolean):Void

Sets the player to fullscreen / full viewport or exits from there depending if goFullscreen set to TRUE (on) or FALSE (off). Does nothing if ALLOWFULLSCREEN is FALSE or if the new state is equal to the current one.

player.setResize()

Triggers the internal “resize” event in order to rescale relative containers. This comes in handy in cases where DOM manipulations happen due to other scripts (e.g. sliders, popups etc.)

player.setSize({width:<x>, height:<y>})

Allows to set the player´s dimensions during runtime. Will also trigger “resize” in order to apply rescaling (if required).

player.setPlayPause():Boolean

Sets the player to pause if its playing or vis versa.

player.setPlay():Boolean

Sets the player to play. If its already playing no changes apply.

player.setPause():Boolean

Sets the player to pause . If its already paused no changes apply.

player.setStop():Boolean

Sets the player to stop . Will cause the playback component to stop immediately and displays the current item´s poster image. Furthermore the start-button shows up.

player.setActiveItem(item:mixed):void

Initializes playback of media item identified by the given item. Accepts an integer representing the item to be played or a “shortcut” string as follows:

Shortcuts:

next - Will activate the next item relatively to the currently active one
previous - Will activate the previous item relatively to the currently active one
poster - Will send the player to IDLE and display the player-poster.

If the player has been previously awakened by user-interaction or by AUTOPLAY set to TRUE, the new active item will be played back immediately.

player.setCuePoint(cuePoint:Object):void

Adds a cue point to an active player instance.

player.removeCuePoint(group:String, Idx:Integer):this

Instantly removes a cuepoint from the player instance. You must specify a “group” and the “idx” of the affected video item. In order to identify the addressed cuepoints by “group” the cuepoint´s “group” property must be priorly set accordingly.

player.syncCuePoints():this

In case you added one or more cue-points via .setCuePoint() you must let the player know about that. Guess how.

player.setPlaybackQuality(quality:String):this

Overwrites the quality setting applied through the config option “playbackQuality”. Will force the player to instantly switch to the requested quality type. Possibe quality values are: 'small', 'medium', 'large', 'hd720', 'hd1080'.

If parameter is invalid or the requested quality isn´t available nothing will happen. Otherwise the player will trigger the “qualityChange”-event.

player.selfDestruct():void

Instantly destroys the referred instance and reconstructs its host DOM´s original state; the one before the player has been applied.

player.reset():void

Resets the instance while keeping current configuration and schedule intact. Sets the active item pointer back to zero.

player.openUrl(Object:{url:<dest>, target:string:'_self', pause:bool:false})

Opens an URL depending on “target” either in the same or in a new window, optionally pauses the player.

Getters

player.getItemCount():Number

Returns the amount of media items within the playlist.

player.getVolume():Float

Returns the sound volume of the player instance where 0 is muted and 1 is full throttle.

player.getItemIdx():Number

Returns the internal playlist index of the currently played item. Note that 0 is for the first item in line.

player.getItemId():String

Returns the unqiue ID of the currently played item if any.

player.getIsAutoslide():Boolean *

experimental

player.getItem(idx:mixed):Array

Returns one or more items identified by idx. idx can either be a numeric value describing the internal playlist position of the requested item or one of the following shortcuts:

'next' to fetch the next item - relative to the currently playing one
'current' (default) to fetch the data if of the item which is played back right now
'previous' to fetch the previous item - relative to the currently playing one
'*' all items (same as getPlaylist())

Not setting “idx” will return the currently played item so you don´t have to use 'getItemIdx()' beforehand.

This method returns copies not references. To alter items you have to use setItem().

The resulting array holds 0..n objects of “processed” playlist data. Each object has the following properties:

ID: A unique as either specified in the “playlist”-config or a randomly created on.
cat: A “category” string which is “clip” by default
config: An object holding item specific configuration parameters.
file: An array of all files defined in the playlist config for this very playlist object.
mediaModel: The internal player model chosen to use for playback.
qualities: An array of possible quality-variant-keys.

player.getLoadProgress(idx:mixed):Float

Returns how many percent of the currently played item has been loaded/buffered so far. Will instantly be 100 on media types available for random-seeking.

player.getLoadPlaybackProgress(idx:mixed):Float

Returns the current playhead position in percent relative to the currently played item´s duration.

player.getCuePoints(idx:Integer):Array

soon

player.getPosition():Number

Returns the current playhead position in milliseconds.

player.getDuration():Number

Returns the duration of the currently played item in milliseconds.

player.getTimeLeft():Number

Retruns the difference between currently played item´s duration and the playhead position in milliseconds.

player.getKbPerSec():Float

Experimental

player.getTrackId():String

Experimental

player.getPreloaderPct():Float

~~Experimental~~ Moved to “Splash” plugin

player.getInFullscreen():Boolean

Returns TRUE if the player is in fullscreen / full viewport mode, otherwise FALSE.

player.getPublicName():String

Returns the player´s current unique DOM ID.

player.getMediaType():String

Returns of what type the currently played item is. (LIST GOES HERE)

player.getUsesFlash():Boolean

Returns true if the current item uses the Flash fallback component for playback.

player.getCanPlay(type:String, platform:String):Boolean

Returns TRUE if the client browser is able to play back the provided type in general - regardless if html5-video, Flash or any other plugin will be used to do so.

You can fine-tune the testing by setting platform to any value described here.

player.getCanPlayNatively(type:String):Boolean

Used without parameter this method returns TRUE if the client browser is able to play back at least one media type natively. If type parameter is set the test is performed for the specific media type and will return TRUE if it can be played back natively.

player.getIframeWindow():JQueryObject

If the player is in “iframe mode” this function returns the iframe´s parent window for further manipulations.

player.getIframe():JQueryObject

If the player is in “iframe mode” this function returns the iframe the player lives in.

player.getPlaylist():Object

Returns the whole currently scheduled playlist. Same as getItem('*').

player.getState(test:string):Object

If called without argument this method returns the current state of the player. You can find a list of possible states here. If “test” is not NULL and a valid state string the method will return TRUE or FALSE according to current playerstate (e.g.: getState('PLAYING') will return TRUE if the player is playing).

VAST Plugin

operator — Sun, 07 Apr 2013 18:39:07 +0200

VAST Plugin

General

The VAST/IMA plugin turns Projekktor into an VAST compliant, HTML5 based advertising video player. It supports linear ads (pre-roll ads) , non-linear ads (overlays *) and companion banners.

Get it here.

Install / Preparation

Scripts

Include the “projekktor.ima.js”. Make sure its loaded after “projekktor.min.js”.

The plugin features a callback function which is triggered in case the user´s client has an active ad-blocker. This function can be applied via the plugin´s config parametera (see below). The callback only gets the pointer to the affected player-instance as optional parameter. So, nothing special at all.

HTML

If your want to support video related companion ads make sure you have properly placed and dimensioned DOM elements with unique “id”-attributes placed somewhere next to the player´s DOM. The IDs must be provided as config-parameter (see below).

CSS

Once the player plays a preroll-ad it gets and additional CSS-class: “ad”. This can be utilized to customize e.g. the player´s control elements during ad-playback. Usually you will hide all control-buttons here and just keep the progress-bar, the time index and a title visible here. Below an example how this might look like within your player´s theme.css:

All CSS classes referred to in the next sections of this doc are considered to be prefixed with ”cssClassPrefix” which is “pp” per default.

.ppad .ppplay,
.ppad .pppause,
.ppad .ppnext,
.ppad .ppprev,
.ppad .ppvslider,
.ppad .ppmute,
.ppad .ppvmax,
.ppad .ppunmute,
.ppad .ppfsenter,
.ppad .pptimeleft,
.ppad .pptitle,
.ppad .ppfseexit {
    display: none;
    border: none;
}

.ppad .ppcontrols {
    background: transparent;
    border: none;
}

.ppad .ppadtitle {
    position: absolute;
    bottom: 2%;
    left: 2%;
    border: none;    
}

/*
 * Ad-Skip option overlay:
 */
.ppadskip {
    position: absolute;
    padding-top: 2px;
    top: 0;
    right: 0px;
    width: 85%;
    height: 28px;
    background-color: #333;
    color: #fdfdfd;
    line-height: 28px;
}

.ppadskip.unlocked {
    cursor: pointer;
    color: #fdfdfd;
}



/*
 * Nonlinear Ad Overlay Styling:
 * <div class="ppadoverlay active" data-pp-ima-func="container">
 *    <div class="ppadclose"></div>
 *    <div class="ppadcontent"></div>
 * </div>
 */


/* the overlay wrapper */
.ppadoverlay {
    position: absolute;
    bottom: 40px;
    width: 100%;
    margin: auto;
    z-index: 9999;
}

/* close button */
.ppadclose {
    background: url('overlayclose.jpg') center center no-repeat;
    width: 10px;
    height: 10px;
    float: right;
    text-align: center;
    cursor: pointer;
}

/* content (image/flash/html) container */
.ppadcontent {
    cursor: display;
    margin: auto;
}

Configuration

Setup

Make sure you activate the plugin by adding it to the event dispatcher. To do so set “addplugins” accordingly, e.g.:

var player = projekktor('#player_a', {
   controls: true,
   autoplay: false,
   addplugins: ['ima'],
   playlist: [   
      {
         0: {src:'http://www.projekktor.com/video/mc.mp4', type:"video/mp4"}
      }
   ]
});

The plugin is now active but does absolutely… nothing. In order to unleash it´s power you must at least apply an url pointing to the VAST1 / VAST2 Feed and set the content-type of the very same feed (application/xml or application/jsonp).

Usually you have a specific ad-URL per video so be aware that the plugin is configured on item-level not on player-level.

var player = projekktor('#player_a', {
   controls: true,
   autoplay: false,
   addplugins: ['ima'],
   playlist: [   
      {
         0: {src:'http://www.projekktor.com/video/mc.mp4', type:"video/mp4"},
         config: {
            plugin_ima: {
               url: '<url to your VAST feed including your partner ID and keywords>',
               type: 'application/xml'
            }
         }
      }
   ]
});

Config Options

enableCompanions, enableOverlay, enablePreroll (Boolean:true)

Enables or disables the respective ad type.

url (String:'')

URL to your VAST feed including your partner ID and keywords.

vastProxy (String:'')

URL to an optional proxy. Useful to bypass common CORS issues in insufficient set up environments. The content URL will be escaped added to the “vastProxy”-string.

vastNoCache (Boolean:false)

Setting this to “true” will append the actual timestamp to all tracking-pixel-call-URLs in oder to avoid caching and make redundant tracking calls possible. This feature is NOT covered by the VAST-Standard and strictly only built in for those who really, really need or want it.

type (String:'application/xml')

Either 'application/xml' or 'application/jsonp'. If set to 'application/jsonp' it´s assumed that the incoming data is an XML formatted string wrapped into a JSONP function.

overlayDelay (Integer:1)

If the incoming data provides overlay-information an overlay will be added to the player once the playhead reaches overlayDelay second during playback of the content video.

companionDest (Array:['companiona', 'companionb', 'companionc'])

An array of IDs addressing the DOM-containers to pump the companion ads in - if any. Note that the plugin auto-evaluates the dimensions of the containers and matches them against incoming companion-data. A companion will only be displayed if there´s a free DOM-container with accurate dimensions and an ID as configured.

resourcePriority (Array:['image', 'iframe', 'html', 'flash'])

Companions are delivered in a variety of formats. This array specifies which format to prefer in case there are multiple variants for one companion available. Per default images are preferred before iframe and html, flash is the worst case (as always).

You can remove one or more items from this array. Doing so the missing companion type will be ignored completely.

adblockCallback (Function:function(myPlayer) {}

The plugin is able to detect whether an adblocker is installed and active or not. If so the function provided here will be triggered. This might be useful to bring some info popups up or whatever. if an adblocker is installed the whole VAST mess will be skipped.

title (String:'advertisement')

The title to set for preroll ads. The title will be applied to the controlbar (if any). Furthermore a <div/> container with the class ”<prefix>adtitle” will be added to the screen holding the title given here.

prerollPauseOnClick (Boolean:true)

If set “true” the player will pause once the user clicks on the preroll video (which usually opens an other browser tab and an advertiser´s ressource). On “false” the player will continue playback. Note: This doesn´t work on mobile devices.

prerollSkip (Integer:0)

Allows to add a “skip” button to a running preroll advertisement. If set > 0 a <div/> will be added to the display with the CSS classes ”<prefix>adskip” and “locked”. The container will be filled with the HTML provided by “prerollSkipHtml”. It will fade in after prerollSkip/2 seconds and “lock” will turn to “unlocked” “prerollSkip/2” seconds later. At this point the container will become click-able.

prerollSkipHtml (String:'Skip this ad in %{secs}')

A HTML string to fill the “adskip” container generated via “prerollSkip”. Can be any markup you want to. %{secs] will be replaced with the remaining seconds to wait until the skip feature will become unlocked.

prerollUnlockedHtml (String:'Click here to skip this ad.')

An HTML string to fill the “adskip” container once the ad has been unlocked.

prerollCat (String:'pre-roll')

The clip category for the pre-roll can be set here. Relevant for tracking purposes only.

prerollCappingLimit (Integer:0)

Maximum amount of pre-rolls delivered to the client within the period defined by ”prerollCappingPeriod”. 0=unlimited

prerollCappingPeriod(Integer:1)

Number of Days until the client´s capping limit will be reseted.

Quick Install Guide (from scratch edition)

operator — Thu, 04 Apr 2013 10:17:06 +0200

Quick Install Guide (from scratch edition)

Using the Projekktor player in your own projects is extremely easy and straightforward. You have to include two JS-files (Projekktor and jQuery) at least one CSS for the theme and, widdy well, your are ready to go. Once you did that you can morph any <video>, <audio> or block styled DOM element into a Projekktor - even within Internet Explorer (6,7,8).

Preparation

Make sure you uploaded the following files to your site:

projekktor.min.js
jquery.min.js
jarisplayer.swf
at least one theme directory including a CSS + its image files

jQuery Inclusion

Projekktor uses the jQuery library. If you do not know what jQuery is, feel free to check it out at jquery.com - but it´s not necessary to know it in detail. If you have jQuery already included to your page (which is not unlikely these days) make sure it is at least V1.4.1.

If you have an earlier version of jQuery installed you must update it in order to run Projekktor. You can grab the most recent one from jquery.com or by using the one bundled with the Projekktor distribution package. Usually this will not cause any problems but your should do some testing with other scripts on your site - if any. Btw: Don´t start to install multiple jQuerys of different versions. It isn´t worth the try.

To make jQuery available add the following HTML to your page´s HEAD section:

<script type="text/javascript" src="jquery.min.js"></script>

Don´t forget to alter the src as required or desired.

Make sure you include jquery BEFORE you include projekktormin.js

Projekktor Inclusion

Add the following HTML to your page´s HEAD section too. This will load the Projekktor itself and a funky theme for its control elements.

<script type="text/javascript" src="projekktor.min.js"></script>
<link rel="stylesheet" href="style/maccaco/style.css" type="text/css" media="screen" />

Once again, check the paths.

Projekktor Instantiation

This is where the real fun begins. Depending on you requirements you can morph one, multiple or all media elements on your page into a Projekktor.

If you want to apply the player to all HTML5 media elements on one page add the following to the HEAD section:

  
    <script type="text/javascript">
         $(document).ready(function() {
               projekktor('video');
         })
    </script>

The $(document).ready() stuff is provided by jQuery. Code within is executed once the whole page has been loaded and became script-able.

Custom Configuration

Projekktor supports a big bunch of configuration options. All of them are strictly optional, two of them are most likely to be of interest for your.

First things first. How to apply custom configurations? Well, Projekktor knows two kinds of config parameters: Dynamic and static ones. The dynamic ones can be set per playlist item and will affect the behavior of the player during runtime. Those options are a long story and since this is a beginners guide we will ignore them for now.

“Static” parameters affect the very basic environment. They define paths, toggles if the player should use flash fallback and a lot of other things more. As said above two of them are very likely to require customization and as such they are good examples to show how the static configurations are applied in general. Here we go, back on or example above:

  
    <script type="text/javascript">
         $(document).ready(function() {
               projekktor('video');
         })
    </script>

You should know that during instantiation projekktor() also takes a second parameter which represents the mentioned config-mess.

  
    <script type="text/javascript">
         $(document).ready(function() {
               projekktor('video', {
	                /* path to the MP4 Flash-player fallback component */
	                playerFlashMP4:		'http://www.yourdomain.com/jarisplayer.swf',
	        
	                /* path to the MP3 Flash-player fallback component */
	                playerFlashMP3:		'http://www.yourdomain.com/jarisplayer.swf'         
               });
         }
    </script>

playerFlashMP4 and playerFlashMP3 define the paths to the SWF-components to be used in case of a flash fallback is performed. Depending on your environment it might be necessary to alter them. It´s good practice to set them to full qualified URLs.

Example

This is how it may look like. The following shows a Projekktor to be mounted on a <video> tag with the ID player_a, sets the default volume to 80%, defines custom paths for the flash fallback component and sets a custom logo overlay which is clickable, Sweet, huh?

<!DOCTYPE HTML>
<html>
<head>
<title>Projekktor Version 8 Test</title>
<link rel="stylesheet" href="theme/style.css" type="text/css" media="screen" />

<script type="text/javascript" src="jquery.min.js"></script> <!-- Load jquery -->
<script type="text/javascript" src="projekktor.min.js"></script> <!-- load projekktor -->
</head>
<body>


<video id="player_a" class="projekktor" poster="intro.png" title="this is projekktor" width="640" height="360" controls>
    <source src="http://www.projekktor.com/intro.ogv" type="video/ogg" />
    <source src="http://www.projekktor.com/intro.mp4" type="video/mp4" />
</video>


<script type="text/javascript">
$(document).ready(function() {
    projekktor('#player_a', {
	volume: 0.8,
	playerFlashMP4: 'http://www.yourdomain.com/jarisplayer.swf',
	playerFlashMP3: 'http://www.yourdomain.com/jarisplayer.swf'
    });
});
</script> 


</body>
</html>

Configuration parameters

operator — Tue, 26 Mar 2013 14:31:59 +0200

Configuration parameters

General

In general Projekktor differentiates three types of config parameters:

Those that affect the player on its whole, …
those that affect single items scheduled and
those that configure plugins / addons.

E.g: “loop” (which makes the player loop all scheduled items permanently) affects the player. On the other hand “title” or “poster” is of interest on item-level only.

As such all config parameters shown below can be set on instantiation as described here. Parameters set this way will be used for the player and - where applicable - as defaults for all items in schedule.

You should know: All this mess is to avoid breaking the time/space continuum and prevent strange effects regarding the player itself.

Config options to be set prior initialization only

cookieName (String:'qwprojaaekktor')

Sets the name of the cookie to store userspecific, permanent information and settings in.

cookieExpiry (Integer:356)

Days to keep the cookie alive.

plugins (Array:['display', 'controlbar'])

Plugins to load on instance initialization. Plugins are automatically extending the projekktorPluginInterface class. The order how the plugins are set here is important because they are added from z-index 0 to n one by one to the player DOM. As such it is useful to add the “Display” plugin always first.

addplugins (Array:[])

Adds one plugin or more plugins to the player. Alternative to “plugins” above. Will be merged with it.

reelParser (function:function(data){return data;})

Projekktor can read external playlists loaded via Ajax. These playlists can either be “XML” or “JSON formatted and should follow the Projekktor playlist scheme.

Nevertheless it´s possible to 3rd party formats, e.g. RSS feeds. The incoming data must be reformatted to a valid playlist then. This is where “reelParser” comes in handy. Once the Ajax request was successful “reelParser” is called and gets the raw input data as parameter. Inside you can hack your alchemy and return a valid Projekktor playlist.

Don´t trigger any further asynchronous operations here. This will break iDevice-support instantly.

ns (String:'pp')

Namespace-Prefix added to all css-classnames and data-attributes used by the player in order to avoid conflicts with existing stuff. This option was formerly known as “cssClassPrefix”.

platforms (Array:['browser', 'ios', 'native', 'flash'])

A prioritized collection of enabled platforms.

Background:

There are several “player models” available for Projekktor. A model handles all the stuff to create a media playback object and interacts with it. E.g. the model “FlashVideo” does the Flash-Embed mess, assigns appropriate parameter to the SWF-movie and handles the Javascript interaction via Flash´s “External Interface”.

The fact that the model uses Flash is indicated by a model-property called “platform”. In this example, guess what, this property has the value “flash”.

There are other models using other platforms. One model handles “ios” specific mechanics. “native” models handle media using the browser´s native <video> and <audio> elements and “browser”-models handle the common stuff like images, iframes and html markup (in fact the “browser”-models are special ones but this is an other story to be told later).

So, WTF?

The default value ['browser', 'ios', 'native', 'flash'] tells the player that it can use four different platforms. BUT, e.g. let´s say we have a <video>-capable browser featuring the H.264 codec plus having Flash installed. In fact we now have two possible platforms to handle this: “native” and “flash”. In our default setup “native” has a lower “platforms”-array index than “flash” and the player will use the native-platform instead of flash. Hence per default “Flash” is configured to be the worst case.

Lets say you want to make the player ignore Flash completely even if the client has the plugin installed you can rewrite “platforms” to ['browser', 'ios', 'native'] and all is good.

iframe (Boolean:false)

If set “true”, Projekktor assumes to live within an iframe and will act accordingly (used for embedding).

loop (Boolean:false)

Enables / disables playlist loop.

autoplay (Boolean:false)

Enables / disables autoplay / autostart. Doesn´t work on most mobile platforms.

ignoreAttributes (Boolean:false)

If Projekktor is pumped into an <audio> or <video> container usually the element-attributes will overwrite given configuration parameters. Setting this to “false” will turn this behavior off. Affected config parameters are “autoplay”, “controls”, “width” and “height”.

continuous (Boolean:true)

Enables / disables conitnuous playback. If enabled the player - once started - will play each playlist item one by one automatically and return to IDLE mode once all playlist items are played back and “loop” is “false”.

In case “continuous” is “false” the player will play the actual media item. Once finished it increases the internal playlist-position-pointer and sets the player to IDLE which brings up the poster for the new playlist item. So, one more user interaction is required to start the new video.

thereCanBeOnlyOne(Boolean:true)

“true” will stop all other player instances but the one the user clicked play on. This way its sure that only one player is running at time.

playlist (Array:[])

An array of objects following the Projekktor playlist scheme to schedule one or more media items.

height (Integer:0)

The height of the player in pixels. In case of “0” the player will use the destination´s container height but at least “minHeight”.

width (Integer:0)

The width of the player in pixels. In case of “0” the player will use the destination´s container width but at least “widthHeight”.

minHeight (Integer:40)

The minimum height of the player.

minWidth (Integer:40)

The minimum width of the player.

forceFullViewport (Boolean:false)

Some devices like the iPad do not support native fullscreen. Instead they allow to bring the native video element itself into fullscreen. The primary effect - seamless video view - is the same but as the player literary pops out of the browser all HTML overlays (ads, logos, CI) and extras will not be visible during that state. Setting “forceFullViewport” to “true” will make Projekktor ignore these “native video fullscreen”-thing but will blow up the player to full browser-viewport instead. All HTML-overlays will stay present then. The only drawback is that in most environments browsertabs and similar elements will stay visible.

keys (Array:[...see blow...])

An array of objects featuring keycode⇒function pairs in order to setup keyboard controls. The player must have focus in order to process keyboard events. This option´s default setup is as follows:

[{
    32: function(player) {player.setPlayPause();},
    27: function(player) {player.setFullscreen(false);},
    13: function(player) {player.setFullscreen(true);},
    39: function(player) {player.setPlayhead('+5');},
    37: function(player) {player.setPlayhead('-5');},
    38: function(player) {player.setVolume('+5');},
    40: function(player) {player.setVolume('-5');},
    68: function(player) {player.setDebug();},
    67: function(player) {$p.utils.log('Config Dump', player.config);},
    80: function(player) {$p.utils.log('Schedule Dump', player.media);}
}];

As “keys” is an array you can setup more than one function per keycode. E.g.:

[
 {32: function(player) {player.setPlayPause();}},
 {32: function(player) {console.log("USER PRESSED PLAY;}}
];

messages (Object:{... see below... })

A set of messages shown in case of errors / on testcards.

  
  // general
  0:'An error occurred.',
  1:'You aborted the media playback. ',
  2:'A network error caused the media download to fail part-way. ',
  3:'The media playback was aborted due to a corruption problem. ',
  4:'The media (%{title}) could not be loaded because the server or network failed.',
  5:'Sorry, your browser does not support the media format of the requested file.',
  6:'Your client is in lack of the Flash Plugin V%{flashver} or higher.',
  7:'No media scheduled.',
  8: '! Invalid media model configured !',
  9: 'File (%{file}) not found.',
  10: 'Invalid or missing quality settings for %{title}.',
  11: 'Invalid streamType and/or streamServer settings for %{title}.',
  12: 'Invalid or inconsistent quality setup for %{title}.',
  80: 'The requested file does not exist or delivered with an invalid content-type.',
  97:'No media scheduled.',
  98:'Invalid or malformed playlist data!',
  99:'Click display to proceed. ',
  100: 'PLACEHOLDER',
  // Youtube errors
  500: 'This Youtube video has been removed or set to private',
  501: 'The Youtube user owning this video disabled embedding.',
  502: 'Invalid Youtube Video-Id specified.'

Config options available per playlist item

ID (String:'0')

A unique itemID used for internal identification and tracking purposes. Randomly generated in case non is provided.

title (String:'')

A title is a title is a title.

poster (String:'')

URL to a poster image - will be overwritten by poster-attribute in case Projekktor is pumped into a <media> tag.

cover (String:'')

URL to a cover image shown on audio playback only. If “cover” is empty “poster” will be used instead.

controls (Boolean:false)

Enables / disables the controlbar plugin GUI.

duration (Integer:0)

Sets the duration of the played media item. Currently works for “images” only.

start (Integer:0)

start offset in seconds for randomly seekable media. (EXPERIMENTAL)

stop (Integer:0)

Stop endpoint in seconds for randomly seekable media. (EXPERIMENTAL)

volume (Float:0.5)

Initial player volume while 0 is mute and 1 is full throttle.

disablePause (Boolean:false)

Enables / disables the possibility to pause a video during playback via the GUI. JS API calls are not affected.

disallowSkip (Boolean:false)

Enables / disables the possibility to skip or search/scrub a video during playback via the GUI. JS API calls are not affected.

fixedVolume (Boolean:false)

Enables / disables the possibility to alter the player volume via the GUI. JS API calls are not affected.

imageScaling (String:'aspectratio'), videoScaling (String:'aspectratio')

Possible values are “fill”, “aspectratio” or “none”.

Configures how the cover, poster or the video is scaled within the display area. “fill” stretches the source to fit the display but may deform the image / video. “aspectratio” may result in black (empty) areas but keeps the source´s aspect ratio and “none” will just center either the image or video without resizing it. This may cause black areas or a cropped image.

playerFlashMP4 (String:'jarisplayer.swf'), playerFlashMP3 (String:'jarisplayer.swf')

Sets the URL to the (default) flash fallback component.

streamType (String:'file')

Defines the streaming method. The offical Projekktor-distro currently supports:

file - progressive download streaming (http, default)
http - http pseudo streaming
rtmp - RTMP streaming - requires “flashRTMPServer” to be set.

startParameter (String:'start')

The name of the GET variable defining the time offset for “pseudo” stream-environments.

streamServer (String:'')

Sometimes required in combination with “streamType”.

useYTIframeAPI (Boolean: false)

Youtube offers two different player APIs: fLaSh and “iFrame” for HTML5 . Make your choice here. For mobile devices this is forced to TRUE

enableKeyboard (Boolean: true)

Enable / Disable keyboard interactions with the player.

enableFullscreen (Boolean: true)

Enable / Disable fullscreen / full viewport. If disabled all GUI interactions forcing “fullscreen” will be discarded. JS API calls are not affected.

enableTestcard (Boolean: true)

If testcard is disabled and in case no native-media or flash is available the player will force a filedowload. Otherwise (enableTestcard=true) a testcard with an errormessage is shown in case of any playback issue.

skipTestcard (Boolean: false)

If the scheduled playlist holds more than one item and “skipTestcard” is set TRUE in case of an error the player will proceed to the next item without showing a testcard / errormessage.

className (String:'')

Sets an additional CSS class to the player. If configured on “item” level the class is being removed and the original classes are restored once the internal playlist pointer changes.

playbackQualities (Array:[ ... see below ... ])

Configures automatic quality selection in case videos are provided in different resolutions and qualities. The details of this mechanics and how to use it are described here.

{key: 'small', minHeight: 240, minWidth: 240},
{key: 'medium', minHeight: 360, minWidth: [{ratio: 1.77, minWidth: 640}, {ratio: 1.33, minWidth: 480}]},
{key: 'large', minHeight: 480, minWidth: [{ratio: 1.77, minWidth: 853}, {ratio: 1.33, minWidth: 640}]},
{key: 'hd1080', minHeight: 1080, minWidth: [{ratio: 1.77, minWidth: 1920}, {ratio: 1.33, minWidth: 1440}]},
{key: 'hd720', minHeight: 720, minWidth: [{ratio: 1.77, minWidth: 1280}, {ratio: 1.33, minWidth: 960}]},
{key: 'highres', minHeight: 1081, minWidth: 0}

Configuring Plugins

xxxx

Tracking Plugin - [Ajax based tracking]

operator — Mon, 25 Mar 2013 14:35:10 +0200

Tracking Plugin

General

Allows tracking of all player -events and -states plus some additional client information to any pixel- or ajax based tracker.

Get it here.

Install

Scripts

Load “porjekktor.tracking.js” into the head of your page and activate the plugin by stetting “addplugin” accordingly.

HTML

This plugin does not require any additional markup.

CSS

This plugin does not require any additional CSS.

Config Parameters

respectDNT (Boolean: true}

Modern browsers feature a config option called “Do not Track” which is intended to be a sort of client side tracking-opt-out. Per default the plugin respects this flag and will not track sessions of clients having this flag set.

permanentUuid (Boolean: false}

Per default the plugin generates a unique user ID when a new client comes along and stores it within a cookie: User-tracking. Setting this parameter to “false” will generate a new ID on each new player session: More Privacy.

track (Array:[])

This parameter configures the tracking behavior. See next section for more details.

The "track" parameter

Basics

The “track” parameter is an array filled with objects. Each object must at least have one “events” and one “url” property. The “event” property defines WHEN a track call is being processed. Track calls can be fired on any event listed here. Below an example “track” setup - just to have something to start with:

track:  [
  {events: ["state.playing", "time.5", "fullscreen"], url:"http://www.projekktor.com/trackpixel.png?trackingdata"},
  {events: ["firstquartile", "state.paused"], url:"http://www.projekktor.com?quartileundpaused"},
  {events: ["mute", "unmute", 'thirdquartile'], url:"http://www.projekktor.com?res=%{res}&pltfrm=%{pltfrm}"}
]

Lets have a closer look on the first sub-set:

{events: ["state.playing", "time.5", "fullscreen"], url:"http://www.projekktor.com/trackpixel.png?trackingdata"}

When ever the player reaches the “playing” state (state.playing) OR when the playhead reaches the 5th second of the media (time.5) OR the player is toggled into or from fullscreen a tracking call is fired to “http://www.projekktor.com/trackpixel.png?trackingdata”.

Pixel based tracking

You can add additional client information to be sent to your tracking backend by adding GET parameters to your tracking URL. E.g.:

{events: ["mute", "unmute", 'thirdquartile'], url:"http://www.projekktor.com?res=%{res}&cp =%{cp}"}

Whenever the user “mutes” OR “unmutes” the player OR once he or she watched at least three quarters of the video the plugin adds a tracking pixel to the DOM. Before this is done the URL “http://www.projekktor.com?res=%{res}&pltfrm=%{cp}” will be parsed and the given place-holders will be substituted by the respective data. In this example the URL might become: “http://www.projekktor.com?res=800x600&pltfrm=Browser.Flash.Native”.

All this will end up in the following img-tag created on each of the events mentioned above:

<img src="http://www.projekktor.com?res=800x600&pltfrm=Browser.Flash.Native" class="<playerID>_tracking" style="display: none;"/>

Ajax based tracking

Instead of creating img-tags you can push data via POST to your tracking backend. To do so just add a “post” property to a tracking call config sub-set:

{events: ["state.playing", "time.5", "fullscreen"], url:"http://www.projekktor.com/trackingendpoint.php", post:{varA:'post this, babe', varB:'%{murl}'}}

“post” must be an object and can hold as many properties as you need. Each property string is parsed to substitute place-holders with tracking data analogue to the pixel based method.

In case your tracking endpoint resides on a different domain than the player itself you must have a proper backend CORS setup.

Javascript Callbacks

If your site already loads a tracker framework like Piwik or Google Analytics and you do not want to rebuilt or mimic their tracking pixel calls you can assign callback functions additionally to or instead of pixel URLs.

The callback function will receive all constants, variables and the player instance as arguments. E.g:

{events: ["state.playing", "time.5", "fullscreen"], callback:myFunction'}

Projekktor allows you to organise scheduled media in categories. This can be done by applying the “cat” parameter to each playlist entry. By default this is set to “clip”. By adding the “cat” property to a tracking config sub set you can specify for which media category the respective tracking setup is applied. E.g. this sub set will trigger a tracking call only for media files of the category “trailer”:

{cat:'trailer', events: ["state.playing", "time.5", "fullscreen"], url:"http://www.projekktor.com/trackingendpoint.php", post:{varA:'post this, babe', varB:'%{murl}'}}

track-able constants

%{uid} - A cross-session user ID
%{sid} - A unique session ID regenerated every time the player initializes
%{sst} - A unix timestamp marking the time the player was initialized (session start).
%{plyid} - The playerID as set through the HTML markup (id attribute) or config option.
%{r} - A random string set at the beginning of the session.
%{pver} - The Projekktor version in use.
%{url} - The current URL as provided by “window.location.href” but without hash.
%{ref} - Alias for %{url}
%{cpl} - A string containing all video types the client can play natively, separated by a ”.”
%{pltfrm} - A string holding the “platform” the client is using right now (e.g.: “flash”, “native”)
%{pltfrms} - A string holding all “platforms” available on client side, separated by a ”.”
%{fl} - Client´s Flash version, “0” if no Flash is installed.
%{res} - The client´s video resolution <height>x<width>

track-able variables

%{cat} - Clip category as specified via playlist config (e.g. trailer, clip, ad,..) default is “clip”
%{dur} - The duration of the currently played media
%{durms} - The duration of the currently played media in milliseconds
%{err} - is “1” in case the player fired an error, default is “0”
%{fs] - Player is in fullscreen mode
%{h} - The hour of the day on client side.
%{m} - The minute of the hour on client side.
%{mf} - The currently playing media format (ogg, mp4, etc.)
%{mt} - The currently playing media type (audio, video, image, html)
%{mid} - The itemID as configured via the Projekktor playlist
%{midx} - The playlist position of the current media.
%{mod} - Name of the player-model currently used for playback (e.g. FLASHVIDEO, VIDEO, AUDIO, …).
%{murl} - The URL to the currently active media.
%{pstate} - The player state in the very moment the track call is fired (e.g. IDLE, PLAYING, PAUSED …).
%{pos] - Current playhead position.
%{posms} - Current playhead position in milliseconds.
%{rnd} - A random string built with 8 numeric characters.
%{seq} - Session´s pixel sequence number. Increased by one at each tracking call.
%{s} - The second of the minute on client side.
%{sdur} - Duration of the current player session.
%{title} - The title of the current item.
%{ts} - Client´s current time as Unix timestamp

Projekkt related

operator — Mon, 18 Mar 2013 12:58:33 +0200

Projekkt related

Where can I find the release roadmap of this project?

Projekktor releases are published spontaneously. This is no full time project so I can´t give guarantees for anything at this point. Nevertheless the project is still under active development and will be at least till end 2012.

If you need a special feature you can buy support. If this is an option for you please feel free to contact me.

Why is your site so damn ugly?

Thank you. Well, we spent most of our time to do player-stuff, no self-congratulating web-stuff. That´s it.

Nearly 150 KB, are you kiddin´ me?

Projekktor re-implements the whole decision-tree needed to find the proper playout method for your content. Doing so you have total control about what format in what quality is being pumped into what client and what platform. This not only allows total cost- but also quality- assurance on a level no other player on the market is able to provide. Please feel free to get in touch in case you want to learn more.

General

Projekktor´s Jarisplayer Flash component doesn´t support proper (...put in a lot of freaky flashstuff here...)

This projekkt is all about HTML5 and future orientated, re-liberalized media delivery and not Flash. Deciding to use HTML5 video/audio (or maybe even Projekktor) is not just choosing an other player. It´s more like a strategic reorientation. “In for a penny, in for a pound.” Jarisplayer has very basic RTMP support. There are yet no plans to enlarge the feature set of it. If you want to learn why Projekktor uses Jarisplayer and not JWplayer or Flowplayer please check this blog entry: http://www.projekktor.com/blog/2010/11/thanks-for-jarisplayer/

Nevertheless for business users we offer alternate Flash models for both, JWPlayer and Flowplayer. If you are interested in one of them please feel free to get in touch.

What is the difference between .ogv and .ogg

The file extension it is. Usually OGV is used for ogg/theora encoded video while OGA is for ogg/vorbis encoded audio. For historical reasons sometimes OGG is used instead of OGA and in order to guarantee perfect confusions OGG is also used for OGV. At the end its up to you to clean up the mess.

Autoplay

I tried to apply the "autostart" attribute to the VIDEO-tag in order to make it play, well, automatically, but something is messed up.

This is a known issue with some browsers. Some of them initialize the native players before they fire the contentLoaded or similar event which triggers Projekktor to initialize. As such, if you apply the autostart attribute the affected videos will start playback for a glimpse, stop and the new Projekktor instance gets started. Some times this causes some interesting audio-visial effects but mostly this ends up in a total mess.

To avoid that you should use the autoplay = true config.option of Projekktor itself instead, e.g.:

 projekktor('#player_a', {
     volume: 0.8,
     autoplay: true
 });

I applied the autoplay config option as described above but it does not work on mobile devices, what´s wrong?

Simply forget it. Autostarting video- or audio- playback doesn´t work on most mobile devices. This is not a bug but a limitation by Apple / Google / <put vendor name here>. Most likely this is to protect the users from enervating ads and to save battery power.

You said autoplay doesn´t work on iOS but there are workarounds for this. Shouldn´t you change your field of scripting, dude?

It is true that there are workarounds to force autoplay e.g. on an iPad. But they are what they are: Workarounds to bypass an intended feature. There is no guarantee that they will work after the next iOS update. As such it doesn´t make any sense to be part of this cat-and-mouse game.

Fullscreen

Why does the fullscreen button just make the player fill my browser window? The browser tabs are still visible - this suckz.

Older browsers - especially IE - do not support true HTML fullscreen. Projekktor is able to detect this and will stretch the player to full-viewport instead. That´s it.

I put Projekktor into an iframe in order to allow 3rd party embedding but the fullscreen-button doesn´t show up. What´s wrong?

This is not a bug but a feature. If the base URL of the parent window is unequal the URL of the iframe, browser security restrictions apply. In such situations the script can neither initialize true fullscreen nor force the player-container to full viewport. A fullscreen-button would irritate users then and that´s why it´s being disabled.

Why does the player loose its fancy design when fullscreen is invoked on iOS / Android devices?

Toggling fullscreen will open the media content within a native iOS / Android player. While it is possible to overlay HTML to it during “inline” mode this isn´t possible once fullscreen gets invoked. This is system immanent. You can get around this on most tablets by setting the config option “forceFullViewport” to “true”. Note that browser tabs stay visible in this mode.

Layout

The theme / layout / video overlay / subtitle / (...) looks awful in Internet Explorer 6. What´s the problem?

The used browser of course. Projekktor should work on IE6 but there´s no guarantee because we do not check this. Building the player for modern environments and especially for more recent versions of Internet Explorer´s is painful enough.

Setup

I used the video-/audio- tag as e.g. seen in your demos but the player doesn´t come up. No poster, no controls, nothing.

Media-tags are not natively supported in IE <9 and Projekktor uses a dirty trick to bypass this. Unfortunately this trick doesn´t work if the tag is wrapped by an inline DOM container. Make sure it´s a block styled one and under no circumstances a p-aragraph.

Video Issues

While in Flash fallback (e.g. IE <9, H.264 in Firefox etc. pp.) the video is being completely downloaded before playback starts. What can I do?

! Make sure the moov atom meta data is being set in the beginning of your .mp4 video file and not at the end. Check your encoder for an encoding option like “quick start”, “faststart” or similar. For FFMPEG the command line option is called -movflags faststart. There´s also a stand alone tool available called “qt-faststart”.

While playing back OGG/Theora in Firefox the player stops playback within the first second or so.

Most likely you´re using Firefox 5 with Firebug enabled. Just disable Firebug and all is good. Please don´t ask. Took my hours to get the trick.

The video could not be loaded, either because the server or network failed or because the format is not supported.

HUH?

I want to play a THEORA / WEBM video hosted on my own server. I´ve checked the links, permissions and everything but Firefox ends up with a testcard (error message). What´s wrong?

Most native players requires proper type header responses from the web server. Some older server setups do not know how to handle the *.oga, *.ogg,. *.ogv and / or *.webm extension. In order to make things work create an .htaccess file in your video / audio directory and hack the following lines into it:

AddType audio/ogg .oga
AddType video/ogg .ogv .ogg
AddType video/webm .webm

In most browsers the player sometimes plays a video for a couple of seconds and suddenly ends up with an error message (testcard).

In some browsers with native video support this happens if the delivering web server uses GZIP compression. Usually this compression makes sense only for text based files (CSS, HTML, Javascripts etc.pp.). So you have to check your server setup in order to make sure that at least your media content is NOT being compressed.

If you do not have access to your httpd.conf you can try to bypass this by adding a .htaccess with the following line:

AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/x-javascript

Note that this is a positive list and only text files are compressed now - no video/ogg etc. pp.

In CHROME the player sometimes plays a video for a couple of seconds and suddenly ends up with an error message (testcard).

As of February 2013 Chrome seems to have issues with hardware accelerated H.264 playback on some operating systems. Disabling acceleration helps. Open “chrome:\/\/flags” and uncheck the “Enable hardware acceleration” checkbox to disable hardware acceleration.

Youtube

I added a Youtube video to the playlist but all I got is an error message / testcard. Why is that?

Youtube allows its premium users to disable embedding. This feature not only affects the players you can find in blogs or similar but also the ones provided by the Javascript API. The latter one is used to projekktorize Youtube-videos and as such the mentioned option also affects Projekktor. So, in case you stumble upon a “this media can not be…” …something error while using a Youtube video you´ve choosen one which can not be embedded - that´s all.

Tracks Plugin - [Config Options]

operator — Mon, 11 Mar 2013 14:11:15 +0200

Tracks Plugin

General

Get it here.

Install

Scripts

Load “porjekktor.tracks.js” into the head of your page and activate the plugin by stetting “addplugin” accordingly.

HTML

Output Container

This plugin does not require any additional mark-up. Nevertheless it is possible to create a dedicated output DOM-container outside the player. To do so you must provide data attributes as follows to bind the container to a player instance:

data-<namespace>-tracks-host=”<player id>” and
data-<namespace>-tracks-func=“container”

E.g. to bind the subtitle-display-container to a player with the configured namespace “pp” (which is default) and an ID of “player_a” you have to use:

<div data-pp-tracks-host="player_a" data-pp-tracks-func="container"></div>

You may add style-classes and other attributes as desired and required.

Controlbar Modifications

In order to provide a on/off button for subtitles you need to alter the controlbar template as described in the controlbar plugin documenation. The required template tag is %{tracksbtn}.

CSS

In case the output-container is injected to the player DOM the following CSS is recommended. Note the absolute positioning. The output container will get the additional class “shifted” in case the player´s control-bar fades in. The class is removed once it fades out. This way you can prevent overlapping.

.pptracks  {
    position: absolute;
    bottom: 2%;
    left: 2%;
    width: 100%;
    height: auto;
    overflow: hidden;
    color: #fdfdfd;
    z-index: 1000;
}

The controlbar button is subject of four different states: inactive, active, on and off. The button gets the class “inactive” in case the tracks-plugin is active but no tracks-data has been set. Accordingly “active” is applied in case a subtitle file for the user´s browser-language is available. The states “on” and “off” are set to the user´s decision accordingly to turn subtitles on or off. Below please find a very basic and ugly CSS example to illustrate this:

.pptracksbtn.inactive,
.pptracks.inactive {
    display: none;
}

.pptracksbtn.active,
.pptracks.active {
    display: block;
}

.pptracks span {
    position: relative;
}


.pptracksbtn.off {
    width: 30px;
    height: 30px;
    background-color: red;
    display: block;
}

.pptracksbtn.on {
    width: 30px;
    height: 30px;
    background-color: green;
}

Player Setup

In case you´re mounting Projekktor on a <video>-tag the player will fetch relevant data from standard conform <track> tags. E.g.:

<video id="example_video_1" class="projekktor" controls width="640" height="264" poster="clip.jpg">
  <source type="video/mp4" src="clip.mp4">
  <track kind="subtitles" src="captions.vtt" srclang="en" label="English">
</video>

Otherwise you may simply add the necessary information to the “config” object of each playlist entry. E.g.:

playlist: [
    {
        1: {src: "videofile.webm", type:"video/webm"},
        config: {
            tracks: [
                { src: "subtitles.xml", srclang:"en"},
                { src: "subtitles.xml", srclang:"de"}
            ]
              
        }
    }
];

Configuration

Config Options

This plugin features the following config-parameters:

force (Boolean:false)

Forces loading and display of subtitles even it the user disabled them.

offset (Integer:0)

A time offset in milliseconds to compensate non “trimmed to zero” time marks within the subtitle data. All marks are assumed to be relative to the players progress bar - beginning by zero. Some subtitle data however might be provided with a zero-position of 10 hours plus or even stranger offsets. To deal with this without the need to re-process the subtitle file itself you can define an offset here which is being subtracted from all interpreted time marks.

stack (Boolean:false)

Per standard subtitles can be assigned exactly to a specific video frame and / or by using milliseconds in the time mark definitions. Unfortunately the player itself is not capable to handle such an accuracy. This might result in “overlapping” subtitles depending on internal rounding processes. Per default the output-container´s content is completely wiped before a new subtitle gets injected. By setting “stack” to “true” this wipe is being suppressed and the new textline is being appended to the output-container´s current content.

style (Boolean:false)

If set “true” the plugin will apply style information as defined in the DXFP head section to the paragraphs “style” attribute. Note that the “style”-id is always also applied to the textlines as CSS-class - regardless if this option is true or false. This way you can style them without relying on the styles predefined in the DXFP-file.

ttstyle(Boolean:false)

Some subtitle feeds feature style information as paragraph attributes. Setting ttstyle to “true” will apply them to the respective paragraph directly via setting its “style” attribute.

ttsoverwrite(Boolean:false)

If “ttstyle” and “ttsoverwrite” are both “true” the tts-styles are not applied as “style” attribute but as classNames. E.g. tts:color=”#fdfdfd” will apply the class “ppttfdfdfd”. Note that “pp” is the result of the “ns” player config parameter.

Compatibility Chart

operator — Fri, 08 Mar 2013 12:25:30 +0200

Compatibility Chart

This page is out of date. Please visit our new, auto-generated compatibility-chart.

The following browser / platform combinations have been successfully tested with Projekktor. This list also provides an overview of the availability of Projekktor specific features within the respective environment.

*Format*:	Vorbis	Theora	webM	MP3	H.264	custom controls	dynamic overlays	playlists	true fullscreen	notes
*Render Engine / Browser*
Internet Explorer
IE6	–	–	–	via Flash	via Flash	yes	yes	yes	no	are you kidding?
IE7	–	–	–	via Flash	via Flash	yes	yes	yes	no
IE8	–	–	–	via Flash	via Flash	yes	yes	yes	no
IE9	–	–	–	yes	yes	yes	yes	yes	no	better than expected
Gecko
Firefox 3	–	–	–	via Flash	via Flash	yes	yes	yes	no
Firefox >3.5	yes	yes	–	via Flash	via Flash	yes	yes	yes	no
Firefox 4	yes	yes	yes	via Flash	via Flash	yes	yes	yes	no	quite cool
Firefox 8	yes	yes	yes	via Flash	via Flash	yes	yes	yes	no	quite cool
WebKit
Chrome >15	yes	yes	yes	yes	yes	yes	yes	yes	yes	supercool
Safari 4 (Mac & PC)	yes*	yes*	–	yes	yes	yes	yes	yes	no	* requires quicktime plugin
Safari 5 (Max & PC)	yes*	yes*	–	yes	yes	yes	yes	yes	yes	* requires quicktime plugin
Opera
Opera 10.51	yes	yes	yes	via Flash	via Flash	yes	yes	yes	no	Groovy
Mobile Devices
iPad (3.2)	–	–	–	yes	yes	impossible	impossible	yes	yes
iPhone iOS 3+4	–	–	–	yes	yes	impossible	impossible	yes	yes
iPad iOS 3+4	–	–	–	yes	yes	not supported	not supported	yes	yes
Android >2.x	–	–	–	yes	yes	not supported	not supported	yes	yes

Building Projekktor from Source - [The Models]

operator — Wed, 06 Mar 2013 00:38:54 +0200

Building Projekktor from Source

General

Once you downloaded the player´s source you will find the script separated into multiple files. In order to get the un-compressed and un-merged Javascript running you need to include the mentioned files one by one to your development page or merge them into a single file. The most important trick is:

Including / merging ALL files will fail. Also be aware that projekktor.js MUST BE INCLUDED FIRST - after jQuery of course.

Directory Structure

The /js path of the repository holds four sub-directories:

jQuery - Includes one or more incarnations of jQuery for testing purposes.
controller - Holds the player´s core controller, models and basic tools.
models - Holds, well, the playback models.
plugins - Holds (not so) optional plugins.
parsers - Some custom reel parser functions needed to convert incoming feed into the Projekktor playlist format. (coming up)

The Controller and Tools

Projekktor´s controller is generated out of all /js/controller/projekktor.*.js files. Each of the following files is strictly obligatory. It´s vital to load projekktor.js first.

projekktor.js - The player´s controller itself.
projekktor.config.js - The default configuration object with all available config parameters.
projekktor.utils.js - A set of more or less useful utility-functions used within the player.
projekktor.plugininterface.js - A basic plugin-prototype all plugins are extended from.

The Models

The player models handle the content-playout itself. Some of them are obligatory, some are optional and some will replace other ones depending on the setup.

player.js - The model prototype - obligatory
player.NA.js - “Invalid File” dummdy model - obligatory
player.playlist.js - Allows to load a playlist from within a playlist - optional
player.audio.video.js - Native audio / video support - optional
player.audio.video.flash.js - Flash audio / video support featuring Jarisplayer - optional
player.jwflash.js - Flash audio / video support featuring JWplayer - replaces “player.audio.video.flash.js” - optional
player.youtube.js - Youtube API support - optional
player.image.html.js - Displays images and HTML pages as regular content - optional

The Default Plugins

projekktor.display.js - holds the video / poster / image screen as well as the start button, the buffer icon and the logo. Not including this will make an extremely boring video player.
projekktor.controlbar.js - the custom control bar

The Parsers

(coming up)

Player Events

operator — Mon, 25 Feb 2013 14:23:17 +0200

Player Events

This documentation applies to player version V0.8.x and higher. Please refer to API, section Instantiation in order to learn how to add and remove listeners.

scheduleLoading

Triggered in case of an AJAX call fetching an external playlist from server has been initiated

scheduleModified

Fired whenever an item has been added to or removed from schedule after the player has been initialized successfully.

scheduled

The initial scheduling process has finished and the player is ready for action.

configModified

Fired if player configuration has been altered as the result of an AJAX call (e.g. in conjunction with “schduleLoading”).

item (itemIndex)

Triggered once a new item got the “current” focus.

displayReady

Triggered as soon as the media display for the current item has been successfully initialized. May result in a poster-image or media playback.

pluginsReady

Triggered as soon as all plugins are ready to go for the current item.

ready

Triggered as soon as the player is ready for action and ready to play the current item. This is the case after “displayReady” and “pluginsReady” has been fired. Depending on “autostart” or “continuous” config this may either result in an IDLE or a PLAYING state.

start

The media playback started and the first frame has been displayed.

state (string)

Triggered when ever the state of the current playback component changes to one of the following:

possible states

IDLE The playback component is waiting for user-interaction and has not started playback yet. Usually a poster-image is shown at this state.

AWAKENING The playback component initializes for a new session. This may be either if “autoplay” is FALSE and the user clicked “start” or the player is configured to AUTOPLAY and starts automatically.

STARTING The playback component has been successfully initialized and synchronized and will begin playback shortly.

PLAYING The playback component is currently playing (SNAFU).

PAUSED The playback component has been paused by the user or via an external JS API call.

STOPPED The playback component has stopped playing either because of user-interaction or close of the corresponding browser window.

COMPLETED The current media item has been played back completely.

ERROR An error occured.

DESTROYING The playback component is being removed from the DOM and all connections to the controller are being cut.

buffer (string)

Triggered when ever the buffer-state of the current playback component changed.

possible states

EMPTY The buffer under-run, the playback component has been paused and new media data is being buffered.

FULL Enough data has been buffered in order to play the current media item back.

volume (currentVolume:float)

Triggered on change of volume of the current playback component. Is also triggered during the playback component´s initialization process.

mute

Fired once the player gets muted (volume equal 0).

unmute

Fired once the player gets unmuted (volume gets adjusted from 0 to >0).

resume

Fired once the current media continues playback after a prior “PAUSED” state.

time (float)

Continuously triggered during change of play-head position but at a maximum of a 500 millisecond interval.

progress (float)

Continuously triggered during change of buffer-load but at a maximum of a 500 millisecond interval. Will stop once the media file has been completely buffered or became available for random-seeking.

firstquartile, midpoint, thirdquartile (void)

The playhead passed the 1st, 2nd (midpoint) or 3rd quartile of the overall media duration for the very first time. Use “start”-event or “completed” state to track the missing cornerstones.

seek (float)

The user or a script sent the “setSeek” command and the player component does everything necessary in order to continue playback from the specified position.

fullscreen (boolean)

Triggered whenever the player switches from or into fullscreen / full viewport mode.

resize

The document or the player itself has been resized.

scale

Triggered once the current media (video or image) has been scaled to fit the player dimensions.

qualityChange

The playback-quality has been changed.

detach

The current playback component detached the actual media and destroyed itself successfully.

mousemove

The user moved the mouse while the pointer is over the player instance.

mouseenter (MouseEvent)

The user moved the mouse pointer over the player instance.

leftclick / rightclick / middleclick (Click:event)

OBSOLETE ~~Triggered whenever the player either receives a left-, right- or middle- click.~~

mousedown (ClickEvent)

Triggered on mouse click. Check ClickEvent.which to get the mouse button used.

mouseleave (MouseEvent)

The user moved the mouse beyond the borders of the player instance.

key (KeydownEvent)

The player instance has the focus and the user hit a key on keyboard (or remote control). Note that most keys (e.g. alphanumeric) will result in a keyCode equal 0 due to underlying security restrictions.

done

Triggered if the current item is the last one scheduled and reached the “COMPLETED” state ⇒ “playlist completely played back”

Display Plugin - [Config Options]

operator — Mon, 04 Feb 2013 14:36:49 +0200

Display Plugin

General

This plugin features the media display, a buffering indicator and a logo-overlay.

Install

Scripts

This plugin is bundled to the official Projekktor distribution. No need to take care of any extras here.

HTML

Nothing special here. If no container with the class ”<prefix>display” is available within the player´s dest. container the plugin will inject one.

CSS

The display container can be styled as you like. To make the display fill the whole player container the theme.css should feature something like this:

.ppdisplay {
    position: relative !important;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    margin: 0;
    padding: 0;    
}

Configuration

….

Config Options

displayClick (Object:{callback: 'setPlayPause', value: null}

Triggeres “callback” in case the display area is being clicked while the player is in IDLE state. “callback” can either be a Projekktor API method or a custom function.

displayPlayingClick (Object:{callback: 'setPlayPause', value: null}

Triggeres “callback” in case the display area is being clicked during media playback. “callback” can either be a Projekktor API method or a custom function.

displayDblClick (Object:{callback: null, value: null}

Triggeres “callback” in case the display area is beeing doubleClicked. “callback” can either be a Projekktor API method or a custom function.

staticControls(Boolean: false}

If “staticControls” is “true”, the media display is automatically scaled to full player height minus the height of the control bar generated by the controlbar plugin| to avoid overlapping.

bufferIconDelay(Integer: 10000}

Setting this to a value > 0 (milliseconds) will delay the appearance of the “buffering” indicator after the player sent the respective event. This is used to compensate possible flickering and assure a cleaner userexperience.

spriteUrl(String: ''}

Usually the “buffericon” is an animated GIF made visible via a background-image for the corresponding DOM container. Unfortunately animated GIFs may have artefacts which don´t look good in case you want a transparent buffering icon. A transparent PNG is much cleaner but unfortunately not animatable cross-browser (APNG). You can “emulate” APNG by using a sprite which is animated via Projekktor.

“spriteUrl” must point to a PNG featuring an animation-sequence represented by vertically stacked animation-frames. All frames must be of the same size.

spriteWidth(Integer: 50}

The width of one icon animation frame.

spriteHeight(Integer: 50}

The height of one icon animation frame

spriteTiles(Integer: 25}

Total amount of single animation frames featured in the PNG sprite set at “spriteUrl”.

spriteOffset(Integer: 1}

If the single frames are separated by an empty space or any other kind of spacer you must provide the spacer´s height here.

spriteCountUp(Boolean: false}

Indicates if the PNG sprite is animated fom top to button (spriteCountUp = true) or from button to top (spriteCountUp = false).

Controlbar Plugin - [Config Options]

operator — Wed, 23 Jan 2013 11:06:54 +0200

Controlbar Plugin

General

This plugin handles a couple of buttons and sliders to control the player.

Install

Scripts

This plugin is bundled to the official Projekktor distribution. No need to take care of any extras here. If you use a custom build make sure “projekktor.controlbar.js” and a “theme.css” is included to your page.

HTML / CSS

Please check our theming the player guide to learn more about the general principles here.

Setup

If you do NOT use the official Projekktor distro make sure you activate the plugin by adding it to the event dispatcher. To do so set “addplugins” accordingly, e.g.:

var player = projekktor('#player_a', {
   controls: true,
   autoplay: false,
   addplugins: ['controlbar'],
   playlist: [   
      {
         0: {src:'http://www.projekktor.com/video/mc.mp4', type:"video/mp4"}
      }
   ]
});

Config Options

All config options described below are optional.

Options marked with an “*” have no effect in case you use the Projekktorize my HTML principle (patent pending).

designMode (Boolean: false}

~~Setting this to “true” prevents the buffer-indicator form fading out in order to make styling easier.~~ Obsolete

disableFade (Boolean: false} *

~~If set “true” the controls-container won´t fade away after “fadeDelay” seconds but stay persistent during playback.~~ Obsolete. Please alter the theme-CSS to keep the controlbar visible on “inactive” state (display: block;)

fadeDelay (Integer: 2500}

Milliseconds to toggle control-bar´s state from “active” to “inactive” after last user-interaction (e.g. mousemove, keypress etc.pp.) and in case the container does not have the focus (e.g. mouseover).

showOnStart (Boolean: false}

Setting this to “true” will turn the controls-container “active” right after the player begins playback and turn it “inactive” automatically after “fadeDelay” milliseconds.

showOnIdle (Boolean: false}

Turns the control-bar-container “active” right after the player initialized but no playback has yet started. This usually is the case while the “poster” is shown.

showCuePoints (Boolean: false)

If enabled (and proper CSS is set) cuePoint markers will be displayed on top of the scrubber-bar.

controlsTemplate (String: '<ul class="left"><li><div %{play}></div><div % ... and much more ...') *

In case you do NOT use the Projekktorize my HTML principle (patent pending) the plugin will apply the markup set here to the player automatically.

Logo Plugin - [Config Options]

operator — Fri, 30 Nov 2012 17:33:47 +0200

Logo Plugin

General

This plugin adds an image overlay to the player´s video display to be used for branding. The image is click able and can be configured for each playlist item individually. It is possible to define a time-offset to delay appearance of the image according to the current playhead position.

This plugin implements a functionality formerly built into the download bundle of Projekktor.

Get it here.

Install

Scripts

Load “porjekktor.logo.js” into the head of your page and activate the plugin by stetting “addplugin” accordingly.

HTML

This plugin does not require any additional markup.

CSS

The plugin adds an <img/> to the player´s DOM holding the configured image URL as 'src' attribute. It gets the class <prefix>logo (“pplogo” per default). The additional classes “active” and “inactive” are added dynamically in order to reflect the configured delay.

The following example CSS uses transitions in order to provide a fancy fade-in/fade-out effect:

.pplogo {
    position: absolute;
    top: 2%;
    left: 2%;
}


img.pplogo.inactive {
    -moz-opacity: 0;
    -khtml-opacity: 0;
    opacity: 0;
    -webkit-transition: opacity 1.0s linear;
    -moz-transition: opacity 1.0s linear;
    -o-transition: opacity 1.0s linear;
    transition: opacity 1.0s linear;      
}

img.pplogo.active {
    -moz-opacity: 1;
    -khtml-opacity: 1;
    opacity: 1;
    -webkit-transition: opacity 1.0s linear;
    -moz-transition: opacity 1.0s linear;
    -o-transition: opacity 1.0s linear;
    transition: opacity 1.0s linear;  
}

Configuration

Config Options

This plugin features the following config-parameters:

image (String:'')

The full URL to the image resource to be loaded as logo/watermark. If empty ⇒ no fun.

delay (Integer:1)

Seconds to delay the activation of the logo container. Will also define the negative offset in relation to the total runtime of the video. E.g.: A value of “1” will activate the logo one second after the video has started and deactivate it one second before the video ends.

logoClick (function:function(player){})

Providing a callback function here the logo becomes clickable. On click this function will be triggered.

Plugins

operator — Wed, 28 Nov 2012 17:37:28 +0200

Plugins

General

Projekktor plug-ins are (optional) components extending the basic player´s functionality, behavior and / or look. They can be applied to one, more or all player instances and at any time during player instantiation. All Projekktor plug-ins consist of at least one Javascript file and sometimes an additional CSS featuring a basic demo-style. Some plug-ins require additional HTML markup either within the page or the player itself.

Setup

Plugins have unique, single word names, e.g. “share”, “related”. The plugin files are named accordingly following this namescheme: projekktor.<plugin name>.<extention>, e.g. “projekktor.share.js”, “projekktor.share.css” etc. pp.

To activate a plugin all *.JS and *.CSS files coming with the plugin-archive must be correctly included into the page in question and possibly required HTML markups must be copy and pasted from an existing projekktor.<pluginname>.html - file into the player´s DOM or the page´s body.

Additionally the player has to learn which plugin(s) should be fired with events. To do so the plugin´s name must be added to the “addplugins”-config array, e.g. to activate the “related” plugin you hack :

var player = projekktor('#player_a', {
   controls: true,
   autoplay: false,
   addplugins: ['related'],
   playlist: [   
      {
         0: {src:'demovideo.mp4', type:"video/mp4"},
      }
   ]
});

The plugin´s name is also relevant to address plugin specific configuration. Once a plugin has been added via “addplugins” the player eats additional config-objects named by the plugin and prefixed with “plugin_”. E.g. below, note the “plugin_related” object (on player level configuration):

var player = projekktor('#player_a', {
   controls: true,
   autoplay: false,
   addplugins: ['related'],
   playlist: [   
      {
         0: {src:'http://www.projekktor.com/video/mc.mp4', type:"video/mp4"},
      }
   ],
   plugin_related: {
       related: {
            enabled: true,
            title: 'Related Videos',
            items: [
                {poster: './videoposter1.jpg', url: 'http://www.yoursite.com/vid1', title:'Title 1'},
                {poster: './videoposter2.jpg', url: 'http://www.yoursite.com/vid2', title:'Title 2'},
                {poster: './videoposter3.jpg', url: 'http://www.yoursite.com/vid3', title:'Title 3'}
            ]
       }
   }
});

Please note that some plugins must be configured on item-level why most are configured on player level.

Available Plugins

A

Audio Slideshow - Create media synchronized image slideshows. This plugin also features a nifty image slider.

C

Controlbar - Handles a couple of buttons and sliders to control the player.

D

Display - This plugin features the media display, a buffering indicator and a logo-overlay.

L

Logo - Adds an ordinary, clickable image overlay to the player´s display to be used as watermark, logo or whatever.

P

Postertitle - Adds the title of the currently IDLEing video over the poster image. Fades out on mouseout.

R

Related - Adds a post-roll panel which shows thumbnails of related or recommended videos. Also features a “replay” button and optional sharing features.

S

Share - Adds social share buttons to the video display, per default those are: facebook, twitter. Links can be easily added, removed and altered by config parameters. It also promotes the embed-code for iframed players.

T

Tracking - Allows tracking of all player events and states plus some additional client information by any pixel-image based tracker.

Tracks - Implements cross-browser interpretation of the HTML5 <tracks>-element to provide subtitles and closed captions. Eats DXFP and SRT / webVTT formatted data feeds.

V

VAST / IMA - Reads VAST 1.0 and VAST 2.0 feeds. Supports pre-roll-, overlay- and companion- ads plus relevant tracking. Approved by Smartclip and Google.

Plugins marked with are built into the official Projekktor releases.

Share Plugin - [CSS]

operator — Wed, 28 Nov 2012 17:34:42 +0200

Share Plugin

General

Adds social share buttons to the video display - Facebook and Twitter by default. Links can be easily added, removed and altered by config parameters. It also promotes the embed-code for iframed players.

Get it here.

Install

Scripts

Load “porjekktor.share.js” into the head of your page and activate the plugin by stetting “addplugin” accordingly.

HTML

This plugin does not require any additional markup.

CSS

To understand the example CSS which comes with plugin below please find the HTML-markup the plugin dynamically injects into the player-DOM:

This part of the markup represents the “social bar” which holds the different share-buttons:

<div class="ppsocialbar inactive" data-pp-share-func="container">
    <div class="ppsocialbutton ppembed">embed</div>
    <div class="ppsocialbutton pptwitter">Twitter</div>
    <div class="ppsocialbutton ppfacebook">Facebook</div>
</div>

The following represents the popup-window which comes up once the “embed” button is available and has been clicked:

<div class="ppsocialpopup inactive" data-pp-share-func="popup">
   <p>This is the embed (...)</p>
   <p>Copy this:</p>
   <textarea readonly="readonly"></textarea>
   <a>Close Window</a>
</div>

Configuration

Config Options

This plugin features the following config-parameters:

fadedelay (Integer:1800)

Milliseconds to delay fadeout of the social-bar after player losses focus.

embed (Object:{..see below..})

This object allows to i18n the texts of the popup holding the embed code (headlineText, closeText, descText) and the embed- code itself. If you customize the embed-code you can use the following placeholders which are dynamically replaced by the respective data:

%{embedid} - A randomly generated 8 digit alpha-string.
%{playerurl} - The URL of the iframe holding the player including its hash.
%{ID} - The ID of the currently playing playlist-item as configured in the player´s playlist.

{
    code:           '<'+'if'+'rame id="%{embedid}" src="%{playerurl}#%{ID}" width="640" height="385" frameborder="0"><'+'/if'+'rame>',
    buttonText:     'embed',
    headlineText:   'Copy this:',
    closeText:      'Close Window',
    descText:       'This is the embed code for the current video which supports iPad, iPhone, Flash and native players.'
}

links (Object:{..see below..})

This objects holds a collection of config-objects defining the links you want to provide. The keys (e.g. twitter, facebook) are used as internal identifiers and classnames for the corresponding buttons. “buttonText” defines the onscreen text while ”text” defines the text to be pumped into ”code”. While hacking the code you can use two placeholders:

%{pageurl} - Will be replaced by the page URL the current player is embedded into.
%{text} - Will be replaced by the escaped version of the text defined above.

'twitter': {
    buttonText: 'Twitter',
    text:       'I found a cool HTML5 video player. Check this out: http://www.projekktor.com',
    code:       'http://twitter.com/share?url=%{pageurl}&text=%{text}&via=projekktor'       
},

'facebook':{
    buttonText: 'Facebook',
    text:       'I found a cool HTML5 video player. Check this out: http://www.projekktor.com',     
    code:       'http://www.facebook.com/sharer.php?u=%{pageurl}&t=%{text}'     
}

Postertitle Plugin - [General]

operator — Mon, 26 Nov 2012 13:46:06 +0200

Postertitle Plugin

General

Adds the title of the currently IDLEing media item to the poster screen. Fades out on mouseout.

Get it here.

Install

Scripts

Load “porjekktor.postertitle.js” into the head of your page and activate the plugin by stetting “addplugin” accordingly.

HTML

This plugin does not require any additional markup.

CSS

The plugin adds an additional DIV-container to the player´s DOM holding the title-string. It get the class <cssprefix>postertitle (“pppostertitle” per default). The additional classes “active” and “inactive” are added according to the current state.

Configuration

Config Options

This plugin doesn´t feature any config options.

Audio Slideshow Plugin - [General]

operator — Mon, 26 Nov 2012 13:45:40 +0200

Audio Slideshow Plugin

General

The Audio Slideshow plugin generates time-index controlled image slideshows. Hence it allows to illustrate any sort of audio e.g. interviews, dramas and report pieces.

The plugin is very easy to setup, style and integrates seamlessly into existing Projekktor installations.

Get it here.

Install

Scripts

The plugin comes with one JS file (projekktor.audioslideshow.js) which needs to be included to your page.

HTML

The plugin requires additional HTML-Markup which must be present prior player initialization. The plugin is shipped with a file called “projekktor.audioslideshow.html” for further references.

<!-- THE PLAYER -->
<div class="projekktor audio" id="player2" style="width: 576px; height: 250px; margin: 15px;"></div>

<!-- THUMB CONVEYOR -->
<div class="ppsliderwrapper">
    <div class="ppsliderconveyor" data-pp-audioslideshow-host="player2" data-pp-audioslideshow-func="conveyor"></div>
    <div class="ppsliderprev" data-pp-audioslideshow-host="player2" data-pp-audioslideshow-func="prev"></div>
    <div class="ppslidernext" data-pp-audioslideshow-host="player2" data-pp-audioslideshow-func="next"></div>

</div>


<!-- FULL SIZE IMAGE -->
<div class="ppslidertitle" data-pp-audioslideshow-host="player2" data-pp-audioslideshow-func="title"></div>
<div class="ppsliderimage" data-pp-audioslider-host="player2" data-pp-audioslider-func="canvas"></div>

The CSS classes can be set on your desire. This example uses class-prefixes / namespace (“pp” per default) but this purely optional. Also the “ppsliderwrapper” container is just for some additional styling and not required for the plugin´s functionality.

In the above example containers with assigned “data” are the important ones and all of them are optional.

The following “data-pp-audioslideshow-func” values are interpreted:

“prev” will become the “jump to previous image” button.
“next” will become the “jump to next image” button.
“conveyor” will be filled with the thumbnail slider.
“canvas” will be used as canvas for the full sized version of active images. If this container is missing images will be displayed within the player´s display area.
“title” will be filled with the active item´s title as set in the plugin-config.

As you can have multiple audio sliders on one page you need to assign the discussed HTML set to a specific player instance. This is done by using the “data-pp-audioslideshow-host” attribute with which you can assign a player ID. In the given example the slider is tied to a Projekktor instance with the ID “player2”.

CSS

The plugin comes with a very basic CSS example (projekktor.audioslideshow.css). Nothing special here.

Setup

The Audio Slides extension needs to get installed as a plugin as described here. Basically this will look like this:

var player = projekktor('#player_a', {
   controls: true,
   autoplay: false,
   addplugins: ['controlbar'],
   playlist: [   
      {
         0: {src:'http://www.projekktor.com/video/mc.mp4', type:"video/mp4"}
      }
   ]
});

Config Options

images (Array: [])

Images holds an array of objects. Each of those objects requires four properties to be set:

src_pre - URL to a preview image (thumbnail) to add to the conveyor area.
src - URL to the full size version of the image as to display in the audio-slide canvas area.
title - The image´s title.
on - A string representing the human readable time-index to trigger focusing of the respective image.

plugin_audioslideshow: {
	images: [
        {src_pre: 'images/t1.jpg', src: 'images/t1-big.jpg', on: '00:00:02', title: 'Oh long and dark the stairs I trod,'},
        {src_pre: 'images/t2.jpg', src: 'images/t2-big.jpg', on: '00:00:14', title: 'with stumbling feet to find my God,'},
        {src_pre: 'images/t3.jpg', src: 'images/t3-big.jpg', on: '00:00:34', title: 'Gaining a foothold bit by bit'},
        {src_pre: 'images/t4.jpg', src: 'images/t4-big.jpg', on: '00:01:20', title: 'Then slipping back and losing it.'},       
        {src_pre: 'images/t5.jpg', src: 'images/t5-big.jpg', on: '00:01:55', title: 'There came a certain time when I'},
        {src_pre: 'images/t6.jpg', src: 'images/t6-big.jpg', on: '00:02:15', title: 'Loosened my hold and fell thereby,'},
        {src_pre: 'images/t7.jpg', src: 'images/t7-big.jpg', on: '00:02:45', title: 'Down to the lowest step my fall'},
        {src_pre: 'images/t8.jpg', src: 'images/t8-big.jpg', on: '00:03:10', title: 'As if I had not climbed at all.'},     
        {src_pre: 'images/t9.jpg', src: 'images/t9-big.jpg', on: '00:03:45', title: 'And as I lay despairing there,'},
        {src_pre: 'images/t10.jpg', src: 'images/t10-big.jpg', on: '00:04:10', title: 'there came a footfall on the stairs'},
        {src_pre: 'images/t11.jpg', src: 'images/t11-big.jpg', on: '00:04:40', title: 'And lo when hope had ceased to be'},
        {src_pre: 'images/t12.jpg', src: 'images/t12-big.jpg', on: '00:04:50', title: 'My God came down the stairs to me.'}    
    ]
}

Related Plugins

The “controlbar” plugin visualizes cue-points used for the audioslides. To toggle this you can use the “showCuePoints” parameter, e.g.:

plugin_controlbar: {
     showCuePoints: true,
}

Audio Slides Plugin - [Config Options]

operator — Sat, 01 Sep 2012 14:34:38 +0200

Audio Slides Plugin

DRAFT

General

The Audio Slideshow plugin generates time-index controlled image slideshows. Hence it allows to illustrate any sort of audio e.g. interviews, dramas and report pieces.

The plugin is very easy to setup, style and integrates seamlessly into existing Projekktor installations.

Install

Scripts

The plugin comes with one JS file (projekktor.audioslideshow.js) which needs to be included to your page.

HTML

The plugin requires additional HTML-Markup which must be present prior player initialization. The plugin is shipped with a file called “projekktor.audioslideshow.html” for further references.

<!-- THE PLAYER -->
<div class="projekktor audio" id="player2" style="width: 576px; height: 250px; margin: 15px;"></div>

<!-- THUMB CONVEYOR -->
<div class="ppsliderwrapper">
    <div class="ppsliderconveyor" data-pp-audioslideshow-host="player2" data-pp-audioslideshow-func="conveyor"></div>
    <div class="ppsliderprev" data-pp-audioslideshow-host="player2" data-pp-audioslideshow-func="prev"></div>
    <div class="ppslidernext" data-pp-audioslideshow-host="player2" data-pp-audioslideshow-func="next"></div>

</div>


<!-- FULL SIZE IMAGE -->
<div class="ppslidertitle" data-pp-audioslideshow-host="player2" data-pp-audioslideshow-func="title"></div>
<div class="ppsliderimage" data-pp-audioslider-host="player2" data-pp-audioslider-func="canvas"></div>

In the above example containers with assigned “data” are the important ones and all of them are optional.

The following “data-pp-audioslideshow-func” values are interpreted:

“prev” will become the “jump to previous image” button.
“next” will become the “jump to next image” button.
“conveyor” will be filled with the thumbnail slider.
“canvas” will be used as canvas for the full sized version of active images. If this container is missing images will be displayed within the player´s display area.
“title” will be filled with the active item´s title as set in the plugin-config.

CSS

The plugin comes with a very basic CSS example (projekktor.audioslideshow.css). Nothing special here.

Setup

The Audio Slides extension needs to get installed as a plugin as described here. Basically this will look like this:

var player = projekktor('#player_a', {
   controls: true,
   autoplay: false,
   addplugins: ['controlbar'],
   playlist: [   
      {
         0: {src:'http://www.projekktor.com/video/mc.mp4', type:"video/mp4"}
      }
   ]
});

Config Options

images (Array: [])

Images holds an array of objects. Each of those objects requires four properties to be set:

src_pre - URL to a preview image (thumbnail) to add to the conveyor area.
src - URL to the full size version of the image as to display in the audio-slide canvas area.
title - The image´s title.
on - A string representing the human readable time-index to trigger focusing of the respective image.

                plugin_audioslides: {
                    images: [
                        {src_pre: 'http://farm6.staticflickr.com/5002/5292903664_d834670a40_s.jpg', src: 'http://farm6.staticflickr.com/5002/5292903664_d834670a40.jpg', on: '00:03', title: 'Goa 1'},
                        {src_pre: 'http://farm6.staticflickr.com/5208/5292295427_3583e5f90c_s.jpg', src: 'http://farm6.staticflickr.com/5208/5292295427_3583e5f90c.jpg', on: '00:14', title: 'Goa 2'},
                        {src_pre: 'http://farm6.staticflickr.com/5002/5292747298_6758f7b847_s.jpg', src: 'http://farm6.staticflickr.com/5002/5292747298_6758f7b847.jpg', on: '00:18', title: 'Goa 3'},
                        {src_pre: 'http://farm6.staticflickr.com/5001/5296532040_4636267f4a_s.jpg', src: 'http://farm6.staticflickr.com/5001/5296532040_4636267f4a.jpg', on: '00:20', title: 'Goa 4'},	    
                        {src_pre: 'http://farm6.staticflickr.com/5050/5296537706_573db3443c_s.jpg', src: 'http://farm6.staticflickr.com/5050/5296537706_573db3443c.jpg', on: '00:22', title: 'Goa 5'},
                        {src_pre: 'http://farm6.staticflickr.com/5207/5296026757_fcda8fb50b_s.jpg', src: 'http://farm6.staticflickr.com/5207/5296026757_fcda8fb50b.jpg', on: '00:25', title: 'Goa 6'},
                        {src_pre: 'http://farm6.staticflickr.com/5290/5299481744_9c68e0f43f_s.jpg', src: 'http://farm6.staticflickr.com/5290/5299481744_9c68e0f43f.jpg', on: '00:29', title: 'Goa 7'},
                        {src_pre: 'http://farm6.staticflickr.com/5289/5299623458_313e63a732_s.jpg', src: 'http://farm6.staticflickr.com/5289/5299623458_313e63a732.jpg', on: '00:30', title: 'Goa 8'},	    
                        {src_pre: 'http://farm6.staticflickr.com/5281/5319016324_4faed43fdc_s.jpg', src: 'http://farm6.staticflickr.com/5281/5319016324_4faed43fdc.jpg', on: '00:35', title: 'Goa 9'},
                        {src_pre: 'http://farm6.staticflickr.com/5243/5320211422_3510e790d9_s.jpg', src: 'http://farm6.staticflickr.com/5243/5320211422_3510e790d9.jpg', on: '00:55', title: 'Goa 10'}	 	    
                    ]
                }

Using Playlists - [Asynchronously loaded Playlist Feeds]

operator — Tue, 07 Aug 2012 16:19:17 +0200

Using Playlists

This doc applies to V0.8.11 or higher

General (for developers)

Projekktor has a built in playlist support. You may want to ignore this and - if required - do the all the schedule handling via the JS API. That´s OK and the possibilities to handle this are legion. Basically its all about fetching the “COMPLETED” state of the playback component and re-instantiate a new Projekktor with new media URLs afterwards. This is common practise (with other products) and will work fine. However you may find Projekktor itself a bit bloated then because you will not need about two-thirds of its functionality.

As such it works best to use the player as central data handler and - if necessary - write plugins or wrappers to do the custom stuff. What ever you do, may the force be with you.

General (for webmasters)

In fact you have three options to pump schedule data into the player core:

via the config object
via javascript API calls
via asynchronously loaded XML or JSON feeds

It is hard to make a recommendation which option works best since all three are the result of daily practice. If you just want to apply a pre- or post- roll ad the first option would work best because it keeps fragmentation of your code and mark-up low. On the other hand using feeds is the perfect way to go for video-focused sites with only a few central players (e.g. webTV). So it´s all up to you.

Projekktor Playlist Format

A Projekktor playlist is an array holding multiple objects where each object configures a single media item in the matter of its location (URL), type and optional item specific player-configuration.

[
  {
     // minimum 
     0:{src:'item_one_format_one.ext', type: 'video/...'}     
  },
  {
     // one content, multiple formats
     0:{src:'item_two_format_one.ext', type: 'video/...'},
     1:{src:'item_two_format_two.ext', type: 'video/...'}
  },
  {
     // one content, multiple formats, item specific config
     0:{src:'item_three_format_one.ext', type: 'video/...'},
     1:{src:'item_three_format_two.ext', type: 'video/...'},
     3:{src:'item_three_format_three.ext', type: 'video/...'},
     4:{src:'item_three_format_four.ext', type: 'video/...'},          
     config: {
        option1: value1,
        option2: value2
     }
     
]

Basic Playlist / Schedule Setup

As you might already know the player is instantiated this way (btw: in case you do not, learn more here):

<div id="player_a" class="mybasicplayerstyle"></div>

<script type="text/javascript">
    projekktor('#player_a', {});
</script>

Parameter one is a jQuery DOM selector and indicates the destination DOM container(s), the second parameter is for additional configuration. E.g. in order to play a single content in two formats, having controls enabled and set the volume to 50% you hack this:

projekktor('#player_a', {
    controls: true,
    volume: 0.5,
    playlist: [
       {
          0:{src:'myvideo.mp4', type: 'video/mp4'},
          1:{src:'myvideo.ogv', type: 'video/ogv'}
       }
    ]
});

Consistently it is possible to schedule multiple videos by extending the playlist array. Let ´s add a kinda preroll-ad:

projekktor('#player_a', {
    controls: true,
    volume: 0.5,
    playlist: [
       {
          0:{src:'advertisement.mp4', type: 'video/mp4'},
          1:{src:'advertisement.ogv', type: 'video/ogv'}
       },
       {
          0:{src:'myvideo.mp4', type: 'video/mp4'},
          1:{src:'myvideo.ogv', type: 'video/ogv'}
       }       
    ]
});

You now have two videos in schedule which are played back one after one in a row. While this is quite cool it is not perfect yet. In general ads are enervating and users have tendencies to skip them when ever possible. To avoid this you may want to make use of Projekktor´s item-wise re-configuration feature.

In order to prevent skipping and pausing of the first clip you can set config.disablePause and config.disallowSkip to TRUE like that:

projekktor('#player_a', {
    controls: true,
    volume: 0.5,
    playlist: [
       {
          0:{src:'advertisement.mp4', type: 'video/mp4'},
          1:{src:'advertisement.ogv', type: 'video/ogv'},
          config: {
             disablePause: true,
             disallowSkip: true
          }
       },
       {
          0:{src:'myvideo.mp4', type: 'video/mp4'},
          1:{src:'myvideo.ogv', type: 'video/ogv'}
       }       
    ]
});

Et voila: Perfect constraint!

Note that configuration options above “playlist” define the defaults for all scheduled items while config options on item level affect only the respective item.

Dynamic Scheduling via Javascript API

Assumed you set a player up and running this way (learn more here):

<div id="player_a" class="mybasicplayerstyle"></div>

<script type="text/javascript">
projekktor('#player_a', {
    controls: true,
    volume: 0.5
});
</script>

It is possible to set (or overwrite) its schedule by using the setFile or setItem method. Below we define a new playlist and apply it to an already instantiated player with the ID “player_a”:

var playlist = [
       {
          0:{src:'advertisement.mp4', type: 'video/mp4'},
          1:{src:'advertisement.ogv', type: 'video/ogv'},
          config: {
             disablePause: true,
             disallowSkip: true
          }
       },
       {
          0:{src:'myvideo.mp4', type: 'video/mp4'},
          1:{src:'myvideo.ogv', type: 'video/ogv'}
       }   
];

projekktor('player_a').setFile(playlist);

The player instance will fire the “scheduled” event once the setFile-call has been processed. Note that ”setFile” overwrites all previously set items - which is close to a full reset. If you want to manipulate, add or remove single items without discarding the current schedule you better use the setItem method.

Asynchronously loaded Playlist Feeds

Loading feeds will not work if you´re testing / developing through the file system. Files MUST be delivered by a HTTP server sending proper content-type header information.

Projekktor can eat XML and JSON formatted playlist feeds either of a proprietary format or any other format by applying custom filter functions. If you´re planing a project from scratch and want to use the Projekktor we highly recommend to use JSON feeds in order to save overhead and performance.

Feeds are applied like ordinary media files just by a given URL and a type set either to “text/json” to load a JSON formatted feed or “text/xml” to load - guess what - a feed which is handled as XML. As such the following example could do the job:

<div id="player_g"></div>

<script>
projekktor('#player_g', {
    file: [{src:'playlistserver.php', type: 'text/json'}]
});
</script>

The following will work also:

<video id="player_g" width="640" height="480" controls>
   <source src="playlistserver.php" type="text/json"/>
</video>

<script>
projekktor('#player_g', {});
</script>

XML and JSON feeds must be loaded from the same domain as the page with the player itself loads from. Otherwise security restrictions apply and you get an error. If you need to load data from an external domain you can either use a simple proxy on your server which passes the feed through or use a JSONP formatted feed (set player to “application/jsonp” then).

During the load process the player will go to IDLE state and will refuse any user interaction or JS call until all feed data has been processed and all plugins (re-) initialized.

Loading a (new) feed will ALWAYS overwrite all scheduled items so far. This is important to know because it is possible to “chain” playlists. Once the player reaches an item of type “application/json”, “application/xml” or “application/jsonp” it will load the feed from the given URL and continues playback with item #1 of the new scheduled items.

The following example would play back the advertisement.*-video first and load the playlist.xml feed afterwards:

projekktor('#player_a', {
    controls: true,
    volume: 0.5,
    playlist: [
       {
          0:{src:'advertisement.mp4', type: 'video/mp4'},
          1:{src:'advertisement.ogv', type: 'video/ogv'}
       },
       {
          0:{src:'playlist.xml', type: 'text/xml'}
       }       
    ]
});

Icing on the cake: data types are “always functional” fallback options. Read on:

You can set up extremely complex format fallback scenarios by providing feeds as alternate media sources. Since feeds are understood by all browsers even setting like this will work:

projekktor('#player_a', {
    controls: true,
    volume: 0.5,
    playlist: [
       {
          0:{src:'advertisement.webm', type: 'video/webm'},
          1:{src:'alternate-playist.xml', type: 'text/xml'}
       }       
    ]
});

In this example every client which is not able to play WEBM will load the “alternate-playist.xml” feed.

Quality Toggle - [Configuration]

operator — Fri, 27 Jul 2012 15:38:15 +0200

Quality Toggle

General

Projekktor allows to provide multiple quality versions of a video. You can set up as many different versions of a specific video as you like. The player automatically detects a set of two “best matches” the user can toggle between. The player´s decision is based upon the available display dimensions which may vary on different platforms and devices. Quality toggling works transparently and independently of the available platform (html5, flash etc.pp.). However this mechanism doesn´t affect native quality-toggling e.g. for HDS and HLS players.

Configuration

Configuration is handled via the “playbackQualities” config parameter. It assigns an internal quality “key” and a set of detections rules in order to parametrize the auto-detection logic.

Simple Width-Height Testing

Let´s have a look on this very basic example object:

 
{
  {key: 'small', minHeight: 240, minWidth: 240},
  {key: 'highres', minHeight: 1081, minWidth: 0}           
}

The object holds two rule-sets for two different quality versions: “small” and “highres”. Note that these keys are just an example. You can set keys of any value you want to.

The properties “minHeight” and “minWidth” define the rule itself. The given names should be quite self-explanatory at this point. So, the quality key “small” will be chosen if the player has minimum dimensions of 240x240px but less than 1081px of height. Setting either “minHeigh” or “minWidth” to zero will make the respective property ignored. So for “highres” only the height of the player will be tested but not its width.

Complex Aspect Ratio Testing

Here we go. E.g.:

 
{
  {key: 'small', minHeight: 240, minWidth: 240},
  {key: 'medium', minHeight: 360, minWidth: [{ratio: 1.77, minWidth: 640}, {ratio: 1.33, minWidth: 480}]},
  {key: 'highres', minHeight: 1081, minWidth: 0}           
}

No panik. The “minWidth” property can be set to take respect of aspect ratios and as such it can be an object. Because the height of the player is the reference value for further calculations “minHeight” can only of type integer.

In addition to the decision tree described in the simple example above the player got a new rule-set keyed with “medium”.

For “medium” the player must have a minimum height of 360px. Furthermore - talking about {ratio: 1.77, minWidth: 640} - the minimum width must be either 640px in case the player has at least an aspect ratio of 16:9 (because 16 / 9 = 1.77) or a minimum width of 480px if the player has at least an aspect ratio of 4:3 (4/3=1.33). You can set as many aspect ratio rules as you want to.

Complex Aspect Ratio Testing

Below you´ll find a complex setup and a (hopefully) human readable translation:

{key: 'small', minHeight: 240, minWidth: 240},
{key: 'medium', minHeight: 360, minWidth: [{ratio: 1.77, minWidth: 640}, {ratio: 1.33, minWidth: 480}]},
{key: 'large', minHeight: 480, minWidth: [{ratio: 1.77, minWidth: 853}, {ratio: 1.33, minWidth: 640}]},
{key: 'hd1080', minHeight: 1080, minWidth: [{ratio: 1.77, minWidth: 1920}, {ratio: 1.33, minWidth: 1440}]},
{key: 'hd720', minHeight: 720, minWidth: [{ratio: 1.77, minWidth: 1280}, {ratio: 1.33, minWidth: 960}]},
{key: 'highres', minHeight: 1081, minWidth: 0}

small: The player height is 240px and its width at least 240px
medium: Player height is 360px, and player dimensions are 640px by 360px (for 16:9 aspect ratio) or 480px by 360px (for 4:3 aspect ratio).
large: Player height is 480px, and player dimensions are 853px by 480px (for 16:9 aspect ratio) or 640px by 480px (for 4:3 aspect ratio).
hd720: Player height is 720px, and player dimensions are 1280px by 720px (for 16:9 aspect ratio) or 960px by 720px (for 4:3 aspect ratio).
hd1080: Player height is 1080px, and player dimensions are 1920px by 1080px (for 16:9 aspect ratio) or 1440px by 1080px (for 4:3 aspect ratio).
highres: Player height is greater than 1080px, which means that the player's aspect ratio is greater than 1920px by 1080px.

Setup

/* small: Player height is 240px, and player dimensions are at least 320px by 240px for 4:3 aspect ratio. medium: Player height is 360px, and player dimensions are 640px by 360px (for 16:9 aspect ratio) or 480px by 360px (for 4:3 aspect ratio). large: Player height is 480px, and player dimensions are 853px by 480px (for 16:9 aspect ratio) or 640px by 480px (for 4:3 aspect ratio). hd720: Player height is 720px, and player dimensions are 1280px by 720px (for 16:9 aspect ratio) or 960px by 720px (for 4:3 aspect ratio). hd1080: Player height is 1080px, and player dimensions are 1920px by 1080px (for 16:9 aspect ratio) or 1440px by 1080px (for 4:3 aspect ratio). highres: Player height is greater than 1080px, which means that the player's aspect ratio is greater than 1920px by 1080px. */