Nuke Studio - Shotgun aware exporting

ShotGrid Export

App that adds ShotGrid awareness to Nuke Studio's sequence export. It adds a new processor that will use the configuration to determine paths for Nuke scripts and plates. It also will use the tags to determine ShotGrid Shot status and task templates to create/update the Shots in ShotGrid.
Latest Version: v0.7.0 (prod)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-hiero-export

Please Note: This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations User Guide for more details.
Overview Summary
                        Overview Video & Demo
                  Shotgun Shot Processor
                  Custom Template Fields
                  Shotgun Tasks
                  Export process
                  Sequence and Shot updates in Shotgun
                  Cut Schema Support
                  Alternate Shot Hierarchies
Installation, Updates and Development
Configuration Options
Release Notes History

This app adds Shotgun functionality to the Nuke Studio sequence export. It registers a new preset that will use templates to determine the output paths for a shot, include a shotgun aware transcode step to publish plates for Screening Room, and setup a mapping from Nuke Studio tags to Shotgun Shot statuses and Shot task templates. On export, Shots in Shotgun are updated and the full directory structure on disk as configured in the schema is created.



This app adds Shotgun awareness to Hiero's export dialog for sequences.

Overview Video & Demo

If you're new to Shotgun Toolkit or the Hiero integration, check out the following video which gives a fast-paced overview of what you can do in your pipeline with the Shotgun Toolkit Hiero integration.

If you're already familiar with Toolkit and Hiero, then feel free to continue on to the docs below.

Shotgun Shot Processor

When this app activates itself it registers a bunch of changes with the Hiero export dialog:

Export Dialog

The first thing to notice is the new processor that is registered:


When you click on this processor, there are some new things to notice.

At the top of the dialog, there is extra UI that helps control how shots get created/updated in Shotgun as a result of exporting the sequence:

Shotgun UI


By adjusting the dropdowns you can map various Hiero tags into Shotgun shot statuses and shot task templates. Thus via Hiero's tagging workflow you can set a Shotgun shot to being in progress or setup the tasks for the Shot for a green screen, cg extra, or whatever makes sense for your configuration. This UI is populated via a hook and is easy to configure for extra functionality.


There are also options to control collating track items together that mirror Hiero's built in logic. If you have multiple items that make up a shot (either overlapping, on different tracks or with the same shot name on multiple tracks) then you should turn these options on. This will cause the Shotgun Toolkit Shot updater to treat the matching collated items as a single Shot.


For example, assume we have two track items representing shots 010 and 020. 010 comes first and 020 overlaps with the end of 010 on a different track. Since 010 comes first, it's the hero and with collating enabled, Shotgun treats the two items as a single shot, 010. This means Shot 010 will be created or updated in Shotgun. The cut in will match the beginning of track item 010 and the cut out will match the end of track item 020. A Screening Room-ready Version will be created for each item, but both will be linked to Shot 010. A plate will be created for each item as a Published File but both will be linked to Shot 010. A single Nuke script will be published linked to Shot 010 containing 2 read nodes, one for each item. Note that in this situation, there is no creation or update to Shot 020 in Shotgun, since it has been collated into Shot 010.



Below the Shotgun UI is the standard paths dialog. There are three items that are added to Shots via Hiero by default... a default Nuke script, a default Nuke write location, and a default location for a plate transcode. The locations of these items are determined by the app configuration and can make full use of the templating system:


This app adds a {tk_version} token to Hiero which will be replaced by the version string, correctly formatted for Shotgun Toolkit.

Custom Template Fields

Any tokens you define in the custom_template_fields setting that are resolved by the resolve_custom_strings hook will automatically be added to Hiero's list of valid replacement tokens and will be considered valid replacements in your Toolkit template paths.

For example, in your Toolkit templates.yml file, say you define a key with the following:

        type: str 
        filter_by: alphanumeric

In your project.yml settings for tk-hiero-export you have:

        - {description: Shot Resolution, keyword: resolution}

And then you modify the resolve_custom_strings hook with something like the following:

