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/
    ├── {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 `CompItem`s. 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 `CompItem`s.
- **Line 2** — Result or progress message from the last operation.

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