HTML5 Video - Docs

Tracking Plugin - [Config Options]

operator — Wed, 16 May 2012 14:46:46 +0200

Tracking Plugin

General

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

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.

Modern browsers feature a config option called “Do not Track” which is intended as 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.

track (Array:[])

This parameter configures the tracking-behavior itself and as such the triggers for different pixel-URLs. Triggers can be bound to one ore more of the following events:

any event listed here
firstquartile - the playhead reached 25% of the duration of the vid for the very fist time
midpoint - the playhead reached 50% of the duration of the vid for the very fist time
thirdquartile - the playhead reached 75% of the duration of the vid for the very fist time

Below find an example “track” setup:

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}"}
]

“track” is an array holding unlimited sub-sets. Each set consists of an “events” array and an “url” string.

Lets have a closer look on the first set:

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

The plugin will create an <img/> element with a “src” attribute pointing to “http://www.projekktor.com/trackpixel.png?trackingdata” whenever the player goes “fullscreen”, the user watched the first five seconds of the vid and whenever “state” becomes “playing”. That´s it.

You can add additional client information to be sent to your tracking server by adding magic 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 and once he or she watched at least three quarters of the video the player loads a tracking pixel. Before this is done the URL “http://www.projekktor.com?res=%{res}&pltfrm=%{cp}” will be parsed and the given placeholders will be replaced by the respective data. In this example the URL might become: “http://www.projekktor.com?res=800x600&pltfrm=Browser.Flash.Native”

Available placeholders so far:

%{vidId} - The itemID as configured via the Projekktor playlist
%{plyId} - The playerID as set through the HTML markup (id attribute) or config option.
%{title} - The title of the current item.
%{r} - A random string.
%{h} - The hour of the day on client side.
%{m} - The minute of the hour on client side.
%{s} - The second of the minute on client side.
%{url} - The current URL as provided by “window.location.href” but without hash.
%{cp} - A string containing all video types the client can play natively, separated by a ”.”
%{pltfrm} - A string holding all available “platforms”, separated by a ”.”
%{res} - The client´s video resolution <height>x<width>

VAST Plugin - [Config Options]

operator — Sun, 13 May 2012 14:02:30 +0200

VAST Plugin

The VAST Projekktor-Plugin is not available for public download. If you´re interested to get a copy please get in touch.

General

The Projekktor VAST plugin supports three ad types: preroll, companions and overlays. (…)

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:

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

.projekktor.ad .ppcontrols {
    background: transparent;
    border: none;
    border: 4px solid red;
}

.projekktor.ad .pptitle {
    border: none;
    left: 5px;
}

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 will do absolutely… nothing. In order to unleash it´s power you must at least apply an url pointing to the VAST1 / VAST2 XM-feed, the content-type of the mentioned feed (XML or JSONP-wrapped XML).

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.

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 the overlayDelay second while playing back the content video.

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

An array of IDs addressing the DOM-containers to playe 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.

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 prefered before iframe and html, flash is the worst case.

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. The whole VAST mess will be skipped then and playback of the content video gets started.

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 “adtitle” will be added to the screen holding the title.

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 “adskip” and “locked” and filled with the HTML provided by “prerollSkipHtml”. The mentioned container will be faded in after prerollSkip/2 seconds and “lock” will turn to “unlocked” further more “prerollSkip/2” seconds later. At this point the container will become clickable.

prerollSkipHtml (String:'%{secs}')

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

The title to set for preroll ads.

Configuration parameters - [addplugins (Array:[])]

operator — Fri, 11 May 2012 15:45:43 +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. Those playlists can either be “XML” or “JSON formatted and should follow the Projekktor playlist scheme.

Nevertheless it´s possible to read different 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.

cssClassPrefix (String:'pp')

Prefix added to all css-classnames used by the player in order to avoid conflicts with existing CSS.1

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 the and interact with a given media object. 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 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 let´s say we have a <video>-capable browser featuring the H.264 codec and with 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.

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.

