kdenlive/data/effects

Effects (and Transitions)

Kdenlive uses MLT for all video/audio effects/filters. For filters that provide metadata the GUI can be generated automatically. If the generated GUI is not sufficient a custom one can be build using a XML file describing the effect and its parameters.

Important notes

• Effects can be blacklisted in kdenlive/data/blacklisted_effects.txt. All effects with a custom XML GUI need to be blacklisted

• Effects can be added to "Main effects" list in kdenlive/data/preferred_effects.txt

• Effects can be assigned to an effect category in kdenlive/data/kdenliveeffectscategory.rc.

• Kdenlive parses the effect folder at each startup, so that if you have an XML file describing a new effect, just copy it to your ~/.kde/share/apps/kdenlive/effects/ folder and restart Kdenlive to enable the new effect.

The basic structure of a XML filter description:

01 <!DOCTYPE kpartgui>
02 <effect tag="mlt_filter" id="mlt_filter_custom1">
03      <name>Filter name</name>
04      <description>Filter the image</description>
05      <author>Anon</author>
06      <parameter type="constant" name="amount" default="10" min="0" max="1000" factor="1000">
07              <name>Amount of filtering</name>
08      </parameter>
09      <parameter type="bool" name="enable" default="0">
10              <name>Enable</name>
11      </parameter>
15 </effect>

Line 1:

• required to make strings used in the effect translatable (see here)

Line 2:

tag name	description
tag	MLT ("mlt_service") name of the effect (see MLT Docs)
id	internal kdenlive id, can be anything, but must be unique for each effect
type	(default = "video") whether effect modifies video or audio (use "audio" then)
unique	(default = "0") this effect cannot be attached multiple times to one clip (speed, fades, ...)
version	(optional) minimum version of the effect required to be available (works only if the MLT filter provides the necessary metadata)
dependency	(optional) ) MLT ("mlt_service") name of an effect or composition this asset depends on. If the dependency is not available this asset will not be available in Kdenlive too

Line 3:

• name of the effect that will appear to the user

Line 4:

• Short description of the effect to be shown in the effects list
• Additionally a part can be added inside. It's content will be available in the effect stack (see frei0r_lightgraffiti.xml for an example):
  • supports HTML formatting (requires the use of CDATA)

Line 5:

• name of the author(s) of the filter (not of the XML file ;))

The rest:

list of tags for <parameter>...</parameter>

tag name	description
name	visible name of the parameter (depending on the GUI this parameter uses)
comment	(optional) description of the parameter (support HTML formatting) (not yet supported by all widgets)

list of attributes for <parameter ...>

attribute name	description
name	MLT filter parameter name
paramprefix	a string to be prepended to the parameter value before passing it to MLT
suffix	a string to be appended to the parameter (for UI display only)
min	the minimal accepted value
max	the maximal accepted value
visualmin	the minimal value displayed in timeline keyframes (can be > than min)
visualmax	the maximal value displayed in timeline keyframes (can be < than max)
default	initial value, format depends on parameter type
value
optional	if it is set, it means that this parameter can have an empty value. So then loading a project, don't set its value to default
type	widget (GUI) to use. See section below for possible values

For double values these placeholders are available:

placeholder	description
%maxWidth	width of the current profile
%maxHeight	height of the current profile
%width	synonym for %maxWidth
%height	synonym for %maxHeight
%contentWidth	width of the target clip
%contentHeight	height of the target clip
%fittedContentWidth	width of the target clip scaled to fit current profile
%fittedContentHeight	height of the target clip scaled to fit current profile
%out	the out position of the current item
%fade"	the default fade duration (can be configured by the user)

values for attribute type

"fixed"

• sets a (MLT filter) parameter, but does not expose it to the user (no GUI)

"constant"

• number
• represented by a slider

• additional parameter attributes:

attribute name	description
factor	(optional) values coming from MLT will be multiplied with factor
offset	(optional) will be added to values coming from MLT after factor is applied
min	smallest value possible (after multiplying with factor)
max	largest value possible (after multiplying with factor)
suffix	(optional) displayed unit of the value

"double"

• synonym for "constant"

"bool"