<a name="Copyright (c) 2014 Shotgun Software Inc."></a>
# Copyright (c) 2014 Shotgun Software Inc.
<a name="This work is provided _AS IS_ and subject to the Shotgun Pipeline Toolkit"></a>
# This work is provided "AS IS" and subject to the Shotgun Pipeline Toolkit
<a name="Source Code License included in this distribution package. See LICENSE."></a>
# Source Code License included in this distribution package. See LICENSE.
<a name="By accessing, using, copying or modifying this work you indicate your"></a>
# By accessing, using, copying or modifying this work you indicate your
<a name="agreement to the Shotgun Pipeline Toolkit Source Code License. All rights"></a>
# agreement to the Shotgun Pipeline Toolkit Source Code License. All rights
<a name="not expressly granted therein are reserved by Shotgun Software Inc."></a>
# not expressly granted therein are reserved by Shotgun Software Inc.

from tank import Hook

class HieroResolveCustomStrings(Hook):
    """Translates a keyword string into its resolved value for a given task."""

    RESOLUTION_TOKEN_NAME = "{resolution}"

    def execute(self, task, keyword, **kwargs):

        self.parent.log_debug("attempting to resolve custom keyword: %s" % keyword)
        if keyword == self.RESOLUTION_TOKEN_NAME:
            translated_value = self._clip_resolution_string(task)
            raise RuntimeError("No translation handler found for custom_template_field: %s" % keyword)

        self.parent.log_debug("Custom resolver: %s -> %s" % (keyword, translated_value))
        return translated_value

    # Handle the {resolution_fs} token 
    def _clip_resolution_string(self, task): 
        """ returns sequence resolution or task format override""" 
        width = "" 
        height = ""

        sequence_format = task._sequence.format()

        width = sequence_format.width() 
        height = sequence_format.height()

        if "reformat" in 
            task_reformat_settings =["reformat"] 
            if task_reformat_settings['to_type'] != "None": 
                width = task_reformat_settings['width'] 
                height = task_reformat_settings['height']

        return "%sx%s" % (width, height)

You can now not only use the resolution token in Hiero but it will validate against any template paths you have defined in Toolkit so you can export to a location like:

    hiero_plate_path: "sequences/{Sequence}/{Shot}/hiero_plates/{resolution}/v{version}/{project}_{Shot}.mov"

Shotgun Tasks

There are two new task types registered.

Shotgun Transcode Images

This is a subclass of the standard Hiero transcoding task, which will register the results of the transcode as a Publish in Shotgun. Optionally a Version will also be created in Shotgun. If a Version is created, then a Quicktime will also be created and uploaded as Screening Room media.

Shotgun Nuke Project File

This is a subclass of the standard Hiero Nuke script exporter, which registers the resulting Nuke script as a PublishedFile in Shotgun linked to the Shot. The settings allow you to specify which Toolkit-enabled WriteNodes to include in the file on export.

Nuke Project File Settings

The app settings plate_published_file_type and nuke_script_published_file_type allow you to control what file type the PublishedFiles are registered as. In addition, nuke_script_toolkit_write_nodes allows you to control which WriteNode settings should be available in the export dialog.

Export process

When the export is run, there will be some extra tasks that show up in the export queue:

Export Queue

Each shot will run a ShotgunShotUpdater tasks that is responsible for creating the Shot in shotgun and creating the full Shot structure specified in the schema configuration:


Sequence and Shot updates in Shotgun

The name of the Hiero sequence will be used for the sequence name, and the shots will have their cut info filled in (Cut Order, Head In, Cut In, Cut Out, Tail Out, Cut Duration, and Working Duration). In addition if poster frames were selected for the sequence or the items that make up the shot, they will be uploaded as the thumbnails for the shots.

If your workflow uses an entity other than Sequence as the shot parent (like Episode), then you can override the get_shot_parent method in the hook_get_shot hook. The default implementation creates (if necessary) and returns a Sequence.

Cut Schema Support

If your Shotgun site supports the Cuts schema (v7.0.0 or later), then this app will automatically generate a Cut with corresponding CutItems in Shotgun. The Cut entity corresponds to the Hiero sequence and the CutItems correspond to the items in the sequence. The Cut will be linked to the parent entity (Sequence by default) as returned by the get_shot_parent method in the hook_get_shot hook. The CutItems will be associated with a Shot entity and linked to the reviewable Version created during the export. After exporting, the Cut will be playable in the Media tab in Shotgun and in RV.

