opentimelineio.core package

Internal implementation details of OpenTimelineIO.


opentimelineio.core.composable module

Composable class definition.

An object that can be composed by tracks.

class opentimelineio.core.composable.Composable(name=None, metadata=None)

Bases: opentimelineio.core.serializable_object.SerializableObject

An object that can be composed by tracks.

Base class of:
Item Transition

Returns true if self is a parent or ancestor of other.


Metadata dictionary for this Composable.


Composable name.

static overlapping()

Return whether an Item is overlapping. By default False.


Return the parent Composable, or None if self has no parent.

static visible()

Return the visibility of the Composable. By default True.

opentimelineio.core.composition module

Composition base class. An object that contains Items.

class opentimelineio.core.composition.Composition(name=None, children=None, source_range=None, markers=None, effects=None, metadata=None)

Bases: opentimelineio.core.item.Item,

Base class for an OTIO Item that contains other Items.

Should be subclassed (for example by Track and Stack), not used directly.


Which children overlap time t?


Returns a label specifying the kind of composition.

each_child(search_range=None, descended_from_type=<class 'opentimelineio.core.composable.Composable'>)

If media beyond the ends of this child are visible due to adjacent Transitions (only applicable in a Track) then this will return the head and tail offsets as a tuple of RationalTime objects. If no handles are present on either side, then None is returned instead of a RationalTime.

Example usage: >>> head, tail = track.handles_of_child(clip) >>> if head: … print(‘Do something’) >>> if tail: … print(‘Do something else’)

insert(index, item)

Insert an item into the composition at location index.

range_of_child(child, reference_space=None)

The range of the child in relation to another item (reference_space), not trimmed based on this composition’s source_range.

Note that reference_space must be in the same timeline as self.

For example:

[—–] | seq

[—————–] Clip A

If ClipA has duration 17, and seq has source_range: 5, duration 15, seq.range_of_child(Clip A) will return (0, 17) ignoring the source range of seq.

To get the range of the child with the source_range applied, use the trimmed_range_of_child() method.


Return the range of a child item in the time range of this composition.

For example, with a track:
The self.range_of_child_at_index(2) will return:
TimeRange(ClipA.duration + ClipB.duration, ClipC.duration)

To be implemented by subclass of Composition.


Return the first visible child that overlaps with time t.


Deprecated field, do not use.

trimmed_range_of_child(child, reference_space=None)

Get range of the child in reference_space coordinates, after the self.source_range is applied.

Example | [—–] | seq [—————–] Clip A

If ClipA has duration 17, and seq has source_range: 5, duration 10, seq.trimmed_range_of_child(Clip A) will return (5, 10) Which is trimming the range according to the source_range of seq.

To get the range of the child without the source_range applied, use the range_of_child() method.

Another example | [—–] | seq source range starts on frame 4 and goes to frame 8 [ClipA][ClipB] (each 6 frames long)

>>> seq.range_of_child(CLipA)
0, duration 6
>>> seq.trimmed_range_of_child(ClipA):
4, duration 2

Return the trimmed range of the child item at index in the time range of this composition.

For example, with a track:

[ ]


The range of index 2 (ClipC) will be just like range_of_child_at_index() but trimmed based on this Composition’s source_range.

To be implemented by child.

opentimelineio.core.item module

Implementation of the Item base class. OTIO Objects that contain media.

class opentimelineio.core.item.Item(name=None, source_range=None, effects=None, markers=None, metadata=None)

Bases: opentimelineio.core.composable.Composable

An Item is a Composable that can be part of a Composition or Timeline.

More specifically, it is a Composable that has meaningful duration.

Can also hold effects and markers.

Base class of:
  • Composition (and children)
  • Clip
  • Gap

Implemented by child classes, available range of media.


Convience wrapper for the trimmed_range.duration of the item.


List of effects on this item.


List of markers on this item.


Metadata dictionary for this item.


Item name.


Find and return the untrimmed range of this item in the parent.


Range of source to trim to. Can be None or a TimeRange.

transformed_time(t, to_item)

Converts time t in the coordinate system of self to coordinate system of to_item.

Note that self and to_item must be part of the same timeline (they must have a common ancestor).


0 20 [——t—-D———-] [–A-][t—-B—][–C–] 100 101 110 101 in B = 6 in D

t = t argument

transformed_time_range(tr, to_item)

Transforms the timerange tr to the range of child or self to_item.


The range after applying the source range.


Find and return the trimmed range of this item in the parent.

static visible()

Return the visibility of the Item. By default True.


The range of this item’s media visible to its parent. Includes handles revealed by adjacent transitions (if any). This will always be larger or equal to trimmed_range().

opentimelineio.core.json_serializer module

Serializer for SerializableObjects to JSON