playlist (Array:[])

An array of objects featuring 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.

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

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

  
  // flash & native:
  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 (%{file}) could not be loaded because the server or network failed.',
  5:'Sorry, your browser does not support the media format of the requested file (%{type}).',
  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.',
  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.

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

enableFlashFallback (Boolean: true)

~~subject for changes Enable / Disable Flash fallback.~~ OBSOLETE

enableNativePlayback (Boolean: true)

~~subject for changes Enable / Disable native media playback.~~ OBSOLETE

enableNativePlatform, enableFlashPlatform (Boolean: true)

Enable / Disable different playback methods. The most common ones are “native” (for the <video> and <audio> tags) and Flash. Setting “enable<platformname>Platform” to false is equal to strip a platform from the ”platform” config array.

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.

enableNativeFullscreen (Boolean: true)

Enable / Disable true HTML fullscreen.

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

Javascript API Functions - [player.setStop():Boolean]

operator — Thu, 10 May 2012 14:48:18 +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.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):Object

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().

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.getCanPlayNatively(mediaTypes:Array):Boolean

Used without parameter this method returns TRUE if the client browser is able to play back at least one media type natively. If mediaTypes parameter is set the test is performed for every media type provided and will return TRUE if one or more types specified can be played back natively.

E.g.: ['video/ogg', 'video/webm']) will return TRUE in Chrome and TRUE in FF ⇐9 but ['video/webm']) will return TRUE in Chrome only.

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 getItems('*').

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).

Cue Points - [The Cuepoint Object]

operator — Thu, 10 May 2012 11:32:20 +0200

This docu is work in progress. Sorry about that.

Cue Points

General

Projekktor features setting of “cuepoints” which can be set through playlists or by calling API functions.

Cuepoints trigger custom callback functions depending on the current time index (the playhead position) of the player. Furthermore they can be grabed via the player´s JS API e.g. in order to create visual chapter indexes.

The Cuepoint Object

{
id: 'words1',
item: '*',
group: 'cue3',
on: '00:01',
off: '00:09',
value: 'hallo baby',
callback: function() {alert("trigger me, babe"}
}

Setting Cuepoints via the API

Setting Cuepoints via Playlists

Plugins

operator — Thu, 03 May 2012 09:27:44 +0200

Plugins

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.

R

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

T

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

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.

Quality Toggle - created

operator — Fri, 27 Apr 2012 18:55:07 +0200

Quality Toggle

General

Configuration

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

Setup

Display Plugin - [Config Options]

operator — Wed, 25 Apr 2012 15:19:43 +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 methor 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 methor 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 methor 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 by horizontally stacked icon-animation-frames / stills. 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).

logoImage(String: ''}

Full qualified URL to an optional logo-image. Preferably this should be a transpatent PNG but, well, it´s up to you.

logoDelay(Integer: 1}

If “logoDelay” is > 0 the logo will smoothly fade in at the givin playhead position. Also the logo will fade out “logoDelay” seconds prior end of video.

logoPosition(String: 'tl'}

The position of the logo can be set here. Contrary CSS direcives will be overwritten. Possible values are:

“tl” for “top left”
“tr” for “top right”
“br” for “bottom right”
“bl” for “bottom left”

logoClick(Object: {callback: '', value: null}}

Triggeres “callback” in case the logo image is beeing clicked. “callback” can either be a Projekktor API methor or a custom function.

Controlbar Plugin - [Config Options]

operator — Tue, 24 Apr 2012 10:56:57 +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).

disableFade(Boolean: false} *

If set “true” the controls-container won´t fade away after “fadeDelay” seconds but stay persistent during playback.

fadeDelay(Integer: 10000}

If “disableFade” is “false” the controls-container will fade away after “fadeDelay” milliseconds without any 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 make the controls-container visible right after the player begins playback. Will fade away if “disableFade” is not “false” after “fadeDelay” milliseconds.

