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.

The amount of Kdenlive project data considers considerably between gen-1 and gen-2 projects.

"Kdenlive Projects" article on the Website

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

Further Reading

• Kdenlive Project Format gives more insight into the general structure of Kdenlive gen-2 project files.
• The Kdenlive Project Analyzer is kind of a (crazy) simple Kdenlive doctor, showing some statistics and details when given a Kdenlive gen-2 project file. You can even try the Kdenlive Project Analyzer online using Chrome/Chromium or Firefox. Sources are available on GitHub.