Flame - Shot Creation and Plate Export

Flame Shot Export

Export Flame sequences to Shotgun and the file system.


By: Shotgun Software
Latest Version: v1.7.6 (beta)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-flame-export

Table of Contents:

Overview Summary

Documentation

            Pushing a conform to Shotgun

            Sending batch renders to Review

            Want to learn more?

      Advanced Topics

            Using export presets

            Bypassing Shotgun server side transcoding

            Customizing ffmpeg

                  Copying the settings hook

                  Modifying the hook

Installation, Updates and Development

Configuration Options

Release Notes History

Overview

This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations User Guide for details. 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.

Documentation

The Shotgun Flame Export App helps kickstart your project!

Once you have created an initial conform in Flame, the Shot Exporter can help you quickly generate content in Shotgun, render out plates to disk and send content to review.

Once you are up and running, the exporter app will also track all the renders happening in Flare or in Flame batch mode, making it easy to send content to review as part of your workflow.

Pushing a conform to Shotgun

Once you have your conform set up in Flame for a sequence, and have allocated shot names to all the segments in your timeline, select the sequence, right click and choose the Shotgun Shot Export option.

This will bring up a Shotgun UI where you can enter some initial comments for your publish. These comments will be sent to review and also used when adding description to publishes and other content.

In addition to the description, you can also select which output data format you want to use for your exported plates. These presets are part of the toolkit app configuration and can be configured to suit the needs of your studio.

Once you click the submit button, a number of things will happen straight away:

  • Shots and Tasks will be created in Shotgun. The list of tasks to associate with each new Shot that gets created is configurable via a Task template setting to make it quick and painless to create consistent structures. The shots will be parented under a sequence by default, but this is also configurable and if you are working with Scenes or Episodes, it is possible to reconfigure the exporter to work with these instead.

  • Once Shotgun contains the right data, folders will be created on disk using the standard folder creation mechanism. This ensures that the project can be kick-started with a set of consistent folders for all shots that are being created.

Once the two steps above have been carried out, you have the basic structure to proceed with further steps. These will happen in the background:

  • Plates will be exported on disk for each shot according to the presets defined in your configuation. File locations are defined using the Toolkit Template system, meaning that the location of these plates will be well defined and understood by other tools downstream in the pipeline.

  • Batch files and clip xml files will be exported. These are used by Flame to enable an iterative workflow where you can quickly render out new versions that are later pulled in to the main conform in Flame.

  • Quicktimes are generated and uploaded to Shotgun for review.

Sending batch renders to Review

Once you have published a Flame batch file for a Shot, you can launch Flare directly from that Shot in order to open up the batch file with render and output settings pre-populated. In order to render out a new version, simply click the Render Range Button.

Toolkit will display a dialog at this point where you can choose to send the render to Shotgun review or not.

Files will be published and tracked by Shotgun and optionally also sent to review.

Want to learn more?

If you want to learn more, and see this workflow in action, head over to the Flame engine documentation where we also have some video content that demonstrates the various workflows in action.

As always, if you have question regarding integration or customization, don't hesitate to reach out to our Support: toolkitsupport@shotgunsoftware.com

Advanced Topics

Below you'll find more advanced details relating to configuration and customization

Using export presets

The exporter uses a concept of Export Presets in its configuration. When you launch the Export UI inside of Flame you see a dropdown with the available export presets. Each preset is a configuration option which allows you to configure how files are written to disk and uploaded to Shotgun. High level settings such as file locations on disk are controlled directly in the environment configuration, making it easy to adjust the default configuration options to work with your pipeline.

More advanced settings and control over the actual export xml content that is being passed to flame in order to control Flame, is handled by a hook where the behaviour is defined for each preset. In the hook, you have complete control over how media is being generated by the exporter.

Bypassing Shotgun server side transcoding