showOnIdle(Boolean: false}

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

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.

Projekktor Theming - [Customizing the Controlbar´s Layout]

operator — Tue, 24 Apr 2012 09:38:58 +0200

Projekktor Theming

Preamble

In fact, when ever we talk about “theming” we talk about editing the player´s CSS and optional applying selected configuration options to one or more plugins - e.g. the “controlbar”-plugin.

For your understanding: A bare Projekktor does not require any “theming”. Its not more or less than a <div> container where all the media stuff is injected into. Nevertheless plugins (which are in terms of the MCV-pattern “views”) usually add DOM-containers to the player´s container or somewhere else on the page.

The official packed Projekktor distribution features two built-in plugins: Controlbar and Display. So theming this distributions usually end up a customized CSS file replacing the default “theme/style.css” and sometimes providing custom config parameters for one or both of the mentioned plugins.

Customizing the Controlbar´s Layout

Ok, let´s have a look on the default controlbar template. You can alter it by setting the plugin_controlbar.controlsTemplate config parameters:

<ul class="left"><li><div %{play}></div><div %{pause}></div></li><li><div %{title}></div></li></ul><ul class="right"><li><div %{fsexit}></div><div %{fsenter}></div></li><li><div %{vmax}></div></li><li><div %{vslider}><div %{vmarker}></div><div %{vknob}></div></div></div></li><li><div %{mute}></div></li><li><div %{timeleft}>%{hr_elp}:%{min_elp}:%{sec_elp} | %{hr_dur}:%{min_dur}:%{sec_dur}</div></li><li><div %{next}></div></li><li><div %{prev}></div></li></ul><ul class="bottom"><li><div %{scrubber}><div %{loaded}></div><div %{playhead}></div><div %{scrubberdrag}></div></div></li></ul>

It looks more complex than it actually is. This is because all carriage returns, tabs and so on has been stripped out. Let´s get them back in:

<ul class="left">
   <li><div %{play}></div><div %{pause}></div></li>
   <li><div %{title}></div></li>
</ul>

<ul class="right">
   <li><div %{fsexit}></div><div %{fsenter}></div></li>
   <li><div %{vmax}></div></li>
   <li><div %{vslider}><div %{vmarker}></div><div %{vknob}></div></div></div></li>
   <li><div %{mute}></div></li>
   <li><div %{timeleft}>%{hr_elp}:%{min_elp}:%{sec_elp} | %{hr_dur}:%{min_dur}:%{sec_dur}</div></li>
   <li><div %{next}></div></li>
   <li><div %{prev}></div></li>
</ul>

<ul class="bottom">
  <li><div %{scrubber}><div %{loaded}></div><div %{playhead}></div><div %{scrubberdrag}></div></div></li>
</ul>

Ah, much better. But a little bit cryptic, though. Of course you noted the ”%{}”-tags. And of course they are just place-holders which are overwritten during runtime. Assumed you have a player having the cssClassPrefix set to pp (which is the default) the controlbar plugin would generate the following HTML based on the above template - the timecodes are just examples of course:

<ul class="ppleft">
   <li><div class="ppplay"></div><div class="pppause"></div></li>
   <li><div class="pptitle"></div></li>
</ul>

<ul class="ppright">
   <li><div class="ppfsexit"></div><div class="ppfsenter"></div></li>
   <li><div class="ppvmax"></div></li>
   <li><div class="ppvslider"><div class="ppvmarker"></div><div class="ppvknob"></div></div></div></li>
   <li><div class="ppmute"></div></li>
   <li><div class="pptimeleft">00:30:12 | 00:33:44</div></li>
   <li><div class="ppnext"></div></li>
   <li><div class="ppprev"></div></li>
</ul>

<ul class="ppbottom">
  <li><div class="ppscrubber"><div class="pploaded"></div><div class="ppplayhead"></div><div class="ppscrubberdrag"></div></div></li>
</ul>

Dedicated Tags

The following tags are replaced by class attributes and are bound to specific controlbar functions. Eg.

