pinto/vfxreview
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7dcb9303e5bdf15d6a694f4dbe8f7997869d8151
vfxreview/VFXReviewConnector.md
T
twotalesanimation 7dcb9303e5
Deploy / deploy (push) Successful in 6m32s
Details
updated export paths
2026-08-07 12:07:16 +02:00

16 KiB
Raw Blame History

VFXReview Connector

A dockable ScriptUI panel for Adobe After Effects 2024+ that integrates with the VFXReview platform to streamline shot management, render queuing, and workspace setup for VFX production pipelines.

Configuration

Settings are stored per-machine via the ⚙ Settings button in the panel (persisted in After Effects' built-in preferences — no need to edit the JSX file).

Setting Purpose
Server URL Base URL of the VFXReview server (e.g. https://review.twotalesvfx.com)
API Token Bearer token matching API_SECRET_KEY in the server .env
Export Root Local path where renders and deliverables are written
Footage Root Local path where EXR plate folders are read from
Banner Path Path to the panel banner image
Artist Email Used for render attribution in the pipeline
Handle Frames Plate handle frames prepended before the shot's source TC in-point (default: 8)

Pipeline Folder Structure

Export Root

All outputs from the connector are written under <Export Root>/{SHOW_ID}/ (e.g. V:/_EXPORTS). The show ID is appended automatically from the selected project — configure exportRoot as the bare root without a show ID.

<Export Root>/
└── {SHOW_ID}/                                     # e.g. UNG/
    ├── {SHOT_CODE}/                                # e.g. UNG_108_001_010/
    │   ├── {shot}_cmp_TT_{ver}.[#####].exr         # Queue EXR / Queue EXR (Review)
    │   └── {shot}_cmp_TT_{ver}.mp4 / .mov          # Queue MP4 / Queue MOV
    │
    ├── DELIVERY/
    │   └── {EPISODE_OR_SCENE}/                     # e.g. UNG_108/
    │       └── {YYYYMMDD}_Delivery/
    │           └── {SHOT_CODE}/
    │               └── {shot}_cmp_TT_{ver}.[#####].exr
    │
    └── (render farm outputs — managed by the server)
        └── {PROJECT_CODE}/{EPISODE}/{SHOT_CODE}/{ver}/
            └── {shot}_cmp_TT_{ver}.[#####].exr

Version naming: {SHOT_CODE}_cmp_TT_{version} — e.g. UNG_108_001_010_cmp_TT_v003.[01001].exr

Versions are set manually via Increment Shot Version or the shot detail page. Queuing a render does not auto-increment the version.

Footage Root

Source EXR plates are read from <Footage Root>/{SHOW_ID}/. Configure footageRoot as the bare root (e.g. V:/_FOOTAGE).

<Footage Root>/
└── {SHOW_ID}/                      # e.g. UNG/
    ├── {EPISODE_CODE}/             # episodic: e.g. UNG_108/
    │   └── {SHOT_CODE}_{CLIP}/     # e.g. UNG_108_001_010_A315C001/
    │       └── *.exr               # EXR sequence
    │
    ├── {SCENE}/                    # standard: e.g. 001/
    │   └── {SHOT_CODE}_{CLIP}/
    │       └── *.exr
    │
    └── _PICLOCKS/
        └── {EPISODE_CODE}_*.mov    # matched by episode prefix

Sequence folders must start with the shot code followed by an underscore ({SHOT_CODE}_*). The connector imports all matching folders as separate footage layers.

Episodic vs. Standard productions

Episodic Standard
Shot code format {SHOW}_{EP}_{SCENE}_{NUM} {SHOW}_{SCENE}_{NUM}
Shot Builder Episode dropdown → Shot dropdown Scene dropdown → Shot dropdown
Footage path {footageRoot}/{showId}/{EPISODE}/ {footageRoot}/{showId}/{SCENE}/
Export path {exportRoot}/{showId}/{SHOT_CODE}/ same
Delivery subfolder DELIVERY/{EPISODE}/… DELIVERY/{SCENE}/…

Migrating an existing project (e.g. UNG)

If you previously set exportRoot = V:/_EXPORTS/UNG, update it to V:/_EXPORTS. The code now appends /{showId}/ automatically, so V:/_EXPORTS/UNG/… is still produced — no files need to move.

Same applies to footageRoot: change V:/_FOOTAGE/UNG → V:/_FOOTAGE.

New production checklist

  1. Create <Footage Root>/{SHOW_ID}/{EPISODE or SCENE}/ and place EXR sequences inside, named {SHOT_CODE}_{clip}.
  2. <Export Root>/{SHOW_ID}/ is created automatically on first render.
  3. Add the project to the VFXReview server with the correct Show ID set.
  4. Open the panel in After Effects, click ⚙, enter the Server URL, API Token, bare exportRoot, and bare footageRoot, then click Save.
  5. The Project dropdown will populate automatically. Select the production and the episode/scene list will load.
Variable Default Description
TOKEN am3O0PWU… Bearer token used to authenticate all API requests
BASE_URL https://review.twotalesvfx.com Base URL of the VFXReview platform
PROJECT_CODE UNG_S1 Project identifier used in all API endpoints
EXPORT_ROOT V:/_EXPORTS/UNG Root path where rendered outputs are written
FOOTAGE_ROOT V:/_FOOTAGE/UNG Root path where source EXR footage sequences live
BANNER_IMAGE_PATH V:/VFXReviewConnector/banner.png Optional banner image displayed at the top of the panel

Panel Layout

The panel is divided into five sections:

  1. Shot Builder — Episode/shot selection and comp creation
  2. Actions — Per-shot and batch operations
  3. Workspace — One-time project initialisation
  4. Color Space — OCIO effect management
  5. Status — Live feedback on selected comps and last action

Shot Builder

Episode Dropdown

Populated automatically on panel load by calling GET /api/ext/projects/{PROJECT_CODE}/episodes. Each item stores the episode label (e.g. UNG_106) and the raw API episode value used for subsequent shot queries.

Shot Dropdown

Populated when an episode is selected by calling GET /api/ext/projects/{PROJECT_CODE}/shots?episode={value}. Displays shot codes (e.g. UNG_106_010_020).

Build Shot

Constructs a full shot composite in the open AE project from the episode and shot selected in the dropdowns.

Process:

  1. Calls the shot lookup API to retrieve metadata (description, notes, episode, scene, etc.).
  2. If a comp with the shot code already exists, updates its overlay instead of rebuilding.
  3. Scans FOOTAGE_ROOT/{episodeCode}/ for subfolders matching {shotCode}_* and imports each as an EXR image sequence at 24 fps.
  4. Creates a {shotCode}_FOOTAGE precomp containing all imported sequences, each with an OCIO Color Space Transform effect added (disabled by default).
  5. Creates the main {shotCode} comp and places the footage precomp inside it.
  6. If a _SHOW LUT comp exists in the project, adds it as a collapsed layer on top.
  7. Calls Add Overlay logic to attach the UNG_VFX_OVERLAY comp.
  8. Organises items into __SHOTS/{episodeCode}, _FOOTAGE_4K, and _PRECOMPS project folders.

Actions

Refresh

Updates the Status panel to show the current count of selected CompItems. Has no effect on the project.

Fix Comp Names

Renames selected comps so their names match the shot code extracted from their current name.

  • Shot codes follow the pattern XXX_000_000_000 (e.g. UNG_106_010_020).
  • If a comp name contains a valid shot code but has extra text, it is trimmed to the code only.
  • Wrapped in an undo group.

Add Overlay

Adds or updates the UNG_VFX_OVERLAY comp as a layer on each selected comp (or the active comp if nothing is selected).

Process:

  1. Looks up each shot via the API to confirm it exists.
  2. If the overlay layer is not already present, adds the UNG_VFX_OVERLAY comp and moves it to the top of the layer stack.
  3. Sets two Essential Properties on the overlay layer:
    • DATE — today's date in YYYY/MM/DD format.
    • SHOT NAME — {shotCode}_cmp_TT_v001.
  4. Reports how many overlays were added vs. updated vs. skipped.
  5. Wrapped in an undo group.

Requirement: A comp named UNG_VFX_OVERLAY must exist in the project.

Build Preview

Creates a {shotCode}_PREVIEW comp for each selected (or active) comp using a standardised export template.

Process:

  1. Duplicates the UNG_EXPORT_TEMPLATE comp and names the copy {shotCode}_PREVIEW.
  2. Moves the copy into the _PREVIEWS project folder if it exists.
  3. Replaces the SHOT and THUMBNAIL layers with the shot comp.
  4. Populates the NETFLIX_SLATE Essential Properties:
    • Shot name ({shotCode}_cmp_TT_v001)
    • Date, Description, Notes, Shot Code, Episode, Scene, Frame count
  5. Adjusts the preview comp duration to match the shot comp duration.
  6. Wrapped in an undo group.

Requirements:

  • UNG_EXPORT_TEMPLATE comp must exist in the project.
  • Shot metadata must be available from the API.

Queue EXR

Queues each selected comp for EXR sequence render using the EXR Sequence output module template.

Process:

  1. Looks up each shot via the API to get the exrOutput filename stem.
  2. Sets the comp's display start frame to 1001.
  3. Disables any layers named UNG_VFX_OVERLAY or _SHOW LUT in the comp.
  4. Ensures the output folder EXPORT_ROOT/{shotCode}/ exists.
  5. Queues the comp with output path {folderPath}/{exrOutput}.[#####].exr.
  6. Wrapped in an undo group.

Requirement: The EXR Sequence output module template must be configured in AE preferences.

Queue MP4

Queues a preview render for each selected (or active) comp as an MP4 file.

  • Uses the REVIEW_PREVIEW output module template.
  • Output path: EXPORT_ROOT/{shotCode}_cmp_TT_v001.mp4
  • Automatically calls Build Preview first if a {shotCode}_PREVIEW comp does not exist.
  • Updates the overlay on the main shot comp before queuing.
  • Wrapped in an undo group.

Requirement: The REVIEW_PREVIEW output module template must be configured in AE preferences.

Queue MOV

Identical to Queue MP4 but uses the 4444 Tri output module template and writes a .mov file.

  • Output path: EXPORT_ROOT/{shotCode}_cmp_TT_v001.mov

Requirement: The 4444 Tri output module template must be configured in AE preferences.

Import Renders

Imports rendered EXR sequences for the active/selected shot comp from the shared renders folder.

Process:

  1. Resolves the renders folder at X:/shared_projects_2026/UNGO_VFX/production/renders/{shotCode}.
  2. Iterates subfolders first (separate render passes/layers), importing each as an EXR sequence at 24 fps. Falls back to sequences directly in the root folder.
  3. Adds each imported footage item to the _RENDERS project folder.
  4. Adds all footage as layers to the target comp and applies the Extractor effect to each layer.
  5. Pre-composes all added layers into a single {shotCode}_RENDER comp.
  6. Wrapped in an undo group.

Pull Picture Lock

Imports a picture-lock (offline cut) video file and trims it to the correct sequence timecode range for the shot, including handles.

Process:

  1. Calls the API to retrieve seqTimecodeStart and seqTimecodeEnd for the shot.
  2. Searches the _PICLOCKS project folder for already-imported footage matching the episode prefix (first 7 characters of the shot code, e.g. UNG_106).
  3. If not found, scans FOOTAGE_ROOT/_PICLOCKS/ for a file matching {episodePrefix}_* and imports it.
  4. Calculates the in/out offsets from the sequence timecodes relative to the piclock's start (assumed 01:00:00:00 / 3590 s unless embedded timecode is available), with ±8 frame handles.
  5. Adds the piclock footage as a layer at the top of the comp, scales it to fill the frame, and sets startTime, inPoint, and outPoint to isolate the correct range.
  6. Wrapped in an undo group.

Requirement: Shot must have seqTimecodeStart and seqTimecodeEnd populated in the VFXReview database.

Workspace

Initialise Workspace

One-time setup that creates the standard project folder hierarchy, imports the slate/overlay template AEP, and configures color settings.

Folder structure created:

__SHOTS/
  UNG_101/
  UNG_102/
  …
  UNG_117/
_PREVIEWS/
_PRECOMPS/
_PICLOCKS/
_FOOTAGE_4K/
_STOCK/
_RENDERS/
_UTILITIES/

Template import: Imports X:/shared_projects_2026/UNGO_VFX/production/working_files/UNG_VFXOVERLAY_SLATE_TEMPLATE.aep as a project merge.

Color settings (applied outside the undo group):

  • Sets project bit depth to 32-bit.
  • Enables color management via app.project.colorSettings.enabled.
  • Attempts to set the working color space to ACES 1.2 by searching the available space list. Falls back to "ACES - ACES2065-1" if the list API is unavailable. If the scripting API does not support this, a message prompts manual configuration.

Color Space

Add OCIO to Footage Layers

Adds an OCIO Color Space Transform effect (disabled) to every footage layer in each selected (or active) comp.

  • Only targets FootageItem layers backed by a FileSource (skips solids, comps, etc.).
  • Sets the Output Color Space property to index 93.
  • The effect is added in a disabled state so it can be enabled selectively during grading.
  • Wrapped in an undo group.

API Reference

All HTTP calls use system.callSystem with curl. Requests include:

Authorization: Bearer {TOKEN}
Accept: application/json
Endpoint Method Description
/api/ext/projects/{PROJECT_CODE}/episodes GET List all episodes for the project
/api/ext/projects/{PROJECT_CODE}/shots?episode={value} GET List shots for a given episode
/api/ext/shots/lookup?shotCode={code}&projectCode={code} GET Retrieve full metadata for a single shot

Shot Metadata Fields Used

Field Used By
shotCode All operations — canonical identifier
exrOutput Queue EXR — filename stem for EXR renders
description Build Preview — slate Description property
notes Build Preview — slate Notes property
episode Build Preview — slate Episode property
scene Build Preview — slate Scene property
seqTimecodeStart Pull Picture Lock — in-point calculation
seqTimecodeEnd Pull Picture Lock — out-point calculation

Shot Code Convention

Shot codes follow the pattern AAA_NNN_NNN_NNN where:

  • AAA = three-letter show prefix (e.g. UNG)
  • First NNN = episode number (e.g. 106)
  • Second NNN = sequence number (e.g. 010)
  • Third NNN = shot number (e.g. 020)

Example: UNG_106_010_020

Episode codes follow the pattern AAA_NNN (e.g. UNG_106).

Required Project Assets

The following comps/items must exist in the AE project for certain features to work:

Name Type Required By
UNG_VFX_OVERLAY Comp Add Overlay, Build Preview, Queue MP4/MOV
UNG_EXPORT_TEMPLATE Comp Build Preview, Queue MP4/MOV
_SHOW LUT Comp Build Shot (optional — applied if present)
_PREVIEWS Folder Build Preview (optional — used if present)
_PRECOMPS Folder Build Shot (optional — used if present)
_FOOTAGE_4K Folder Build Shot (optional — used if present)
_RENDERS Folder Import Renders (optional — created if absent)
_PICLOCKS Folder Pull Picture Lock (optional — created if absent)
__SHOTS Folder Build Shot / Initialise Workspace

Output Module Templates Required

These must be created in After Effects > Edit > Templates > Output Module before using the corresponding queue buttons:

Template Name Used By Format
EXR Sequence Queue EXR OpenEXR image sequence
REVIEW_PREVIEW Queue MP4 H.264 / MP4
4444 Tri Queue MOV ProRes 4444 / MOV

Status Panel

The Status panel at the bottom of the UI shows two lines:

  • Line 1 — Number of currently selected CompItems.
  • Line 2 — Result or progress message from the last operation.

Both lines are updated throughout batch operations so progress is visible in real time.

Reference in New Issue View Git Blame Copy Permalink