Kdenlive Project File Format

Kdenlive’s project file format is XML (not that this helps much at this time, except being once a hype buzzword). More precisely, the XML markup needs to follow the MLT schema (see also MLT’s DTD/document type definition), with additional Kdenlive data added wherever necessary. Unfortunately, the MLT DTD is a bit terse when it comes to explaining the semantics. We will try to cover this gap at least to the extend our limited understanding will allow, so we should get a better insight into what is going on inside Kdenlive/MLT project files.

Important aspects of this file format decision are:

  • MLT is able to directly render Kdenlive project files. MLT simply ignores all the additional Kdenlive-specific project data and just sticks to its rendering information. The Kdenlive-specific data is the additional icing on top that makes working with projects much easier than editing at the (lower) rendering level.
  • Kdenlive can directly include and work with MLT rendering files, just the same way it works with other media. In fact, Kdenlive’s library clips are simply MLT rendering files, and nothing more.

Overall Project XML Structure

The overall structure of the XML data inside Kdenlive project files is roughly as illustrated next:

<mlt producer="main bin">
  <!-- definition of rendering profile -->

  <!-- definition of master clips, as well as derived producers -->
  <producer id="#"/>
  <producer id="#_video"/>
  <producer id="#_playlist"/>
  <producer id="slowmotion:#:#:#"/>

  <!-- project settings, and more -->
  <playlist id="main bin">
  <property name="kdenlive:...">...</property>

  <producer id="black"/>

  <!-- the individual timeline tracks -->
  <playlist id="playlist#"/>

  <!-- the main tractor is the last producer in the document,
       so MLT takes it as the default for playout -->
  <tractor id="maintractor">
    <track producer="..."/>

    <!-- all transitions -->
    <transition id="transition#"/> <!-- user transitions -->
    <transition id="transition#"> <!-- internally added trans -->
      <property name="internal_added">237</property>


So let’s break this down into the interesting tidbits…

Project Bin

The (project) bin is represented by an MLT <playlist> element with the well-known id “main bin” (sic!). This element holds project-specific (meta) data, the bin folders as well as their hierarchy, clip groups, and some more stuff.

Note: While Kdenlive now mainly uses the term “bin” when talking about what formerly was the “project bin”, the early internal name “name bin” has stuck since the early days of Kdenlive.

Timeline Tracks

The setup of the timeline tracks is represented by an MLT <tractor> element with the well-known id “maintractor“. The elements inside are the individual timeline tracks: these are referenced, with the actual tracks then being MLT producers (see next).

The indivdual Kdenlive timeline tracks can be found in form of MLT <playlist> elements. They can also easily be identfied according to their “playlist#” id naming scheme; here, “#” is a number internally maintained by Kdenlive. The tracks feature additional properties that describe their title, locking state, and some more.

There is one semi-internal track here, the built-in “blacktrack. As you can see here, while it is built into Kdenlive, it isn’t so into MLT. Instead, to MLT this is just another track that happen to be created by Kdenlive. Kdenlive never shows this background track in the timeline as an individual track. But you can reference it from transitions (the composite ones, that is).

Transitions (Compositions)

Transitions come in two (three) flavors, but always represented by MLT <transition> elements:

  • user transitions are the ones added by, you’ve guessed it … users. These are the transitions currently shown slightly moved down and overlaying timeline tracks and their clips.
  • internally added transitions are basically a convenience to make the timeline do automatic audio mixing across multiple tracks, and (with more recent Kdenlive versions) transparent tracks.

Not Shown

  • bin clip producers,
  • proxy clips.

Slightly Invalid XML?

When you need to process Kdenlive project files using XML tools, there’s a gotcha to be aware in case of gen-2 project files. As soon as a project makes use of track-wide effects, the project XML as written by Kdenlive becomes invalid. You won’t notice this when editing Kdenlive project files just inside Kdenlive, and render them using MLT. You will only notice when editing them using standard XML tools.

The reason is that Kdenlive uses (or has used) its own attributes inside a separate “kdenlive” namespace. This is actually a good thing(tm) to do. But unfortunately, Kdenlive forgets to declare this additional namespace it uses at the beginning of every XML project document. As a simple fix, you’ll need to add the missing namespace yourself before processing the Kdenlive project file with XML tools:


<?xml version='1.0' encoding='utf-8'?>
<mlt xmlns:kdenlive="http://www.kdenlive.org/project" ...>

Further Reading