Commit f8d41fda authored by Julius Künzel's avatar Julius Künzel
Browse files

GIT_SILENT Update dev docs

parent 3c9fb1a0
Pipeline #51590 passed with stage
in 10 minutes and 30 seconds
================================
------------EFFECTS-------------
================================
==========
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.
==========
==========
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
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 effects 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 use 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 supported by all widgets)
- attribute "name": MLT filter parameter name
- attribute "paramprefix": a string to be prepended to the parameter value before passing it to MLT
- attribute "suffix": a string to be appended to the parameter (for UI display only)
- attribute "min": the minimal accepted value
- attribute "max": the maximal accepted value
- attribute "visualmin": the minimal value displayed in timeline keyframes (can be > than min)
- attribute "visualmax": the maximal value displayed in timeline keyframes (can be < than max)
- attribute "default": initial value, format depends on parameter type
- attribute "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
- 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
- "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 values
- "double":
- synonym for "constant"
- "bool":
- true/false
- represented by a checkbox
- "switch":
- 2 possible options defined by strings (max / min)
- represented by a checkbox
- "list":
- multiple choice
- represented by a drop-down menu
- additional parameter attribute:
- "paramlist": list of possible values separated by semicolon (no whitespaces!)
- additional tag:
- "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:
- "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:
- "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:
- "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
- additional attributes:
- "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"
- "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)
- "keywords":
- Text entry with a selection of possible keywords to be inserted in the text.
- additional tags:
- "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.
==========
==========
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.
==========
# 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:
```xml
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](https://api.kde.org/frameworks/ki18n/html/prg_guide.html))
Line 2:
| tag name | description |
| :---------| :------------- |
| `tag` | MLT ("mlt_service") name of the effect (see [MLT Docs](https://www.mltframework.org/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) |
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 <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):
* 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 |
| `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 avaible:
| placeholder | Header Two |
| :------------- | :------------- |
| `%maxWidth ` | width of the current profile |
| `%maxHeight` | height of the current profile |
| `%width` | synonym for `%maxWidth` |
| `%height` | synonym for `%maxHeight` |
| `%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
##### `"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` avaible 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 |
##### `"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"` |
<!-- 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 -->
##### `"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 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 avaible 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
##### `"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)
##### `"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.
......@@ -63,9 +63,9 @@ Each provider config files should only specify a certain media type such as `vid
| homepage | String | yes | Url pointing to the providers webpage |
| type | String | yes | one of `video`, `image`, `music`, `sound` |
| integration | String | yes | Must be `buildin` as this is the only supported value at the moment |
| clientkey | String | If OAuth2 or `%clientkey%` is used | The client key to access the api. </br>*Kdenlive has some keys build in: `%pixabay_apikey%`, `%freesound_apikey%` and `%pexels_apikey%` will be replaced by a key for the certain provider.* |
| clientkey | String | If OAuth2 or `%clientkey%` is used | The client key to access the api. </br>_Kdenlive has some keys build in: `%pixabay_apikey%`, `%freesound_apikey%` and `%pexels_apikey%` will be replaced by a key for the certain provider._ |
| downloadOAuth2 | bool | no | Whether OAuth2 authentification is need to download files
| api | Object | yes | see [Api](#Api) |
| api | Object | yes | see [Api](#api) |
## Api
The `api` object describs the api endpoints
......@@ -73,9 +73,9 @@ The `api` object describs the api endpoints
| Key | Type | Required | Description |
| :------------- | :------------- | :------------- | :------------- |
| root | String | yes | The apis base url (should *not* end with `/`) |
| oauth2 | Object | If [`downloadOAuth2`](#Base-Structure) is `true` | See [OAuth2](#OAuth2) |
| search | Object | yes | See [Search](#Search) |
| downloadUrls | Object | yes | See [Fetch Download Urls](#Fetch-Download-Urls) |
| oauth2 | Object | If [`downloadOAuth2`](#base-structure) is `true` | See [OAuth2](#oauth2) |
| search | Object | yes | See [Search](#search) |
| downloadUrls | Object | yes | See [Fetch Download Urls](#fetch-download-urls) |
### OAuth2
......@@ -90,7 +90,7 @@ The `search` object should hold the two objects `req` and `res`.
#### Request
| Key | Type | Required | Description |
| :------------- | :------------- | :------------- | :------------- |
| path | String | yes | Path to the search endpoint (appended to [`root`](#Api), should start with `/`) |
| path | String | yes | Path to the search endpoint (appended to [`root`](#api), should start with `/`) |
| method | String | yes | HTTP method. Only `GET` is supported at the moment |
| params | Array of Objects | no | List of HTTP params |
| header | Array of Objects| no | List HTTP headers |
......@@ -107,15 +107,15 @@ The objects in the arrays in `params` and `header` should contain two fields: `k
| filetype | String | no | The items filetype |
| id | String | yes | Name of the key in a list element holding the items id |
| url | String | | Url to the item to be opened in a external browser |
| licenseUrl | String | | Url to the license to be opened in a external browser. If you use a [template](#Templates), always use link to the english license version. Kdenlive can generate License names out of links to Creative Commons, Pexels and Pixabay Licenses for all other links the License name is "Unknown License". |
| licenseUrl | String | | Url to the license to be opened in a external browser. If you use a [template](#templates), always use link to the english license version. Kdenlive can generate License names out of links to Creative Commons, Pexels and Pixabay Licenses for all other links the License name is "Unknown License". |
| description | String | no | Description of the item |
| author | String | no | Name of the items author |
| authorUrl | String | no | Link to the items authors page to be opened in a external browser |
| duration | String | no | Duration of the item (for video and audio)|
| width | String | no | Width of the item (for video and image) |
| height | String | no | Height of the item (for video and image) |
| downloadUrl | String | no, if `downloadUrls` or [Fetch Download Urls](#Fetch-Download-Urls) | To be used when there is only one download url (i.e. one file version) for the item |
| downloadUrls | Object | no, if `downloadUrl` or [Fetch Download Urls](#Fetch-Download-Urls) | To be used when there are multiple download url (i.e. one file version) for the item. See description in [table](#Mutliple-Download-Urls) below |
| downloadUrl | String | no, if `downloadUrls` or [Fetch Download Urls](#fetch-download-urls) | To be used when there is only one download url (i.e. one file version) for the item |
| downloadUrls | Object | no, if `downloadUrl` or [Fetch Download Urls](#fetch-download-urls) | To be used when there are multiple download url (i.e. one file version) for the item. See description in [table](#mutliple-download-urls) below |
| previewUrl | String | no | Url to preview file of the item |
| imageUrl | String | no | Url to image thumb of the item (for audio e.g. album cover, for video a still)|
......@@ -137,18 +137,18 @@ The objects in the arrays in `params` and `header` should contain two fields: `k
```
### Fetch Download Urls
Only necessary in special cases (e.g. https://archive.org) when no download urls are provided with the search response i.e. neither `downloadUrl` nor `downloadUrls` can be set in [Search `res`](#Response)
Only necessary in special cases (e.g. https://archive.org) when no download urls are provided with the search response i.e. neither `downloadUrl` nor `downloadUrls` can be set in [Search `res`](#response)
For the `req` object see the description of the [`req` obeject for `search`](#Request)
For the `req` object see the description of the [`req` obeject for `search`](#request)
The `res` object should hold two fileds: `format` (same as in [search response](#Response)) and `downloadUrl` (same as in [search response](#Response)) or `downloadUrls`. The field `downloadUrls` is again similar to the one in [search response](#Response), but has some additional fields:
The `res` object should hold two fileds: `format` (same as in [search response](#response)) and `downloadUrl` (same as in [search response](#response)) or `downloadUrls`. The field `downloadUrls` is again similar to the one in [search response](#response), but has some additional fields:
| Key | Type | Required | Description |
| :------------- | :------------- | :------------- | :------------- |
| isObject | Boolean | no | Whether the list not a normal array but a object and each subobject contains metadata about a file (e.g. `"files": { "file1": { "name": "&" }, "file2": { … }, …}`)|
| format | String | no | Format of the file |
If `isObject` is `true` there is a special case for `format`, `url` and `name`: if they have the value `&` (or `{&}` within a [template](#Templates)) it is replace by the key of the parent object. In the example in the table above this means `name` will be `file1`
If `isObject` is `true` there is a special case for `format`, `url` and `name`: if they have the value `&` (or `{&}` within a [template](#templates)) it is replace by the key of the parent object. In the example in the table above this means `name` will be `file1`
#### Example
```json
......@@ -167,9 +167,9 @@ If `isObject` is `true` there is a special case for `format`, `url` and `name`:
}
```
### Special Keys
Special keys are avaible for the following fields in [Search `res`](#Response): `author`, `authorUrl`, `name`, `filetype`, `description`, `id`, `url`, `licenseUrl`, `imageUrl`, `previewUrl`, `downloadUrl`, `downloadUrls.url` and `downloadUrls.name`.
Special keys are avaible for the following fields in [Search `res`](#response): `author`, `authorUrl`, `name`, `filetype`, `description`, `id`, `url`, `licenseUrl`, `imageUrl`, `previewUrl`, `downloadUrl`, `downloadUrls.url` and `downloadUrls.name`.
In [`res` of Fetch Download Urls](#Fetch-Download-Urls) they are avaible for these fields: `downloadUrl`, `downloadUrls.format`,`downloadUrls.url` and `downloadUrls.name`
In [`res` of Fetch Download Urls](#fetch-download-urls) they are avaible for these fields: `downloadUrl`, `downloadUrls.format`,`downloadUrls.url` and `downloadUrls.name`
#### Placeholders
Placeholders are expressions that will be replaced by something.
......@@ -181,7 +181,7 @@ For `params` and `header` these of placeholders are available.
| %pagenum% | Th number of the page to request results for | Only for search |
| %perpage% | Number of results that should be shown per page | |
| %shortlocale% | Short local like `en-US` (at the moment always `en-US`) | |
| %clientkey% | The clients apikey defined in [`clientkey`](#Base-Structure) | |
| %clientkey% | The clients apikey defined in [`clientkey`](#base-structure) | |
| %id% | Id of the item to fetch urls for | Only for Fetch Download Urls |
#### Templates
......
......@@ -55,7 +55,13 @@ bool logScale = KdenliveSettings::logscale();
KdenliveSettings::setLogscale(true);
```
## Effects and Transitions
Effects and Transitions are stored in subfolders of the [`data`][data] folder.
For a detailed description see [here][effect-readme].
[sett]: ../src/kdenlivesettings.kcfg
[data]: ../data/
[effect-readme]: ../data/README.md
[mlt-intro]: https://www.mltframework.org/docs/framework/
[qt5c]: https://doc.qt.io/qt-5/classes.html
[qt-sig]: https://doc.qt.io/qt-5/signalsandslots.html
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment