RV/Shotgun Integration (v1.30)

Quick Start

The quickest possible route to seeing what RV and Shotgun can do together is to setup RV 3.8.6 as the rvlink protocol handler then use the demo shotgun site we’ve set up.

Introduction

Because production tracking and media playback are both so ubiquitous in the production workflow, tightly integrating Shotgun and RV holds the promise of making almost every part of your workflow a little bit more efficient.

This first release of the RV/Shotgon integration package includes the following features:

  • Click on links in Shotgun to play media

  • Exchange URLs that will load the designated shotgun versions into RV with one click

  • Play sets of media from any Shotgun page displaying Versions

  • Compare two or more Versions in RV after selecting in Shotgun

  • Play media arranged in Shotgun Playlists

  • Display Shotgun information (from any shotgun entities) in RV

  • From RV, go directly to Shotgun pages corresponding to loaded media

  • From RV, update media to the latest version registered in Shotgun

  • Store Shotgun information in RV session files

  • Swap media type (movies or hires frames or whatever) from within RV

  • Use editorial information stored in Shotgun to adjust media EDL in RV, or to find and load media corresponding to neighboring shots

  • Configurability.  After a configuration step, the integration package should be able to handle most shotgun schemas

Installation

The most important part of getting the RV/Shotgun integration package working is the custom config module, which may require some back-and-forth to get working the first time. But much of the following can be completed before the config module is ready.

 

General Installation

There are a couple different ways to use the integration package but in all cases the following steps need to be completed first.

RV 3.8.6

Make sure you have RV 3.8.6 or later installed (Any OS). As always you can download RV.

The Shotgun integration relies on the general rvlink functionality added in RV 3.8 that allows RV to act as a protocol handler for rvlink:// URLs. The registration of the protocol handler depends on the OS (and the desktop environment). That process is described in this Knowledge Base Article.

Once the protocol handler is registered, you can test it with the links on this page.

 

Install Shotgun Integration Package

The shotgun integration package comes as a zip file (shotgun.zip). To install it,

  1. Save it anywhere (don’t unzip it)

  2. Start RV and go to the Packages tab of the Preferences dialog

  3. Click Add Package, browse to your saved package, choose a location for the package

  4. Make sure both the Install and Load boxes are checked

  5. Restart RV

 

RV/Shogun Evaluation Using Demo Site

After completing the General Installation steps described above, if you don’t actually have Shotgun set up yet, or you’d like to see how RV and Shotgun can work together without fiddling with your shotgun instance, you can evaluate the integration with some test data as follows:

  1. Start RV and set the config style to “demo” (ShotgunPreferencesSet Shotgun Config Style)

  2. Point your browser at the BBB_Short project on the demo site https://rvdemo.shotgunstudio.com/page/1096. You can use the user/password rvdemo/rvdemo007.

At this point you can use the Play In RV and Compare In RV Shotgun action menu items, and try out the Items on the Shotgun menu in RV, including viewing shotgun information in the heads-up display with the Shotgun Info Widget. But it’s a lot more fun with actual media.

To install the media package, down load it from here and unpack it into a directory of your choice (on linux or mac) or to C:\ on windows. On linux or mac, add a symbolic link from /rvshotgundemo to the location where you unpacked the media.

Now RV should find the appropriate media for all the BBB_Short Versions.

Site-Wide Demo

If you want to demo site-wide without everyone having to set their "Config Style preference, you can

  1. Find the file shotgun_fields_config_demo.mu in RV_HOME/plugins/Mu or wherever you installed the shotgun.zip package.

  2. Copy the demo file to shotgun_fields_config_custom.mu

  3. Edit shotgun_fields_config_custom.mu and change the module definition line to

    module: shotgun_fields_config_custom

Switching To A “Real” Install

After a successful demo, please see the following section, Site-Specific Custom Configuration in order to move to using your own Shotgun instance in place of the demo site.

Site-Specific Custom Configuration

