OpenTimelineIO

0.18.1 verified Fri May 01 auth: no python

OpenTimelineIO (OTIO) is an interchange format and Python API for editorial timeline information. It provides a common data model for representing timelines, clips, effects, markers, and transitions, and includes adapters for reading/writing various editorial formats (e.g., AAF, CMX 3600 EDL, Final Cut Pro XML). The current version is 0.18.1 (Beta). Release cadence is approximately two major beta releases per year. Requires Python >3.9.

pip install opentimelineio

Common errors

error ModuleNotFoundError: No module named 'opentimelineio' ↓

cause Package not installed or installed in a different Python environment.

fix

Run pip install opentimelineio in the same environment where your script runs.

error ModuleNotFoundError: No module named 'opentimelineio_adapters' or 'otio_adapters' ↓

cause User tried to import adapters from a separate package after v0.17.0 extraction.

fix

Install pip install opentimelineio-plugins and import from opentimelineio.adapters (the core package now includes a thin wrapper that finds adapters from plugins).

error AttributeError: module 'opentimelineio' has no attribute 'schema' ↓

cause Incorrect import pattern (e.g., `import opentimelineio` and then `opentimelineio.schema` should work; but if user did `from opentimelineio import *` submodules may not be imported).

fix

Use explicit submodule import: from opentimelineio import schema or import opentimelineio.schema.

error opentimelineio.exceptions.CannotComputeSynchronizationException: ... ↓

cause Attempting to compute a synchronized time range when the media reference does not have a defined available_range or the range is undefined.

fix

Ensure that the media_reference has an available_range set before calling timeline methods that compute synchronization.

Warnings

breaking Adapter extraction: As of v0.17.0, many file format adapters (AAF, EDL, FCP XML, etc.) have been moved to the separate `opentimelineio-plugins` package. They are no longer included in the core `opentimelineio` install. If you need those adapters, install `pip install opentimelineio-plugins`. ↓

fix Install OpenTimelineIO-Plugins package.

deprecated OTIOView removed: The `OTIOView` graphical viewer utility was removed from the core library in v0.18.0. Use alternative viewers or implement your own with the core API. ↓

fix Remove any imports of `opentimelineio.viewers` or usage of OTIOView.

gotcha Case-sensitive imports: The Python package name is all lowercase `opentimelineio`. Many users mistakenly use `OpenTimelineIO` (mixed case) as the module name, which fails on Linux/macOS. ↓

fix Use `import opentimelineio` (lowercase) always.

gotcha Schema changes: The `Marker` schema gained a `comment` field in v0.16.0. Older code that assumes Marker only has name and marked_range may break when reading files written with newer versions. ↓

fix Update code to handle the optional `comment` attribute on Marker objects.

gotcha Effect 'enabled' flag: The `Effect` schema now includes an `enabled` boolean field (added in v0.18.0). Older code may ignore this field, causing subtle behavior differences when effects are disabled. ↓

fix Check the `enabled` attribute when iterating over effects; default is True.

Install

pip install opentimelineio-plugins

Imports

opentimelineio
wrong
```
import OpenTimelineIO
```
correct
```
import opentimelineio as otio
```
Module name is lowercase; case-sensitive on case-sensitive filesystems.
otio.schema
wrong
```
from otio import schema
```
correct
```
from opentimelineio import schema
```
Use the full package name on import; the alias 'otio' is conventional but not an importable module.
otio.adapters
wrong
```
import adapters
```
correct
```
from opentimelineio import adapters
```
adapter aliases may shadow; always import from opentimelineio.

Quickstart

Creates a simple timeline with one video track and a clip, then outputs as OTIO JSON.

import opentimelineio as otio

# Create a timeline
timeline = otio.schema.Timeline("example_timeline")
track = otio.schema.Track("video_track", kind="Video")
timeline.tracks.append(track)

# Create a clip from an external reference
clip = otio.schema.Clip(
    name="shot1",
    media_reference=otio.schema.ExternalReference(
        target_url="/path/to/file.mov",
        available_range=otio.opentime.TimeRange(
            start_time=otio.opentime.RationalTime(0, 24),
            duration=otio.opentime.RationalTime(48, 24)
        )
    )
)
track.append(clip)

# Serialize to JSON (native format)
print(otio.adapters.write_to_string(timeline, "otio_json"))