<div %{play}>PLAY</div>

will become

<div class="ppplay">PLAY</div>

and will be bound to a “click” handler which causes the player to start playback once triggered.

tag var	Usage / Description
playhead	Area indicating the current playhead position / current timeindex in percent of the total duration - “width”-style is set accordingly.
loaded	Area indicating how much of the media file has been loaded in percent - “width”-style is set accordingly.
scrubber	Wrapper for the playhead & loaded marker
scrubberdrag	A knob which enables “live scrubbing”
play	The play-button. Is visible if player is paused, invisible elsewise.
pause	The pause-button. Is visible if player is playing, invisible if paused.
stop	The stop-button.
prev	“Previous” button
next	“Next” button
rewind	“Rewind” button (-5 secs. scrubbing, decreasing)
Forward	“Forward” button (+5 secs. scrubbing, increasing)
fsexit	Exit fullscreen button. Is invisible if player is in fullscreen mode.
fsenter	Enter fullscreen button. Is invisible if player is NOT in fullscreen mode.
loquality	Set the playback quality to an alternate, lower one.
hiquality	Sets the playback quality to the highest possible (and configured) one.
vslider	Wrapper for the “Volume Marker” vmarker and vknob.
vmarker	Area indicating the current volume in percent - “width”-style is set accordinigly.
vknob	The knob which can be dragged and dropped by the user in order to set the volume.
mute	The mute-button - sets volume to 0 when clicked.
unmute	The unmute-button - sets volume to the one prior muting.
vmax	The mute-button - sets volume to 100 when clicked.
title	Once an item starts playback, the innerHTML of this is filled with the current item´s title.
draghandle	If used the whole controlbar can be dragged and drop within boundaries of the media display.
open
close
loopon
loopoff

Timecode Tags

tag var	Usage / Description
sec_dur	The seconds string of the current media element´s total duration. E.g. if duration is 130 seconds, sec_dur=10, if duration is 60 seconds, sec_dur=00, if duration is 30 seconds, sec_dur=30
min_dur	The minutes string of the current media element´s total duration. E.g. if duration is 130 seconds, min_dur=02, if duration is 60 seconds, min_dur=01, if duration is 30 seconds, min_dur=00
hr_dur	The hours string of the current media element´s total duration. E.g. if duration is 130 seconds, hr_dur=00, if duration is 3600 seconds, hr_dur=01, if duration is 4000 seconds, hr_dur=01
sec_elp	Follows the same scheme like 'sec_dur' but is based on the media time elapsed
min_elp	Follows the same scheme like 'min_dur' but is based on the media time elapsed
hr_elp	Follows the same scheme like 'hr_dur' but is based on the media time elapsed
sec_rem	Follows the same scheme like 'sec_dur' but is based on the media time remaining.
min_rem	Follows the same scheme like 'min_dur' but is based on the media time remaining.
hr_rem	Follows the same scheme like 'hr_dur' but is based on the media time remaining.

This way you can use a template string like this:

'duration: %{hr_dur}:%{min_dur}:%{sec_dur} | remaining: %{hr_rem}:%{min_rem}:%{sec_rem}'

Assumed you have a media file with a duration of 5.640 seconds (94 minutes), after 228 seconds of playback the above string will end up in this:

'duration: 01:34:00 | remaining: 01:30:12'

Open Tags

All tags which are not recognized as “dedicated”- or “timecode”- tags can be used for what ever you want to. %{myname} will become 'class=“ppmyname”', %{foo} will become 'class=“ppfoo”' and so on. As such you get classes taking the cssClassPrefix-config-option into consideration.

Customizing the CSS

… is easy. As stated above all layout relevant stuff getting to live by a player instance is managed via plugins. Once you know the class-names of plugin-generated containers you can pimp them via CSS. From this point of view the CSS bundled with the official distribution is a CSS designing the output of the “controlbar-” and “display-” plugins.