After completing the General Installation steps described above, if you want to use RV with your Shotgun instance, you’ll need a custom config module (this module adapts the actual arrangement of fields and entities in your Shotgun database to RV’s idea of the “standard” fields). If you’re not already in communication with us about this, please email us.

Note

In order to understand what RV can and cannot do in terms of adapting to arbitrary Shotgun configurations, a good first step is to review the information in this Appendix

Create Shotgun "Script Key"

In order for RV to authenticate itself to the shotgun server, it needs to know the script key. To set this up, a shotgun admin needs to add a shotgun script called “rv”. That means go to the Scripts page listed in the Admin section of the standard navigation bar, click the + (Add Script) button to add a script, and name the script “rv”. The key for this script (in the Application Key field) will be passed to RV from the custom config module.

Note that if the script key is incorrect, you’ll get an error about “Can’t authenticate script rv”.

Turn On RV Action Items In Shotgun

Contact Shotgun Support and ask them to activate the Play in RV and Compare in RV action menu items in your Shotgun instance.

Install Your Config Module

To use a custom config module we built for you, you need to install it in RV’s MU_MODULE_PATH. You can add your own directories to this path, but by default it includes a location in your home directory, and one the directory in which RV is installed (RV_HOME):

Linux

~/.rv/Mu
RV_HOME/plugins/Mu

Windows

~/Application Support/RV/Mu
RV_HOME/plugins/Mu

Mac

~/Library/Application Support/RV/Mu
RV_HOME/PlugIns/Mu

If we’ve provided you with a custom config module (it’ll be called “shotgun_fields_config_custom.mu”), you just need to copy it to somewhere in the MU_MODULE_PATH and it should be picked up by the RV/Shotgun integration package at runtime.

Testing And Troubleshooting Your Installation

If the Play in RV and Compare in RV items on the Shotgun action menu seem to work perfectly, then you’re done. But if not, it’s useful to separate the testing of the integration code from the protocol handler. . You can assemble your own rvlink url and test the Shotgun integration from the command line like so:

% rv "rvlink:// -play -l -eval 'shotgun.sessionFromVersionIDs(int[] {VID});'"

Where VID should be replaced by the ID of any valid Version entity in your Shotgun database.

To make sure you’re loading the right config module and connecting to the right server, you can bring up RV’s Console window (WindowsConsole). You should see something like:

INFO: loaded shotgun config module 'shotgun_fields_config_demo'
      (/Users/alan/Library/Application Support/RV/Mu/shotgun_fields_config_demo.mu)
INFO: using shotgun server 'https://rvdemo.shotgunstudio.com'
INFO: Loaded "shotgun_mode"
INFO: Loaded "shotgun_info_mode"

To test the protocol handler registration independent of the integration code, try the links on this page.

Usage

Heads-Up “Shotgun Info Widget”

In Progress

Switching Media Types

In Progress

Changing The Edit

In Progress

New Sessions

In Progress

Preferences

In Progress

FAQ

In Progress

 

Appendix: Shotgun Entity/Field Survey

In order to use the RV Shotgun integration package, we need to be able to translate your shotgun structure into something that looks “standard” to RV. In general, the config module is very flexible and can make use of information stored in arbitrarilly-named fields on arbitrary entities. But there are some restrictions as follows:

The entity field of a Version must be connected to a Shot or an Asset

Otherwise we won’t be able to find the latest version of a shot or asset, or all the versions of a given shot or asset, and in the case of shot’s we won’t be able to put the Version in context with it’s neighbors in the cut.

Some field of a Version must be connected to a Project entity

So that several kinds of searchs can be limited to a single Project.

Some field of a Version must be connected to a Human User entity

So that notes can be addressed properly by default.

An integer order in the cut must be computable from a field on the Shot

Otherwise we won’t be able to find the neighbors of the Version of a Shot in order to play it in context.

Some field of a Shot must be connected to some entity that represents a sequence

Otherwise we won’t be able to find the neighbors of the Version of a Shot in order to play it in context.

For us to get started writing a config module for your shotgun setup, we need some information about the way you store information in shotgon. Hence the following survey. Please answer the questions below as completely as you can. In particular when we ask for name/type, please include the name and the type !