All of the meta data associated with the Cut and CutItem entities is inferred from Hiero except the Cut Type field which can be specified in the export UI.

Cut Type

The value here will show up in the Type field of the Cut.

It should be noted that the Cut schema is not supported when either of the Collate options are selected, and creation of Cut and CutItem entries will be skipped.

In addition, the Cut schema does not handle retimed clips. A debug warning will be logged when exporting retimed clips.

Alternate Shot Hierarchies

For studios that don't work in the standard Sequence > Shot hierarchy, but perhaps use Episodes and/or Scenes, there is a hook hiero_get_shot that allows you to configure the app to work with whatever Shot hierarchy is in use at your studio.

Related Apps and Documents

Flame Shot Export

The Flame shot exporter makes it easy to kickstart your Shotgun project! Simply select a Sequence to export inside of Flame, and the exporter will take care of the rest. It will create shots, tasks, set up cut information in Shotgun, generate folders on disk, render out plates to disk and send the media to Shotgun Review. Once done, you can jump straight into other tools such as Flare or Nuke to continue your work there.

Flame Review Export

The Flame Review app makes it easy and effortless to send sequences to review in Shotgun. Flame will generate a quicktime and upload it to Shotgun where it can be reviewed in Screening Room, the Client Review Site or the Shotgun iPhone app. All processing is running in the background so that you can focus on the work at hand.

Open In ShotGrid

This is a simple app that finds the Shots in Shotgun related to the selected track items and opens their detail pages in a browser window.

Installation and Updates

Adding this App to the Shotgun Pipeline Toolkit

If you want to add this app to Project XYZ, in an environment named asset, execute the following command:

> tank Project XYZ install_app asset tk-hiero tk-hiero-export

Updating to the latest version

If you already have this item installed in a project and you want to get the latest version, you can run the update command. You can either navigate to the tank command that comes with that specific project, and run it there:

> cd /my_tank_configs/project_xyz
> ./tank updates

Alternatively, you can run your studio tank command and specify the project name to tell it which project to run the update check for:

> tank Project XYZ updates

Collaboration and Evolution

If you have access to the Shotgun Pipeline Toolkit, you also have access to the source code for all apps, engines and frameworks in Github where we store and manage them. Feel free to evolve these items; use them as a base for further independent development, make changes (and submit pull requests back to us!) or simply tinker with them to see how they have been built and how the toolkit works. You can access this code repository at

Special Requirements

  • You need Shotgun Pipeline Toolkit Core API version v0.18.124 or higher to use this.


Below is a summary of all the configuration settings used. These settings need to be defined in the environment file where you want to enable this App or Engine.


Type: str

Default Value: Basic shot template

Description: The default shot task template to use when the app is creating new shots in ShotGrid. This setting is presented in the Custom ShotGrid Export UI and you can change it prior to running the export if you want.


Type: tank_type

Default Value: Hiero Audio

Description: The string value of the Published File/Tank Type used for published audio.


Type: tank_type

Default Value: Hiero Plate

Description: The string value of the Published File/Tank Type used for published plates.


Type: tank_type

Default Value: Nuke Script

Description: The string value of the Published File/Tank Type used for Nuke scripts.


Type: list

Description: None


Type: list

Description: A list of custom strings to add to Hiero's resolver. Each item is a dictionary specifying the keyword to be replaced and a description for that keyword that will show up in the tooltip for the export tree. A valid entry will look like '{keyword: a_keyword, description: This is a keyword}'. Each keyword needs to be translated to a resolved string by the resolve custom strings hook.


Type: str

Default Value: [['step.Step.code', 'is', 'Comp']]

Description: A filter that will return the task in the Shot that publishes will be registered against. This value must be a valid filter that can be passed to the find method of the ShotGrid api, without a condition for entity (a value linking entity to the Shot will be added at publish time). If the filter contains a condition in the form ['step.Step.code', 'is', VALUE], then whatver VALUE is will be used by the default translate_template hook as the value to use when expanding {Step} in the publish templates. If the filter results in a single task, then any publishes created by the app will be associated with that task. Otherwise they will only be associated with the Shot.


