Let's have a look at the meaning of elements which can occur in a timeline description. Every timeline (which is stored as a <timeline> element) consists of objects, transitions and groups; the corresponding XML elements are <object>, <transition_object> and <group>. Each of these elements must have a unique identifier specified in the id attribute.

Objects correspond to pieces of input and their content is stored in external multimedia files. A simple description of an object called object0 might look like this:

<object id="object0">
   <position time_from="5.0" time_to="15.0" track="AA"/>
   <source src_from="10.0" src_to="20.0">
      <channel name="audio0"/>
      <params>
         <param name="filename">D:\Movies\input.avi</param>
      </params>
   </source>
</object>

Every <object> element must have <position> and <source> as its subelements. The <position> element contains information about object location on timeline; in our example the object is placed on track AA (attribute track), it begins at time 5.0 seconds (attribute time_from) and ends at time 15.0 seconds (attribute time_to).

The <source> element describes object's content and must have <params> and <channel> as its subelements; <params> is composed of individual <param> elements which represent parameters passed to the input module. The <channel> element is always empty and its attribute name identifies an output connector of the input module. Finally, <source> has two attributes called src_from and src_to which identify the part of the input file we are interested in.

Returning to our example, the object is stored in file in D:\Movies\input.avi (which is passed as parameter filename to the input module). It corresponds to its first audio channel (i.e. output connector audio0) and we take only the subset between 10.0 s and 20.0 s.

The <source> element can optionally have <filters> and/or <overlay_params> subelements. The former lists all filers applied to the object as well as parameters passed to them; the latter contains parameters which are passed to the overlay module (therefore it makes sense only for objects on overlay tracks). Here's an example:

<object id="object1">
   <position time_from="5.0" time_to="15.0" track="V0"/>
   <source src_from="0" src_to="0">
      <channel name="video0"/>
      <params>
         <param name="filename">D:\Images\picture*.png</param>
         <param name="fps">1</param>
      </params>
   </source>
   <filters> 
      <filter name="Flip">
         <params>
            <param name="direction">vertical</param>
         </params>
      </filter>
   </filters>
   <overlay_params>
      <param name="x">590</param>
      <param name="y">50</param>
   </overlay_params>
</object>

This is an object placed on track V0, it begins again at time 5.0 seconds and ends at time 15.0 seconds. It corresponds to a sequence of bitmap images that match the regular expression D:\Images\picture*.png. Note that src_to="0" is equivalent to saying "to the end of the file". This is the only exception when src_to-src_from need not be equal to time_to-time_from. We have also applied a filter called Flip (with parameter direction set to vertical) on our object. The parameters passed to overlay module are x=590 and y=50 (they correspond to overlay position with respect to the background).

The description of transitions is similar to objects. First an example:

<transition_object id="trans0">
   <position time_from="300" time_to="400" track="VFx" direction="AB"/>
   <transition name="Crossfade">
      <params>
         <param name="rate">4.0</param>
      </params>
   </transition>
</transition_object>

Every <transition_object> element must have <position> and <transition> as its subelements. The <position> element contains information about object location on timeline; it has the same attributes as in case of objects except there is an additional attribute direction whose value is either "AB" or "BA". In our example we have used "AB" which means that the transition should start with video frames from track VA and blend them gradually with video frames taken from track VB (the value "BA" would start with VB and end with VA).

The <transition> element identifies which transition to use (attribute name) and lists the parameters passed to that transition.

We finally proceed to groups. The purpose of groups is that they bind objects and/or transitions; all members of a group move together when one of them is moved along the timeline (in the OpenVIP GUI). Here's an example:

<group id="group0">
   <item ref="object0"/>
   <item ref="object1"/>
</group>

Every <group> element has one or more <item> subelements; they correspond to members of the group which are identified using the ref attribute.

How does OpenVIP process timelines? The answer is that timelines can always be converted to networks (but not necessarily vice versa). Timeline to network conversion is handled automatically when using the OpenVIP GUI. You can also convert a timeline XML file using the script timeline2network.py and then process the network XML file using cli:

timeline2network.py example.timeline example.openvip output.avi
cli example.openvip

The script takes three parameters - timeline filename, network filename and the name of the file where the output should be written after processing the network (i.e. the filename parameter passed to the output module).