olive-0.2.0-doc-wip.md

Olive 0.2.0 File Format

Overview

The Olive Video Editor project file ("project file") is a standard XML 1.0 file that can be written and read by the Olive video editor.

This file contains the project's sequence data, color management settings, media file links, and other project data. It has a MIME type of application/vnd.olive-project.

Being XML-based, it is easy to edit and read both by humans and by applications. For example, fixing corrupted project files are easily done through a text editor or an automated program.

The specifications, as with the application itself, is subject to rapid development, and ultimately depends on the implementation. You should keep this in mind when reading this specification.

Structure

Here's what a typical project file will look like if you open it in a text editor:

<olive>

    <version>0.2.0</version>

    <project>

        <url>C:\Users\User\Desktop\project.ove</url>

        <folder name="">
          <footage ...>
          <footage ...>
          ...

          <sequence ..>
          <sequence ..>
          ...

          <folder name="something">
              <footage ...>
              <sequence ..>
          </folder>

          <folder name="something 2">
              <footage ...>
              <sequence ..>
          </folder>

        </folder>

        <colormanagement>
            <config>
                config.ocio
            </config>

            <default>
                Default Color Space
            </default>
        </colormanagement>

    </project>

</olive>

The structure headings shall be titled in basic XPath format to prevent ambiguity, but at the risk of redundant headings. In this format, a <bar> child element of <foo> would be rendered as "foo/bar".

olive

The top element (root node) of the file is the <olive> element, in which it contains the <version> element and <project> elements.

olive/version

The <version> element is the version of Olive in which the file is saved with.

<version>0.2.0</version>

olive/project

This element defines the project data. It contains the <url> of the project, <folder> structure as well as <colormanagement> configurations.

<project>
    <url>C:\Users\User\Desktop\project.ove</url>
    <folder name="">
    <colormanagement>
</project>

olive/project/url

This is the path in which the project file is located. The URL is written as the element's text node. (absolute / relative?)

<url>C:\Users\User\Desktop\project.ove</url>

olive/project/folder

This element houses all the project data such as <footage> and <sequences>.

The <folder> element that is a direct descendant of <project> is designated as the "root folder" of the project. Any project data that is not a descendant of this root folder is ignored.

A project file may have several "folders" in which to store the project data. These will be children of the root folder, and will have any name.

<folder name="">
  <footage ...>
  <footage ...>
  <sequence ..>
  <sequence ..>

  <folder name="something">
      <footage ...>
      <sequence ..>
  </folder>
</folder>

Attributes

Attribute	Type	Description
name	string	The folder name. The root folder usually will have an empty string as its name, e.g. name="".

olive/project/folder/footage

This element defines a linked footage to use in the project.

<footage ...>
    <points>
        <workarea .../>
        <markers>
            <marker .../>
        </markers>
    </points>
    <stream ...>
        <colorspace></colorspace>
    </stream>
    <stream .../>
</footage>

Attributes

Attribute	Type	Description
name	string	Footage name to use in the project sequences, etc.
filename	string	File system path pointing to the footage file.

olive/project/folder/footage/points

This element contains various points to use for a footage. It contains the points to use for in/out points for a footage's <workarea> as well as the footage's <markers>.

At this point, we define a rational type as this is what's used for in/out points.

A rational is simply a fraction consisting of a whole number as a numerator and another as a denominator. For example, 0.8 may be expressed as "4/5". It is used because floats present inaccuracies when dealing with time in video.

In video editing, you may have seen weird frame rates being used, such as 29.97 instead of 30 whole frames per second. There are many resources on the internet explaining why this is the case, but the short version is that early television engineers had to integrate color into black and white television while remaining backwards-compatible. In order to do that, they had to fit color data in to the existing bandwidth. Thus they decided to decrease the frame rate a tiny bit - from, you guessed it, a perfect 30.000/1.000 (~30fps) to 30.000/1.001 (~29.97fps).

<points>
    <workarea enabled="1"
      in="11011/6000"
      out="1001/400"/>
    <markers>
        <marker
          name="Marker"
          in="1001/300"
          out="1001/300"/>
    </markers>
</points>

olive/project/folder/footage/points/workarea

This defines the in/out points to use for a footage.

<workarea enabled="1"
  in="11011/6000"
  out="1001/400"/>

Attributes