To simplify things a little all class-names are prefixed with “pp” (which is a short for “Projekktor Player”). This prefix can be reconfigured for each installation but most people use the default “pp” one. Those who don´t should care for the relevant CSS changes for themselves.

Below the classes used in the official distro - without prefix:

classname	Description
playhead	Area indicating the current playhead position / current timeindex in percent of the total duration - “width”-style is set accordingly.
loaded	Area indicating how much of the media file has been loaded in percent - “width”-style is set accordingly.
scrubber	Wrapper for the playhead & loaded marker
scrubberdrag	A knob which enables “live scrubbing”
play	The play-button. Is visible if player is paused, invisible elsewise.
pause	The pause-button. Is visible if player is playing, invisible if paused.
prev	“Previous” button
fsexit	Exit fullscreen button. Is invisible if player is in fullscreen mode.
fsenter	Enter fullscreen button. Is invisible if player is NOT in fullscreen mode.
vslider	Wrapper for the “Volume Marker” vmarker and vknob.
vmarker	Area indicating the current volume in percent - “width”-style is set accordinigly.
vknob	The knob which can be dragged and dropped by the user in order to set the volume.
mute	The mute-button - sets volume to 0 when clicked.
vmax	The mute-button - sets volume to 100 when clicked.
title	Once an item starts playback, the innerHTML of this is filled with the current item´s title.
start	The startbutton showing up during IDLE
buffering	The buffer-indicator

Projekktor-izing Anything

… a very cool but complex feature to be described later.

Share your Work

If you made a theme for your own why not give us a note? We like totally love to see new themes and we would be proud to featured yours in our download section. ZIP all relevant files and post a link to the archive to your forum. Don´t forget to provide your name and URL to your homepage. Please note that we will only re-publish themes which are under GPL.

Building Projekktor from Source - [The Controller and Tools]

operator — Thu, 19 Apr 2012 14:06:24 +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 their 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)

SPEAKKER - The Free HTML5 Audio Player - [SPEAKKER - The Free HTML5 Audio Player]

operator — Wed, 28 Mar 2012 15:29:11 +0200

SPEAKKER - The Free HTML5 Audio Player

You don´t know what Speakker is? Go here to learn more.

AS OF March, 28th 2012 THIS DOC is outdated and currently being rewritten. Sorry for any inconveniences.

Quick Install Guide

Mounting Speakker into any website is quick and very straight forward:

Make sure your page loads jQuery V1.4.2 or higher
Upload the “speakker”-folder of the download archive to your site. Make sure this includes all directories and files within. Speakker will automatically load it´s flash fallback component files from there.
Inlude the “projekktor.min.js”.
Inlude the “speakker.min.js”.
Inlude “speakker.css” and “mspeakker.css”
Create an empty DOM container where you want the player to sit on.
Instantiate as described below.
Done.

Something similar to this should be in your page´s header now:

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

<!-- INCLUDE SPEAKKER -->
<link rel="stylesheet" href="speakker/css/speakker.css" type="text/css" media="screen">
<link rel="stylesheet" href="speakker/css/mspeakker.css" type="text/css" media="screen">
<script type="text/javascript" src="speakker/projekktor.min.js"></script> 
<script type="text/javascript" src="speakker/speakker.min.js"></script> 
<!-- That´s it -->

Instantiating the tiny Player

Assumed you´ve something like this somewhere in your markup:

<div class="speakkerSmall"></div>

You can bring up the small version of the player with this:

<script type="text/javascript">
$(document).ready(function() {	
	$('.speakkerSmall').speakker({
		file: 'http://url/toyour/music.mp3',
		title: 'one single MP3',
		theme: 'light',
		poster: 'cover.jpg'
	});
</script>

Instantiating the Big Boy

The small Speakker is nice but the big one rocks. It´s designed for playlists. That´s why we want to focus on setting up a playlist driven instance here. Playlists will work for the tiny variant also - but who cares.

To bring up the big sticky Speakker just use $().speakker (without a selector) as shown below. The script will generate the necessary DOM elements and will glue the player to the bottom of the page.

<script type="text/javascript">
$(document).ready(function() {
	$().speakker({
		file: 'http://www.speakker.com/opentape/code/projekktor.php',
		playlist: true,
		theme: 'light',
		admin: 'http://www.speakker.com/opentape/code/login.php',
		lastfm: 'http://www.lastfm.de/music/paniq'
	});
});
</script>

As you can see file does not point to an OGV or MP3 but to a PHP file. This is where the JSON playlist is generated. To learn more about playlists please refer the Projekktor Playlist Docu. To get a first insight just open the mentioned PHP to see what it pumps out: http://www.speakker.com/opentape/code/projekktor.php

You can´t apply http://www.speakker.com/opentape/code/projekktor.php to your local test installation or within a page at an other domain due to Javascript security restrictions.

To avoid frustration and strange results let Speakker know that you feed him with a playlist by setting playlist to TRUE.

Et voila… and yes, it is that easy.

Optionally the big player variant features three custom links: “lastfm”, “wikipedia” and “admin”. Setting values for them will enable the corresponding GUI elements.

Config Parameters

file (string): URL to a single audio file or a projekktor playlist holding one or more
playlist (boolean): Load “file” as JSON playlist on TRUE. Assume a single audio file otherwise.
poster (string): The default poster / cover for the given file.
title (string): The player´s title used on single file playback.
theme (string): Use “dark” or “light” color scheme.
fat (boolean): Makes the sticky playlist player even bigger if set to TRUE.
wikipedia (string): URL to the artist´s Wikipedia page if any.
lastfm (string): URL to the artist´s last.fm page if any.
admin (string): URL to the admin backend if any.

Player Events

operator — Wed, 07 Mar 2012 10:09:27 +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.

starting

The player got triggered to start and synchronizes the model with the controller.

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 begins playback for the very first time and initializes. This may be either if “autoplay” is FALSE and the user clicked “start” or the player is configured to AUTOPLAY and starts automatically.

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.

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

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

unmute

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

resume

(> V0.9.05) 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.

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

The user moved the mouse pointer over the player instance.

leftclick / rightclick / middleclick (Click:event

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

mouseleave

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

key (KeydownEvent:event)

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”

Related Plugin - [Config Options]

operator — Fri, 02 Mar 2012 11:34:18 +0200

Related Plugin

General

Provides a “related videos” and “share me” postroll display.

Install / Preparation

Scripts

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

HTML

No preparations required. Loads directly into the player´s DOM.

CSS

Include the “projekktor.related.css” to your page´s <head> or copy and paste the mentioned CSS into your theme.css. Alter at will.

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: ['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'}
            ]
       }
   }
   
});

Config Options

showOnStart (Boolean:false)

Display the “related”-panel right after the player initialize and before starting any video. Useful during CSS customization.

related (Object)

Holds the setup for the “related videos” lineup.

related.enable (Boolean:true)

Enable / Disable related items.

related.title (String:'Related Videos')

The headline for all related items.

related.items (Array:[])

An array of items to show within the “related videos” section. E.g.:

[
  {poster: 'http://www.img.com/img1.jpg', url: 'http://www.projekktor.com/vid1', title:'Title 1'}, 
  {poster: 'http://www.img.com/img2.jpg', url: 'http://www.projekktor.com/vid2', title:'Title 2'},
  {poster: 'http://www.img.com/img3.jpg', url: 'http://www.projekktor.com/vid3', title:'Title 3'} 
]

share (Object)

Holds the setup for the link to provide for content sharing.

share.enable (Boolean:true)

Enable / Disable the link-share-textarea.

share.title (String:'Link to this Video')

The headline for the shared URL.

share.code (String:'http://%{playerurl}?vidid=%{ID}')

The URL to provide as “shared URL”. You can use two placeholders here to make the player generate the string automatically.

