Plugin Documentation

This documents all the plugins that ship with in the open source OpenTimelineIO distribution.

This document is automatically generated by running the autogen_plugin_documentation command, or by running make plugin-model. It is part of the unit tests suite and should be updated whenever the schema changes. If it needs to be updated, run: make doc-plugins-update and this file should be regenerated.

Manifests

The manifests describe plugins that are visible to OpenTimelineIO. The core and contrib manifests are listed first, then any user-defined local plugins.

  • opentimelineio/adapters/builtin_adapters.plugin_manifest.json

  • opentimelineio_contrib/adapters/contrib_adapters.plugin_manifest.json

Core Plugins

Manifest path: opentimelineio/adapters/builtin_adapters.plugin_manifest.json

Adapter Plugins

Adapter plugins convert to and from OpenTimelineIO.

Adapters documentation page for more information.

Tutorial on how to write an adapter.

cmx_3600

OpenTimelineIO CMX 3600 EDL Adapter

source: opentimelineio/adapters/cmx_3600.py

Supported Features (with arguments):

  • read_from_string:

Reads a CMX Edit Decision List (EDL) from a string.
  Since EDLs don't contain metadata specifying the rate they are meant
  for, you may need to specify the rate parameter (default is 24).
  By default, read_from_string will throw an exception if it discovers
  invalid timecode in the EDL. For example, if a clip's record timecode
  overlaps with the previous cut. Since this is a common mistake in
  many EDLs, you can specify ignore_timecode_mismatch=True, which will
  supress these errors and attempt to guess at the correct record
  timecode based on the source timecode and adjacent cuts.
  For best results, you may wish to do something like this:

  Example:
      >>> try:
      ...     timeline = otio.adapters.read_from_string("mymovie.edl", rate=30)
      ... except EDLParseError:
      ...    print('Log a warning here')
      ...    try:
      ...        timeline = otio.adapters.read_from_string(
      ...            "mymovie.edl",
      ...            rate=30,
      ...            ignore_timecode_mismatch=True)
      ...    except EDLParseError:
      ...        print('Log an error here')
  • input_str

  • rate

  • ignore_timecode_mismatch

  • write_to_string:

    • input_otio

    • rate

    • style

    • reelname_len

fcp_xml

OpenTimelineIO Final Cut Pro 7 XML Adapter.

source: opentimelineio/adapters/fcp_xml.py

Supported Features (with arguments):

  • read_from_string:

    • input_str

  • write_to_string:

    • input_otio

otio_json

This adapter lets you read and write native .otio files

source: opentimelineio/adapters/otio_json.py

Supported Features (with arguments):

  • read_from_file:

De-serializes an OpenTimelineIO object from a file

  Args:
      filepath (str): The path to an otio file to read from

  Returns:
      OpenTimeline: An OpenTimeline object
  • filepath

  • read_from_string:

De-serializes an OpenTimelineIO object from a json string

  Args:
      input_str (str): A string containing json serialized otio contents

  Returns:
      OpenTimeline: An OpenTimeline object
  • input_str

  • write_to_file:

Serializes an OpenTimelineIO object into a file

  Args:

      input_otio (OpenTimeline): An OpenTimeline object
      filepath (str): The name of an otio file to write to
      indent (int): number of spaces for each json indentation level.
  Use -1 for no indentation or newlines.

  Returns:
      bool: Write success

  Raises:
      ValueError: on write error
  • input_otio

  • filepath

  • indent

  • write_to_string:

Serializes an OpenTimelineIO object into a string

  Args:
      input_otio (OpenTimeline): An OpenTimeline object
      indent (int): number of spaces for each json indentation level. Use
  -1 for no indentation or newlines.

  Returns:
      str: A json serialized string representation
  • input_otio

  • indent

otiod

OTIOD adapter - bundles otio files linked to local media in a directory

Takes as input an OTIO file that has media references which are all
ExternalReferences with target_urls to files with unique basenames that are
accessible through the file system and bundles those files and the otio file
into a single directory named with a suffix of .otiod.

