Video comes to life with KdpOverlaysSynch - Unveil the power of extending KDP

Introduction

The KDP provides an API that enables to extend its features via run-time loaded Flash Modules.
A KDP Flash Module is compiled swf file written in ActionScript 3 for the Flash Player 9 and above. [Read more about KDP Flash modules]
This article unviels the basic power of the dynamic nature of the KDP by going through a KDP Flash module development showcase.

The project: "KDP Overlays Synchronizer"

The KDP Flash module presented in this article is a visual layer that will be loaded on top of the media player screen and create, present and synchronize during playback various overlays types pre-defined in an external XML.

KdpOverlaysSynch Example: Interactive Video Game

KDP with KdpOverlaysSynch module sample (Soon...)

KdpOverlaysSynch XML Provider - possible visual item overlays, filters and actions

KdpOverlaysSynch module can use loaded external swf and image files, run-time created color shapes with filters or a library display object and register certain actions to the click event of each object.
The synch XML and various object, filters and actions possibilities are described below:

Position and dimensions attributes

Each item is defined with its relative position (x%, y%) and relative dimensions (width%, height%).
The values are relative to the physical width and height of the media player screen in pixels, and are defined as relative so a change in the player dimensions such as in fullscreen state will enable the items to reposition and scale accordingly.

Time attributes

Following the position and dimensions attributes, the begin and end attributes define when during playback the item should apear and disapear. The time format used is in the form of HH:MM:SS.

Type, appearance, effects and behaviours

The src, filters and actions attributes are the last set that defines the item type, appearance, applied effects and behavior.

• The src attribute defines the type and appearance of the item.
• The filters attribute define a set of visual filters that can be applied to the object.
• The actions attribute define a set of possible actions to preform when the object is click by the user mouse.

The src, filters and actions attributes are compound from the type and values and may also define multiple definitions (e.g. multiple filters for the same item).
Use the ';' sign as a seperator between the parts that define the attribute.

The src attribute

The src attribute defines the type of element to create or load and it's specific configuration settings. src attribute is defined as one of the following:

• lib;ID_OF_LIBRARY_ELEMENT
  Will create a new instance from a library class (provide the name of the class to instantiate as the ID_OF_LIBRARY_ELEMENT).
• color;HEX_VALUE_COLOR_CODE;INT_VALUE_ALPHA
  This will show a rectangle of the selected color (by hex value) and alpha (0-100)
• text;STRING_TO_SHOW;LINK;HEX_VALUE_COLOR_CODE;FONT_SIZE;FONT_NAME;FONT_WEIGHT;TEXT_ALIGN
  The size of the text is determined by the specified font size.
• url;SOME_URL_OF_ASSET
  Creates an object from a run-time loaded url (image or swf).

The actions attribute

Multiple actions can be defined within the actions attribute, use the following syntax: action1id;action1values;action2id;action2values;...;actionNid;action1Nvalues;
The actions attribute id and values can be defined as one of the following:

• playback;PLAYBACK_ACTION(value1,value2,...,valueN) - PLAYBACK_ACTION can be either of the following commands followed by the passed command values:
  
  • play
  • pause
  • seek("HH:MM:SS")
  • stop
  • changeMedia(entryId,entryVersion,autoPlay)
• url;URL_TO_NAVIGATE_TO - This will turn the item to link (when clicked the browser will open a new tab with the url specified)
• javascript;JAVASCRIPT_FUNCTION_TO_CALL(value1,value2,...,valueN) -
  
  • Call to any externalInterface function on the hosting page followed by the passed function values
• [code]newsynch;URL_OF_SYNCH_XML_FILE -
  
  • Use to load a new synch XML (usfull in cases of changeMedia that require a change to a relevant synch XML as well)
  • For example: newsynch;http://mydomain.com/newSynchItems.xml

For example, use the actions attribute to cause the player to load a new media and the plugin to load a new synch XML:
playback;changeMedia(someentryid);newsynch;http://mydomain.com/newSynchItems.xml

The filters attribute

The filters attribute can be defined in the following format:
filters="filterType1(param1,param2,...paramN);filterType2(param1,param2,...paramN);...;filterTypeN(param1,param2,...paramN);"
The filter type can be defined as one of the following possible filters and their values:

• blur
  
  • blur_x:Number = 30 - Controls the bluriness over the x axis
  • blur_y:Number = 30 - Controls the bluriness over the y axis
• glow
  
  • glow_color:uint = 0x33CCFF - Controls the color of the effect
  • alpha:Number = 0.8 - Controls the alpha (transparency) of the effect
  • blur_x:Number = 30 - Controls the bluriness over the x axis
  • blur_y:Number = 30 - Controls the bluriness over the y axis
  • strength:Number = 2 - Controls the color density of the effect
  • inner:Boolean = false - Determins whether the effect will be applied within the borders or outside the borders of the object
  • knockout:Boolean = false - Determins whether the effect cause the object to disapear and leave only the borders (contour) visible
• dropshadow
  
  • color:uint = 0x000000 - Controls the color of the effect
  • angle:Number = 45 - Controls the angle in which the effect will fall from the center of the object
  • alpha:Number = 0.8 - Controls the alpha (transparency) of the effect
  • blur_x:Number = 8 - Controls the bluriness over the x axis
  • blur_y:Number = 8 - Controls the bluriness over the y axis
  • distance:Number = 15 - Controls the pixel distance of the effect from the object's center
  • strength:Number = 0.65 - Controls the color density of the effect
  • inner:Boolean = false - Determins whether the effect will be applied within the borders or outside the borders of the object
  • knockout:Boolean = false - Determins whether the effect cause the object to disapear and leave only the borders (contour) visible