%{playerurl} will get replaced by the window.location.href of the affected player instance. Note that this will be the iframe-URL for embeddable players.

%{ID} will be replaced either by a randomly generated string of 8 characters or by an ID you specified in your playlist setup by setting “id” within the item specific config block.

embed(Object)

Holds the setup for the shareable embed code.

embed.enable (Boolean:true)

Enable / Disable the embed-code-textarea.

embed.title (String:'Embed this Video')

The headline for embedding.

embed.code (String:'<iframe id="%{embedid}" src="%{playerurl}?vidid=%{ID}" width="640" height="385" frameborder="0" </iframe>')

The code build the embed code from.

%{playerurl} will get replaced by the window.location.href of the affected player instance. Note that this will be the iframe-URL for embeddable players.

%{embedid} will be replaced by the iframe-ID as defined in the parent window.

%{ID} will be replaced either by a randomly generated string of 8 characters or by an ID you specified in your playlist setup by setting “id” within the item specific config blo

replay(Object)

Holds the setup for the “related videos” lineup.

replay.enable (Boolean:true)

Enable / Disable the replay-button.

replay.title (String:'Embed this Video')

Title for the very same button.

General F.A.Q. - [Where can I find the release roadmap of this project?]

operator — Tue, 24 Jan 2012 13:19:15 +0200

General F.A.Q.

Where can I find the release roadmap of this project?

Projekktor releases are published spontaneously. This is (still) 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 does the fullscreen button just make the player fill my browser window and the scrollbars disappear?

In some browsers “Fullscreen” is “full viewport” only because they don´t (yet) support HTML fullscreen. Due to the underlying least common denominator principle Flash- and HTML5- fullscreen are handled the same way.

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.

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

This is a known issue with some browsers. Some browsers initialize their 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 instantly for a glimpse, stop and the new Projekktor instance is started. This behavior causes some interesting effects but most of time this ends up in a total mess.

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

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

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.” So, Jarisplayer can be used to stream progressively and has very basic RTMP support. There are 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.

Browser Issues - IE6, IE7, IE8

The theme / layout / video overlays / subtitles / (...) 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 environmentsand especially for more recent Internet Explorer´s is painful enough.

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

<audio> and <video> tags are not natively supported in IE7+8 and Projekktor uses a dirty trick to bypass this. Unfortunately this trick doesn´t work if the tag is wrapped by an other DOM container, make sure it´s a block styled one and under no circumstances a <p>aragraph.

iPhone, iPad and iPod Issues

I applied the autoplay config option as described above but it does not work in iPhone, iPad, and iPod - what´s wrong?

Simply forget it. Autostart video and audio playback doesn´t work on the mentioned devices. This is not a bug but a limitation by Apple. Most likely this is to protect the users from enervating ads and similar spam and to save battery power.

You said autoplay doesn´t work in iPad, iPhone and so on, 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.

Firefox Issues

If player is in Flash mode (fallback or Youtube) the video restarts on fullscreen toggle. WTF?

This happens thanx to an ancient bug which forces any embedded Flash object to reinitialize in some very special situations. Projekktor unfortunately forces such a situation while expanding the flash fallback component to full viewport. There is a basic workaround implemented but the general issue persists. As such any MP4 and MP3 will restart from the very beginning when ever the user toggles fullscreen. Please refer to bugzilla for detailed information about this.

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.

General Playback Issues F.A.Q.

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

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?

Firefox´ native player requires proper type header responses by 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

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 media 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.

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.

Minimum requirements for a Flash Fallback Component - [Events]

operator — Mon, 16 Jan 2012 18:29:36 +0200

Minimum requirements for a Flash Fallback Component

Setters

The following setters must be available via ”ExternalInferface”. It´s vital that all methods get a prefix like “api_” or something to avoid issues in some browsers. E.g. ”addListener” should become “api_addListener”. None of the methods should return any value as all interactions (except addListener and removeListeners) must result in at least one event.

