vfxreview/DELIVERY_WORKFLOW.md

Delivery Packages — Workflow Guide

How a finished shot becomes a dated folder ready to upload to the client.

There are two kinds of package. An EXR delivery is the shippable one and is what most of this guide describes. A MOV review is a flat folder of preview MOVs shared for a formal review — see MOV review packages at the end.

This is the operational guide. The design rationale and normative rules live in RenderPipeline2.md §11.

---

The short version

1. A shot renders, validates, gets a preview, and passes QC → it becomes eligible for delivery.
2. On Pipeline → Deliveries, pick the project, see "Episode 101 — Ready: 18 shots", click Build delivery.
3. A render worker builds the folder on the delivery volume, verifies every file, and writes a manifest and CSV report.
4. A human uploads that folder to the client, then clicks Mark delivered.

Nothing is ever sent to the client automatically. Step 4 is deliberately manual.

---

What makes a shot eligible

An Export reaches READY_FOR_DELIVERY only by passing QC — from the AE panel or the web. That is the single gate; there is no way to package an export that has not been QC'd.

A render that failed automated validation can still get there: Override validation on the Export detail page (admin/producer/supervisor, reason required) resumes the pipeline at the preview stage, so the shot still goes through QC like any other. The failed checks stay on record and keep appearing as warnings in the QC queue, so whoever QCs it knows what was waved through.

Two rules worth knowing:

• Newest version per shot only. If a shot has two exports sitting ready, the older one is history and is not offered. Building refuses outright if you somehow select two versions of the same shot.
• Version locking. A package references the exact Export rows it was built from and copies the shot code and version string at creation time. Re-render a shot afterwards and the package is untouched — delivery history is immutable by construction.

---

Building a package

Pipeline → Deliveries, choose a project. Each episode with ready shots shows its count and the shots themselves, with frame counts and sizes.

Build delivery creates the package (QUEUED) and a DELIVERY_BUILD job on the same queue the renders use. Requires admin, producer or supervisor.

Delivery jobs run at priority 10, which is inside the urgent threshold — so they claim immediately even during work hours, when a render would wait for the evening window. Packaging is file work with no After Effects involvement, so it does not disturb an artist at the machine.

Watch the package status on the same page:

Status	Meaning
QUEUED	Waiting for a worker to pick it up
BUILDING	A worker is creating folders and linking files
READY	Built and verified — upload it
DELIVERED	You confirmed the client has it
FAILED	Something did not verify — see the error and the per-shot list
CANCELLED	Abandoned before delivery

---

What lands on disk

