OTIO file format

An .otio file is JSON holding a tree of nested objects. The project publishes a draft specification of the file as of OTIO Beta 13, an autogenerated list of the serialised types and the source code of its library. The specification recommends using the library rather than writing a new reader or writer.

JSON rules

Use the extension .otio; .json is discouraged.
Integers are signed 64-bit values and floating-point numbers are IEEE 754 doubles.
Beyond standard JSON, doubles may be NaN, Inf or Infinity, and -Inf or -Infinity. Such a file is not valid strict JSON.
The library writes keys in a predictable order, to help comparison. Minifying is discouraged; to save space, the specification suggests gzip.
There is no file-level version. Each object carries the version of its own type.
The same object cannot appear twice in the tree, so a repeated clip is written as an identical copy.

OTIO_SCHEMA

Every object is a JSON dictionary with a key OTIO_SCHEMA, whose value is a type name, a full stop and a version number, such as Timeline.1 or Clip.2. A reader looks at this first, because the type decides which of the other fields it should expect. Values not in the schema are ignored.

A file’s top-level object is usually a Timeline, but it can be any type, such as a Clip or a RationalTime. An array is allowed, though a SerializableCollection is preferred because it can carry metadata. Readers should check for an unexpected top-level type and fail gracefully.

How a timeline nests

A Timeline has a tracks field holding a Stack. A stack’s children are tracks. Below that, children can be a Clip, Gap, Stack, Track or Transition. Parents use a children list, except Timeline, which uses tracks.

Timelines, stacks, tracks, clips, media references and most other objects have a metadata dictionary, which the library leaves alone. It can hold deeply nested JSON and OTIO objects. The specification asks that metadata be grouped under namespaces, to avoid collisions between workflows.

Special value types

These are written as JSON objects with the fields shown. An absent time, range, box or colour is written as JSON null.

Schema	Field	Type	Meaning
`RationalTime.1`	`rate`	double	Units per second.
`RationalTime.1`	`value`	double	The time, in those units.
`TimeRange.1`	`duration`	RationalTime	Length of the range.
`TimeRange.1`	`start_time`	RationalTime	Start of the range.
`TimeTransform.1`	`offset`	RationalTime	Offset.
	`rate`	double	Rate.
	`scale`	double	Scale.
`V2d.1`	`x`	double	Horizontal.
`V2d.1`	`y`	double	Vertical.
`Box2d.1`	`min`	V2d	Minimum corner.
`Box2d.1`	`max`	V2d	Maximum corner.
`Color.1`	`r`	double	Red.
	`g`	double	Green.
	`b`	double	Blue.
	`a`	double	Alpha.
	`name`	string	Name.

Named colours

The library defines these, used for markers among others. Unrecognised names upgrade to white.

Name	r	g	b	a
Pink	1.0	0.0	1.0	1.0
Red	1.0	0.0	0.0	1.0
Orange	1.0	0.5	0.0	1.0
Yellow	1.0	1.0	0.0	1.0
Green	0.0	1.0	0.0	1.0
Cyan	0.0	1.0	1.0	1.0
Blue	0.0	0.0	1.0	1.0
Purple	0.5	0.0	0.5	1.0
Magenta	1.0	0.0	1.0	1.0
Black	0.0	0.0	0.0	1.0
White	1.0	1.0	1.0	1.0
Transparent	0.0	0.0	0.0	0.0

Schema versions

Each type has its own version. A library release only creates objects at its current version, and it upgrades older ones on read through a chain of upgrade functions, one for each step. On write, a caller can ask for older versions, using a map from schema name to version, and downgrade functions take objects back step by step. Downgrade functions must be consecutive. Adding or removing a field does not always need a new version.

Schema	Library releases	Change
`Clip.2`	0.15.0 and later	Replaces the single `media_reference` field of `Clip.1` with a `media_references` dictionary and an `active_media_reference_key`.
`Marker.2`	0.14.0 to 0.18.1	Field `range` is renamed `marked_range`.
`Marker.3`	0.19.0 development	Field `color` changes from a string to a `Color` object. Names match case-insensitively.

All other schemas are at version 1 in the published version maps from 0.14.0 onwards. Three old names are aliases at version 1: Filler for Gap, Sequence for Track, and SerializeableCollection (the spelling is as written) for SerializableCollection.

An object of an unknown schema is kept, with its original name and version, as UnknownSchema, and written back the same way.