Type: hook

Default Value: hiero_translate_template

Description: Called when a template needs to be translated into a Hiero style replacement string. First argument is the template to translate. Second argument is a string describing the type of template being translated. The return value is the translated string.


Type: hook

Default Value: hiero_upload_thumbnail

Description: Called when a thumbnail needs to be uploaded to ShotGrid for a Hiero source. First argument is a dictionary that is the ShotGrid entity to upload for. The second argument is the Hiero Source to get the thumbnail from. The third argument is the Hiero TrackItem that the source was pulled from. The TrackItem may be None when the thumbnail does not correspond to an item from a timeline.


Type: hook

Default Value: hiero_get_shot

Description: Called to return the shot to update cut information for. The first argument is the Hiero export Task object. The second argument is the hiero.core.TrackItem that is driving shot creation. The third argument is a data dictionary that can be used to pass data between different calls to shot create. The return value is a data dictionary for the shot, whose id will be updated. Cut information will be merged into this dictionary before ShotGrid update is called on the shot. The default implementation creates or looks up a sequence named after the Hiero Sequence being exported and links that to the shot via the sg_sequence field.


Type: hook

Default Value: hiero_pre_export

Description: Called prior to starting ShotGrid's shot processor. It can be used to clear out caches and do other specific initializations.


Type: hook

Default Value: hiero_resolve_custom_strings

Description: Called when resolving custom items added to the Hiero resolver via the custom_template_fields setting. The first argument is the keyword being resolved and the second argument is the Hiero task being run. The return value is the resolved string value for the keyword.


Type: hook

Default Value: hiero_get_quicktime_settings

Description: Called when generating the default settings for creating a quicktime. The argument is a boolean that is True when the resulting quicktime is only for upload to ShotGrid and False when the settings are used for a default Quicktime transcode. The return value is a tuple of two items. The first is a string that is the file_type for the Nuke write node that will be generated. The second is a dictionary where the keys are knob names for the write node, and the values are the corresponding node values.


Type: hook

Default Value: hiero_update_version_data

Description: Called before creating a Version in ShotGrid for a transcode. The default values for the version will already be filled in in the version_data dictionary. Modify this dictionary to change what will be passed as an argument to the ShotGrid API create call.


Type: hook

Default Value: hiero_post_version_creation

Description: Called after the Version entity is created. The hook is provided the new entity data dictionary which will include the ID number of the entity that was created.


Type: hook

Default Value: hiero_get_extra_publish_data

Description: Called before creating a PublishedFile in ShotGrid for a transcode. This hook should return None if there is no extra info to associate with the published file, or a dictionary that is compatible with the ShotGrid API's update method.


Type: hook

Default Value: hiero_customize_export_ui

Description: Called during initialization of the export UI. Provides methods for defining custom UI properties on presets, initializing and injecting custom widgets into the exporter, and setting up custom widgets to make use of property UI widgets.


Type: hook

Default Value: hiero_update_shot

Description: Called during SG shot processing. Provides methods for managing if and how the Shot's entity in updated, and if and how creation of the Shots filesystem structure happens during export.


Type: hook

Default Value: hiero_update_cuts

Description: Called during SG shot processing. Provides methods for managing if and how Cuts and CutItems are created and updated.


Type: template

Optional Template Keys: ***

Description: A reference to a template which specifies the directory to publish shot plates to. The translate template hook must understand how to translate this to Hiero keywords.


Type: template

Optional Template Keys: ***

Description: A reference to a template which specifies what published nuke scripts will be named. The translate template hook must understand how to translate this to Hiero keywords.


Type: template

Optional Template Keys: ***

Description: A reference to a template which specifies what renders will be named. The translate template hook must understand how to translate this to Hiero keywords.


Type: template

Required Template Keys: version

Optional Template Keys: ***

Description: String template that specifies how to format the Hiero tk_version token as a version string for tk.

Release Notes

Welcome to the release notes for this Engine. Below you will find an overview of all the changes we did for each release. We try to be as detailed as possible and include all bugs we have fixed, features we have added and things that may have changed. If you have questions about a particular release, don't hesitate to contact our support team!



