kdenlive Documentation

Technical Documentation: KDE/kdenlive

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Kdenlive

Kdenlive is a powerful, free and open-source video editor that brings professional-grade video editing capabilities to everyone. Whether you're creating a simple family video or working on a complex project, Kdenlive provides the tools you need to bring your vision to life.

For more information about Kdenlive's features, tutorials, and community, please visit our official website.

There you can also find downloads for both stable releases and experimental daily builds for Kdenlive.

Contributing to Kdenlive Copy Chapter

Kdenlive is a community-driven project, and we welcome contributions from everyone! There are many ways to contribute beyond coding:

• Help translate Kdenlive into your language
• Report and triage bugs
• Write documentation
• Create tutorials
• Help other users on forums and bug trackers

Visit kdenlive.org to learn more about non-code contributions.

Developer Information Copy Chapter

Technology Stack Copy Section

Kdenlive is written in C++ and is using these technologies and frameworks:

• Core Framework: MLT for video editing functionality
• GUI Framework: Qt and KDE Frameworks 6
• Additional Libraries: frei0r (video effects), LADSPA (audio effects)

Getting Started Copy Section

1. Check out our build instructions to set up your development environment
2. Familiarize yourself with the architecture and coding guidelines
3. If the MLT library is new to you check out MLT Introduction
4. Join our Matrix channel #kdenlive-dev:kde.org for developer discussions and support

Contributing Code Copy Section

Kdenlive's primary development happens on KDE Invent. While we maintain a GitHub mirror, all code contributions should be submitted through KDE's GitLab instance. For more information about KDE's development infrastructure, visit the KDE GitLab documentation.

Finding Things to Work On Copy Section

• Browse open issues on KDE Invent, for example those labeled with First Task
• Check the KDE Bug Tracker for reported issues
• Look for issues tagged with "good first issue" or "help wanted"

Need help getting started? Join our Matrix channel #kdenlive-dev:kde.org - our community is friendly and always ready to help new contributors!

Please get in touch with us before working on a task, either by commenting in the issue or through our Matrix channel.

Overview (`benchmark/README.md`) Copy Section

This folder provides benchmarking utilities, currently mostly covering the backend model.
The aim is to quantify performance improvements on a wide range of synthetic but hopefully somewhat realistic scenarios.

The benchmark is run manually and is not registered with CTest. With BUILD_TESTING=ON, build and run it from the repository root, redirecting stdout to a file:

cmake --build build --target timelinemodelbenchmark -j4
QT_QPA_PLATFORM=offscreen build/bin/timelinemodelbenchmark > benchmark/baseline.csv

Then, from the repository root, compare two measurements using Python 3 (no additional packages required):

python3 benchmark/compare.py benchmark/base.csv benchmark/improved.csv

This will print the speedup for each operation, in decreasing order. Higher is better. Ideally we'd want to see everything > 1.0, but in practice that's rarely the case. We can make tradeoff where we drastically improve the perf of a function that is called very often, while losing out a little on one that is more rarely called.

Overview (`data/effects/README.md`) Copy Section

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 Copy Chapter

• 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: Copy Chapter

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)

Line 2:

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 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 tags for `...` Copy Section

list of attributes for `` Copy Section

For double values these placeholders are available:

values for attribute `type`

`"animated"`

• Alias for "keyframe"

`"animatedrect"`

• A rectangle that can change in time. The parameter is exported in a semicolon separated string:"keyframe=x y width height opacity", for example: "0=10 10 50 50 1;50=100 100 50 50 1"

`"bezier_spline"`

• cubic Bézier spline editor for the frei0r color curves filter (new version, might be reused for other filters)

`"bool"`

• true/false
• represented by a checkbox

