Package: sg-otio
SG Otio, an OpenTimelineIO ShotGrid LibraryA library to representOpenTimelineIOdata inShotGrid,
and vice versa.DisclaimerSG Otio is currently in Public Alpha. That means that it may be missing
some essential features and there are large changes planned. During this phase
we actively encourage you to provide feedback, requests, comments, and/or
contributions.InstallationSG Python APIThe SG Python API is not available on PyPi and must be manually installed
from github, e.g.pip install git+https://github.com/shotgunsoftware/python-api.gitffmpegsg-otio requires ffmpeg to be installed, and ffmpeg must be in thePATH.Binaries can be downloaded fromFFmpeg download page, in which case the
binaries should be added to thePATHenvironment variable.A package manager can be used, for example on MacOS,brew install ffmpeg, in
which case the PATH should already be updated by the package manager.sg-otio packageSG Otio can be installed from PyPi, e.g.pip install sg-otioSG Otio can also be installed from sources.Get a local copy of this repo:git clone https://github.com/GPLgithub/sg-otio.gitInstall it withpip:pip install ./sg-otiosg-otio usageYou can access the help withsg-otio read --help,sg-otio write --help, orsg-otio compare --help.ShotGrid login informationYou can provide Shotgrid login information in 3 different ways:--login <username> --password <password>--script-name <script name> --api-key <api key>--session-token <session token>Reading a Cut from SGRead a Cut from SG and either output it in OTIO format or write it to a file. Any format suppported by OpenTimelineIO's standard adapters is supported.Examples:sg-otio read --sg-site-url URL --session-token TOKEN --cut-id CUT_ID
sg-otio read --sg-site-url URL --session-token TOKEN --cut-id CUT_ID --file output.otio
sg-otio read --sg-site-url URL --session-token TOKEN --cut-id CUT_ID --file output.xml --adapter-name fcp_xml
sg-otio read --settings SETTINGS.JSON --sg-site-url URL --session-token TOKEN --cut-id CUT_ID --file output.xml --adapter-name fcp_xmlWriting a Cut to SGWrite a Video Track to SG as a Cut.
Example:sg-otio write -u URL --session-token TOKEN --entity-type Cut --entity-id CUT_ID --file INPUT.edl --movie INPUT.mov --settings SETTINGS.JSONComparing a Video Track to a SG CutRead a Video Track from an OpenTimelinio source and compare it to an existing SG Cut.
Any format suppported by OpenTimelineIO's standard adapters is supported for the source.
The video Track can be written to SG as a new Cut by adding the--writeargument.
The new SG Cut will be linked to the SG Entity the previous SG Cut is linked to.
Examples:sg-otio compare --sg-site-url URL  --session-token TOKEN --file INPUT OTIO --cut-id CUT_ID
sg-otio compare --sg-site-url URL  --session-token TOKEN --file INPUT OTIO --cut-id CUT_ID --writeSettings fileSome settings for sg-otio read and write can be stored in a JSON file, and passed
to sg-otio with--settings[-s] path/to/SETTINGS.JSON.
This is what such file would contain with the default settings:{"default_head_in":1001,"default_head_duration":8,"default_tail_duration":8,"use_clip_names_for_shot_names":false,"clip_name_shot_regexp":null,"local_storage_name":"primary","versions_path_template":"{PROJECT}/{LINK}/{YYYY}{MM}{DD}/cuts","version_names_template":null,"create_missing_versions":true,"timecode_in_to_frame_mapping_mode":1,"timecode_in_to_frame_relative_mapping":["00:00:00:01",1001],"use_smart_fields":false,"shot_cut_fields_prefix":null,"shot_omit_status":"omt","shot_reinstate_status":"Previous Status","shot_reinstate_status_default":"act","reinstate_shot_if_status_is":["omt","hld"]}Default Head In, Default Head Duration, Default Tail DurationWhen creating new Shots in ShotGrid, the values to use for the start frame and handles.Use Clip Names for Shot NamesIf set to True, the Clip name will be used as a Shot name if it can't be computed from
locators nor comments in the EDL.Clip Name Shot RegexpIf set, use a regular expression to extract the Shot name from the Clip name.Create Missing VersionsIf set to True, for Clips with media references that don't have a version in ShotGrid,
a new version will be created in ShotGrid.For an EDL without media references, a movie of the Cut needs to be passed to sg-otio,
which will allow to extract the Versions from the Cut movie.For formats like Premiere XML, this means that media references existing in the XML
file will be published to ShotGrid.Local storage nameWhen creating missing Versions, the SG local storage to use to publish the files to.Versions Path TemplateWhen creating missing Versions, the path to use to publish the files to.This is a relative path from the local storage chosen.The following keys are available:PROJECT, CUT_TITLE, LINK, HH, DD, MM, YY, YYYYExample valid templates:{PROJECT}/{LINK}/{YYYY}{MM}{DD}/cuts (default){PROJECT}/{CUT_TITLE}/{YYYY}{MM}{DD}/Version Names TemplateIf not specified, the Version name will be the Clip name.
If specified, the Version name will be computed using the template.The following keys are available:CLIP_NAME, CUT_ITEM_NAME, SHOT, CLIP_INDEX, UUIDTheCLIP_NAMEandCUT_ITEM_NAMEare almost the same, but theCUT_ITEM_NAMEis guaranteed to be unique in a track.
For example, if there are two clips with the nameclip1, their cut item names
will beclip1andclip1_001.TheCLIP_INDEXis the index of the clip in the track (starting from 1, and counting
only clips, not gaps or other elements).TheUUIDis 6 digits long.Even though versions with the same names are allowed, it is recommended to use keys that
guarantee the unicity of the names, like CUT_ITEM_NAME, CLIP_INDEX, or UUID.Example valid templates:{CLIP_NAME}_{UUID}(default){CUT_ITEM_NAME}{SHOT}_{CLIP_INDEX}{CLIP_NAME}_{CLIP_INDEX:04d}(adds some leading zeros)Timecode In to Frame Mapping ModeDifferent timecode in values to frame mapping modesThree mapping modes are available, which are only relevant for straight
imports (without comparing to a previous Cut):0: Automatic. Timecode in is mapped to the Shot head in.1: Absolute. Timecode is converted to an absolute frame number.2: Relative. timecode in is converted to an arbitrary frame
number specified through settings. Example:["00:00:00:01", 1001]Timecode In to Frame Relative Mapping.If the Timecode In to Frame Mapping Mode is set to2, this setting can be used to specify
how to convert the timecode to an arbitrary frame number.Use Smart FieldsIf set to True, the Smart Cut Fields will be used to fill the Shot fields.Shot Cut Fields PrefixIf set, the Shot Cut Fields will be custom fields that use this prefix,
e.g.sg_PREFIX_cut_in,sg_PREFIX_cut_out, etc.Omitting and Reinstating ShotsIf some Shots are omitted from one Cut to the other, their Status will be set
to theshot_omit_statussetting value.
Shots which appear again in a Cut will be reinstated if their current status
is one of the statuses set with thereinstate_shot_if_status_issetting.
Their status will be set to the value set with theshot_reinstate_statussetting,
unless it is the special "Previous Status" value. In this case the status they
had before being omitted will be set.To determine the previous status, it relies on EventLogEntries, which means that if it can't find
one (e.g. they were purged), it will use the value set with theshot_reinstate_status_defaultsetting.LicenseSG Otio is open source software. Please see theLICENSE.txtfor details.