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¶
Adapter for reading and writing native .otio json 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.
If target_schema_versions is None and the environment variable
"OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL" is set, will read a map out of
that for downgrade target. The variable should be of the form
FAMILY:LABEL, for example "MYSTUDIO:JUNE2022".
Returns:
bool: Write success
Raises:
ValueError: on write error
otio.exceptions.InvalidEnvironmentVariableError: if there is a problem
with the default environment variable
"OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL".
input_otio
filepath
target_schema_versions
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.
If target_schema_versions is None and the environment variable
"OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL" is set, will read a map out of
that for downgrade target. The variable should be of the form
FAMILY:LABEL, for example "MYSTUDIO:JUNE2022".
Returns:
str: A json serialized string representation
Raises:
otio.exceptions.InvalidEnvironmentVariableError: if there is a problem
with the default environment variable
"OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL".
input_otio
target_schema_versions
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.
SchemaDefs¶
SchemaDef plugins define new external schema.
HookScripts¶
HookScripts are extra plugins that run on hooks.
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
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
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.
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.
Hooks¶
Hooks are the points at which hookscripts will run.