• true/false
• represented by a checkbox

"switch"

• 2 possible options defined by strings (max / min)
• represented by a checkbox

"multiswitch"

• 2 possible options defined by strings (max / min)
• this special parameter type will affect 2 different parameters when changed. the name of this parameter will contain the name of the 2 final parameters, separated by a LF character: 
. Same thing for the default, min and max which will contain the values for these 2 parameters, separated by an LF character. See for example the fade_to_black effect.
• represented by a checkbox

"list"

• multiple choice
• represented by a drop-down menu

• additional parameter attributes:

attribute name	description
paramlist	list of possible values separated by semicolon (no whitespaces!). Special keyword %lumaPaths available to show files in the applications luma directories

• additional tags:

tag name	description
paramlistdisplay	(optional) list of names to use for the values separated by comma

"position"

• time stored as frame number
• represented by a slider

"color"

• color value, similar to representation HTML ("#rrggbb"/"#aarrggbb" or "0xrrggbbaa")
• represented by a button opening the KDE color dialog + a color picker button

• additional attributes:

attribute name	description
alpha	(default = "0") use to enable alpha support

"keyframe"

• keyframable number
• keyframes are opt-in (only one keyframe by default -> should be preferred over "constant" whenever possible)
• works with MLT filters that utilize start/end values
• same attributes as "constant"

• additional attributes:

attribute name	description
factor	(optional) values coming from MLT will be multiplied with factor
intimeline	(default = "0") parameter to preselect for editing in the timeline (only one parameter can have "1")
widget	(optional) GUI based on the standard keyframe GUI (possible values: "corners")

"simplekeyframe"

• works with MLT filters that use mlt_geometry for keyframe support (includes all frei0r filters)
• same attributes as "keyframe"

"geometry"

• a rectangle: position + dimension + additional value
• works with MLT filters using mlt_geometry
• the rect can be edited on the project monitor

• additional attributes:

attribute name	description
fixed	(default = "0") use to disable keyframe support
showrotation	(default = "0") use to enable support to 3 axis rotation
opacity	(default = "true") use to disable support of the opacity setting

You can set default to "adjustcenter" to adjust the geometry to the frame size

"url"

• url/path
• represented by button to open "file open" dialog

• additional attributes:

attribute name	description
filter	Filter for file extensions. Example : "*.cpp *.cc *.C|C++ Source Files\n*.h *.H|Header files" or as using MIME type: "image/png text html"
mode	(optional) Default is empty = open. "save" means none-exsisting files can be selected and gui label is "save"

"urllist"

• url/path
• represented by button to open "file open" dialog (like url) but in addition the file can be selected from a predefined list (like "list") and it has support for KNewStuff (e.g. https://store.kde.org)

• additional attributes:

attribute name	description
filter	Filter for file extensions. Example : "Source Files (*.cpp *.cc *.C);;Header files (*.h *.H)" (warning: this format is different to url!)
newstuff	(optional) KNewStuff config file (usually placed in kdenlive/data and added to kdenlive/src/uiresources.qrc so the value looks like ":data/kdenlive_wipes.knsrc"). If this is empty no download button is shown
paramlist	list of possible values separated by semicolon (no whitespaces!). Special keywords %lumaPaths and %lutPaths are available to show files in the applications luma/lut directories

• additional tags:

tag name	description
paramlistdisplay	(optional) list of names to use for the values separated by comma

"wipe"

• special GUI for the wipe transition makes it possible to select a direction of a slide

"curve"

• cubic curve editor for the frei0r color curves filter (old version)

"bezier_spline"

• cubic Bézier spline editor for the frei0r color curves filter (new version, might be reused for other filters)

"roto-spline"

• GUI for the rotoscoping filter (spline on the monitor)

"keywords"

• Text entry with a selection of possible keywords to be inserted in the text.

• additional tags:

attribute name	description
keywords	list of possible keyword values separated by semicolon
keywordsdisplay	list of names to use for the values separated by semicolon

"fontfamily"

• Font typeface entry

"readonly"

• Data (usually an animated geometry) that can be pasted to clipboard or dragged/dropped on another geometry parameter. Cannot be modified directly by user.