By default, Quicktimes are uploaded to Shotgun review by setting the Version.sg_uploaded_movie field. This in turn will trigger Shotgun server side transcoding; the uploaded quicktime will be further converted to mp4 and webm representations tailored for playback in browsers and mobile. Sometimes, it can be beneficial to bypass this server side transcoding. This is possible by setting the bypass_shotgun_transcoding configuration setting. When this is set to true, the integration will upload directly to the Version.sg_uploaded_movie_mp4 field in Shotgun, thereby bypassing the server side transcoding. In this case, no webm version is generated, so review playback will not be possible in Firefox.

For more information, see https://support.shotgunsoftware.com/entries/26303513-Transcoding

Customizing ffmpeg

When the exporter generates quicktimes, it uses a version of ffmpeg which comes distributed with Flame. By modifying the settings hook in the exporter, you can specify an external version of ffmpeg to use instead of the built-in one. The version of ffmpeg distributed with Flame is tracking the very latest advancements in ffmpeg transcoding and performance, so sometimes using the latest version may result in performance improvements.

Please note that the way h264 parameters are passed to ffmpeg has changed between the version that is used by default and the latest versions. By switching to the latest generation of ffmpeg, it is possible to implement exactly the recommended transcoding guidelines that results in optimal upload and performance on the Shotgun side. You can find these guidelines here:

https://support.shotgunsoftware.com/entries/26303513-Transcoding

We only recommend changing the ffmpeg version if you are an advanced user. In that case, follow these steps:

Copying the settings hook

All settings that need to be modified can be found in the settings hook that comes shipped with the Flame export app. In order to modify this hook, you first need to copy this hook file from its default location inside the app location into your configuration. Inside your project configuration, you'll typically find the hook file in a location similar to install/apps/app_store/tk-flame-export/va.b.c/hooks/settings.py. Copy this file into the hooks location inside of your configuration, e.g. config/hooks. We recommend renaming it to something a little more verbose than just settings.py in order to make it clear what it is:

install/apps/app_store/tk-flame-export/va.b.c/hooks/settings.py -> config/hooks/flame_export_settings.py

Now edit your Flame environment configuration file. This is typically config/env/includes/flame.yml. Under the tk-flame-export heading, you'll find the path to the hook being defined as settings_hook: '{self}/settings.py'. This essentially means that the configuration will look for the hook file inside the app location (e.g. {self}). Changing this to settings_hook: '{config}/flame_export_settings.py' will tell Toolkit to look for the hook file inside the configuration instad. In summary:

settings_hook: '{self}/settings.py' -> '{config}/flame_export_settings.py'

Modifying the hook

Now we are ready to start modifying our config/hooks/flame_export_settings.py hook! Open it up in a text editor. You'll notice several methods relating to ffmpeg and ffmpeg settings. The first one to modify is the following:

def get_external_ffmpeg_location(self):
    """
    Control which version of ffmpeg you want to use when doing transcoding.
    By default, this hook returns None, indicating that the app should use
    the built-in version of ffmpeg that comes with Flame.

    If you want to use a different version of ffmpeg, simply return the path
    to the ffmpeg binary here.

    :returns: path to ffmpeg as str, or None if the default should be used.
    """
    return None

By returning None by default, the exporter will use Flame's built-in ffmpeg. Change this to return a full path to your ffmpeg. Keep in mind that if you are running a backburner cluster, ffmpeg may be called from any machines in the cluster, so make sure the executable is installed everywhere.

Now that once the ffmpeg location is updated, you most likely either need or want to tweak the parameters passed to ffmpeg. This needs to be changed in two different methods:

  • get_ffmpeg_quicktime_encode_parameters will return the parameters used when generating a quicktime to be uploaded to Shotgun.

  • get_local_quicktime_ffmpeg_encode_parameters will return the parameters used when a quicktime is written to disk.

For the shotgun upload, we recommend using the default Shotgun encoding settings as a starting point:

def get_ffmpeg_quicktime_encode_parameters(self):
    return "-vcodec libx264 -pix_fmt yuv420p -vf 'scale=trunc((a*oh)/2)*2:720' -g 30 -b:v 2000k -vprofile high -bf 0"

