# 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.
<a href=”adapters.html” target=”_blank”> Adapters documentation page for more information</a>
<a href=”write-an-adapter.html” target=”_blank”>Tutorial on how to write an adapter.</a>
### 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:
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
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
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
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
## Media Linkers
Media Linkers run after the adapter has read in the file and convert the media references into valid references where appropriate.
<a href=”write-a-media-linker.html” target=”_blank”> Tutorial on how to write a Media Linker</a>
## SchemaDefs
SchemaDef plugins define new external schema.
<a href=”write-a-schemadef.html” target=”_blank”> Tutorial on how to write a schemadef</a>
## HookScripts
HookScripts are extra plugins that run on _hooks_.
<a href=”write-a-hookscript.html” target=”_blank”>Tutorial on how to write a hookscript.</a>
## 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.
<a href=”adapters.html” target=”_blank”> Adapters documentation page for more information</a>
<a href=”write-an-adapter.html” target=”_blank”>Tutorial on how to write an adapter.</a>
### 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
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
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
### 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)
write_to_string:
``` Write a timeline to Kdenlive project
Re-creating the bin storing all used source clips and constructing the tracks
### 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
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
## Media Linkers
Media Linkers run after the adapter has read in the file and convert the media references into valid references where appropriate.
<a href=”write-a-media-linker.html” target=”_blank”> Tutorial on how to write a Media Linker</a>
## SchemaDefs
SchemaDef plugins define new external schema.
<a href=”write-a-schemadef.html” target=”_blank”> Tutorial on how to write a schemadef</a>
### xges
`
OpenTimelineIO GStreamer Editing Services XML Adapter.
`
source: opentimelineio_contrib/adapters/xges.py
Serializable Classes:
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
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_.
<a href=”write-a-hookscript.html” target=”_blank”>Tutorial on how to write a hookscript.</a>
## Hooks
Hooks are the points at which hookscripts will run.