-Effects
+================================
+------------EFFECTS-------------
+================================
-Kdenlive uses MLT for all video/audio effects. Effects in Kdenlive are now built using
-xml files describing the effect and its parameters.
+==========
+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 cusom one can be build using a XML
+file describing the effect and its parameters.
+==========
-Here is a sample effect file:
---------------------------------------------------------------------------------------
-
-1 <!DOCTYPE kpartgui>
-2 <effect tag="motion_est">
-3 <name>Auto Mask</name>
-4 <properties id="autotrack_rectangle" tag="autotrack_rectangle" />
-5 <parameter type="geometry" name="geometry" default="100,100:100x100">
-6 <name>Geometry</name>
-7 </parameter>
-8 <parameter type="bool" name="debug" default="1">
-9 <name>Debug</name>
-10 </parameter>
-11 <parameter type="bool" name="obscure" default="0">
-12 <name>Obscure</name>
-13 </parameter>
-14 </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 in the effect translatable
+Line 2:
+ - tag: MLT ("mlt_service") name of the effect
+ - 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)
+Line 3:
+ - name of the effect that will appear to the user
+Line 4:
+ - Short description of the effect to be shown in the effect list
+ - Additionally a <full> 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 of CDATA)
+Line 5:
+ - name of the author(s) of the filter (not of the XML file ;))
+The rest:
+ - list of effect parameters:
+ - tag "name": visible name of the parameter (depending on the GUI this parameter uses)
+ - tag "comment": (optional) description of the parameter (support HTML formatting) (not yet support by all widgets)
+ - attribute "name": MLT filter parameter name
+ - attribute "default": initial value, format depends on parameter type
+ - attribute "type": widget (GUI) to use
+ - "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:
+ - "factor": (optional) values coming from MLT will be multiplied with factor, values from the GUI divided by factor
+ - "min": smallest value possible (after multiplying with "factor")
+ - "max": largest value possible (after multiplying with "factor")
+ - "suffix": (optional) displayed unit of the values
+ - "double":
+ - synonym for "constant"
+ - "bool":
+ - true/false
+ - represented by a checkbox
+ - "list":
+ - multiple choice
+ - represented by a drop-down menu
+ - additional parameter attribute:
+ - "paramlist": list of possible values separated by comma (no whitespaces!)
+ - addtional tag:
+ - "paramlistdisplay": (optional) list of names to use for the values
+ - "position":
+ - time stored as frame number
+ - represented by a slider
+ - "color":
+ - color value in similar to HTML ("#rrggbb" or "0xrrggbb")
+ - represented by a button opening the KDE color dialog + a color picker button
+ - "keyframe":
+ - keyframable number
+ - keyframes are opt-in (only one keyframe by default -> should be prefered over "constant" whenever possible)
+ - works with MLT filters that utilize start/end values
+ - same attributes as "constant"
+ - additional attribute:
+ - "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: postion + dimension + additional value
+ - works with MLT filters using mlt_geometry
+ - the rect can be edited on the project monitor
+ - additional attributes:
+ - "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
+ - "url":
+ - url/path
+ - represented by button to open "file open" dialog
+ - "wipe":
+ - special GUI for the wipe transition makes it possible to select a direction of a slide
+ - "addedgeometry":
+ - parameter linked to a "geometry" parameter
+ - "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)
+==========
-Line 1 is required to have the effect and parameter names added to the translation files
-In line 2, the "tag" is the name of the mlt filter
-Line 3 is the name of the effect that will appear to the user
-Line 4 holds several effect parameters:
- id is an internal kdenlive id, can be anything, but must be unique for each effect
- tag is the "mlt_service" name of the effect
- type defines if the effect is "audio" or "video". If omitted, effect is considered as video
-
-Then, you have the parameter definitions.
-The parameter entry has the following attributes:
- type is used by Kdenlive to build the UI for this effect.
- allowed types are:
- - constant = a number, represented by a slider
- - bool = boolean value, represented as a checkbox
- - color = a color value, represented by a selectable color button
- - list = a combobox listing different strings
- - geometry = 4 different sliders for x, y, width and height values that will end up as x,y:wxh
- - position = a frame number that can be obtained from current cursor position
- - double = a number with keyframes
- - complex = only used in obscure effect, has x, y, width, height and pixellation values
-
- The integer values can have max, min and default values defined, see effect files in this folder for more examples
- the "name" parameter is the name that will be passed to MLT
-
-The "name" tag gives the parameter name as it will appear to the user
-
-Kdenlive parses the effect folder at each startup, so that if you have an xml file describing a new effect, just copy it in your ~/.kde/share/apps/kdenlive/effects/ folder and restart Kdenlive to enable the new effect.
+==========
+Effects can be blacklisted in kdenlive/data/blacklisted_effects.txt
+All effects with a custom XML GUI need to be blacklisted.
+==========
-Effects need to be blacklisted in the file kdenlive/data/blacklisted_effects.txt if they use a custom (i.e. non-default) XML GUI from this directory.
\ No newline at end of file
+==========
+Kdenlive parses the effect folder at each startup, so that if you have an XML file describing a new effect,
+just copy it in your ~/.kde/share/apps/kdenlive/effects/ folder and restart Kdenlive to enable the new effect.
+==========
projects / kdenlive / commitdiff