You can send your survey answers to Shotgun Support to start the process.

 


 

For convenience we refer to each of these bits of information as a "field", but remember that they can actually be computed from several fields or even from an environment variable or other outside source. For each field that RV can make use of in the shotgun integration, we list

Internal Field Name

The name that RV uses to refer to this bit of info. In general the actual name of the field is not important (can be easily set in the config module).

Recommended Entity

The type of entity we’re thinking is most appropriate for this bit of info. We’ll say required in the case where we think the bit must be on a particular entity.

Recommended Field Name

In most cases the field name can really be anything, but if you have no preference or you’re just setting up a project/pipeline, you can use this name so that the shotgun integration will work with minimal configuration.

Interpretation

The “meaning” of this bit of info for RV.

Your Field ?

This is where you tell us about the shotgun structure you use. In your answer, please list field name, field type, entity type that holds the field, and how that entity is linked to the Version entity.

If you don’t store that information directly, feel free to write more about how other fields on other entities could be used to assemble or compute the required information. For example, if your Version doesn’t have something like a maxFrame, but it has a firstFrame and a mediaDuration, then obviously maxFrame can be computed from those fields.

Also, if some information is not stored because it always has a certain value, just tell us what value we can assume in those cases.

 

Media Info

The most fundamental point of the RV/Shotgun integration is to give you good access to your media. We assume that for each version (take) there may be any number of media types (movie, high-res frames, low-res frames, etc). These types can differ in resolution, file format, etc. But they should all represent the same frame range (though some may have slates and some not).

For these three items, we need the corresponding info for each type of media you register "per-version" (movie, high-res frames, etc). So if you register a movie and a dpx sequence, we’re asking below for field information for path, aspect ratio, and slate for both media types (IE six fields).

Internal Field Name

mt_type

Recommended Entity

Version

Recommended Field Name

sg_path_to_frames, sg_path_to_movie, etc.

Interpretation