`"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:

`"constant"`

• number
• represented by a slider

• additional parameter attributes:

`"curve"`

• cubic curve editor for the frei0r color curves filter (old version)

`"double"`

• synonym for "constant"

`"fakepoint"` and `"animatedfakepoint"`

• A way to handle 2 separate MLT parameters as the x, y coordinates of a point
• represented by 2 spin boxes

• additional required parameter attributes:

• requires 2 additional parammap child elements with attributes:

`"fakerect"` and `"animatedfakerect"`

• A way to handle 4 separate MLT parameters as the left, top, width, height coordinates of a point. Additional right, bottom values are supported
• represented by a geometry widget

• additional required parameter attributes:

• requires 2 additional parammap child elements with attributes:

`"fixed"`

• sets a (MLT filter) parameter, but does not expose it to the user (no GUI)

`"fontfamily"`

• Font typeface entry

`"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:

You can set default to "adjustcenter" to adjust the geometry to the frame size

`"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:

`"keywords"`

• Text entry with a selection of possible keywords to be inserted in the text.

• additional tags:

`"list"`

• multiple choice
• represented by a drop-down menu

• additional parameter attributes:

• additional tags:

`"multiswitch"`

• 2 possible options defined by strings (max / min)
• this special parameter type will affect 2 different parameters when changed. the name of this parameter will contain the name of the 2 final parameters, separated by a LF character: 
. Same thing for the default, min and max which will contain the values for these 2 parameters, separated by an LF character. See for example the fade_to_black effect.
• represented by a checkbox

`"point"`

• A point coordinate, represented in MLT by a rectangle, using only the first 2 x, y coordinates
• represented by 2 spin boxes

`"position"`

• time stored as frame number
• represented by a slider

`"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.

`"roto-spline"`

• GUI for the rotoscoping filter (spline on the monitor)

`"simplekeyframe"`

• works with MLT filters that use mlt_geometry for keyframe support (includes all frei0r filters)
• same attributes as "keyframe"

`"switch"`

• 2 possible options defined by strings (max / min)
• represented by a checkbox

`"url"`

• url/path
• represented by button to open "file open" dialog

• additional attributes:

