Skip to content

Reference Project File Format

Zumi edited this page Sep 19, 2020 · 2 revisions

This page currently pertains to 0.1.x and might be updated soon

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