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

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:
- filepath
- simplify
- transcribe_log
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.