Keditor kplayer

From Kaltura Wiki

[edit] Overview

Kaltura’s Collaborative Media Platfrom offers a full featured online collaborative video editing system that allows users to do with audio, video, and animation what Wiki platforms allow them to do with text.

The online editor, or Keditor, is the main authoring environment of the platform. Combined with a player called KPlayer that can play collaborative videos, the collaborative rich-media creations authored using Kaltura’s platform can be embedded anywhere on the web.

For core developers, Keditor is available as an open-source software project (written on top of Adobe® Flex®).

For non-core developers, Keditor offers an extensions framework that allows non-experts to ad functionalities like transitions, overlays, dynamic layers and effects to the video.

Using this extensions framework which leverages an extensive XML sequence description language, Keditor can be extended and integrated into any 3rd party system quickly and easily. Using a modules based plugins framework, Keditor utilizes the Adobe® Flash® Player 9 platform abilities to deliver endless possibilities of creative video components such as transitions, overlays, and many types of video effects.

Even more, you can modify it, personalize it and extend it easily and without being an expert developerKeditor can be used for simple video mash-ups as easily as it can be used as a full featured editor that replaces offline software. In addition, the sequence description language used by Keditor can accommodate dynamic data feeds and allows automatic creation of collaborative videos.

[edit] Feature List

[edit] Main timeline Media assets

1. Video, Audio and Voice clips
   • Duplicate – use the same clips multiple times in the same show.
   • Split – cut a clip into two different clips to be placed in show.
   • Precise trimming – cut the clip in a precision of 0.16 of a second.
   • Freeze single frame – the ability to take a single snapshot from a video clip and use as image.
   • Audio control –
     • Precise volume points UI to allow the editor to determine the clip's volume level anytime during play.
     • Overall volume slider to easily set the volume level of the entire clip.
     • Extract only audio or video – turn a video clip to audio clip or mute the volume completely.
   • Time control – make changes to pitch and speed to play faster or slower (Future release).
   • Voice can be recorded while playing to allow an easy way for dubbing (voice commentary).
2. Image, Vector (swf / svg) and Solid Color clips –
   • Crop.
   • Resize.
   • Rotate.
   • Determine time on the sequence.
   • Duplicate.

[edit] Plugin assets

Plugin assets are flex modules that can be created by extending the plugin framework of Keditor & Kplayer. Plugins are divided into three types;

• Plugins that add an extra timeline to load asset into overlays
• Plugins that change the how the visual elements are being presented effects
• Plugins that define how the sequence will transition from one clip to the next clip.

1. Overlays – defines an extra "clip independent timeline" over the main timeline. Overlays can load any asset, and change all properties accessible by ActionScript®.
   Default overlays defined by Keditor:
   • Text overlays – provides the ability to place custom text messages, subtitles, animated texts and even Dynamic loaded text data (such as RSS feeds) over the video sequence.
   • Graphics overlay – provides a simple way to load any clip to an extra timeline that will be shown over the main timeline sequence.
   • Keying and Masking – provides a way to mask out a key color from a clip, or to hide potion of the clip on the main timeline or over a loaded asset in the overlay.
   • Animated overlays – simple animations like snow or leaves falling over the main timeline.
2. Effects – defines a way to perform bitmap manipulations on the way the main timeline is shown.
   Default effects defined by Keditor:
   • Color control - provides the ability to change different color components in the main timeline.
     • Saturation, Hue, Brightness and Contrast.
     • Colorize.
     • Perform average.
     • Invert colors.
     • Color threshold.
     • Randomize color pixels.
     • Black / White, Speia, effect...
   • Displacement – provides a way to displace an object according to predefined map (ie. Fisheye, wrap, pinch…).
   • Convolution – provides a way to distort the main timeline frames (ie. blurring, edge detection, sharpening, embossing, and beveling).
3. Transitions – define the way the sequence will transform from one clip to another. Transitions are practically a type of effect that is applied to the main timeline only between two clips. (ie. Cross-dissolve, wipe and shrinking-circle…).

[edit] Pre-made sub schemes