Used for the otio_json adapter as well as for plugins and manifests.


Deserialize the file at otio_filepath containing JSON to OTIO.


Deserialize a string containing JSON to OTIO objects.

opentimelineio.core.json_serializer.serialize_json_to_file(root, to_file)

Serialize a tree of SerializableObject to JSON.

Writes the result to the given file path.

opentimelineio.core.json_serializer.serialize_json_to_string(root, indent=4)

Serialize a tree of SerializableObject to JSON.

Returns a JSON string.

opentimelineio.core.media_reference module

Media Reference Classes and Functions.

class opentimelineio.core.media_reference.MediaReference(name=None, available_range=None, metadata=None)

Bases: opentimelineio.core.serializable_object.SerializableObject

Base Media Reference Class.

Currently handles string printing the child classes, which expose interface into its data dictionary.

The requirement is that the schema is named so that external systems can fetch the required information correctly.


Available range of media in this media reference.


Metadata dictionary.


Name of this media reference.

opentimelineio.core.serializable_object module

Implements the otio.core.SerializableObject

class opentimelineio.core.serializable_object.SerializableObject

Bases: object

Base object for things that can be [de]serialized to/from .otio files.

To define a new child class of this, you inherit from it and also use the register_type decorator. Then you use the serializable_field function above to create attributes that can be serialized/deserialized.

You can use the upgrade_function_for decorator to upgrade older schemas to newer ones.

Finally, if you’re in the process of upgrading schemas and you want to catch code that refers to old attribute names, you can use the deprecated_field function. This raises an exception if code attempts to read or write to that attribute. After testing and before pushing, please remove references to deprecated_field.

For example

>>>    import opentimelineio as otio
>>>    @otio.core.register_type
...    class ExampleChild(otio.core.SerializableObject):
...        _serializable_label = "ExampleChild.7"
...        child_data = otio.core.serializable_field("child_data", int)

# @TODO: delete once testing shows nothing is referencing this. >>> old_child_data_name = otio.core.deprecated_field()

>>>    @otio.core.upgrade_function_for(ExampleChild, 3)
...    def upgrade_child_to_three(_data):
...        return {"child_data" : _data["old_child_data_name"]}

Returns true if the contents of self and other match.

classmethod schema_name()
classmethod schema_version()

For marking attributes on a SerializableObject deprecated.

opentimelineio.core.serializable_object.serializable_field(name, required_type=None, doc=None)

Create a serializable_field for child classes of SerializableObject.

Convienence function for adding attributes to child classes of SerializableObject in such a way that they will be serialized/deserialized automatically.

Use it like this:
class foo(SerializableObject):
bar = serializable_field(“bar”, required_type=int, doc=”example”)
This would indicate that class “foo” has a serializable field “bar”. So:

f = foo() = “stuff”

# serialize & deserialize otio_json = otio.adapters.from_name(“otio”) f2 = otio_json.read_from_string(otio_json.write_to_string(f))

# fields should be equal ==

Additionally, the “doc” field will become the documentation for the property.

opentimelineio.core.type_registry module

Core type registry system for registering OTIO types for serialization.

opentimelineio.core.type_registry.instance_from_schema(schema_name, schema_version, data_dict)

Return an instance, of the schema from data in the data_dict.

opentimelineio.core.type_registry.register_type(classobj, schemaname=None)

Register a class to a Schema Label.

Normally this is used as a decorator. However, in special cases where a type has been renamed, you might need to register the new type to multiple schema names. To do this:

>>>    @core.register_type
...    class MyNewClass(...):
...        pass
>>>    core.register_type(MyNewClass, "MyOldName")

This will parse the old schema name into the new class type. You may also need to write an upgrade function if the schema itself has changed.

opentimelineio.core.type_registry.schema_label_from_name_version(schema_name, schema_version)

Return the serializeable object schema label given the name and version.


Return the schema name from the label name.


Return the schema version from the label name.

opentimelineio.core.type_registry.upgrade_function_for(cls, version_to_upgrade_to)

Decorator for identifying schema class upgrade functions.

Example >>> @upgrade_function_for(MyClass, 5) … def upgrade_to_version_five(data): … pass

This will get called to upgrade a schema of MyClass to version 5. My class must be a class deriving from otio.core.SerializableObject.

The upgrade function should take a single argument - the dictionary to upgrade, and return a dictionary with the fields upgraded.

Remember that you don’t need to provide an upgrade function for upgrades that add or remove fields, only for schema versions that change the field names.

opentimelineio.core.unknown_schema module

Implementation of the UnknownSchema schema.

class opentimelineio.core.unknown_schema.UnknownSchema

Bases: opentimelineio.core.serializable_object.SerializableObject

Represents an object whose schema is unknown to us.


Exposes the data dictionary of the underlying SerializableObject directly.