User Tools

Site Tools


configuration

Table of Contents

Configuration parameters

General

In general Projekktor differentiates three types of config parameters:

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 load external playlist-data (Ajax) provided in either XML or JSON -format. In case the JSON data is doesn´t follow the Projekktor playlist scheme or XML is provided you need to set this config option in order to apply a custom function which parses incoming data and returns a valid Projekktor playlist.

The function receives the incoming raw data as argument and must return a proper playlist object.

Example parsers for Youtube and media-RSS can be found here.

:!: Don´t trigger any further asynchronous operations within the callback function as 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.

Supported Platform Shorts

  • browser - handles display of general WEB fluff like images, html, javascript etc. pp.
  • ios - handles i*-device specific HLS streaming
  • android - handles HLS for android where avaiable
  • native - handles native HTML5 audio- and video playback
  • flash - handles flash fallback for ancient browsers and/or FLV playback
  • vlc - features VideoLan´s VLC Web Plugin for tons of different formats

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 TRUE 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 “null” the player will keep the destination´s container width.

width (Integer:0)

The width of the player in pixels. In case of “0” the player will keep the destination´s container width.

ratio (Float:16/9)

In case of “height” is set to “false” the player will be set “height” to match the ratio given here according to its width.

Rescaling will happen automatically in case the document window is being resized. Otherwise you need to trigger the .setSize() API-method “manually”.

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.

leaveFullscreen(Boolean:false)

Setting this to “true” the player will try to leave fullscreen once the "done" event has been fired. Reliably fails in Firefox due to some strange security restrictions (or a browser bug).

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

Options configurable for individual playlist items

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.

cat (String:'clip')

In order to structure playlists or working with ads you optionally can assign a category type for each item. By default this is “clip”.

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:'StrobeMediaPlayback.swf'), playerFlashMP3 (String:'StrobeMediaPlayback.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

configuration.txt · Last modified: 2013/12/07 11:14 by operator