addListener(<Event:String>, <Javascript Call to trigger:String>

Ads a Javascript call to the event given. E.g.: obj.api_addlistener(“volume”, “JSvolumeListener”);

removeListeners()

A method which removes all listeners added via the “addListener” method. An optional parameter which specifies the very special event to be removed is cool but not necessary.

seek(<second to seek for:Integer>)

Force the player to set the playhead to a given position. If the requested position is out of the buffered range jump to the maximum available position.

volume(<volume:Float>)

A value between 0 and 1 where 0 sets the volume, well, to zero (or muted) and 1 sets the player to full throttle.

pause()

Pauses the playback.

play()

Resumes / Starts playback.

scale(<width:Integer>, <height:Integer>, <x:Integer>, <y:integer>)

If the Flash component doesn´t listen to “stage” events and / or automatically scales the media to the maximum stage you must allow scaling through this method where the given parameters indicate the required dimensions of the video (which may be greater than the current stage) and the x,y offset to place the video in relation to the upper left corner of the movie (which may become <0 each).

Its recommended to implement this scaling mechanism right into the Flash component and allow two different types of scaling set via flashvar params: “aspectratio” and “fill”

“fill” scales the video in a way that the whole stage without changing the aspect ratio which will cause a cut image but a completely filled stage.

“aspectratio” scales the video in a way that the whole video is shown while using the maximum available stage. This may result in black areas next to or over and below the video image.

Events

Each event must trigger one (and only one) matching Javascript call set via “addListener”. Some events must provide parameters as described below.

timeupdate( {duration(Float), position(Float)} )

Triggered on every single change of playhead´s position. Shouldn´t be triggered more than twice in a second to avoid Flash´s “externalInterface”-flood-protection.

Must send and object with two properties: duration and position.

duration indicates the duration of the complete media element in seconds. position indicates the playhead´s current position.

progress( {total(integer), loaded(integer)} )

Triggered whenever the buffer got filled a little more. Shouldn´t be triggered more than twice in a second to avoid Flash´s “externalInterface”-flood-protection.

total indicates the total amount of bytes to be loaded while: loaded indicates how much of the current media has already been buffered (in bytes)

meta({videoWidth(integer), videoHight(integer))

Optionally triggered once the component received META data from the currently selected media. Should at least contain the real video dimensions then.

start()

Triggered once the component was able to successfully establish a connection to the media and began playback (not resuming).

error({code:<Error Code>})

play()

Triggered whenever the component begins or resumes playback as the result of a “play”-method call NOT due to buffering.

pause()

Triggered whenever the component pauses playback as the result of a “play”-method call / user interaction NOT due to buffering.

ended()

Triggered whenever the current media has been played back completely.

volumechange({volume:<Lautstärke 1=Voll, 0=Mute, 0.5=Halb usw.})

Triggered whenever the volume changed either as the result a user-interaction, method call or any other event.

mute() (optional)

Triggered once the player got muted.

buffering()

Triggered once the component began to buffer content.

notbuffering()

Triggered once the component stopped buffering OR has buffered enough content to continue playback.

scaled()

The video image got scaled to fit the screen.

Building Projekktor from Source - [General]

operator — Thu, 15 Dec 2011 13:52:59 +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 them one by one to your development page´s header or merge them into one file.

Including / merging ALL files will fail. Also be aware that projekktor.js MUST BE INCLUDED FIRST - after jQuery of course. In this section you´ll learn what to take care of.

Directory Structure

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

jQuery - Includes one or more incarnations of jQuery for testing purposes.
main - Holds the player´s core controller and models and basic tools.
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/main/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 an other one depending on their 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)

Using Playlists - [Asynchronously loaded Playlist Feeds]

operator — Wed, 14 Dec 2011 13:30:15 +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

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>

Make sure that your feeds are 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 must use a simple proxy on your server which passes the feed through.

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 reinitialized.

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 “text/json” or “text/xml” 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: text/xml and text/json 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.