For example: filters="blur(3);dropshadow;glow(0xFF000, 0.8, 10)" -
Blur filter with blurX set to 3, blurY set to default, a DropShadow filter with all default values and a Glow filter with red color, alpha set to 0.8, blurX set to 10 and the rest of the values set to defaults.

KdpOverlaysSynch: Module blueprint

KDP Command Events

To handle the synchronization of objects in run-time the module is registered to the follwoing KDP Command Events:

• PLAYER_UPDATE_PLAYHEAD -
  The module register for this event to respond to the playback time progress.
  As the playback progress, the module orchastrate the display; add and remove various display objects.
• DO_SEEK -
  The second way playback time can change is when the user click the progress bar and seek through the media.
  The module register for this event to respond to the playback time change by the user seek action.
  As the playback time change, the module orchastrate the display; add and remove various display objects.
• FullScreen states (HAS_OPENED_FULL_SCREEN and HAS_CLOSED_FULL_SCREEN) -
  In order to maintain a "stretchable" display where the overlays position and dimentsions are always relative to the media player dimenstions, the module is registered to these events in order to react to the change in the player size and redraw the overlay items.

XML synch provider

The module provides the functionality to change the synch xml provider at run-time.
This functionality is useful in cases where sets of synch providers is required or as a more specific example when a change in media occure - usually it is also required to change the set of overlays to be relevant to the new media that was loaded.
To allow this functionality, the module implement the following methods that are being called in sequence:

• loadSynchXml - Given a url to the synch XML, will load the xml provider.
• clearAll - Being called by the loadSynchXml to remove all items currently in the display list and clearing all hash objects that are used by the synchronization process.
• completeHandler - Is the handler to the loadSynchXml XML load complete event, this method will create an XML object of the loaded XML and call the parseItems method.
• parseItems - The last method in the sequence is responsible for parsing the synch XML and create overlay item objects and items array that will be used during the synchronization process, this parsing is done to provide faster access to the items during playback (instead of traversing the XML tree in every update in playback time.

Utility functions

To provide a short syntax to the synch XML that will be both flexible and coherent, the module implemet the following utility functions:

• parseTimeString - Parses a string representation of time (in the form of: HH:MM:SS) and transform it to milliseconds (unsigned 32bit int value).
• createFunctionItem - Given a String representation of a function name and values [in the form of functionName(value1,...,valueN)] creates an object with the function id and array of its values.
• Filter creation functions (getBlurFilter, getGlowFilter, getDropShadowFilter) - helper functions to create instances of Flash Bitmap Filter to be applied on the display objects according to the defined filters attribute in the synch XML.
• String utility functions -
  
  • replace - Helper function to replace a substring in a source string with a given string.
  • trim - Helper function to remove leadings and tralings of a given character from a given string (Also use trimFront and trimBack).
    Used to remove space from the start and end of strings.
  • stringToCharacter - Given a string returns only the first character.

Display synchronization process

The module synchronize the display list during playback progress and during manual user seek action.
The method that is responsible for the synchronization process is onUpdatePlayhead.
The onUpdatePlayhead method is also being called by the manual seek action handler onSeek and by the resize handler when the KDP dimensions are changed.

The onUpdatePlayhead function

The onUpdatePlayhead handler is being called approcimately every 25ms - for every KDP PLAYER_UPDATE_PLAYHEAD event callback.
The synchronization process is divided into two parts:

• Synchronize items to be added to the display.
  This step include looping through the items array from the first to last item that its begin time is equal or smaller than the current playback time.
  Create and add to the display list the items that are not already in the display list.
• Synchronize items to be removed from the display.
  This step include looping through the items that are currently being presented in the display list and remove the items with end time smaller than the current playback time.

Validation on manual seek action and change in player dimensinos

When the user manually seek through time or the player dimensions are changed the items should be redrawn and repositioned to relate to the new playback time and dimensions.
To redraw the items, all the items are removed from the display list and the onUpdatePlayhead is being called manually, which in turn recreate all removed items according to the new time and dimensions.

Overlay items creation methods

To create the various overlay types a method for each type is implemented:

• placeColorRect - Create monochromatic colored rectangles.
• placeLibraryItem - Create instances of library defined classes.
• placeLoadedItem - Create an object that contains a loaded image or swf.
• placeTextItem - Create single line text fields.

Actions and Filters

To register various actions to the overlay items and apply visual filters the module implement the following functions:

• setItemFilters - Applies the visual filters on a given item.
• setItemActions - Register listeners to the MouseEvent.CLICK event to the following action handlers:
  
  • externalInterfaceActionHandler - Action handler that implement ExternalInterface calls.
  • urlActionHandler - Action handler that implement navigateToURL calls to open a new browser tab with a given url.
  • synchXmlLoadActionHandler - Action handler that implement loading of a new synch XML provider.
  • playbackActionHandler - Action handler that implement various playback commands; seek, changeMedia, play, pause, and more KDP commands.

Further reading

• Learn more about KDP Flash Modules and download the Sample Kit.
• Explore the KDP.

Extending KdpOverlaysSynch functionality ideas

• Integration: Usage of an animation library to provide run-time animation control of overlay items.
• Integration: Usage of an object and motion detection libraries to enable run-time creation of objects according to identified objects in the video.
• Integration: Integration with an ad server to provide real-time overlay ad injection to playing media.
• Management: Create a management KDP module that allows editing of the synch XML provider using wysiwyg tools.
• Management: Create an additional application to manage synch XMLs with interface to create subtitles.

Can you add more? :)