OpenTimelineIO Application Integrator's Guide

Introduction

OpenTimelineIO (OTIO for short) is an interchange format and API for editorial cut information that strives to be a superset of data models like EDL, ALE, AAF, and FCP 7 XML while providing a data and mental model that is accessible for people familiar with NLE (Non-Linear Editing) software.

Key Concepts

OTIO's implementation is in two layers:

1. The serialization scheme for storing structured data along with a schema name and version for interpreting the data
2. A set of schema which define types of objects and the fields they provide

Application's integrating OTIO should rely on one of the implementations provided by the project to read and write .otio files, but to illustrated the core concepts, we'll include some JSON serialization as examples.

SerializableObject

The basis of all OTIO serialization is the SerializableObject.

{
    "OTIO_SCHEMA": "SerializableObject.1"
}

Note that this is simply a JSON dictionary with one field: OTIO_SCHEMA This field contains the name of the schema, SerializableObject in this case, and the version of that schema, 1 in this case. When the deserializer encounters this, it knows what kind of object to deserialize the data as and which version of that object was encoded in the file.

The metadata dictionary

When interpreting the schema, there is a certain hierarchy of objects based on "is-a" relationships. Most objects you'll encounter in OTIO are actually SerializableObjectWithMetadata "descendants".

{
    "OTIO_SCHEMA": "SerializableObjectWithMetadata.1",
    "metadata": {
        "MyApplication": {
            "extra_information": "my application's extra data"
        }
    },
    "name": "My Serialized Object"
}

Note that this provides two extra fields over the standard SerializableObject, name and metadata. name is generally used for things like the human-readable name you'd see on a clip or timeline in you project tree.

The metadata field is a bit more special. This is a spot on just about every OTIO object that allows applications and users to attach any arbitrary metadata they like. This is a unique feature of OTIO and provides some powerful uses in a production pipeline. Studios attach identifiers for internal production tracking systems, adapters store format-specific contextual metadata about the file they derived the OTIO from, and some users even attach metadata like source script page information or notes from a review system. The metadata dictionary is also a powerful tool in driving the evolution of first-class schema in OTIO.

OTIO allows for any arbitrarily deep collection of other dictionaries, lists, scalars, and even SerializableObjects in the metadata dictionary - the implementation enforces no structure, but there are some strong conventions implementers should follow.

use a unique "namespace" key for data your application stores within object metadata dictionaries

Using a unique namespace helps avoid collision with metadata populated by others. The "namespace" key in this case is just the top-level key in the metadata dictionary under which an implementor places the dictionary containing their data. These top-level "namespace" keys denote informal sorts of sub-schema.

For example, a clip may have a metadata dictionary like the following:

{
  "myAnimStudio": {
    "sequence": "ABC",
    "shot": "ABC010",
    "shot_id": "7b3aaa14-8305-4fdd-87c2-b0b9d3f9dac7"
  },
  "cdl": {
    "asc_sat": 0.9,
    "asc_sop": {
      "offset": [
        1,
        -0.0122,
        0.0305
      ],
      "power": [
        1,
        0,
        1
      ],
      "slope": [
        0.1,
        0.2,
        0.3
      ]
    }
  },
  "cmx_3600": {
    "comments": [
      "SOURCE FILE: ABC010.LAYOUT3.01"
    ]
  }
}

Note that information for studio production tracking, CDL values, and a comment field from the original CMX 3600 EDL all coexist as separated by their namespace keys.

Preserve Metadata to the best of your abilities

In reading and writing OTIO, make a best effort to preserve the data in metadata dictionaries. If possible, only mutate the data under the namespaces your application controls. This ensures that metadata populated upstream of your application will flow downstream without loss. In the previous example, the identifiers under the myAnimStudio namespace provide critical value to the pipeline and avoid using brittle file-path based matching. Likewise, critical creative decisions are stored in the cdl namespace, preserving them helps us ensure we maintain the artistic vision of the piece.

OTIO is an Evolving format

OTIO a lot of the essentials for the most common types of cut information used in pipelines, but the team is also actively expanding the schema to enable more and more use cases. Schema development is driven by real-world use in production for a period of time when possible.

metadata dictionaries are a good place to store information that is not yet part of the "first-class" schema

By making data available early in a metadata dictionary, it allows pipelines to start making use of it and aid in the design of an "first-class" schema to be added to OTIO. Most new schema in OTIO starts as some extra information in a metadata dictionary, once it has been proven useful and the form has been refined, an update to OTIO will then promote that to new "first-class" schema.

Schema Versioning

Each object type has an independent schema version that is stored as an integer that increments each time there is a breaking change. This means addition of fields won't interfere with loading in older implementations, they just may only be accessible through non-standard means.

When the library encounters a serialized object with an older schema, it automatically upgrades that object to the newest available schema, even doing data transformation if needed. This means application implementors do not need to worry about having multiple versions of schema in-memory for a given object.

There are currently no mechanisms for downgrading schema.

Keep up-to-date with the OTIO implementation

Upgrading the OTIO release used in your software ensures you have maximum read compatibility with other applications, moving forward with the format helps users from having to make special concessions for you.

Guidelines For Implementers

Following is a compilation of the guidelines scattered throughout the guide as a reference:

• Use a unique "namespace" for data your application stores within object metadata dictionaries.
• Preserve metadata to the best of your abilities.
• metadata dictionaries should be used to store important information that is not yet a "first-class" part of the OTIO schema.
• Keep up-to-date with the OTIO implementation.