`"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:

• additional tags:

`"wipe"`

• special GUI for the wipe transition makes it possible to select a direction of a slide

Overview (`data/resourceproviders/README.md`) Copy Section

How To Write Provider Configurations

Instruction written 2021 by Julius Künzel as part of Kdenlive (www.kdenlive.org)

Overview Copy Chapter

Provider configuration files are json files.
Here is an example for freesound

/* Detailed source-code truncated for AI context efficiency. */

Base Structure Copy Chapter

Each provider config files should only specify a certain media type such as video. If the provider provides multiple types, create one config file for each.

Api Copy Chapter

The api object describes the api endpoints

OAuth2 Copy Section

Search Copy Section

The search object should hold the two objects req and res.

Request

The objects in the arrays in params and header should contain two fields: key and value

Response

Multiple Download Urls

Example

"downloadUrls": {
    "key": "video_files",
    "url":"link",
    "name":"${quality} {width}x{height}"
}

Fetch Download Urls Copy Section

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

For the req object see the description of the req object for search

The res object should hold two fields: format (same as in search response) and downloadUrl (same as in search response) or downloadUrls. The field downloadUrls is again similar to the one in search response, but has some additional fields:

If isObject is true there is a special case for format, url and name: if they have the value & (or {&} within a template) it is replace by the key of the parent object. In the example in the table above this means name will be file1

Example

"downloadUrls": {
    "req": {
        "path": "/details/%id%",
        "method": "GET",
        "params": [
            { "key": "output", "value": "json"}
        ]
    },
    "res": {
        "format": "json",
        "downloadUrls": {"key":"files", "isObject":true, "url":"$http://archive.org/download/%id%{&}", "format": "format", "name":"${source} {format} {width}x{height}"}
    }
}

Special Keys Copy Section

Special keys are available for the following fields in Search res: author, authorUrl, name, filetype, description, id, url, licenseUrl, imageUrl, previewUrl, downloadUrl, downloadUrls.url and downloadUrls.name.

In res of Fetch Download Urls they are available for these fields: downloadUrl, downloadUrls.format,downloadUrls.url and downloadUrls.name

Placeholders

Placeholders are expressions that will be replaced by something.

For params and header these of placeholders are available.

Templates

Templates must always start with $. Within a template string you can use keys like this {username}.

NOTE: You can not use the general key like author. You must use the key of the response like username in the example for freesound!

Example

If your response looks like

{
  "results": [
    {
      "name": "example",
      "files": [
        {"picname": "nice-picture", "id": "1234"},
        ...
      ]
    }
  ]
}

and your config like this

{
  ...
  "api": {
    ...
    "search": {
      ...
      "res" {
        ...
        "downloadUrls": {
            "key": "files",
            "url":"$https://example.org/files/{picname}-{id}",
            "name":"picname"
        }
      }
    }
  }
}

you will finally get https://example.org/files/nice-picture-1234 as url.

Overview (`packaging/flatpak/README.md`) Copy Section

Package Kdenlive as Flatpak

Stable Version Copy Chapter

The manifest for the stable Kdenlive version on Flathub is hosted on https://github.com/flathub/org.kde.kdenlive

Nightly Version Copy Chapter

The nightly flatpak is on the kde flatpak repository (kdeapps). The build scripts for this repository are living at https://invent.kde.org/packaging/flatpak-kde-applications but in Kdenlives case it is just a link to the .flatpak-manifest.json file in the root of the Kdenlive repository. It is used by the new GitLab Flatpak CI.

How to build Copy Chapter

First you need to setup flatpak and flatpak-builder. On Ubuntu you do it by running

sudo apt install flatpak flatpak-builder

To build Kdenlive you also need some dependencies:

flatpak install org.kde.Sdk

To build and install the Flatpak just run the following command from the root of the Kdenlive repository:

flatpak-builder ~/flatpak-buildir .flatpak-manifest.json --install

Read the flatpak build instructions for further general instructions on the flatpak build system: https://docs.flatpak.org/en/latest/building.html

Tip: use flatpak make-current master or flatpak make-current stable to switch the current version for flatpak run org.kde.kdenlive

Check for updates of dependencies Copy Chapter

The flatpak manifest contains x-checker-data for flatpak-external-data-checker.

That means that after you installed it with

flatpak install --from https://dl.flathub.org/repo/appstream/org.flathub.flatpak-external-data-checker.flatpakref

you can simply run

flatpak run org.flathub.flatpak-external-data-checker .flatpak-manifest.json

to get a report about all dependencies with new versions available.

Overview (`src/lib/external/kiss_fft/README.md`) Copy Section

kiss_fft

Files in the this directory are copied from https://github.com/mborgerding/kissfft, except for the CMakeLists.txt file which was written by the Kdenlive team. Addionally the files have been modified to use #pragma once and SPDX-License headers. The last update is has happend with commit f5f2a3b2f2cd02bf80639adb12cbeed125bdf420.

Doc CMakeLists (`doc/CMakeLists.txt`) Copy Section

SPDX-License-Identifier: BSD-2-Clause

SPDX-FileCopyrightText: Julius Künzel

kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${KDE_INSTALL_DOCBUNDLEDIR}/en SUBDIR kdenlive)

Src Doc CMakeLists (`src/doc/CMakeLists.txt`) Copy Section

SPDX-License-Identifier: BSD-2-Clause

SPDX-FileCopyrightText: Vincent PINON

set(kdenlive_SRCS
${kdenlive_SRCS}
doc/documentchecker.cpp
doc/dcresolvedialog.cpp
doc/documentcheckertreemodel.cpp
doc/documentvalidator.cpp
doc/kdenlivedoc.cpp
doc/kthumb.cpp
doc/docundostack.cpp
PARENT_SCOPE)

--- METRICS ---

• Files Extracted: 8
• Estimated Token Budget: ~7413 tokens
• Canonical Reference: https://codewiki.google/github.com/KDE/kdenlive