Kdenlive/Development/File format

Kdenlive's project files (.kdenlive files) use an XML format, based on MLT's format to describe the source media used in a project, as well as the use of that media as in the timeline. For most media, such as video, audio, and images, Kdenlive stores only a reference in a project, but not the media itself. Only some media gets stored directly inside Kdenlive’s project files, most notably Kdenlive title and color clips.

There are different file format generations depending on the version of Kdenlive you're using.

Generation 1

Generation 1 (gen-1) projects were created and edited the last time using Kdenlive up to 0.9.10. These are the Kdenlive versions developed for KDE 4.x. (While this isn’t strictly true, we won’t go into discussions about the early KDE 3.x versions of Kdenlive.)

The gen-1 projects contain a lot of project data that needs to be duplicated into the outer MLT XML data in order to MLT understanding what it needs to do. As an unfortunate consequence of this data duplicity, 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. As the proper remedy for this situation, the Kdenlive developers switched to Generation 2 as part of their porting Kdenlive to the KDE Frameworks 5 (or “KF5” for short).

Generation 2: KF5

Generation 2 projects are those created or last edited using Kdenlive 15.04 or later, up to 17.08 stable.

With the KF5/Qt5 version of Kdenlive, we now store all Kdenlive data through MLT's xml module to remove the data duplicity from the Kdenlive project file structure. This fixed project data model 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. We avoid storing any inner Kdenlive project data that’s already present in the outer MLT data layer, this means that all information must be stored in MLT objects like Tractor, Playlist, Producer, etc.

To separate these properties from other MLT properties, we prefix them with "kdenlive:". This page lists the properties that we use in this new file format.

Properties applied to project clips (MLT Producer object)

kdenlive:clipname
Stores the name that will be displayed for this clip in the Project Bin
kdenlive:folderid
Stores a string containing the id of the folder where this clip is (empty if clip is in the root folder).
kdenlive:zone_in
Stores the "in" point for the play zone defined for this clip
kdenlive:zone_out
Stores the "out" point for the play zone defined for this clip
kdenlive:originalurl
Stores the clip's original url. Useful to retrieve original url when a clip was proxied.
kdenlive:proxy
Stores the url for the proxy clip, or "-" if no proxy should be used for this clip.

Properties applied to the Bin Playlist (MLT Playlist object "main bin")

kdenlive:folder.xxx.yyy
This property stores the names of folders created in the Project Bin. xxx is the id of the parent folder (-1 for root) and yyy is the id for this folder. The value of this property is the name of the folder.

Generation 3: Timeline 2

Generation 3 projects are those projects created or edited using Kdenlive versions with the new Timeline 2 engine.

Generation 4

TODO