Default layout (the studio's confirmed structure):

{deliveryRoot}/{episode}/{YYMMDD}_Delivery/
├── {SHOT_CODE}/
│   ├── {shot}_cmp_TT_{ver}.[#####].exr     ← the EXR sequence
│   └── {shot}_cmp_TT_{ver}.mov             ← slate/burn-in delivery MOV
├── manifest.json                            ← every file, size, checksum, source export
└── {YYMMDD}_Delivery_report.csv             ← one row per shot (client-facing)

EXRs and the MOV sit side by side in each shot folder — no exr/ and mov/ subfolders, matching current practice.

The CSV carries: shot, version, frame range, frame count, file count, bytes, checksum, MOV filename and status. Confirm these columns against the production's delivery spec before the first real delivery.

---

Hard links, and why the package appears instantly

Files are hard-linked, not copied, when the source and destination are on the same volume. A hard link is a second name for the same data — not a shortcut and not a copy — so an 18-shot EXR package builds in seconds and consumes essentially no extra disk.

Verified on the studio SAN (\\TRUENAS\vfx over SMB): hard links work there, and renders and deliveries live on the same share.

Is that safe? Deleting the delivery folder does not delete the render — the data survives until the last name referring to it is gone. And nothing in the pipeline ever rewrites an existing EXR: a new version is always a new directory.

Two escape hatches:

• A delivery root on a different volume falls back to copying automatically.
• "copyMode": "always-copy" in the project's delivery config forces real copies for a production that mandates physical separation.

The linkMode column on each item records what actually happened, so a package never claims to have linked when it copied.

---

Verification

Verification is proportional to what the builder actually did, which is what keeps a package fast:

Mode	How it verifies	Cost for a 25-shot episode
Hard-linked (default)	The entry is the source data, so the validation-time digest already describes it. Checks each file exists, and that no source was modified after it passed QC.	seconds
Copied	Read back in full and hashed; the sequence digest must match the one recorded at validation.	~30 s per 2.8 GB shot

Re-reading a hard link cannot disagree with validation — it is the same bytes under a second name — and at ~100 MB/s over SMB it costs roughly half an hour per episode to prove something that cannot be false. A copy is genuinely different: it can be truncated or corrupted, so it is always read back.

Set "verifyMode": "always-hash" in the delivery config to read everything back regardless, for a production that requires it contractually.

An item fails, and the whole package fails with it, when:

Failure	Meaning
Checksum mismatch (copied items)	The delivered bytes differ from what passed QC
A source file modified after validation	The render changed after it passed QC — a link would carry the new bytes faithfully
Frame count differs from the export record	The render folder changed after QC — someone re-rendered in place
Source folder missing	The render is not where the export says it is
No matching files	The folder exists but holds nothing matching the output pattern

A package only reaches READY when every shot verified. One bad shot means FAILED, and no export is marked as packaged — there is no partial delivery.

A missing delivery MOV is the one non-fatal case: the EXRs are the deliverable, so it is logged and the package continues without it.

Without validation there is nothing to verify against. An export whose checksum was never recorded (validation disabled, or rendered before it shipped) still packages, but the digest is computed with nothing to compare it to. The ready list flags these as "N without a validation checksum".

---

Marking delivered

Once you have uploaded the folder, Mark delivered moves every packaged export to DELIVERED. Requires admin, producer or supervisor.

This is the end of the pipeline, and it is a human statement of fact — the app has no way to know the client received anything.

---

When something goes wrong

A package failed. Expand it: every shot shows its own status and error. Fix the cause (usually a re-render after QC), then build a new package. Packages are never deleted; a mistaken one is cancelled.

The worker died mid-build. The package is marked FAILED with "check the package folder before rebuilding". It is deliberately not retried automatically — a half-written folder on the delivery volume is something a human should look at first.

Cancelling. Only DRAFT, QUEUED and FAILED packages can be cancelled. A READY or DELIVERED package stays in the history permanently; supersede it by building a new one.

---

Configuration

Per project, in Project.deliveryConfig; studio-wide defaults in the delivery.defaultConfig SystemConfig key; built-in defaults otherwise. Merged key by key, so a project can override just deliveryRoot.

{
  "packageNameTemplate": "{yymmdd}_Delivery",
  "layout": {
    "packageDir": "{deliveryRoot}/{episode}/{packageName}",
    "shotDir":    "{packageDir}/{shotCode}",
    "reportFile": "{packageDir}/{packageName}_report.csv"
  },
  "deliveryRoot": "//SAN/DELIVERY",
  "includeMovs": true,
  "checksumAlgo": "xxh64",
  "reportFormats": ["csv", "json"],
  "copyMode": "auto",
  "verifyMode": "auto"
}

Tokens: {showId} {episode} {yymmdd} {yyyymmdd} {packageName} {packageDir} {deliveryRoot} {shotCode} {versionString} {packageNumber}.

The resolved config is snapshotted onto the package at build time, so a historic package always shows the rules it was built with, and a production with a different spec is a config change rather than a code change.

deliveryRoot must be reachable from the worker machine — check with VFXReviewWorker.exe --check if a build fails on paths.

---

API

#	Method	Path	Purpose
E16	POST	/api/deliveries	Create a package and queue the build
E17	GET	/api/deliveries	List packages / history
E18	GET	/api/deliveries/ready	Ready exports grouped by episode
E19	POST	/api/deliveries/{id}/delivered	Mark delivered
—	POST	/api/deliveries/{id}/cancel	Cancel a package
—	POST	/api/ext/render/jobs/{jobId}/delivery	Worker reports a build (API key)

POST /api/deliveries takes { projectId, episode?, exportIds?, options? }. Omit exportIds to take every ready export in the episode; options accepts date, name, includeMovs and copyMode to override the config for one build.

---

MOV review packages

For a formal review you share the preview MOVs, not the EXRs. That is its own kind of package, built the same way and listed on the same page.

Building one

Shot Status, tick the shots, then Bulk Actions → Build MOV Review Package. A dialog shows exactly what would be built before anything happens: the folder name, the version each shot contributes, and any shots being left out. Requires admin, producer or supervisor.

The version each shot contributes is its newest export that actually has a preview MOV — not necessarily its newest export. A shot whose latest version is still rendering goes into the review as the version that can be watched. A shot with no MOV at all is listed as left out, with the reason, rather than quietly reducing the folder.

What lands on disk

{deliveryRoot}/PRODUCER_REVIEWS/20260828_Producer_review/
├── EP6_VFX_012_v004.mov
├── EP6_VFX_013_v002.mov
└── UNG_106_010_040_cmp_TT_v001.mov

Flat — the MOVs sit beside each other so they can be scrubbed through in order. Names follow the same client-naming rule as a delivery: the production's own code where it has one, ours where it does not, so a shot reads identically in a review folder and in the delivery that follows it.

The folder is exactly the MOVs: no CSV, no manifest.json beside them. The manifest still goes back to the app, so the record of what was shared is kept without cluttering the share.

Second review the same day is 20260828_Producer_review_02, then _03. A number is never reused, even if the package that took it was cancelled.

What it does not do

A review never moves a shot along. Reviews happen throughout a shot's life, long before QC passes it, and the same version is routinely shown twice — so building one changes nothing about the exports in it, and there is no Mark delivered on a review package. Shots stay exactly where they are in the pipeline.

A missing MOV fails the package here, unlike in an EXR delivery where a missing MOV is logged and the build continues. In a review the MOV is the deliverable, and a review folder quietly one shot short is worse than one that says so.

Configuration

Two more keys in the same deliveryConfig (§11.6):

{
  "reviewNameTemplate": "{yyyymmdd}_Producer_review",
  "layout": {
    "reviewDir": "{deliveryRoot}/PRODUCER_REVIEWS/{packageName}"
  }
}