vfxreview/VFXReviewConnector.md

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/ or DH2_VFX/
    ├── {EPISODE_CODE}/             # episodic only: e.g. UNG_108/
    │   └── {SHOT_CODE}/            # standard layout: plates grouped per shot
    │       └── {SHOT_CODE}_{ELEM}_{VER}/
    │           └── *.exr
    │
    └── _PICLOCKS/
        └── {EPISODE_CODE}_*.mov    # matched by episode prefix

Scenes are not folders. Standard projects have no level between the show folder and the shot folder — the scene picker filters the shot list only.

Two layouts are supported, and neither is migrated. The connector prefers the grouped layout above; where a {SHOT_CODE}/ folder does not exist it falls back to scanning the parent for folders named {SHOT_CODE}_* (the original UNG layout, where plates sit directly in the episode folder). All matching folders are imported as separate footage layers. If a {SHOT_CODE}/ folder exists but holds no plate subfolders, that is reported as no footage — the fallback scan is not attempted, so stray plate folders sitting beside the shot cannot be picked up as its footage. Underscore-prefixed folders (_ARCHIVE, _GFX, _PULLS, …) are never treated as shots or plates.

---

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_CODE}/]{SHOT_CODE}/ — episode level for episodic shows only, never a scene level — and place each plate in its own {SHOT_CODE}_{ELEM}_{VER}/ folder inside it.
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 seven sections:

1. Shot Builder — Episode/shot selection and comp creation
2. Render Pipeline — Queue Export, status polling, retry, regenerate previews
3. QC — Technical QC queue for rendered exports
4. Actions — Per-shot and batch operations
5. Workspace — One-time project initialisation
6. Color Space — OCIO effect management
7. Status — Live feedback, plus Diagnostics and the last report

---

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.

If any step fails, the status line names the stage and a copyable report opens — see Diagnostics and logging.

---

QC

Technical QC on the rendered EXRs, not the H.264 preview — the point is catching mask slips, export glitches and metadata faults at full resolution. QC is per-export: a new export always needs new QC.

Control	Behaviour
Load QC Queue	Lists every export in READY_FOR_QC for the selected project, oldest first. Entries flagged with a warning count had a non-blocking validation warning worth a closer look.
Open Render (or double-click)	Imports that export's actual EXR sequence into a QC_{shot}_{version} comp at full res and opens it. Re-selecting an already-imported shot just reopens the comp.
Notes	Sent with the decision. Optional on pass; a fail with no notes asks for confirmation, because the artist only sees what you write here.
QC Pass	Marks the version ready for delivery and nothing else — nothing is shared to the client, no approval state changes, no task moves.
QC Fail	Sets the export to QC_FAILED and the comp task to CHANGES. The artist fixes and queues a new version; the old export is superseded.

Passing an export is what makes it eligible for a delivery package on the web app's Pipeline → Deliveries page.

---

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 are read by anchoring on the selected project's showId — see Shot Code Convention.
• 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 — {showId}_{episode} on episodic shows (e.g. UNG_106), plain {showId} on standard ones.
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 are the project's showId followed by three-digit tokens:

Project type	Pattern	Example
Episodic	{showId}_{episode}_{scene}_{shot}	UNG_106_010_020 (showId UNG)
Standard	{showId}_{scene}_{shot}	DH2_VFX_027_010 (showId DH2_VFX)

The showId is not always three letters and may itself contain underscores, so codes are parsed by stripping the known showId prefix — never by counting underscores or matching a fixed AAA_ pattern. Everything after the showId is three digits per token.

Episode codes follow {showId}_{episode} (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.

Below them are two buttons:

• Diagnostics — runs the environment self-test described below.
• Show Last Report — re-opens the trace from the last button pressed.

---

Diagnostics and logging

Every button press is traced: what it tried, in what order, with the paths and HTTP codes it was working with. The trace goes to an in-memory buffer and to a log file, and it is shown automatically when something fails.

Log file: %APPDATA%/VFXReviewConnector/connector.log (next to config.json). It is truncated once it passes 1 MB, so it can always be pasted into a message. The API token is never written to it — only whether one is set.

When Build Shot fails

The status line now names the stage it failed at, and a scrollable report opens with the whole trace. The stages, and what each one means:

Stage	Meaning	Usual fix
project	No project selected in the panel	The project dropdown is empty because the server URL or token is wrong
shot lookup	The server returned no shot record	Report shows the HTTP code: 0 = server unreachable, 401/403 = bad token, 404 = shot not in that project
configuration	Footage Root is blank in Settings	Settings are per-machine; a fresh workstation starts blank
footage folder	The show/episode folder does not exist here	Report names the deepest folder that does exist — usually an unmapped drive or a different drive letter/UNC on that machine
plate folders	Folder exists, no plates for that shot code	Report lists the folders that are there, so a naming mismatch is visible
plate import	Plate folders matched but held no importable EXRs	Report lists each folder's contents (n .exr, n other files)
comp creation	After Effects threw while building the comps	Not a path or server problem — the AE error text is in the report
unexpected error	Anything thrown that was not anticipated	Report carries the error text, line number and stack

Non-fatal conditions are traced too rather than passing silently: a missing _SHOW LUT, an overlay that could not be applied, a missing __SHOTS/{group} folder.

Diagnostics button

Checks everything Build Shot depends on without building anything, so a workstation can be cleared before an artist is blocked. It verifies:

1. curl.exe is present and runnable (every server call goes through it).
2. Server URL and API token are set, and GET /api/ext/projects succeeds.
3. Footage Root resolves to a folder that exists, and lists the plate folders found for the currently selected shot.
4. Export Root resolves to a folder that exists.
5. The shot lookup succeeds for the currently selected shot.
6. The open AE project has UNG_VFX_OVERLAY, UNG_EXPORT_TEMPLATE, _SHOW LUT, and the __SHOTS / _FOOTAGE_4K / _PRECOMPS / _PREVIEWS folders.

Each failure is reported as a PROBLEM line with the offending path or HTTP response, and the report ends with a problem count.

Errors that used to be invisible

ScriptUI silently swallows exceptions thrown inside a button handler, so a hard failure looked like a button that did nothing at all. Every handler is now wrapped: anything thrown is caught, logged with its line number and stack, shown in the status line, and surfaced in the report dialog.