README.md
1# Effects (and Transitions)
2
3Kdenlive uses MLT for all video/audio effects/filters.
4For filters that provide metadata the GUI can be generated automatically.
5If the generated GUI is not sufficient a custom one can be build using a XML
6file describing the effect and its parameters.
7
8## Important notes
9* Effects can be blacklisted in `kdenlive/data/blacklisted_effects.txt`. All effects with a custom XML GUI need to be blacklisted
10
11* Effects can be added to "Main effects" list in `kdenlive/data/preferred_effects.txt`
12
13* Effects can be assigned to an effect category in `kdenlive/data/kdenliveeffectscategory.rc`.
14
15* Kdenlive parses the effect folder at each startup, so that if you have an XML file describing a new effect,
16just copy it to your `~/.kde/share/apps/kdenlive/effects/` folder and restart Kdenlive to enable the new effect.
17
18## The basic structure of a XML filter description:
19```xml
2001 <!DOCTYPE kpartgui>
2102 <effect tag="mlt_filter" id="mlt_filter_custom1">
2203 <name>Filter name</name>
2304 <description>Filter the image</description>
2405 <author>Anon</author>
2506 <parameter type="constant" name="amount" default="10" min="0" max="1000" factor="1000">
2607 <name>Amount of filtering</name>
2708 </parameter>
2809 <parameter type="bool" name="enable" default="0">
2910 <name>Enable</name>
3011 </parameter>
3115 </effect>
32```
33
34Line 1:
35* required to make strings used in the effect translatable (see [here](https://api.kde.org/frameworks/ki18n/html/prg_guide.html))
36
37Line 2:
38
39| tag name | description |
40| :------------| :------------- |
41| `tag` | MLT ("mlt_service") name of the effect (see [MLT Docs](https://www.mltframework.org/docs/)) |
42| `id` | internal kdenlive id, can be anything, but must be unique for each effect |
43| `type` | _(default = `"video"`)_ whether effect modifies video or audio (use `"audio"` then) |
44| `unique` | _(default = `"0"`)_ this effect cannot be attached multiple times to one clip (speed, fades, ...) |
45| `version` | _(optional)_ minimum version of the effect required to be available (works only if the MLT filter provides the necessary metadata) |
46| `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|
47
48Line 3:
49* name of the effect that will appear to the user
50
51Line 4:
52* Short description of the effect to be shown in the effects list
53* Additionally a <full> part can be added inside. It's content will be available in the effect stack (see [frei0r_lightgraffiti.xml](frei0r_lightgraffiti.xml) for an example):
54 * supports HTML formatting (requires the use of CDATA)
55
56Line 5:
57* name of the author(s) of the filter (not of the XML file ;))
58
59The rest:
60
61### list of tags for `<parameter>...</parameter>`
62
63| tag name | description |
64| :-------- | :------------- |
65| `name` | visible name of the parameter (depending on the GUI this parameter uses) |
66| `comment` | _(optional)_ description of the parameter (support HTML formatting) (not yet supported by all widgets) |
67
68### list of attributes for `<parameter ...>`
69| attribute name | description |
70| :------------- | :------------- |
71| `name` | MLT filter parameter name |
72| `paramprefix` | a string to be prepended to the parameter value before passing it to MLT |
73| `suffix` | a string to be appended to the parameter (for UI display only) |
74| `min` | the minimal accepted value |
75| `max` | the maximal accepted value |
76| `visualmin` | the minimal value displayed in timeline keyframes (can be > than min) |
77| `visualmax` | the maximal value displayed in timeline keyframes (can be < than max) |
78| `default` | initial value, format depends on parameter type |
79| `value` | |
80| `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 |
81| `type` | widget (GUI) to use. See section below for possible values
82
83For double values these placeholders are available:
84
85| placeholder | Header Two |
86| :------------- | :------------- |
87| `%maxWidth ` | width of the current profile |
88| `%maxHeight` | height of the current profile |
89| `%width` | synonym for `%maxWidth` |
90| `%height` | synonym for `%maxHeight` |
91| `%out` | the out position of the current item |
92| `%fade"` | the default fade duration (can be configured by the user) |
93
94
95
96#### values for attribute `type`
97
98##### `"fixed"`
99* sets a (MLT filter) parameter, but does not expose it to the user (no GUI)
100
101##### `"constant"`
102* number
103* represented by a slider
104* ###### additional parameter attributes:
105| attribute name | description |
106| :------------- | :------------- |
107| `factor` | _(optional)_ values coming from MLT will be multiplied with factor |
108| `offset` | _(optional)_ will be added to values coming from MLT after `factor` is applied |
109| `min` | smallest value possible (after multiplying with `factor`) |
110| `max` | largest value possible (after multiplying with `factor`) |
111| `suffix` | _(optional)_ displayed unit of the value
112
113
114##### `"double"`
115* synonym for `"constant"`
116
117
118##### `"bool"`
119* true/false
120* represented by a checkbox
121
122
123##### `"switch"`
124* 2 possible options defined by strings (max / min)
125* represented by a checkbox
126
127
128##### `"list"`
129* multiple choice
130* represented by a drop-down menu
131* ###### additional parameter attributes:
132| attribute name | description |
133| :------------- | :------------- |
134| `paramlist` | list of possible values separated by semicolon (no whitespaces!). Special keyword `%lumaPaths` available to show files in the applications luma directories |
135* ###### additional tags:
136| tag name | description |
137| :----------------- | :------------- |
138| `paramlistdisplay` | _(optional)_ list of names to use for the values separated by comma |
139
140
141##### `"position"`
142* time stored as frame number
143* represented by a slider
144
145
146##### `"color"`
147* color value, similar to representation HTML (`"#rrggbb"`/`"#aarrggbb"` or `"0xrrggbbaa"`)
148* represented by a button opening the KDE color dialog + a color picker button
149* ###### additional attributes:
150| attribute name | description |
151| :------------- | :------------- |
152| `alpha` | _(default = `"0"`)_ use to enable alpha support |
153
154
155##### `"keyframe"`
156* keyframable number
157* keyframes are opt-in (only one keyframe by default -> should be preferred over "constant" whenever possible)
158* works with MLT filters that utilize start/end values
159* same attributes as "constant"
160* ###### additional attributes:
161| attribute name | description |
162| :------------- | :------------- |
163| `factor` | _(optional)_ values coming from MLT will be multiplied with factor |
164| `intimeline` | _(default = `"0"`)_ parameter to preselect for editing in the timeline (only one parameter can have `"1"`) |
165| `widget` | _(optional)_ GUI based on the standard keyframe GUI (possible values: `"corners"`) |
166
167
168##### `"simplekeyframe"`
169* works with MLT filters that use mlt_geometry for keyframe support (includes all frei0r filters)
170* same attributes as "keyframe"
171
172
173##### `"geometry"`
174* a rectangle: position + dimension + additional value
175* works with MLT filters using mlt_geometry
176* the rect can be edited on the project monitor
177* ###### additional attributes:
178| attribute name | description |
179| :------------- | :------------- |
180| `fixed` | _(default = `"0"`)_ use to disable keyframe support |
181| `showrotation` | _(default = `"0"`)_ use to enable support to 3 axis rotation |
182| `opacity` | _(default = `"true"`)_ use to disable support of the opacity setting |
183
184You can set `default` to `"adjustcenter"` to adjust the geometry to the frame size
185
186
187##### `"url"`
188* url/path
189* represented by button to open "file open" dialog
190* ###### additional attributes:
191| attribute name | description |
192| :------------- | :------------- |
193| `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"` |
194| `mode` | _(optional)_ Default is empty = open. `"save"` means none-exsisting files can be selected and gui label is "save"
195
196<!-- Attention if you see this comment (i.e. your editor does not support markdown), note that the string above is probably not show right. Please consider "*.cpp *.cc *.C|C++ Source Files\n*.h *.H|Header" to be right -->
197
198
199##### `"urllist"`
200* url/path
201* 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)
202* ###### additional attributes:
203| attribute name | description |
204| :------------- | :------------- |
205| `filter` | Filter for file extensions. Example : `"Source Files (*.cpp *.cc *.C);;Header files (*.h *.H)"` (warning: this format is different to `url`!) |
206| `newstuff` | _(optional)_ KNewStuff config file (usually placed in `kdenlive/data` and added to to `kdenlive/src/uiresources.qrc` so the value looks like `":data/kdenlive_wipes.knsrc"`). If this is empty no download button is shown|
207| `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 |
208* ###### additional tags:
209| tag name | description |
210| :--------------- | :------------- |
211| `paramlistdisplay` | _(optional)_ list of names to use for the values separated by comma |
212
213##### `"wipe"`
214* special GUI for the wipe transition makes it possible to select a direction of a slide
215
216
217##### `"addedgeometry"`
218* parameter linked to a "geometry" parameter
219
220
221##### `"curve"`
222* cubic curve editor for the frei0r color curves filter (old version)
223
224
225##### `"bezier_spline"`
226* cubic Bézier spline editor for the frei0r color curves filter (new version, might be reused for other filters)
227
228
229##### `"roto-spline"`
230* GUI for the rotoscoping filter (spline on the monitor)
231
232
233##### `"keywords"`
234* Text entry with a selection of possible keywords to be inserted in the text.
235* ###### additional tags:
236| attribute name | description |
237| :------------- | :------------- |
238| `keywords` | list of possible keyword values separated by semicolon |
239| `keywordsdisplay` | list of names to use for the values separated by semicolon |
240
241
242##### `"fontfamily"`
243* Font typeface entry
244
245
246##### `"readonly"`
247* Data (usually an animated geometry) that can be pasted to clipboard or dragged/dropped on another geometry parameter. Cannot be modified directly by user.
248