2016-07-22

Inside Kdenlive Projects: Timeline Tracks

So how does Kdenlive projects store its timeline tracks in its XML project files? So let's look into the details of the MLT "maintractor" and how it lists all the timeline tracks, and some more...

Timeline Tracks


Following the MLT information model, Kdenlive uses a tractor (<tractor>) to tell MLT what tracks are in a project. This tractor always is easily found by its unique identifier "maintractor" (without a space, as opposed to the "main bin").
<mlt>
  ...
  <tractor id="maintractor">
    <track producer="black_track"/>
    <track producer="playlist1" hide="video"/>
    <track producer="playlist2" hide="audio"/>
    <track producer="playlist3" hide="both"/>
    <track producer="playlist4"/>
    ...
  </tractor>
  ...
</mlt>

Black Track


So in the example above, we see 4(+1) timeline tracks. I'm counting the number of timeline tracks not as 5 on purpose, as when you load this project into Kdenlive you'll only see four(!) timeline tracks.

The first and bottommost(!) track is the black track (id="black_track"). It is special in that it is built into Kdenlive and hidden from the timeline. However, as a user you'll notice it nevertheless when working with transitions: in the transition property pane there is a track list. And this track list always contains the bottommost black track, albeit you can't see or delete it.

Individual Tracks


The following <track> elements inside the maintractor define the individual tracks in your project timeline. At this point, we cannot tell whether a track is an audio/video track or an audio-only track. We'll only learn later where Kdenlive stores the type of a particular track.

At this point in the maintractor we only see the current track state as to whether audio is muted or video is hidden. This is indicated by the hide attribute:
  • no hide attribute present: audio is audible, and video is visible.
  • hide="audio" or hide="both": audio is muted; Kdenlive then shows the muted loudspeaker track control.
  • hide="video" or hide="both": video is hidden; Kdenlive then shows the hidden film strip track control. 

MLT, Tracks, and Track Indices


An important detail to know for later is that MLT assigns track indices to the <track>s listed in a <tractor>. These indices become of importance when we later come to the topic of transitions, and internally added transitions in particular.

MLT track indices are 0-based cardinal numbers. With the above tractor and track setup in mind, this means that the hidden black track always gets index 0. From the perspective of a Kdenlive user, the bottommost timeline track is always assigned an index of 1. The topmost timeline track gets the highest number.

Note: Be careful when you look at or work with Kdenlive's source code: internally, Kdenlive numbers its timeline tracks just the opposite from MLT track indices; Kdenlive itself identifies the topmost track by (K-) index 0. This has been a constant source of bugs and regressions, but should rarly pop up again these days.

Next: individual tracks.