opentimelineio package

An editorial interchange format and library.

see: http://opentimeline.io

Subpackages

Submodules

opentimelineio.exceptions module

Exception classes for OpenTimelineIO

exception opentimelineio.exceptions.AdapterDoesntSupportFunctionError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.CannotComputeAvailableRangeError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.CannotTrimTransitionsError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.CouldNotReadFileError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.InstancingNotAllowedError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.InvalidSerializableLabelError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.MisconfiguredPluginError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.NoDefaultMediaLinkerError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.NoKnownAdapterForExtensionError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.NotAChildError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.NotSupportedError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.OTIOError

Bases: Exception

exception opentimelineio.exceptions.ReadingNotSupportedError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.TransitionFollowingATransitionError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.UnsupportedSchemaError

Bases: opentimelineio.exceptions.OTIOError

exception opentimelineio.exceptions.WritingNotSupportedError

Bases: opentimelineio.exceptions.OTIOError

opentimelineio.hooks module

HookScripts are plugins that run at defined points (“Hooks”).

They expose a hook_function with signature: hook_function :: otio.schema.Timeline, Dict -> otio.schema.Timeline

Both hook scripts and the hooks they attach to are defined in the plugin manifest.

You can attach multiple hook scripts to a hook. They will be executed in list order, first to last.

They are defined by the manifests HookScripts and hooks areas.

>>>
{
    "OTIO_SCHEMA" : "PluginManifest.1",
    "hook_scripts" : [
        {
            "OTIO_SCHEMA" : "HookScript.1",
            "name" : "example hook",
            "execution_scope" : "in process",
            "filepath" : "example.py"
        }
    ],
    "hooks" : {
        "pre_adapter_write" : ["example hook"],
        "post_adapter_read" : []
    }
}

The ‘hook_scripts’ area loads the python modules with the ‘hook_function’s to call in them. The ‘hooks’ area defines the hooks (and any associated scripts). You can further query and modify these from python.

>>> import opentimelineio as otio
... hook_list = otio.hooks.scripts_attached_to("some_hook") # -> ['a','b','c']
...
... # to run the hook scripts:
... otio.hooks.run("some_hook", some_timeline, optional_argument_dict)

This will pass (some_timeline, optional_argument_dict) to ‘a’, which will a new timeline that will get passed into ‘b’ with optional_argument_dict, etc.

To Edit the order, change the order in the list:

>>> hook_list[0], hook_list[2] = hook_list[2], hook_list[0]
... print hook_list # ['c','b','a']

Now c will run, then b, then a.

To delete a function the list:

>>> del hook_list[1]
class opentimelineio.hooks.HookScript(name=None, execution_scope=None, filepath=None)

Bases: opentimelineio.plugins.python_plugin.PythonPlugin

run(in_timeline, argument_map={})

Run the hook_function associated with this plugin.

opentimelineio.hooks.available_hookscript_names()

Return the names of HookScripts that have been registered.

opentimelineio.hooks.available_hookscripts()

Return the HookScripts objects that have been registered.

opentimelineio.hooks.names()

Return a list of all the registered hooks.

opentimelineio.hooks.run(hook, tl, extra_args=None)

Run all the scripts associated with hook, passing in tl and extra_args.

Will return the return value of the last hook script.

If no hookscripts are defined, returns tl.

opentimelineio.hooks.scripts_attached_to(hook)

Return an editable list of all the hook scriptss that are attached to the specified hook, in execution order. Changing this list will change the order that scripts run in, and deleting a script will remove it from executing

opentimelineio.media_linker module

MediaLinker plugins fire after an adapter has read a file in oder to produce MediaReferences that point at valid, site specific media.

They expose a “link_media_reference” function with the signature: link_media_reference :: otio.schema.Clip -> otio.core.MediaReference

or:
def linked_media_reference(from_clip):

result = otio.core.MediaReference() # whichever subclass # do stuff return result

To get context information, they can inspect the metadata on the clip and on the media reference. The .parent() method can be used to find the containing track if metadata is stored there.

Please raise an instance (or child instance) of otio.exceptions.CannotLinkMediaError() if there is a problem linking the media.

For example:
for clip in timeline.each_clip():
try:

new_mr = otio.media_linker.linked_media_reference(clip) clip.media_reference = new_mr

except otio.exceptions.CannotLinkMediaError:

# or report the error pass

class opentimelineio.media_linker.MediaLinker(name=None, execution_scope=None, filepath=None)

Bases: opentimelineio.plugins.python_plugin.PythonPlugin

class opentimelineio.media_linker.MediaLinkingPolicy

Bases: object

DoNotLinkMedia = '__do_not_link_media'
ForceDefaultLinker = '__default'
opentimelineio.media_linker.available_media_linker_names()

Return a string list of the available media linker plugins.

opentimelineio.media_linker.default_media_linker()
opentimelineio.media_linker.from_name(name)

Fetch the media linker object by the name of the adapter directly.

opentimelineio.media_linker.linked_media_reference(target_clip, media_linker_name='__default', media_linker_argument_map=None)

opentimelineio.opentime module

Library for expressing and transforming time.

NOTE: This module is written specifically with a future port to C in mind. When ported to C, Time will be a struct and these functions should be very simple.

class opentimelineio.opentime.BoundStrategy

Bases: object

Different bounding strategies for TimeRange

Clamp = 2
Free = 1
class opentimelineio.opentime.RationalTime(value=0, rate=1)

Bases: object

Represents an instantaneous point in time, value * (1/rate) seconds from time 0seconds.

almost_equal(other, delta=0.0)
rescaled_to(new_rate)

Returns the time for this time converted to new_rate

value_rescaled_to(new_rate)

Returns the time value for self converted to new_rate

class opentimelineio.opentime.TimeRange(start_time=otio.opentime.RationalTime(value=0, rate=1), duration=otio.opentime.RationalTime(value=0, rate=1))

Bases: object

Contains a range of time, starting (and including) start_time and lasting duration.value * (1/duration.rate) seconds.

A 0 duration TimeRange is the same as a RationalTime, and contains only the start_time of the TimeRange.

clamped(other, start_bound=1, end_bound=1)

Apply the range to either a RationalTime or a TimeRange. If applied to a TimeRange, the resulting TimeRange will have the same boundary policy as other. (in other words, _not_ the same as self).

contains(other)

Return true if self completely contains other.

(RationalTime or TimeRange)

property duration
end_time_exclusive()

“Time of the first sample outside the time range.

If Start Frame is 10 and duration is 5, then end_time_exclusive is 15, even though the last time with data in this range is 14.

If Start Frame is 10 and duration is 5.5, then end_time_exclusive is 15.5, even though the last time with data in this range is 15.

end_time_inclusive()

The time of the last sample that contains data in the TimeRange.

If the TimeRange goes from (0, 24) w/ duration (10, 24), this will be (9, 24)

If the TimeRange goes from (0, 24) w/ duration (10.5, 24): (10, 24)

In other words, the last frame with data (however fractional).

extended_by(other)

Construct a new TimeRange that is this one extended by another.

overlaps(other)

Return true if self overlaps any part of other.

(RationalTime or TimeRange)

class opentimelineio.opentime.TimeTransform(offset=otio.opentime.RationalTime(value=0, rate=1), scale=1.0, rate=None)

Bases: object

1D Transform for RationalTime. Has offset and scale.

applied_to(other)
opentimelineio.opentime.duration_from_start_end_time(start_time, end_time_exclusive)

Compute duration of samples from first to last. This is not the same as distance. For example, the duration of a clip from frame 10 to frame 15 is 6 frames. Result in the rate of start_time.

opentimelineio.opentime.from_footage(footage)
opentimelineio.opentime.from_frames(frame, fps)

Turn a frame number and fps into a time object. :param frame: (int) Frame number. :param fps: (float) Frame-rate for the (RationalTime) instance.

Returns

(RationalTime) Instance for the frame and fps provided.

opentimelineio.opentime.from_seconds(seconds)

Convert a number of seconds into RationalTime

opentimelineio.opentime.from_time_string(time_str, rate)

Convert a time with microseconds string into a RationalTime.

Parameters

  • time_str – (str) A HH:MM:ss.ms time.

  • rate – (float) The frame-rate to calculate timecode in terms of.

Returns

(RationalTime) Instance for the timecode provided.

opentimelineio.opentime.from_timecode(timecode_str, rate)

Convert a timecode string into a RationalTime.

Parameters

  • timecode_str – (str) A colon-delimited timecode.

  • rate – (float) The frame-rate to calculate timecode in terms of.

Returns

(RationalTime) Instance for the timecode provided.

opentimelineio.opentime.range_from_start_end_time(start_time, end_time_exclusive)

Create a TimeRange from start and end RationalTimes.

opentimelineio.opentime.to_footage(time_obj)
opentimelineio.opentime.to_frames(time_obj, fps=None)

Turn a RationalTime into a frame number.

opentimelineio.opentime.to_seconds(time_obj)

Convert a RationalTime into float seconds

opentimelineio.opentime.to_time_string(time_obj)

Convert this timecode to time with microsecond, as formated in FFMPEG

Returns

Number formated string of time

opentimelineio.opentime.to_timecode(time_obj, rate=None)

Convert a RationalTime into a timecode string.

Parameters

  • time_obj – (RationalTime) instance to express as timecode.

  • rate – (float) The frame-rate to calculate timecode in terms of. (Default time_obj.rate)

Returns

(str) The timecode.

opentimelineio.opentime.validate_timecode_rate(rate)

Check if rate is of valid type and value. Raises (TypeError for wrong type of rate. Raises (VaueError) for invalid rate value.

Parameters

rate – (int) or (float) The frame rate in question

opentimelineio.test_utils module

Utility assertions for OTIO Unit tests.

class opentimelineio.test_utils.OTIOAssertions

Bases: object

assertIsOTIOEquivalentTo(known, test_result)

Test using the ‘is equivalent to’ method on SerializableObject

assertJsonEqual(known, test_result)

Convert to json and compare that (more readable).