1. The ability to add to the sequence a pre made edited sequences, such as intros, fins.
2. Credits – provides an automatic way to add in the end of the Kaltura Video a credits roll with the names of all users who contributed to the Kaltura Video.
3. Chapters (Future Release) – the ability to link between chapters to create a Kaltura Video that is a part of a series.

[edit] Supported File types

Utilizing Adobe® Flash® Player 9 and ActionScript 3, Keditor & Kplayer supports the following types of media:

[edit] Platform

Kaltura's platfrom is offered to 3rd party's as an open source library of widgets designed to run on Adobe® Flash® Player 9. The library is supported by an extensive backend set of web-services.

The client side requires a standard web-browser with the Adobe® Flash® Player 9 plugin or Adobe Integrated Runtime . The Server (backend) is based on PHP and is hosted at Kaltura's global data center.

[edit] Data Flow

The format used to pass metadata between the keditor, kplayer and the server is XML. Content is passed between the client and server as follows:

1. Uploading – when uploading a media asset, Kaltura will save three versions of that asset:
   • The original asset, untouched.
   • Videos:
     • Will be converted to flv file type.
     • Low quality, densely keyframed (videos) version to be used while editing (Keditor).
     • High quality, widely keyframed (videos) version to be used while playing (Kplayer).
   • Videos:
     • Will be converted to 640x480, 75% jpeg file.
2. Before playing a Kaltura Video:
   • The Video, Audio and Voice assets in the Kaltura Video will be cut (corresponding to the user generated Kaltura Video description) and combined into three pairs of streams (odd and even streams) to reduce bandwidth usage and loading time while allowing transitioning between clips.
3. When Re-Editing a Kaltura Video:
   • The Video, Audio and Voice assets will be cut and only the relevant parts of the files will be downloaded to the client to reduce bandwidth usage and loading time. When the user will ask to re-edit a clip beyond its cutting points, the original clip will be downloaded to the client for full control.

[edit] Sequence Description Language

A Kaltura Video is described by SDL - Sequence Description Language, The SDL is an XML schema of the following structure:

<xml>
	<MetaData>
		<Publish>
			<Application>'Keditor'</Application>
		</Publish>
		<SeqDuration></SeqDuration>
		<ShowVersion></ShowVersion>
	</MetaData>
	<VideoAssets>
		<EndTransition />
	</VideoAssets>
	<AudioAssets>
		<EndTransition />
	</AudioAssets>
	<VoiceAssets>
		<EndTransition />
	</VoiceAssets>
	<AudioEffects>
		<EndTransition />
	</AudioEffects>
	<Plugins>
		<Overlays></Overlays>
		<Effects></Effects>
	</Plugins>
</xml>

Tags in the basic SDL scheme are interpreted as follows:

<MetaData> contains the global definitions to identify the publisher tool used to create the SDL <Application>, the total duration of the Kaltura Video <SeqDuration> and the version of the edit <ShowVersion>.

Following the MetaData, the three basic elements that can be used to produce a video – The <VideoAsset> represents the visual elements in a video; Video, Image and Solid Color and the transitions between assets on the sequence. The <AudioAsset> represents the master sound track of the video. The <VoiceAsset> represents the voice over channel for creating dubbings or synching voice messages. The <AudioEffects> represents an extra channel for audio effects.

The <Plugins> segments of the SDL describe all the plugins used in the Kaltura Video. Plugins represents all visual or audio effects; <Overlays> from subtitles and text on top the video thorough adding extra channels of video or images and using masks or chroma keying. The <Effects> represents all transformations and manipulation applied to the video (ie. Black & White, Invert Colors…).

<EndTransition> represents any transition used between two assets; this element is positioned in the SDL inside the asset tag itself to improve SDL readability.

[edit] The Plugins Framework

[edit] Overview

Based on Adobe® Flex’s® modules framework, Keditor and Kplayer can be easily extended. Minimum requirements for writing new plugins (i.e. transitions, overlays, or effects) include basic knowledge of ActionScript and the Flex SDK & Compiler.