For the local Shotgun transcode, we recommend basing your settings on the Shotgun transcode settings but removing the resolution constraints and increasing the bit rate:

def get_local_quicktime_ffmpeg_encode_parameters(self):
    return "-vcodec libx264 -pix_fmt yuv420p -g 30 -b:v 6000k -vprofile high -bf 0"

Related Apps and Documents

Flame Review Export

This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the [Shotgun Integrations User Guide](https://support.shotgunsoftware.com/hc/en-us/articles/115000068574) for details. 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.

Shotgun Export

This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the [Shotgun Integrations User Guide](https://support.shotgunsoftware.com/hc/en-us/articles/115000068574) for details. 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.

Loader

This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the [Shotgun Integrations User Guide](https://support.shotgunsoftware.com/hc/en-us/articles/115000068574-Integrations-User-Guide#The%20Loader) for details. The Shotgun Loader lets you quickly overview and browse the files that you have published to Shotgun. A searchable tree view navigation system makes it easy to quickly get to the task, shot or asset that you are looking for and once there the loader shows a thumbnail based overview of all the publishes for that item. Through configurable hooks you can then easily reference or import a publish into your current scene.

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-maya tk-flame-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 https://github.com/shotgunsoftware/tk-flame-export.

Special Requirements

  • You need Shotgun Pipeline Toolkit Core API version v0.14.77 or higher to use this.
  • You need Engine version v1.6.3 or higher to use this.

Configuration

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.

segment_clip_template

Type: template

Description: Toolkit file system template to control where segment based clip files go on disk. A segment in Flame is a 'block' on the timeline, so a shot may end up with multiple segments. This clip file contains Flame related metadata that Flame uses to deconstruct data as it is being read back into the system.

task_template

Type: str

Default Value: Basic shot template

Description: The Shotgun task template to assign to new shots created

batch_publish_type

Type: tank_type

Default Value: Flame Batch File

Description: The publish type for Flame batch scripts

menu_name

Type: str

Default Value: Shotgun Shot Export

Description: One line description of this profile. This will appear on the menu in Flame.

shot_parent_link_field

Type: str

Default Value: sg_sequence

Description: The name of a single entity link field which links shot to a the parent entity type defined in the shot_parent_entity setting

shot_parent_task_template

Type: str

Description: The Shotgun task template to assign to new shot parent entities

plate_presets

Type: list

Description: A list of dictionaries in which you define the various export presets to appear on the profiles dropdown in the user interface. These presets are matched up with export profiles defined inside the settings hook. The list of presets in this setting basically defines the various profiles and their locations on disk, and the hook contains all the details defining how the export should be written out to disk (resolution, bit depth, file format etc). The structure of this setting is a list of dictionaries. Each dictionary item contains three keys: name, publish_type and template. The name parameter is the identifier for the preset - this name will appear in the dropdown in the UI. It is also used to identify the preset inside the settings hook. The publish_type parameter defines the publish type that should be associated with any exported plates when they reach Shotgun. Lastly, the template parameter defines where on disk the image sequence should be written out.

shot_parent_entity_type

Type: shotgun_entity_type

Default Value: Sequence

Description: The entity type which shots are parented to in the current setup.

settings_hook

Type: hook

Default Value: {self}/settings.py

Description: Contains logic to generate settings and presets for the Flame export profile used to generate the output.

batch_template

Type: template

Description: Toolkit file system template to control where Flame batch files go on disk

shot_clip_template

Type: template

Description: Toolkit file system template to control where shot based clip files go on disk

bypass_shotgun_transcoding

Type: bool

Description: Try to bypass the Shotgun server side transcoding if possible. This will only generate generate and upload a h264 quicktime and not a webm, meaning that playback will not be supported on all browsers. For more information about this option, please see the documentation.

Release Notes

Welcome to the release notes for this App. 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!

v1.7.6

2016-Nov-03

Updated Flame icons

v1.7.5

2016-Aug-12

Bug fixes to support Flame 2107 export presets.

v1.7.4

2016-Aug-01

Updated to support Flame 2107 export presets.

v1.7.3

2016-May-23

Updates to use new time code fields for cut schema.

v1.7.2

2016-Apr-28

Fixed bug causing export to fail when a user had partially cancelled it.

v1.7.1

2016-Apr-25

Added improved Cut support.

Details:

This adds support for the new shotgun cut schema integration.

  • When running the export, a new cut entity with associated cut items is created every time. The revision number for the cut gets bumped every time. On older versions of Shotgun, this is skipped.
  • Cut type is configurable via the app configuration. Cut name is based on the sequence name.
  • Export now correctly supports handles for versions of flame that emit handle related metadata. This was previously a problem if say 10 frame handles were requested from Flame but there was not enough media to generate a 10 frame handle for a segment - previously, the 10 frame handle length was assumed, now shotgun correctly stores the handle length.
  • Lots of code cleanup and refactor to make the structure clearer and more decoupled.
  • Time code data is now generated and supports both NDF and DF modes. Time codes are pushed into shotgun using SMPTE/Avid standard, e.g. HH:MM:SS;FF for DF and HH:MM:SS:FF for NDF.
  • Collating no longer happens - each shot is determined based on the lowest occurrence of the Shot in the timeline stack. Cut items are generated based on this plate layer in the timeline. Moving segments around in element layers above the base layer will not affect the cut, (however versions are generated in Shotgun for all segments). This is different from before, where the length of each shot length was incorrectly computed as an union of all segments belonging to that Shot.

v1.6.1

2016-Mar-03

Adds metrics logging

v1.6.0

2016-Jan-12

Added configuration options for image sequence start frame and handles.

v1.5.1

2015-Oct-06

Added additional compatibility logic for older flame versions.

v1.5.0

2015-Oct-05

Added support for 2016.1 new batch render outputPathPattern parameter.

v1.4.0

FPS data is now embedded into transcoded quicktimes.

v1.3.5

Improvements to transcoding and quicktime generation.

Details:

  • Added support for local quicktime generation
  • Tweaked default resolution and transcoding parameters for uploaded quicktimes
  • Ability to turn off quicktime uploads
  • Ability to customize which version of ffmpeg that is used for transcoding. This is an expert option and for more information, please see the engine documentation.
  • Ability to upload quicktimes to Shotgun in a way which bypasses server side transcoding.

v1.2.1

Misc. performance improvements.

Details:

  • Video media is scaled down to 720 (or whatever suitable resolution is closest) prior to quicktime generation and upload to Shotgun.
  • Shot update checks are done as single call
  • Shot creation is done as a single call
  • Improved UI progress feedback for folder creation
  • Cut changes and version creation is done in the foreground, as single call
  • Publishes are done as the first bg job after the export media, all in a single pass
  • Quicktime generation happens in separate bg jobs as the last thing in the workflow
  • Improved back burner job names.
  • General renaming and code cleanup.

v1.2.0

Several optimizations and improvements. QA Release only, not intended for general use.

v1.1.0

Improved frame range matching. Suppressed compatibility warning messages.

Details:

  • The flame conform and the shotgun in and outs now match exactly. Previously, it was trying to intelligently normalize frame values.
  • Preset profile compatibility warnings are now handled gracefully and should no longer appear.

v1.0.3

Added improved UI feedback when creating new shots in Shotgun.

v1.0.2

Minor tweaks to some of the wording in the user interface text.

v1.0.1

First official version of the Flame exporter.

This resolves a couple of smaller issues that were found in previous (pre-1.0) versions of the app: - Cut tail values are now correct in shotgun (previously off by one due to flame exclusive frame out points) - Fixed issues with PySide when running jobs on the backburner queue.

Follow

0 Comments

Please sign in to leave a comment.