1 ================================
2 ------------EFFECTS-------------
3 ================================
6 Kdenlive uses MLT for all video/audio effects/filters.
7 For filters that provide metadata the GUI can be generated automatically.
8 If the generated GUI is not sufficient a custom one can be build using a XML
9 file describing the effect and its parameters.
15 The basic structure of a XML filter description:
16 --------------------------------------------------------------------------------------
17 01 <!DOCTYPE kpartgui>
18 02 <effect tag="mlt_filter" id="mlt_filter_custom1">
19 03 <name>Filter name</name>
20 04 <description>Filter the image</description>
21 05 <author>Anon</author>
22 06 <parameter type="constant" name="amount" default="10" min="0" max="1000" factor="1000">
23 07 <name>Amount of filtering</name>
25 09 <parameter type="bool" name="enable" default="0">
26 10 <name>Enable</name>
29 --------------------------------------------------------------------------------------
32 - required to make strings used in the effect translatable
34 - tag: MLT ("mlt_service") name of the effect
35 - id: internal kdenlive id, can be anything, but must be unique for each effect
36 - type: (default = "video") whether effect modifies video or audio (use "audio" then)
37 - unique: (default = "0") this effect cannot be attached multiple times to one clip (speed, fades, ...)
38 - version: (optional) minimum version of the effect required to be available (works only if the MLT filter provides the necessary metadata)
40 - name of the effect that will appear to the user
42 - Short description of the effect to be shown in the effect list
43 - 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):
44 - supports HTML formatting (requires the use of CDATA)
46 - name of the author(s) of the filter (not of the XML file ;))
48 - list of effect parameters:
49 - tag "name": visible name of the parameter (depending on the GUI this parameter uses)
50 - tag "comment": (optional) description of the parameter (support HTML formatting) (not yet supported by all widgets)
51 - attribute "name": MLT filter parameter name
52 - attribute "default": initial value, format depends on parameter type
53 - attribute "type": widget (GUI) to use
55 - sets a (MLT filter) parameter, but does not expose it to the user (no GUI)
58 - represented by a slider
59 - additional parameter attributes:
60 - "factor": (optional) values coming from MLT will be multiplied with factor, values from the GUI divided by factor
61 - "min": smallest value possible (after multiplying with "factor")
62 - "max": largest value possible (after multiplying with "factor")
63 - "suffix": (optional) displayed unit of the values
65 - synonym for "constant"
68 - represented by a checkbox
71 - represented by a drop-down menu
72 - additional parameter attribute:
73 - "paramlist": list of possible values separated by comma (no whitespaces!)
75 - "paramlistdisplay": (optional) list of names to use for the values
77 - time stored as frame number
78 - represented by a slider
80 - color value, similar to representation HTML ("#rrggbb" or "0xrrggbb")
81 - represented by a button opening the KDE color dialog + a color picker button
84 - keyframes are opt-in (only one keyframe by default -> should be prefered over "constant" whenever possible)
85 - works with MLT filters that utilize start/end values
86 - same attributes as "constant"
87 - additional attributes:
88 - "intimeline": (default = "0") parameter to preselect for editing in the timeline (only one parameter can have "1")
89 - "widget": (optional) GUI based on the standard keyframe GUI (possible values: "corners")
91 - works with MLT filters that use mlt_geometry for keyframe support (includes all frei0r filters)
92 - same attributes as "keyframe"
94 - a rectangle: postion + dimension + additional value
95 - works with MLT filters using mlt_geometry
96 - the rect can be edited on the project monitor
97 - additional attributes:
98 - "fixed": (default = "0") use to disable keyframe support
99 - "showrotation": (default = "0") use to enable support to 3 axis rotation
100 - "opacity": (default = "true") use to disable support of the opacity setting
103 - represented by button to open "file open" dialog
105 - special GUI for the wipe transition makes it possible to select a direction of a slide
107 - parameter linked to a "geometry" parameter
109 - cubic curve editor for the frei0r color curves filter (old version)
111 - cubic Bézier spline editor for the frei0r color curves filter (new version, might be reused for other filters)
113 - GUI for the rotoscoping filter (spline on the monitor)
117 Effects can be blacklisted in kdenlive/data/blacklisted_effects.txt
118 All effects with a custom XML GUI need to be blacklisted.
122 Effects can be assigned to an effect category in kdenlive/data/kdenliveeffectscategory.rc.
126 Kdenlive parses the effect folder at each startup, so that if you have an XML file describing a new effect,
127 just copy it to your ~/.kde/share/apps/kdenlive/effects/ folder and restart Kdenlive to enable the new effect.