Filesystem path to the media. If this is a sequence, ideally the path should be in a form RV can use directly (like foo.#.dpx). But if that’s not convenient, the config module can usualy adapt the path for RV’s use.

Your Field ?

(Please give name, type, entity, linkage to Version)

Internal Field Name

mt_type_aspect

Recommended Entity

Version

Recommended Field Name

sg_frames_aspect, sg_movie_aspect, etc.

Interpretation

Pixel aspect ratio of media. This can often be hard-coded to 1.0, or come from a field on the Project.

Your Field ?

(Please give name, type, entity, linkage to Version)

Internal Field Name

mt_type_hasSlate

Recommended Entity

Version

Recommended Field Name

sg_frames_slate, sg_movie_slate, etc.

Interpretation

If true the media has a slate frame

Your Field ?

(Please give name, type, entity, linkage to Version)

 

Editorial Cut Info

The integration package can show your version media “in the cut” if it can retrieve the appropriate editorial information (frameIn, frameOut). In order to make use of this information it needs to know the actual frame range of the version’s media (frameMin, frameMax).

So, in general we should have, for any particular Version, frameMin < = frameIn < = frameOut < = frameMax

A key assumption that RV is making when using this information is that it applies to all media types. That is, for a given Version, all types of media represent the same set of frames (though some may have slates and some not, as described above).

The In/Out info is in general per-cut and can therefore be stored on the Shot or something else that is not Version-specific. On the other hand, the Min/Max info depends on what frames were actually rendered, and may be different in different departments, etc, so this info should be stored on the Version (or some other per-version entity).

Note that in this version of the integration package, we’re assuming that for RV’s purposes there is only one cut (the current cut). In the future we may support versioned cut information (most likely in the form of Cut and CutItem entities).

Internal Field Name

frameIn

Recommended Entity

Shot

Recommended Field Name

sg_cut_in

Interpretation

Number of first frame of this shot to appear in the current edit

Your Field ?

(Please give name, type, entity, linkage to Version)

Internal Field Name

frameOut

Recommended Entity

Shot

Recommended Field Name

sg_cut_out

Interpretation

Number of last frame of this shot to appear in the current edit

Your Field ?

(Please give name, type, entity, linkage to Version)

Internal Field Name

frameMin

Recommended Entity

Version

Recommended Field Name

sg_first_frame

Interpretation

Number of first non-slate frame in media

Your Field ?

(Please give name, type, entity, linkage to Version)

Internal Field Name

frameMax

Recommended Entity

Version

Recommended Field Name

sg_last_frame

Interpretation

Number of last frame in media

Your Field ?

(Please give name, type, entity, linkage to Version)

 

Editorial Ordering Info

The other bit of information we need to show multiple shots “in the cut” is the actual order of those shots. This is an integer that may be unique over the whole project, but must be unique in a given sequence.

Internal Field Name

cutOrder

Recommended Entity

Shot (required)

Recommended Field Name

sg_cut_order

Interpretation

An integer indicating the order of this shot in the current editorial cut (Can be the order within the sequence, or within the entire project)

Your Field ?

(Please give name, type, entity, linkage to Version)

If your ordering is “per-sequence” RV also needs to know to which sequence each Version belongs. Several studios link shots to Scene entities that function like sequences in this way, and that will work fine too.

Internal Field Name

sequence

Recommended Entity

Shot

Recommended Field Name

sg_sequence

Interpretation

A link to an entity to which all shots in a particular sequence will be linked

Your Field ?

(Please give name, type, entity, linkage to Version)

 

Department Info

The usual Departments are things like “layout”, “animation”, and “lighting” but could also include “pipeline stages” that are smaller than departments, like “lighting QA”.

Internal Field Name

department

Recommended Entity

Version

Recommended Field Name

sg_sequence

Interpretation

A string that “labels” this version with the department or pipeline stage that produced it.

Your Field ?

(Please give name, type, entity, linkage to Version)

Another common way to store department information per-version is to link each version to a Task entity and use the sg_task_type field on the task to hold the department.

How do you store information that describes the “Department” for each Version ?

 

Extra Info

What other fields would you like information gathered from and displayed in the Shotgun Info Widget in RV ? Just list the field name, field type, and entity type of each. If the field’s entity is not Version, please describe how the entity is connected to the version

 


 

That’s it, Thanks! Remember, send your answers to the above to Shotgun Support to start the process of creating a custom configuration module for your Shotgun instance.

Appendix: Customizing the Package

The config module (the module file called shotgun_fields_config_config_name.mu) is designed to be customized per-site. Here are some pointers if you want to do that:

Copy your config module

Copy your current config module to a new new name, say shotgun_fields_config_studioX.mu and place it somewhere in your MU_MODULE_PATH.

Change the module’s internal name

The name of the actual module object inside the module file must match the filename. That is, the line in your new module that starts with module: must look like module: shotgun_fields_config_studioX if that is the name of the file.

Set your config style preference

In RV go to the Shotgun→Preference→Set Shotgun Config Style item, and type just the last part of the name (“studioX” in this case).

Check that the new module is loading

Start RV and open the Console window. At the top of the window you should see something like:

INFO: loaded shotgun config module 'shotgun_fields_config_studioX' (/path/to/your/shotgun_fields_config_studioX.mu)
INFO: using shotgun server 'https://studioX.shotgunstudio.com'
INFO: Loaded "shotgun_mode"
INFO: Loaded "shotgun_info_mode"

In progress

Appendix: Localizing Media Paths

  1. Use PATHSWAP variables in the path values of fields in shotgun. This is nice because it requires no changes on the rv side. Note that before you see the path in rv (for example, in the shotgun info widget) the local PATHSWAP variable will have been swapped in, so you see the local path.

  2. Modify the fieldsCompute() function in your shotgun custom config module to change the paths however you want. Then the behavior of this function can depend on a local env var or some other way of telling what site it’s running at.

  3. Write a separate mode that will get an event whenever a new source is loaded, and have an oportunity to rewrite the file name.

In progress

Follow