git.sesse.net Git - kdenlive/blob - effects/README

   1 ================================
   2 ------------EFFECTS-------------
   3 ================================
   4
   5 ==========
   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.
  10 ==========
  11
  12
  13
  14 ==========
  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>
  24 08      </parameter>
  25 09      <parameter type="bool" name="enable" default="0">
  26 10              <name>Enable</name>
  27 11      </parameter>
  28 15 </effect>
  29 --------------------------------------------------------------------------------------
  30
  31 Line 1:
  32     - required to make strings used in the effect translatable
  33 Line 2:
  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)
  39 Line 3:
  40     - name of the effect that will appear to the user
  41 Line 4:
  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)
  45 Line 5:
  46     - name of the author(s) of the filter (not of the XML file ;))
  47 The rest:
  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 "paramprefix": a string to be prepended to the parameter value before passing it to MLT
  53         - attribute "default": initial value, format depends on parameter type
  54         - attribute "type": widget (GUI) to use
  55             - "fixed":
  56                 - sets a (MLT filter) parameter, but does not expose it to the user (no GUI)
  57             - "constant":
  58                 - number
  59                 - represented by a slider
  60                 - additional parameter attributes:
  61                     - "factor": (optional) values coming from MLT will be multiplied with factor
  62                     - "offset": (optional) will be added to values coming from MLT after "factor" is applied
  63                     - "min": smallest value possible (after multiplying with "factor")
  64                     - "max": largest value possible (after multiplying with "factor")
  65                     - "suffix": (optional) displayed unit of the values
  66             - "double":
  67                 - synonym for "constant"
  68             - "bool":
  69                 - true/false
  70                 - represented by a checkbox
  71             - "list":
  72                 - multiple choice
  73                 - represented by a drop-down menu
  74                 - additional parameter attribute:
  75                     - "paramlist": list of possible values separated by semicolon (no whitespaces!)
  76                 - addtional tag:
  77                     - "paramlistdisplay": (optional) list of names to use for the values separated by comma
  78             - "position":
  79                 - time stored as frame number
  80                 - represented by a slider
  81             - "color":
  82                 - color value, similar to representation HTML ("#rrggbb"/"#aarrggbb" or "0xrrggbbaa")
  83                 - represented by a button opening the KDE color dialog + a color picker button
  84                 - additional attributes:
  85                     - "alpha": (default = "0") use to enable alpha support
  86             - "keyframe":
  87                 - keyframable number
  88                 - keyframes are opt-in (only one keyframe by default -> should be prefered over "constant" whenever possible)
  89                 - works with MLT filters that utilize start/end values
  90                 - same attributes as "constant"
  91                 - additional attributes:
  92                     - "intimeline": (default = "0") parameter to preselect for editing in the timeline (only one parameter can have "1")
  93                     - "widget": (optional) GUI based on the standard keyframe GUI (possible values: "corners")
  94             - "simplekeyframe":
  95                 - works with MLT filters that use mlt_geometry for keyframe support (includes all frei0r filters)
  96                 - same attributes as "keyframe"
  97             - "geometry":
  98                 - a rectangle: postion + dimension + additional value
  99                 - works with MLT filters using mlt_geometry
 100                 - the rect can be edited on the project monitor
 101                 - additional attributes:
 102                     - "fixed": (default = "0") use to disable keyframe support
 103                     - "showrotation": (default = "0") use to enable support to 3 axis rotation
 104                     - "opacity": (default = "true") use to disable support of the opacity setting
 105             - "url":
 106                 - url/path
 107                 - represented by button to open "file open" dialog
 108             - "wipe":
 109                 - special GUI for the wipe transition makes it possible to select a direction of a slide
 110             - "addedgeometry":
 111                 - parameter linked to a "geometry" parameter
 112             - "curve":
 113                 - cubic curve editor for the frei0r color curves filter (old version)
 114             - "bezier_spline":
 115                 - cubic Bézier spline editor for the frei0r color curves filter (new version, might be reused for other filters)
 116             - "roto-spline":
 117                 - GUI for the rotoscoping filter (spline on the monitor)
 118             - "keywords":
 119                 - Text entry with a selection of possible keywords to be inserted in the text.
 120                 - additional tags:
 121                     - "keywords": list of possible keyword values separated by semicolon
 122                     - "keywordsdisplay": list of names to use for the values separated by semicolon
 123             - "fontfamily":
 124                 - Font typeface entry
 125 ==========
 126
 127 ==========
 128 Effects can be blacklisted in kdenlive/data/blacklisted_effects.txt
 129 All effects with a custom XML GUI need to be blacklisted.
 130 ==========
 131
 132 ==========
 133 Effects can be assigned to an effect category in kdenlive/data/kdenliveeffectscategory.rc.
 134 ==========
 135
 136 ==========
 137 Kdenlive parses the effect folder at each startup, so that if you have an XML file describing a new effect,
 138 just copy it to your ~/.kde/share/apps/kdenlive/effects/ folder and restart Kdenlive to enable the new effect.
 139 ==========