Reference Project File Format

Before reading, keep in mind that Olive is still in rapid development, therefore this page may not be accurate by the time you read this.

Also, this page itself still has a lot of things to be written, so watch this space.

About the OVE project file format

This is a standard, XML v.1.0 file that represents a project file that can be written and read by the Olive Video Editor.

The project data is contained within a single <project> node which houses all the links to the media files, the sequence data, and other project data.

This file has a MIME type of application/vnd.olive-project.

XML Elements

The values defined in the following elements may either be numbers (integer or not) or strings (things like names that contain letters and numbers) enclosed in quotation marks ("), except if it is part of an element's contents.

Boolean values are represented as "0" for False and "1" for True.

<project>

Attributes

None

Contents

This element contains all the project data as its child elements.

<version>

Attributes

None

Contents

The version number of Olive that the file was saved with. To be precise, this number is the version of the Olive file specification that the Olive editor works with.

Its value denotes the date of the specification, for example 190201 means the file is using the specification last modified on February 1st, 2019 (2019-02-01).

If the project is opened in a version of Olive that has a differing number than what the project file contains, it will warn the user about compatibility.

This value corresponds to kSaveVersion, currently 190219.

<url>

Attributes

None

Contents

A string containing the path to the project file. This path is usually an absolute path to the project.

<folders>

Attributes

None

Contents

This element contains the Olive folder definitions. Each folder is defined as child element <folder>.

<folder>

Attributes

Parameter	Description
name	The name of the Olive folder.
id	A number by which to refer to this folder.
parent	The id of the parent folder. If this folder isn't contained within another folder, this should be set to "0".

Contents

None

<media>

Attributes

None

Contents

This contains the data for the media files used in the project file. Each media file is contained in its own <footage> element, as a child element of <media>.

<footage>

Attributes

Parameter	Description
id	A number by which to refer to this footage.
folder	The id of the parent folder. If it has no parent folder, this should be "0".
name	The name of the footage.
url	The path to the file, relative to the project path.
duration	The length of the footage, in microseconds.
using_inout	Whether or not the project uses in/out points.
in	Where in the footage shall the in point be placed, in microseconds.
out	Where in the footage shall the out point be placed, in microseconds.
speed	Speed factor, where "1.0" or "1" means 100% speed.
alphapremul	Whether or not the alpha channel is premultiplied.
startnumber	If this is not "0", this indicates an image sequence.
proxy	Whether or not this footage uses a proxy clip.
proxypath	If proxy is "1" (for true), this is the path to the proxy clip, relative to the project path.

Contents

A <video> and/or <audio> element, describing the footage's metadata. It may also contain footage <marker> elements.

<video>

Attributes

Parameter	Description
id	A number by which to refer this video element.
width	The width, or X dimensions of the video element.
height	The height, or Y dimensions of the video element.
framerate	The frame rate of the video, as a float number.
infinite	Whether or not the video is "looped" for a certain amount of time.

Contents

None

<audio>

Attributes

Parameter	Description
id	A number by which to refer this audio element.
channels	How many channels the audio element has. ("1" for mono, "2" for stereo, and so on.)
layout	Should be "3" for stereo audio, and "4" for mono audio.
frequency	The audio's sampling rate.

<marker> (footage)

Attributes

Parameter	Description
frame	Where in the footage shall the marker be placed, in video frames.
name	The name of the marker.

Contents

None

<sequences>

Attributes

None

Contents

This element contains the Olive sequence definitions. Each sequence is defined as child element <sequence>.

<sequence>

Attributes

Parameter	Description
id	A number by which to refer this sequence element.
folder	The id of the parent folder. If there is none, this should be "0".
name	The name of the sequence.
width	The width (or X resolution) of the sequence.
height	The height (or Y resolution) of the sequence.
framerate	The frame rate of the sequence, as a float number.
afreq	The audio's sampling rate of the sequence.
alayout	Usually "3" for stereo audio, "4" for mono.
open	If specified (and set to "1"), Olive will automatically open this sequence upon loading the project file.
workarea	Whether or not the sequence uses in and out points.
workareaIn	Where in the sequence shall the in point be placed, in frames.
workareaOut	Where in the sequence shall the out point be placed, in frames.

Contents

An Olive sequence is made up of several clips, Each clip is contained in its own <clip> element, as a child element of <sequence>. A sequence can also contain one or more <marker> elements.

<marker> (sequence)

Attributes

Parameter	Description
frame	Where in the sequence shall the marker be placed, in sequence frames.
name	The name of the marker.

Contents

None

<clip>

Attributes

Parameter	Description
id	A number by which to refer this clip element.
enabled	Whether or not the clip is enabled in the timeline.
name	The name of the clip in the sequence.
clipin	The start offset of the clip, in frames. If you want the clip to start at the beginning, set this to "0".
in	Where in the timeline should the clip's start point be placed, in frames.
out	Where in the timeline should the clip's end point be placed, in frames.
track	The track number, where "-1" and below places it in the video tracks (bottom to top), while "0" above places it in the audio tracks (top to bottom).
r	The clip's timeline background color. (Red, ranges from 0-255)
g	The clip's timeline background color. (Green, ranges from 0-255)
b	The clip's timeline background color. (Blue, ranges from 0-255)
autoscale	Whether or not to scale the video to fit the sequence resolution. (This scale will be set as 100% in the Transform effect)
speed	The video's speed, where "1.00" is 100%.
maintainpitch	Whether or not to maintain the clip's audio pitch.
reverse	Whether or not the clip is reversed.
type	This is currently "0" if the clip is a media and "1" if it's a nested sequence instead.
media	If type is a media, this is the id of the footage to use for this clip.
stream	If type is a media, this is the id of the video/audio element of the footage to use for this clip. For example, if the <video> of the <footage> has an id of "1", then to use the video stream, you must set this to "1".
sequence	If type is a sequence, this is the id of the nested sequence to use for this clip.

If a clip does not have the type, media, stream, and sequence types set, it won't refer to any footage or sequence and is thus considered a "null clip".

This sort of clip is used for Solid Color clips, Title clips, Bar clips, Tone clips, Noise clips etc. that can be added into the timeline.

Contents

An Olive clip can be <linked>, it can contain <opening> and <closing> transitions, it can have <effect>s and it can also have <marker>s.

<link>

This element should be enclosed in a <linked> element. This <link> element, and subsequently the <linked> element it resides in, would be present on both linked clips.

Attributes

Parameter	Description
id	The id of the clip to link to.

Contents

None

<opening>

Attributes

Parameter	Description
length	Length of the transition in frames.
name	The name of which transition effect to use.
enabled	The transition is enabled if this is set to "1".
shared	The id of the clip to share a transition with. Ideally, this would be with a clip that has an closing transition and the out point of that clip is the same as this clip's in point. However, only one of the two clips can have this shared attribute.

Contents

None

<closing>

Attributes

Parameter	Description
length	Length of the transition in frames.
name	The name of the transition effect to use.
enabled	The transition is enabled if this is set to "1".
shared	The id of the clip to share a transition with. Ideally, this would be with a clip that has an opening transition and the out point of that clip is the same as this clip's in point. However, only one of the two clips can have this shared attribute.

Contents

None

<effect>

Attributes

Parameter	Description
name	The name of the effect to use.
enabled	The effect is enabled if this is set to "1".

Contents

Effect settings, encoded as <field> elements that are enclosed in <row> elements.

<field>

Attributes

Parameter	Description
id	The internally referred effect parameter to change.
value	The value of the parameter. If animated, this value would not matter at all.

Contents

If this parameter is animated, it will contain keyframe elements, known as <key>.

<key>

Attributes

Parameter	Description
value	The value at the keyframe.
frame	Where to put the keyframe, as a sequence frame number.
type	"0" for linear, "1" for bezier, and "2" for hold.
prehx	Bezier only, this is the pre handle's X value.
prehy	Bezier only, this is the pre handle's Y value.
posthx	Bezier only, this is the post handle's X value.
posthy	Bezier only, this is the post handle's Y value.

Contents

None

<marker> (clip)

According to this, this should only be necessary for null clips (solids and titles).

If a marker is set on a clip pointing to a footage or sequence, Olive will set the marker on the footage or sequence itself instead of the clip.

Attributes

Parameter	Description
frame	Where in the clip shall the marker be placed, in frames.
name	The name of the marker.

Contents

None