Rebranded to ShotGrid



Python 3 compatibility.



Bug fix for SG write node parenting on exported scripts.


Previous to this fix, if you attempted to export a nuke script and include SG write nodes, it would add the write node placeholders to the script, but they wouldn't be correctly linked up to the main hierarchy. Now with the fix, they correctly parent before the viewer node.



Bug fix for QuickTime preview generation.


Previous to this fix, if you attempted to export some footage using the Shotgun Transcode plugin, and opted to create a Shotgun Version, and your output was something other than a mov file, and your version of Hiero/Nuke Studio was 11 or above, then it would not generate the preview QuickTime output and upload it.



Minor fix for an incorrect key reference, and removes an unneeded warning log message.



Customizable export UI, plus additional hook methods for Shot/Cut updating.


Provides hook methods for building custom widgets for each processor we provide, plus allows for custom preset properties to be created, and those properties then being used to set/initialize the custom widgets. In addition, to meet the workflow requirements outlined by clients, additional hook methods have been added to allow for customization of if/how Shots, Cuts, and CutItems are created/updated during the export process.



Additional compatibility fixes for Nuke 11.


Quicktime encoding properties on Linux have become unified with those on Windows and OS X. The app's hook that determines those properties has been tweaked to take that into account.



Compatibility with Hiero/Nuke Studio 11.



Tweaks to export label and layout



Fixes broken export dialog UI/layout in Hiero 10.5v1



Uses "scene" instead of "hiero" for name tokens on scene export.



Update quicktime encoder defaults for newer NukeStudio versions



Ensures collate timing, with clip length, and source start working as expected



Simplifies cut logic for exports



Apply custom start frame to cut item fields and set Version frame fields



Ensure return fields are supplied to shot creation in get shot hook



Addresses unreleased recently introduced bug related to transcode task



Addresses regressions with Collate exports



Frame server override tweak to prevent crash in older Hiero



Fixes issue with preview quicktimes not being uploaded to SG



Backward compatibility fixes for Hiero 10



Fix for head tail values on Shot entity using cut length option



Shot entity cut fields now match frames written to disk



Properly update Shot entity cut fields when using the clip length export option



Hiero exporter now requires core v0.17.21.



Hot fix for cut support custom frame export.



Hotfix for Shot entity cut field regression.



Hot fix for legacy Shot cut field values



Updated hiero timecode field names



Adds support for new Cuts schema in SG v7.0.0



Adds support for new Cuts schema in SG v7.0.0



Adds support for new Cuts schema in SG v7.0.0



Update minimum cut support SG version to v7.0.0



Adds support for the new Cut schema to tk-hiero-export



Updates encoding settings for Linux systems.



Fixes Windows error removing temp thumbnail


Windows occasionally holds on to the temporary thumbnail file longer than it needs to which can cause an error when we try and remove it after uploading it to Shotgun:

[Error 32] The process cannot access the file because it is being used by another process.

This fix catches the error and waits 1 second for the process to let go of the file before trying again. If for some reason the file still cannot be removed, we raise the exception.



Adds metrics logging


Handles a lack of thumbnail material more gracefully during export.


Adds context switching support for Nuke Studio.


Fixes to account for FnExternalRender changes in Hiero 9.0v8.


Adds a new hook: post_version_creation.


The new post_version_creation hook is run immediately after the Version entity is created in Shotgun. The hook receives the entity's data dictionary as input.


Adds support for Hiero 9.0.


Hiero 9.0 support has been added with backwards compatibility maintained for previous versions of Hiero. Worth noting is that the UI component of the shot processor has been broken out into its own class, which means that the interface of the processor object that is provided to the hiero_pre_export hook has changed when used in Hiero 9.0+. The interface for previous versions of Hiero is unchanged.



Updates the get_shot hook to accept the task as a first class parameter where previously the task was passed in through kwargs and it wasn't obvious it was available in the hook.


Way to reset a global cache per-export


The resolve hook is called tons during an export, so expensive resolve results need to be cached. There currently isn't a hook available that run pre-export where that cache could be cleared


Fixes an issue with hiero exports with cut length frames


Add a hook to enable custom data to be added to the published files.