Plugins get access to the media library, and all the elements of the Kaltura Video sequence, such as the main timeline assets, the audio assets and the overall volume control. Plugins can also load their own data from external sources, show visual elements on-top of the main timeline and play their own audio or video assets.

Plugins exist on the timeline for a user-defined duration of time. (Note: transition plugins, however, can only exist between the start of the first asset they are applied to until the end of the next asset. (or the start of the next asset's transition).

[edit] UI Control

Plugins can implement two types of UI elements to control their own properties and behaviors:

1. A set of predefined xml components that allows the plugin to use custom UI (i.e. text input box) without the need to deal with positioning, and implementation.
2. Custom developed UI components, that extend a base class (KModule) and follows a set of rules – allow the plugin to have its own special costume UI.

Plugin UI (of either predefined or custom elements) can be presented in two parts of the Keditor interface. In both cases they are described by XML as follows:

1. The Info panel UI – a box that is displayed in the properties tab of the Keditor info panel (in the same way other media asset's properties are displayed), for example:

   <InfoPanel>
       <UIComponents>	
   	<UIComponent type="Button" id="btnPickAsset">
   		<mxAttributes label="Browse..."  width="90" height="20"/>
   	</UIComponent>			
       </UIComponents>
   </InfoPanel>

   the <UIComponents> is an xml list of <UIComponent> elements, each defines a single ui component to be shown on the panel, such as text fields, lables, slider, buttons… Each UIComponent is defined by the element <mxAttributes> that has access to all the mxml available properties of this ui component.

2. The On-Player UI panel – allows the plugin display UI elements on th e Kplayer. This can be used to allow a more precise way of resizing and positioning of elements in the video screen. A basic PlayerPanel is defined in the following example:

   <PlayerPanel>
           <UIComponents>
   		<UIComponent type="ModuleLoader" id="objectHandles">
                           <url>swf/plugins/editor/customUI/ObjectHandlesUI.swf</url>
   			<parameters>
   				<parameter name="ohX" controls="assetXPos" />
   				<parameter name="ohY" controls="assetYPos" />
   				<parameter name="angle" controls="assetRotation" />
   				<parameter name="textScaleX" controls="assetScaleX" />
   				<parameter name="textScaleY" controls="assetScaleY" />
   			</parameters>				
   		</UIComponent>		
   	</UIComponents>
   </PlayerPanel>

   The <UIComponents> is an xml list of <UIComponent> elements, each defines a single ui component to be shown on top of the player. Here in the example we demonstrate the use a custom UI component (defined by attribute type="ModuleLoader") as opposed to a predefined component used in the previous example. Both types of uicomponents share the <parameters> element that holds reference to the plugin logic property the uicomponent controls.

   The custom UI component has an extra child element: <url> the url is used to determine where the custom uicomponent plugin is should be loaded from.

[edit] Basic Plugin structure

A plugin is defined by three files –

1. plugin.swf – this is the compiled plugin module swf file.
2. restrictions.xml – a set of public properties and their restrictions. The properties defined here are properties that are saved in the SDL and the properties the Keditor and Kplayer will handle. A basic restrictions.xml file is defined in the following example:

   <definition>
   	<version>1.00</version>
   	<type>xml</type>
   	<name>The name of the plugin</name>
    
   	<restrictions>	
   		<restriction type="number" default="0">
   			<id>PropertyName</id>
   		</restriction>
   	</restrictions>
   </definition >

   <name> 

   The name of the plugin.

   <restrictions> 

   an xml list of <restriction> elements, each defines a single property and restrictions for it.

   <restriction> 

   Element is defined by the attributes:

   • type – the type of the property (Number, uint, String…).
   • default – the default value of this property.

   And the <id> element that defined the name of the property.

3. ui.xml – a set of UI components that defines what will be shown on the UI-panels as explained in last chapter "UI Control". A basic ui.xml file structure is defined in the following example:

   <definition>
   	<version>1.00</version>
   	<type>xml</type>
   	<name> The name of the plugin</name>
   	<UI>	
   		<InfoPanel>
   			<UIComponents>
   				.
   				.
   				.
   			</UIComponents>
   		</InfoPanel>
    
   		<PlayerPanel>
   			<UIComponents>
   				.
   				.
   				.
   			</UIComponents>
   		</PlayerPanel>
   	</UI>
   </definition>

[edit] Display List Architecture

During their lifetime (duration in the sequence), plugins have access to several elements: The LayersContainer (display object) –holds the main timeline elements that currently being presented in the player. Gaining access to this object allows the plugin to modify and change the way the main timeline is being presented. LayersContainer is composed of two "VSPair Layers", 'current' and 'next', the current layer is the layer that currently at the top of the display and is now the visible, while the next layer holds the objects to be displayed next when the current layer's content duration will be over. A VSPair Layer allows the plugin to access three elements;

1. The Stream – a NetStream object that has access to the currently played video (in case of an image or solid color asset, this will be null).
2. The imageSpr – A Sprite object that holds the visual elements in the Layer.
3. The ImageBD – A BitmapData object that allows access to the bitmapData of the object currently being displayed in the Layer.

[edit] Keditor Services

Keditor provides a singletone services manager. "EditorService" provides an easy and fail proof way to access editor level ui elements and services such as: gaining access to the media library in order to load assets or have control over the timeline. The EditorService make sure that a full separation is maintained, and the plugin can only "ask for the user permission" in order to have access to these elements, and will not be able to harm the users work. An example for an implemented service is the MediaSelectionService which allows access to the media library, that way a plugin can ask the user to load asset from its media library.

[TBD]

[edit] Skinning and Branding

Keditor and Kplayer are based on flex style sheets, which can be compiled into the application or loaded at runtime to change the look and feel dynamically.

The Logo in the header is loaded dynamically and can be easily set to any chosen image.

The set of UI components in Keditor can be re-structured and re-positioned to fit 3rd party needs, UI elements can also be hidden from the user to get a simpler editor or be visible to achieve more editing control.

[edit] Kplayer

Kplayer is a flex® based multi-purpose player. It can be used to play any asset that the Kaltura platform supports whether it is a Kaltura Video, a single video file, a text message, an Image or a swf animation.

Kplayer was designed to be easily embedded and customized, by providing a set of parameters to be changed in order to fit the needs of the embedding site. KPlayer has multiple ways of communicating with its container and a wide range of API's and event callbacks, as described below

[edit] Public Properties

Kplayer provides the following set of parameters that can be set using flashVars on the embed object, or during runtime using ExternalInterface setter functions or by calling the SystemManager of the loaded swf when using kplayer as loaded application inside another flex application. The parameters are:

1. useAdapTvIntegration – used to determine whether or not to show related advertisements in the player during playback.
2. textMsg – used to set the initial state of the player with a text message shown.
3. KShowID – determines the id of the kaltura show to load when the player start.
4. ShowVersion – determines the version of the show to load when the player start.
5. EntryID – determines the id of the kaltura entry (can be a Kaltura Video or any other rich media item that kaltura supports), to load when the player start.
6. KmediaType – determine the media type of the entry to be loaded, media types are as follows:

   ID	Media Type
   0	Reserved (any).
   1	Single video file (flv).
   2	Image file.
   3	Text file.
   4	HTML file.
   5	Single audio file (flv).
   6	Kaltura Video (Show) – ID of entry will be used to get data from kaltura server.
   7	Kaltura Video (XML) – an SDL of a show to be parsed, loaded and played.

7. isWidget – determine the widget type to be used, as follows:
   • isWidget = 0 – the player will be in onsite mode, non-widget.
   • isWidget = 1 – the player will be in MySpace widget mode, where it act as a widget but doesn't use any externalInterface callbacks or remote calls using NavigateURL (allowNetworking=internal and allowScriptAccess=never).
   • isWidget = 2 – the player will be in a full featured widget mode.
   in widget mode, a logo of kaltura will be presented in one of the corners of the player.
8. LogoPosition – determine on which corner to position the kaltura logo; BR = bottom right, BL = bottom left, TL = top left, TR = top right.
9. VidDuration – a way to determine a single video duration, in case the player is used as a widget that shows a single video file.
10. ShowMenuOnEnd – determine whether or not to show the Share and Embed menu in the end of the player.
11. ShowShareMenu – determine whether or not to show the Share button in the bottom right corner.
12. ForceAutoPlay – used to force behavior of auto play when the widget loads. If set, regardless of what command the widget will get after loaded, it will only play if the user clicked the play button.

[edit] External Interface callbacks

Kplayer allows 6 basic functions for its container to control: 2 functions to load a media item:

1. InsertMedia (mediaType:int, mediaURL:String, doPlayAfter:Boolean, durationVid:Number, kShowID:int = -1, thumbURL:String = ) – will get a media type and a url to load and play.
   • doPlayAfter – whether or not to play the media as soon as it's loaded.
   • durationVid – for a single video or audio file, a specified duration in seconds, if this parameter will be -1, the duration will be read from the flv metadata.
   • kShowID – the id of the kaltura that the media belongs to.
   • thumbURL – a thumbnail to show before playing.
2. InsertEntry (KshowID:int, KEntryID:int, autoPlay:Boolean) – will get a kaltura id, entry id and whether or not to play when it's loaded. All other information will be loaded from the kaltura services.

4 functions to control playback:

1. PauseMedia – will pause the currently playing media.
2. ResumeMedia – will resume playback after pause.
3. SeekToTime (seekTo:int) – will seek to the given time in milliseconds.
4. StopAllMedia – will stop all playing media and unload it from the player. After this function is called, the player will be empty from media.

[edit] Event callbacks

In addition to the set of customizing parameters and APIs, Kplayer also defines event callback that if set, will be called upon dispatching:

1. OnCreationCompleteF – A flex application takes time to initialize, during this time ExternalInterface calls cannot be performed. In order to allow an organized way of knowing when the kplayer is ready to receive calls, it is required to register to this callback. When this event is dispatched, kplayer is ready.
2. playCmdF – this event is dispatched whenever the kplayer has been asked to play.
3. pauseCmdF – this event is dispatched whenever the kplayer has been asked to pause.
4. NewThumbMarkF – this event is dispatched during playback of a Kaltura Video, whenever a new asset is shown.
5. updatePlayHeadF – this event is dispatched during playback and is used to synchronize the container with the kplayer play head.
6. updatePlayHeadInterval – this parameter will determine the intervals in which to dispatch the updatePlayHeadF callback.
7. SequenceEndCmdF – this event is called when the playback has finished.

[edit] Installation

[TBD]

[edit] Configuration

Keditor and Kplayer both reads configuration parameters at start, from a file called config.xml and is located at the same directory of the swf itself. config.xml hold the following information:

<XML>
	<DebugFromIDE> 1 </DebugFromIDE>
	<server>
		<url> www.kaltura.com </url>
		<XMLsource> server </XMLsource>
		<PluginsFolder url="swf/plugins">
			<TransitionsFolder> transitions </TransitionsFolder>
			<OverlaysFolder> overlays </OverlaysFolder>
			<EffectsFolder> effects </EffectsFolder>
		</PluginsFolder>
	</server>
	<ExtraInfo>
		<LogoURL> kalturaLogo.png </LogoURL>
	</ExtraInfo>
</XML>

<DebugFromIDE>

determines whether the components is now being debugged from the flex IDE or being loaded from production server.

<server> 

determine where the kaltura services will be loaded from, this is the address of the kaltura services server.

<XMLsource> 

This parameter determine the type of sandbox to use, whether local (local file system) or server (remote).

<PluginsFolder> 

The url attribute determine the base folder of the plugins directory from which the editor and player will be loading the plugins swf and xml files.

<TransitionsFolder> 

determine the name of the transition typed plugins inside the plugins folder.

<OverlaysFolder> 

determine the name of the overlay typed plugins inside the plugins folder.

<EffectsFolder 

determine the name of the effect typed plugins inside the plugins folder.

<ExtraInfo> 

holds any other extra data that might be used by the application.

<LogoURL> 

holds the url to the logo picture that will be shown on the upper left corner of the editor.