Attribute	Type	Description
enabled	int	Boolean int. 1 if enabled, 0 otherwise. (right now it's always 1)
in	rational	The in point in seconds, expressed as a rational number (fraction) in the form of "numerator/denominator".
out	rational	The out point in seconds as a rational.

olive/project/folder/footage/points/markers

This contains footage <marker>s.

<markers>
    <marker .../>
    <marker .../>
    <marker .../>
    ...
</markers>

olive/project/folder/footage/points/markers/marker

This defines a marker to use with a footage.

<marker
  name="Marker"
  in="1001/300"
  out="1001/300"/>

Attributes

Attribute	Type	Description
name	string	Name of marker.
in	rational	The in point in seconds, expressed as a rational number (fraction) in the form of "numerator/denominator".
out	rational	The out point in seconds as a rational. Usually this will be the same as the in point.

olive/project/folder/footage/stream

TBA.

This can also contain a custom color space to use if the stream is a video stream. It is defined inside the <colorspace> element. If no color space is defined here, then it will use the default color space as defined in olive/project/colormanagement/default.

<stream ptr="140736884918672" index="0">
    <colorspace>Custom color space</colorspace>
</stream>

Attributes

Attribute	Type	Description
ptr	int	Where to put a stream in memory.
index	int	Index of stream. Usually 0=video stream, 1=audio stream.

olive/project/folder/sequence

This element defines the sequence data. A sequence is contains the <video> and <audio> metadata, in/out and marker <points>, as well as interconnected <node>s making up the composition. There is also a special <viewer> node, which is basically the final composite node.

<sequence name="Sequence">
    <video ...>
    <audio ...>
    <points ...>

    <node ...>
    <node ...>
    ...

    <viewer ...>
</sequence>

olive/project/folder/sequence/video

This element contains the video metadata. (TBA)

<video>
    <width>1920</width>
    <height>1080</height>
    <timebase>1001/30000</timebase>
</video>

olive/project/folder/sequence/audio

This element contains the audio metadata. (TBA)

<audio>
    <rate>32000</rate>
    <layout>3</layout>
</audio>

olive/project/folder/sequence/points

See ..footage/points.

olive/project/folder/sequence/node

An Olive node definition. (TBA)

<node id="org.olivevideoeditor.Olive.clip" ptr="93825029800288">
    <input id="name_in" keyframing="0">
        <standard><value>DTE_Twibbon.mp4</value></standard>
        <keyframes>
            <track/>
        </keyframes>
        <connections/>
    </input>
    <input id="length_in" keyframing="0">
        <standard><value>11011/375</value></standard>
        <keyframes>
            <track/>
        </keyframes>
        <connections/>
    </input>
    <input id="media_in_in" keyframing="0">
        <standard><value>0/0</value></standard>
        <keyframes>
            <track/>
        </keyframes>
        <connections/>
    </input>
    <input id="speed_in" keyframing="0">
        <standard><value>1/1</value></standard>
        <keyframes>
            <track/>
        </keyframes>
        <connections/>
    </input>
    <input id="buffer_in" keyframing="0">
        <standard><value></value></standard>
        <keyframes>
            <track/>
        </keyframes>
        <connections>
            <connection>93825052310816</connection>
        </connections>
    </input>
    <output id="node_out" ptr="93825029757984"/>
    <link>93825029800960</link>
</node>

Attributes

Attribute	Type	Description
id	string	The ID of the node to use. This is written in the reverse-DNS format, e.g. org.olivevideoeditor.Olive.track.
ptr	int	Where to put a node in memory.

olive/project/folder/sequence/viewer

A viewer node. (TBA)

<viewer id="org.olivevideoeditor.Olive.vieweroutput" ptr="93825021423808">
    <input id="tex_in" keyframing="0">
        <standard>
            <value></value>
        </standard>
        <keyframes>
            <track/>
        </keyframes>
        <connections>
            <connection>93825052311088</connection>
        </connections>
    </input>
    <input id="samples_in" keyframing="0">
        <standard>
            <value></value>
        </standard>
        <keyframes>
            <track/>
        </keyframes>
        <connections>
            <connection>93825045351184</connection>
        </connections>
    </input>
    <input id="track_in_0" keyframing="0">
        <standard>
            <value>0</value>
        </standard>
        <keyframes>
            <track/>
        </keyframes>
        <connections/>
        <subparameters>
            <input id="track_in_00" keyframing="0">
                <standard>
                    <value>0</value>
                </standard>
                <keyframes>
                    <track/>
                </keyframes>
                <connections>
                    <connection>93825052311088</connection>
                </connections>
            </input>
        </subparameters>
    </input>
    <input id="track_in_1" keyframing="0">
        <standard>
            <value>0</value>
        </standard>
        <keyframes>
            <track/>
        </keyframes>
        <connections/>
        <subparameters>
            <input id="track_in_10" keyframing="0">
                <standard>
                    <value>0</value>
                </standard>
                <keyframes>
                    <track/>
                </keyframes>
                <connections>
                    <connection>93825045351184</connection>
                </connections>
            </input>
        </subparameters>
    </input>
    <input id="track_in_2" keyframing="0">
        <standard>
            <value>0</value>
        </standard>
        <keyframes>
            <track/>
        </keyframes>
        <connections/>
        <subparameters/>
    </input>
    <output id="node_out" ptr="93825052312176"/>
</viewer>

olive/project/colormanagement

This element contains the OCIO configuration for the project.

Inside, there are two elements:

• <config> which specifies the path for the OCIO configuration as text.
• <default> specifies the default color space to use for all new footage imported in. It is also written as text.

<colormanagement>
    <config>OpenColorIO-Configs/aces_1.0.3/config.ocio</config>
    <default>ACES - ACES2065-1</default>
</colormanagement>