SG Otio, an OpenTimelineIO ShotGrid Library
=======
[](https://github.com/GPLgithub/sg-otio/actions/workflows/ci.yaml)
[](https://codecov.io/gh/GPLgithub/sg-otio)
A library to represent [OpenTimelineIO](http://opentimeline.io/) data in [ShotGrid](https://www.shotgrid.com),
and vice versa.
Disclaimer
----------
SG 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.
Installation
------------
### SG Python API
The 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.git`
### ffmpeg
sg-otio requires ffmpeg to be installed, and ffmpeg must be in the `PATH`.
- Binaries can be downloaded from [FFmpeg download page](https://ffmpeg.org/download.html), in which case the
binaries should be added to the `PATH` environment 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 package
SG Otio can be installed from PyPi, e.g. `pip install sg-otio`
SG Otio can also be installed from sources.
- Get a local copy of this repo: `git clone https://github.com/GPLgithub/sg-otio.git`
- Install it with `pip`: `pip install ./sg-otio`
sg-otio usage
-------------
You can access the help with `sg-otio read --help`, `sg-otio write --help`, or `sg-otio compare --help`.
### ShotGrid login information
You 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 SG
Read 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_xml
```
### Writing a Cut to SG
Write 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.JSON
```
### Comparing a Video Track to a SG Cut
Read 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 `--write` argument.
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 --write
```
### Settings file
Some 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:
```json
{
"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 Duration
When creating new Shots in ShotGrid, the values to use for the start frame and handles.
##### Use Clip Names for Shot Names
If 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 Regexp
If set, use a regular expression to extract the Shot name from the Clip name.
#### Create Missing Versions
If 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 name
When creating missing Versions, the SG local storage to use to publish the files to.
#### Versions Path Template
When 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, YYYY`
Example valid templates:
- `{PROJECT}/{LINK}/{YYYY}{MM}{DD}/cuts (default)`
- `{PROJECT}/{CUT_TITLE}/{YYYY}{MM}{DD}/`
#### Version Names Template
If 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, UUID`
The `CLIP_NAME` and `CUT_ITEM_NAME` are almost the same, but the `CUT_ITEM_NAME`
is guaranteed to be unique in a track.
For example, if there are two clips with the name `clip1`, their cut item names
will be `clip1` and `clip1_001`.
The `CLIP_INDEX` is the index of the clip in the track (starting from 1, and counting
only clips, not gaps or other elements).
The `UUID` is 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 Mode
Different timecode in values to frame mapping modes
Three 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 to `2`, this setting can be used to specify
how to convert the timecode to an arbitrary frame number.
#### Use Smart Fields
If set to True, the Smart Cut Fields will be used to fill the Shot fields.
#### Shot Cut Fields Prefix
If 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 Shots
If some Shots are omitted from one Cut to the other, their Status will be set
to the `shot_omit_status` setting value.
Shots which appear again in a Cut will be reinstated if their current status
is one of the statuses set with the `reinstate_shot_if_status_is` setting.
Their status will be set to the value set with the `shot_reinstate_status` setting,
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 the `shot_reinstate_status_default` setting.
License
-------
SG Otio is open source software. Please see the [LICENSE.txt](LICENSE.txt) for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/GPLgithub/sg-otio.git",
"name": "sg-otio",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "GPL Technologies",
"author_email": "pipelinesupport@gpltech.com",
"download_url": null,
"platform": null,
"description": "SG Otio, an OpenTimelineIO ShotGrid Library\n=======\n\n[](https://github.com/GPLgithub/sg-otio/actions/workflows/ci.yaml)\n\n[](https://codecov.io/gh/GPLgithub/sg-otio)\n\nA library to represent [OpenTimelineIO](http://opentimeline.io/) data in [ShotGrid](https://www.shotgrid.com),\nand vice versa.\n\nDisclaimer\n----------\n\nSG Otio is currently in Public Alpha. That means that it may be missing\nsome essential features and there are large changes planned. During this phase\nwe actively encourage you to provide feedback, requests, comments, and/or\ncontributions.\n\n\nInstallation\n------------\n\n### SG Python API\n\nThe SG Python API is not available on PyPi and must be manually installed\nfrom github, e.g. `pip install git+https://github.com/shotgunsoftware/python-api.git`\n\n### ffmpeg\nsg-otio requires ffmpeg to be installed, and ffmpeg must be in the `PATH`.\n\n- Binaries can be downloaded from [FFmpeg download page](https://ffmpeg.org/download.html), in which case the\nbinaries should be added to the `PATH` environment variable.\n- A package manager can be used, for example on MacOS, `brew install ffmpeg`, in\nwhich case the PATH should already be updated by the package manager.\n\n### sg-otio package\n\nSG Otio can be installed from PyPi, e.g. `pip install sg-otio`\n\nSG Otio can also be installed from sources.\n- Get a local copy of this repo: `git clone https://github.com/GPLgithub/sg-otio.git`\n- Install it with `pip`: `pip install ./sg-otio`\n\nsg-otio usage\n-------------\n\nYou can access the help with `sg-otio read --help`, `sg-otio write --help`, or `sg-otio compare --help`. \n\n### ShotGrid login information\n\nYou can provide Shotgrid login information in 3 different ways:\n- `--login <username> --password <password>`\n- `--script-name <script name> --api-key <api key>`\n- `--session-token <session token>`\n\n### Reading a Cut from SG\nRead 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.\n\nExamples:\n```\nsg-otio read --sg-site-url URL --session-token TOKEN --cut-id CUT_ID\nsg-otio read --sg-site-url URL --session-token TOKEN --cut-id CUT_ID --file output.otio\nsg-otio read --sg-site-url URL --session-token TOKEN --cut-id CUT_ID --file output.xml --adapter-name fcp_xml\nsg-otio read --settings SETTINGS.JSON --sg-site-url URL --session-token TOKEN --cut-id CUT_ID --file output.xml --adapter-name fcp_xml\n```\n\n### Writing a Cut to SG\nWrite a Video Track to SG as a Cut.\nExample:\n```\nsg-otio write -u URL --session-token TOKEN --entity-type Cut --entity-id CUT_ID --file INPUT.edl --movie INPUT.mov --settings SETTINGS.JSON\n```\n\n### Comparing a Video Track to a SG Cut\nRead a Video Track from an OpenTimelinio source and compare it to an existing SG Cut.\nAny format suppported by OpenTimelineIO's standard adapters is supported for the source.\nThe video Track can be written to SG as a new Cut by adding the `--write` argument.\nThe new SG Cut will be linked to the SG Entity the previous SG Cut is linked to.\nExamples:\n```\nsg-otio compare --sg-site-url URL --session-token TOKEN --file INPUT OTIO --cut-id CUT_ID\nsg-otio compare --sg-site-url URL --session-token TOKEN --file INPUT OTIO --cut-id CUT_ID --write\n``` \n\n### Settings file\n\nSome settings for sg-otio read and write can be stored in a JSON file, and passed\nto sg-otio with `--settings[-s] path/to/SETTINGS.JSON`.\nThis is what such file would contain with the default settings:\n```json\n{\n \"default_head_in\": 1001,\n \"default_head_duration\": 8,\n \"default_tail_duration\": 8,\n \"use_clip_names_for_shot_names\": false,\n \"clip_name_shot_regexp\": null,\n \"local_storage_name\": \"primary\",\n \"versions_path_template\": \"{PROJECT}/{LINK}/{YYYY}{MM}{DD}/cuts\",\n \"version_names_template\": null,\n \"create_missing_versions\": true,\n \"timecode_in_to_frame_mapping_mode\": 1,\n \"timecode_in_to_frame_relative_mapping\": [\"00:00:00:01\", 1001],\n \"use_smart_fields\": false,\n \"shot_cut_fields_prefix\": null,\n \"shot_omit_status\": \"omt\",\n \"shot_reinstate_status\": \"Previous Status\",\n \"shot_reinstate_status_default\": \"act\",\n \"reinstate_shot_if_status_is\": [\"omt\", \"hld\"]\n}\n```\n\n#### Default Head In, Default Head Duration, Default Tail Duration\nWhen creating new Shots in ShotGrid, the values to use for the start frame and handles.\n\n##### Use Clip Names for Shot Names\nIf set to True, the Clip name will be used as a Shot name if it can't be computed from\nlocators nor comments in the EDL.\n\n##### Clip Name Shot Regexp\nIf set, use a regular expression to extract the Shot name from the Clip name.\n\n#### Create Missing Versions\nIf set to True, for Clips with media references that don't have a version in ShotGrid,\na new version will be created in ShotGrid.\n\n- For an EDL without media references, a movie of the Cut needs to be passed to sg-otio,\nwhich will allow to extract the Versions from the Cut movie.\n- For formats like Premiere XML, this means that media references existing in the XML\nfile will be published to ShotGrid.\n\n#### Local storage name\nWhen creating missing Versions, the SG local storage to use to publish the files to.\n\n#### Versions Path Template\nWhen creating missing Versions, the path to use to publish the files to.\n\nThis is a relative path from the local storage chosen.\n\nThe following keys are available:\n`PROJECT, CUT_TITLE, LINK, HH, DD, MM, YY, YYYY`\n\nExample valid templates:\n- `{PROJECT}/{LINK}/{YYYY}{MM}{DD}/cuts (default)`\n- `{PROJECT}/{CUT_TITLE}/{YYYY}{MM}{DD}/`\n\n#### Version Names Template\nIf not specified, the Version name will be the Clip name.\nIf specified, the Version name will be computed using the template.\n\nThe following keys are available:\n`CLIP_NAME, CUT_ITEM_NAME, SHOT, CLIP_INDEX, UUID`\n\nThe `CLIP_NAME` and `CUT_ITEM_NAME` are almost the same, but the `CUT_ITEM_NAME`\nis guaranteed to be unique in a track.\nFor example, if there are two clips with the name `clip1`, their cut item names\nwill be `clip1` and `clip1_001`.\n\nThe `CLIP_INDEX` is the index of the clip in the track (starting from 1, and counting\nonly clips, not gaps or other elements).\n\nThe `UUID` is 6 digits long.\n\nEven though versions with the same names are allowed, it is recommended to use keys that\nguarantee the unicity of the names, like CUT_ITEM_NAME, CLIP_INDEX, or UUID.\n\nExample valid templates:\n- `{CLIP_NAME}_{UUID}` (default)\n- `{CUT_ITEM_NAME}`\n- `{SHOT}_{CLIP_INDEX}`\n- `{CLIP_NAME}_{CLIP_INDEX:04d}` (adds some leading zeros)\n\n#### Timecode In to Frame Mapping Mode\nDifferent timecode in values to frame mapping modes\n\nThree mapping modes are available, which are only relevant for straight\nimports (without comparing to a previous Cut):\n- `0`: Automatic. Timecode in is mapped to the Shot head in.\n- `1`: Absolute. Timecode is converted to an absolute frame number.\n- `2`: Relative. timecode in is converted to an arbitrary frame\nnumber specified through settings. Example: `[\"00:00:00:01\", 1001]`\n\n#### Timecode In to Frame Relative Mapping.\nIf the Timecode In to Frame Mapping Mode is set to `2`, this setting can be used to specify\nhow to convert the timecode to an arbitrary frame number.\n\n#### Use Smart Fields\nIf set to True, the Smart Cut Fields will be used to fill the Shot fields.\n\n#### Shot Cut Fields Prefix\nIf set, the Shot Cut Fields will be custom fields that use this prefix,\ne.g. `sg_PREFIX_cut_in`, `sg_PREFIX_cut_out`, etc.\n\n\n#### Omitting and Reinstating Shots\nIf some Shots are omitted from one Cut to the other, their Status will be set\nto the `shot_omit_status` setting value.\nShots which appear again in a Cut will be reinstated if their current status \nis one of the statuses set with the `reinstate_shot_if_status_is` setting.\nTheir status will be set to the value set with the `shot_reinstate_status` setting, \nunless it is the special \"Previous Status\" value. In this case the status they\nhad before being omitted will be set.\n\nTo determine the previous status, it relies on EventLogEntries, which means that if it can't find\none (e.g. they were purged), it will use the value set with the `shot_reinstate_status_default` setting.\n\nLicense\n-------\nSG Otio is open source software. Please see the [LICENSE.txt](LICENSE.txt) for details.\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "A library for OpenTimelineIO integration with ShotGrid",
"version": "1.1.10",
"project_urls": {
"Homepage": "https://github.com/GPLgithub/sg-otio.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "73d327ee6a93a7acf021d7a92154e7f4fab0d15f4e0099825bcd4994670c378c",
"md5": "10af7575bb07a021abd4962d0d1032d5",
"sha256": "7eac27c6d2e1b13610dc16f02972bdd320e439b7bd0a074d1dc29997004d28d2"
},
"downloads": -1,
"filename": "sg_otio-1.1.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "10af7575bb07a021abd4962d0d1032d5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 126913,
"upload_time": "2025-01-16T13:09:31",
"upload_time_iso_8601": "2025-01-16T13:09:31.101720Z",
"url": "https://files.pythonhosted.org/packages/73/d3/27ee6a93a7acf021d7a92154e7f4fab0d15f4e0099825bcd4994670c378c/sg_otio-1.1.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-16 13:09:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GPLgithub",
"github_project": "sg-otio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sg-otio"
}
JSON