Much like the update version data hook, this hook provides a way to add data to the published files that are created by a Hiero export.


Fixes wrong data exported from some audio exports


Fixes wrong data exported when using audio export with collation on any item but the hero item.


Audio Export with collating fix


Fixes a crash when exporting collated audio files.


Fixes cut order issues with exporting clips on different tracks.


Fix Audio Export with Collating


25562 Added audio export


Added support for shotgun audio export from Hiero. The exporting is currently done for every clip, and does not combine sequences.


Bug fix for wrong read source in exported Nuke scripts.

Details: Bug fix for when the output of the transcode task is selected as a read node for the Nuke export. Before you would end up with the source plates in the read node rather than the results of the transcode. This also updates the default resolve_custom_strings hook to use the get_shot hook to pull the Shot information. This fixes an error where that hook would error out if the Shot did not yet exist.


Fix for Version/Publish creation using the get_shot hook. New hook to configure Versions.

Details: Updated the Version and Publish creation to use the Shot returned from the get_shot hook so that it no longer assumes a Sequence/Shot setup. Added a new hook (update_version_data) to allow for extra customization to the Version that gets created at the end of a transcode.


allow keywords defined custom_template_fields to validate in Toolkit template paths


Updated to match the change from 'channel' to 'output' in the Shotgun Write Node in Nuke.


Added a new hook, get_quicktime_settings to allow customizing the parameters for qt generation.


Added a way to associate Publishes and Versions with a Task in Shotgun.

Details: Added a configuration option so that it is possible to filter for a Task in Shotgun that would be created from a Task Template for a shot that Hiero sets up.


Made Version creation as part of the Shotgun Transcode task optional.

Details: Added a checkbox to the Shotgun Transcode task that controls whether a Version is created in Shotgun for the media. A publish is always created, but if the checkbox is unchecked, then no Version is created (and the quicktime creation for Screening Room is skipped).


Added hook for custom resolvers.

Details: Merged in the pull request from Sebastian Haas to make it easy to register custom resolvers via a setting (for which strings to register) and a hook (to resolve them). Thanks Sebastian!


Fix for using {tk_version} during track building.

Details: Update the resolver for {tk_version} to handle formats other than v# (building tracks can pass in something like 'v*').


Fix for when Hiero is missing tags from the preset.

Details: Fix for when Hiero is missing tags from the preset.


Bug fix for publishing the nuke script and plates on windows.

Details: Bug fix for publishing the nuke script and plates on windows.


Removed default value for template_version setting


add Nuke script and plate renders as PublishedFiles and fix version tag


  • Added new task, Shotgun Nuke Project File, which exports the Nuke Script with selected Shotgun Write Nodes and publishes to Shotgun along with the rendered plate, as PublishedFiles.
  • Added tk_version token to Hiero which resolves to Toolkit-formatted version string


add Nuke script and plate renders as PublishedFiles and fix version tag


  • Added new task, Shotgun Nuke Project File, which exports the Nuke Script with selected Shotgun Write Nodes and publishes to Shotgun along with the rendered plate, as PublishedFiles.
  • Added tk_version token to Hiero which resolves to Toolkit-formatted version string


Default thumbnail for shots now uses middle frame from the timeline

Details: Updated the default thumbnail update hook to pull the middle frame for a shot from the timeline.


Pass the track item to the upload thumbnail hook.

Details: Pass the track item to the upload thumbnail hook.


Bug fix in thumbnail upload hook

Details: Bug fix in thumbnail upload hook


Move logic to upload a thumbnail to Shotgun into a hook.

Details: Moved logic to upload a thumbnail to Shotgun into a hook.


Added ability to collate items and better cut info on shots.

Details: Mirrored NukeShotExport's collate logic to make sure that overlapping/like named items in a timeline are taken into account correctly when figuring out the cut information for a Shot. Fill the full set of cut fields for Shots.


Moved logic about Shot/Sequence hierarchy into a hook.

Details: Added the hook to allow for hierarchies other than Sequence/Shot to be easily configured.


Added missing import statements.


Moved some hooks into the app code base.


First official release to the App Store.


Initial version.

Details: Initial version.


Version Placeholder.