source: opentimelineio/adapters/otiod.py

Supported Features (with arguments):

  • read_from_file:

    • filepath

    • absolute_media_reference_paths

  • write_to_file:

    • input_otio

    • filepath

    • media_policy

    • dryrun

otioz

OTIOZ adapter - bundles otio files linked to local media

Takes as input an OTIO file that has media references which are all
ExternalReferences with target_urls to files with unique basenames that are
accessible through the file system and bundles those files and the otio file
into a single zip file with the suffix .otioz.  Can error out if files aren't
locally referenced or provide missing references

Can also extract the content.otio file from an otioz bundle for processing.

Note that OTIOZ files _always_ use the unix style path separator ('/'). This
ensures that regardless of which platform a bundle was created on, it can be
read on unix and windows platforms.

source: opentimelineio/adapters/otioz.py

Supported Features (with arguments):

  • read_from_file:

    • filepath

    • extract_to_directory

  • write_to_file:

    • input_otio

    • filepath

    • media_policy

    • dryrun

svg

OTIO to SVG Adapter
Points in calculations are y-up.
Points in SVG are y-down.

source: opentimelineio/adapters/svg.py

Supported Features (with arguments):

  • write_to_string:

    • input_otio

    • width

    • height

Media Linkers

Media Linkers run after the adapter has read in the file and convert the media references into valid references where appropriate.

Tutorial on how to write a Media Linker.

SchemaDefs

SchemaDef plugins define new external schema.

Tutorial on how to write a schemadef.

HookScripts

HookScripts are extra plugins that run on hooks.

Tutorial on how to write a hookscript.

Hooks

Hooks are the points at which hookscripts will run.

Contrib Plugins

Plugins in Contrib are supported by the community and provided as-is.

Manifest path: opentimelineio_contrib/adapters/contrib_adapters.plugin_manifest.json

Adapter Plugins

Adapter plugins convert to and from OpenTimelineIO.

Adapters documentation page for more information.

Tutorial on how to write an adapter.

AAF

OpenTimelineIO Advanced Authoring Format (AAF) Adapter

Depending on if/where PyAAF is installed, you may need to set this env var:
    OTIO_AAF_PYTHON_LIB - should point at the PyAAF module.

source: opentimelineio_contrib/adapters/advanced_authoring_format.py

Supported Features (with arguments):

  • read_from_file:

Reads AAF content from `filepath` and outputs an OTIO
  timeline object.

  Args:
      filepath (str): AAF filepath
      simplify (bool, optional): simplify timeline structure by stripping empty
  items
      transcribe_log (bool, optional): log activity as items are getting
  transcribed
      attach_markers (bool, optional): attaches markers to their appropriate items
                                       like clip, gap. etc on the track
      bake_keyframed_properties (bool, optional): bakes animated property values
                                                  for each frame in a source clip
  Returns:
      otio.schema.Timeline
  • filepath

  • simplify

  • transcribe_log

  • attach_markers

  • bake_keyframed_properties

  • write_to_file:

    • input_otio

    • filepath

ale

OpenTimelineIO Avid Log Exchange (ALE) Adapter

source: opentimelineio_contrib/adapters/ale.py

Supported Features (with arguments):

  • read_from_string:

    • input_str

    • fps

  • write_to_string:

    • input_otio

    • columns

    • fps

    • video_format

burnins

FFMPEG Burnins Adapter

source: opentimelineio_contrib/adapters/burnins.py

Supported Features (with arguments):

  • write_to_file:

required OTIO function hook
  • input_otio

  • filepath

fcpx_xml

OpenTimelineIO Final Cut Pro X XML Adapter. 

source: opentimelineio_contrib/adapters/fcpx_xml.py

Supported Features (with arguments):

  • read_from_string:

Necessary read method for otio adapter

  Args:
      input_str (str): An FCP X XML string

  Returns:
      OpenTimeline: An OpenTimeline object
  • input_str

  • write_to_string:

Necessary write method for otio adapter

  Args:
      input_otio (OpenTimeline): An OpenTimeline object

  Returns:
      str: The string contents of an FCP X XML
  • input_otio

hls_playlist

HLS Playlist OpenTimelineIO adapter

This adapter supports authoring of HLS playlists within OpenTimelineIO by using
clips to represent media fragments.

Status:
    - Export of Media Playlists well supported
    - Export of Master Playlists supported
    - Import of Media Playlists well supported
    - Import of Master Playlists unsupported
    - Explicit Variant Stream controls in Master Playlists unsupported

In general, you can author otio as follows:
    t = otio.schema.Timeline()
    track = otio.schema.Track("v1")
    track.metadata['HLS'] = {
        "EXT-X-INDEPENDENT-SEGMENTS": None,
        "EXT-X-PLAYLIST-TYPE": "VOD"
    }
    t.tracks.append(track)

    # Make a prototype media ref with the fragment's initialization metadata
    fragmented_media_ref = otio.schema.ExternalReference(
        target_url='video1.mp4',
        metadata={
            "streaming": {
                "init_byterange": {
                    "byte_count": 729,
                    "byte_offset": 0
                },
                "init_uri": "media-video-1.mp4"
            }
        }
    )

    # Make a copy of the media ref specifying the byte range for the fragment
    media_ref1 = fragmented_media_ref.deepcopy()
    media_ref1.available_range=otio.opentime.TimeRange(
        otio.opentime.RationalTime(0, 1),
        otio.opentime.RationalTime(2.002, 1)
    )
    media_ref1.metadata['streaming'].update(
        {
            "byte_count": 534220,
            "byte_offset": 1361
        }
    )

    # make the fragment and append it
    fragment1 = otio.schema.Clip(media_reference=media_ref1)
    track.append(fragment1)

    # (repeat to define each fragment)

The code above would yield an HLS playlist like:
    #EXTM3U
    #EXT-X-VERSION:7
    #EXT-X-TARGETDURATION:2
    #EXT-X-PLAYLIST-TYPE:VOD
    #EXT-X-INDEPENDENT-SEGMENTS
    #EXT-X-MEDIA-SEQUENCE:1
    #EXT-X-MAP:BYTERANGE="729@0",URI="media-video-1.mp4"
    #EXTINF:2.00200,
    #EXT-X-BYTERANGE:534220@1361
    video1.mp4
    #EXT-X-ENDLIST

If you add min_segment_duration and max_segment_duration to the timeline's
metadata dictionary as RationalTime objects, you can control the rule set
deciding how many fragments to accumulate into a single segment. When nothing
is specified for these metadata keys, the adapter will create one segment per
fragment.

In general, any metadata added to the track metadata dict under the HLS
namespace will be included at the top level of the exported playlist (see
``EXT-X-INDEPENDENT-SEGMENTS`` and ``EXT-X-PLAYLIST-TYPE`` in the example
above). Each segment will pass through any metadata in the HLS namespace from
the media_reference.

If you write a Timeline with more than one track specified, then the adapter
will create an HLS master playlist.

The following track metadata keys will be used to inform exported master
playlist metadata per variant stream:
    bandwidth
    codec
    language
    mimeType
    group_id (audio)
    autoselect (audio)
    default (audio)
These values are translated to EXT-X-STREAM-INF and EXT-X-MEDIA
attributes as defined in sections 4.3.4.2 and 4.3.4.1 of
draft-pantos-http-live-streaming, respectively.

source: opentimelineio_contrib/adapters/hls_playlist.py

Supported Features (with arguments):

  • read_from_string:

Adapter entry point for reading.
  • input_str

  • write_to_string:

Adapter entry point for writing.
  • input_otio

kdenlive

Kdenlive (MLT XML) Adapter.

source: opentimelineio_contrib/adapters/kdenlive.py

Supported Features (with arguments):

  • read_from_string:

Read a Kdenlive project (MLT XML)
  Kdenlive uses a given MLT project layout, similar to Shotcut,
  combining a "main_bin" playlist to organize source media,
  and a "global_feed" tractor for timeline.
  (in Kdenlive 19.x, timeline tracks include virtual sub-track, unused for now)
  • input_str

  • write_to_string:

Write a timeline to Kdenlive project
  Re-creating the bin storing all used source clips
  and constructing the tracks
  • input_otio

maya_sequencer

Maya Sequencer Adapter Harness

source: opentimelineio_contrib/adapters/maya_sequencer.py

Supported Features (with arguments):

  • read_from_file:

    • filepath

  • write_to_file:

    • input_otio

    • filepath

rv_session

RvSession Adapter harness

source: opentimelineio_contrib/adapters/rv.py

Supported Features (with arguments):

  • write_to_file:

    • input_otio

    • filepath

xges

OpenTimelineIO GStreamer Editing Services XML Adapter.

source: opentimelineio_contrib/adapters/xges.py

Supported Features (with arguments):

  • read_from_string:

Necessary read method for otio adapter

  Args:
      input_str (str): A GStreamer Editing Services formated project

  Returns:
      OpenTimeline: An OpenTimeline object
  • input_str

  • write_to_string:

Necessary write method for otio adapter

  Args:
      input_otio (OpenTimeline): An OpenTimeline object

  Returns:
      str: The string contents of an FCP X XML
  • input_otio

Media Linkers

Media Linkers run after the adapter has read in the file and convert the media references into valid references where appropriate.

Tutorial on how to write a Media Linker.

SchemaDefs

SchemaDef plugins define new external schema.

Tutorial on how to write a schemadef.

xges

OpenTimelineIO GStreamer Editing Services XML Adapter.

source: opentimelineio_contrib/adapters/xges.py

Serializable Classes:

  • GESMarker:

An OpenTimelineIO Schema that is a timestamp with metadata,
  essentially mimicking the GstMarker of the GES C libarary.
  • GESMarkerList:

An OpenTimelineIO Schema that is a list of GESMarkers,
  ordered by
  their positions, essentially mimicking the GstMarkerList of the GES
  C libarary.
  • GstCaps:

An OpenTimelineIO Schema that acts as an ordered collection of
  GstStructures, essentially mimicking the GstCaps of the Gstreamer C
  libarary. Each GstStructure is linked to a GstCapsFeatures, which is
  a list of features.

  In particular, this schema mimics the gst_caps_to_string and
  gst_caps_from_string C methods.
  • GstCapsFeatures:

An OpenTimelineIO Schema that contains a collection of
  features,
  mimicking a GstCapsFeatures of the Gstreamer C libarary.
  • GstStructure:

An OpenTimelineIO Schema that acts as a named dictionary with
  typed entries, essentially mimicking the GstStructure of the
  GStreamer C library.

  In particular, this schema mimics the gst_structure_to_string and
  gst_structure_from_string C methods. As such, it can be used to
  read and write the properties and metadatas attributes found in
  xges elements.

  Note that the types are to correspond to GStreamer/GES GTypes,
  rather than python types.

  Current supported GTypes:
  GType         Associated    Accepted
                Python type   aliases
  ======================================
  gint          int           int, i
  glong         int
  gint64        int
  guint         int           uint, u
  gulong        int
  guint64       int
  gfloat        float         float, f
  gdouble       float         double, d
  gboolean      bool          boolean,
                              bool, b
  string        str or None   str, s
  GstFraction   str or        fraction
                Fraction
  GstStructure  GstStructure  structure
                schema
  GstCaps       GstCaps
                schema
  GESMarkerList GESMarkerList
                schema

  Note that other types can be given: these must be given as strings
  and the user will be responsible for making sure they are already in
  a serialized form.
  • XgesTrack:

An OpenTimelineIO Schema for storing a GESTrack.

  Not to be confused with OpenTimelineIO's schema.Track.

HookScripts

HookScripts are extra plugins that run on hooks.

Tutorial on how to write a hookscript.

Hooks

Hooks are the points at which hookscripts will run.