Note: Please check back from time to time as this is an ongoing effort at documenting insights into Kdenlive projects and MLT concepts. In case you notice errors or other mistakes, please feel free to contact me, so I can improve these posts.
The following information applies to (what I like to call) "gen 2" Kdenlive XML project files only. This is the second generation project document format, as used staring with Kdenlive 15.04 on KDE Frameworks 5. In terms of project document versions, this roughly corresponds to document versions 0.91 and later.
Kdenlive Project Elements
For starters, I recommend reading the blog post about MLT concepts first, as MLT is the multimedia engine within Kdenlive. The following posts about particular Kdenlive project concept then build upon those MLT concepts:
- the Main Bin – contains project information, the bin folders and their hierarchy, clip groups, as well as further information.
- timeline tracks (the "maintractor") – which tracks are to be found in Kdenlive's timeline? And is audio muted and video hidden for a particular track?
- individual tracks – further details about a track, such as its title, its locking state, its automatic compositing state, and more.
- timeline transitions.
- internally added transitions – automatic audio mixing across all tracks, as well as transparent video tracks.
- the project bin – describes how clips are organized inside the project bin.
- bin clip producers – the sources for video and audio, but also for images, image sequences, titles, and even more stuff.
- proxy clips – reduced size+quality producers to better performance while working in the timeline.
Project Generations 1/2
Kdenlive project files can roughly be categorized at this time into either generation 1 or 2 projects:
- generation 1 projects were edited last using a Kdenlive version up to 0.9.10.
- generation 2 projects are those edited using Kdenlive 15.04 and later.
With gen 1 projects, any Kdenlive project features a lot of data that is more or less duplicated by the outer MLT data shell. In consequence, such gen 1 projects had the habit of getting the outer MLT data out of sync with the inner Kdenlive project data. For instance, sometimes the effects as rendered got out of sync with the effect parameters as set in the Kdenlive user interface.
Part of the port of Kdenlive 15.04 to KDE Frameworks 5 was to clean up the Kdenlive project files. With these gen 2 projects, the inner Kdenlive project data has been cleaned from duplicate information that's already in the outer MLT data layer. This results in much more stable Kdenlive project behavior. As another positive side effect, it's now much easier to manually edit or create Kdenlive XML project files from outside Kdenlive.
Note: this series of blog posts about Kdenlive projects only covers generation 2 Kdenlive project files. That is, Kdenlive project files last saved from Kdenlive 15.04 or later. Older projects up to 0.9.10 are not covered, so you will need to upgrade them first by loading them into a recent Kdenlive release, such as 16.04, and saving them again.
As the basis of the XML markup used in Kdenlive project files is MLT XML, you may take a look at MLT's DTD (document type definition). While this gives at least an impression on the overall structure of the MLT part of a Kdenlive project, it is unfortunately extremely terse on explaning the semantics behind these tags, such as <mlt>, <tractor>, <playlist>, and so on. I will try to cover their semantics at least to my limited understanding in the following posts about Kdenlive project internals.
Overall Kdenlive Project XML Structure
The overall structure of the Kdenlive XML is roughly as follows, with the main parts we've already shortly mentioned above:
<mlt producer="main bin"> <!-- definition of rendering profile --> <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>
...
</playlist>
<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>
</transition>
</tractor>
</mlt>
There is one important gotcha when trying to process Kdenlive project with standard XML tools: as soon as track effects come into play, then the project XML isn't valid anymore. The reason is that Kdenlive uses (or has used) its own attributes in a kdenlive namespace, yet forgets to declare this namespace at the beginning of the XML document.
As a simple fix, it sufficies to simply declare a kdenlive namespace for any URI you want, such as this:
<?xml version='1.0' encoding='utf-8'?> <mlt xmlns:kdenlive="http://www.kdenlive.org/project" ...> ... </mlt>
Project Analyzer
And, last but not least:
