37 Commits

Author SHA1 Message Date
twotalesanimation b151e8cc52 feat(pipeline): per-shot client naming alias for slates, overlays, and delivery
Deploy / deploy (push) Successful in 7m25s
Clients sometimes ship footage under a naming convention that doesn't
match our own shot codes. Adds an optional Shot.clientCode, editable on
the Slate tab: when set, it replaces shotCode only in what the client
actually sees — slate identity, overlay burn-in, and delivered EXR/MOV
file and folder names in Netflix packages — with our own version string
flatly appended (no "_cmp_TT_" studio jargon mixed in). Internal render
paths, EXR filenames on the SAN, comp names, and DB lookups are
untouched. Shots without a client code render identically to before.

Delivery packages denormalize clientCode at build time, same as the
existing shotCode/versionString snapshot, so a later shot edit can't
retroactively change already-built delivery history. The worker now
renames delivered EXR frames and the delivery MOV using the existing
frame-number parser (SequencePattern) so only the base name changes —
frame numbers and padding survive exactly. This is the one piece of the
change that could plausibly ship the wrong bytes, so it's covered by
new unit tests (renaming, padding, MOV rename, checksum-survives-rename,
and a graceful fallback for an unparseable frame number) rather than
resting on manual verification alone.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-26 00:38:12 +02:00
twotalesanimation 26a4719c2a fix(connector): strip reference LUT/overlay before Queue Export renders EXRs
Build Shot adds the show LUT and overlay burn-in into the artist's main
comp, enabled by default, for reference while compositing. The legacy
manual "Queue EXR" button has always disabled both before rendering;
Queue Export (the pipeline's one-click path) never got that same step,
so EXRs queued through it could ship with the LUT graded in and the
burn-in baked on. Queue Export now disables them the same way, right
before the project save the render worker reads from.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-25 22:47:42 +02:00
twotalesanimation a18dfc6203 revert(pipeline): back out picture-lock trimming from the preview build
Deploy / deploy (push) Successful in 6m19s
Production fallout after enabling it: the trimmed EXR footage started
after the head handle as intended, but the overlay's burn-in timecode
(hardcoded to start at frame 1001) did not shift with it, so the
delivered burn-in no longer matched the footage. The picture-lock
reference render also never worked correctly in practice. Reverts the
AE panel checkbox, the preview-build script's trim/reference logic, and
the server/worker plumbing around it back to their pre-feature state
(82dfaee) — untrimmed previews, no picture-lock reference, overlay
timecode correct again.

The noPictureLock/piclockRefKey schema columns and their migration are
deliberately left in place: they're already applied in production, and
dropping an applied migration's file risks the next `prisma migrate
deploy`. They sit unused and harmless until this is revisited.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-23 21:44:45 +02:00
twotalesanimation 67d8639861 fix(pipeline): trim picture-lock handles at the footage comp, not the template's SHOT layer
Deploy / deploy (push) Successful in 6m17s
Manipulating startTime/outPoint on previewComp's SHOT layer touched a
comp duplicated from the artist-authored template, whose slate/shot
timing relationship the build script doesn't own -- and it dropped the
slate frame in production. The trim now happens one level down, on the
private single-layer footage precomp this script fully controls;
previewComp's own sizing logic is untouched from before this feature
existed, since it already generalizes correctly to any shotComp
duration.

Also threads the picture-lock skip reason through to the export's
timeline, so a shot missing sequence timecodes or a matching picture
lock file is visible without digging into worker-machine logs.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-23 14:22:49 +02:00
twotalesanimation 86962eb4bd feat(pipeline): automate picture-lock trimming in the preview build
Deploy / deploy (push) Successful in 10m37s
Previews used to ship the full padded (handle-included) render to
clients, with an artist manually pulling picture lock and hand-trimming
the comp to match. The automated preview stage now trims the client
comp to the picture-lock edit itself (a fixed handle count off each
end, per the studio's existing convention) and separately builds an
ungraded, full-duration picture-lock reference MP4 as a diagnostic
sidecar to check back against. A new "No Picture Lock" panel checkbox
is the single override for shots where picture lock is missing or
wrong, falling back to today's untrimmed behavior.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-22 12:59:05 +02:00
twotalesanimation 82dfaee56f fix(delivery): stop the 422 retry loop on failed delivery items
Deploy / deploy (push) Successful in 6m37s
A FAILED delivery item never sets fileCount/totalBytes, and the worker's
Dictionary-based JSON payload serializes those as explicit nulls (the
WhenWritingNull option only suppresses nulls on POCO properties, not
dictionary values). The server's schema allowed the fields to be omitted
but not null, so the report was permanently rejected with 422 - and the
worker only ever treated 409/404 as terminal, so it retried the same
malformed payload forever across restarts.
2026-08-21 12:07:30 +02:00
twotalesanimation df219d7932 chore: retrigger deploy
Deploy / deploy (push) Successful in 6m9s
Empty commit to re-fire the Gitea Actions push trigger after a failed
deploy run; no source changes.
2026-08-17 16:05:36 +02:00
twotalesanimation cf55a53c06 fix(client): remove version notes from the client shot-list page
Deploy / deploy (push) Failing after 2s
Removes the three spots on the client review shot-list page that showed
a version's notes under the task title (flat task list, shot-grouped
list, asset list) — one of the three was already commented out by hand,
uncommitted, as a stopgap for the same issue.

The API route backing this page no longer selects notes at all, so it
stops being sent to the client rather than only going unrendered — the
same treatment as removing the pipeline's internal-only notes text in
53fc8dc.

The individual review player (app/client/[token]/review/[versionId]/)
has its own separate notes field and fetch and is untouched: this was
scoped to the shot-list overview only, per what was asked.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-17 15:57:58 +02:00
twotalesanimation 53fc8dc65b fix(pipeline): re-exports keep a shot's approval, and carry no client-facing text
Deploy / deploy (push) Successful in 6m1s
A shot is routinely re-exported for delivery after it has already been
client-approved — most often an unscaled/un-punched-in pass. Every
pipeline-created Version defaulted to approvalStatus PENDING_REVIEW,
which is exactly what the dashboard counts, the shot page badge and the
playlist read as "awaiting review" — so a re-export made an approved
shot look like new unreviewed work to the whole team, with nothing
actually different about its approval.

approvalStatus is now inherited from the task's previous latest version
rather than left at the create default. A task with no prior version
(its first export) still gets PENDING_REVIEW, which is correct.

Separately, every pipeline version was stamped with notes: "Pipeline
render vXXX (internal only)" — and notes is the artist's message to
reviewers, rendered verbatim in the client portal and the review player.
Nothing enforces that a pipeline version stays unshared once created (see
the gap noted in RenderPipeline2.md), so that internal-sounding string
could reach a client if the shot were re-shared after a re-export. notes
is left unset; what a version is and where it came from belongs on the
Export and its timeline, which is where a human would actually go
looking.

RenderPipeline2.md §9 documents both, plus the share-flow gap that let
notes reach a client in the first place: shareWithClient promotes
whichever Version is isLatest with no awareness that a pipeline version
is meant to stay internal permanently. Not fixed here — closing it needs
a way to identify a pipeline-origin version at the share call sites, and
Export.versionId is currently a one-way scalar with no inverse relation
on Version.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-17 15:52:49 +02:00
twotalesanimation ed8a225106 fix(blender): read carriage-return progress, and let any output prove liveness
Deploy / deploy (push) Successful in 6m5s
Blender renders failed with "produced no output for 600s" on every
attempt while rendering perfectly well.

Two causes, both mine. BeginOutputReadLine raises an event per newline,
and Blender writes its render status with a carriage return so it
overwrites one line in place — a frame taking longer than the stall
timeout emits no newline for its whole duration. stdout is now read as a
character stream with CR and LF both ending a line.

The watchdog was also stricter than its own message: it only accepted a
recognised Fra:/Saved: line as a sign of life, so any output we were not
parsing counted as silence. Any output now proves Blender is alive, which
is what "produced no output" is asking; finished frames still drive
progress, since a single frame emits hundreds of status updates.

Also passes -noaudio: a render node has no sound device, and initialising
audio under a session-less service account is a known way to hang.

Covered by tests over a realistic stdout chunk where progress is
CR-separated and only the saved lines end in LF — newline-only splitting
yields one unusable blob and no progress at all.

Worker 1.5.1.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-15 20:44:49 +02:00
twotalesanimation a18aad4373 fix(blender): hold a reference to the project enum items
Deploy / deploy (push) Successful in 6m6s
The project dropdown rendered garbled labels. EnumProperty does not copy
the strings a callback returns — Python has to keep a reference or
Blender reads freed memory, which shows as mojibake rather than as a
crash. The callback built fresh tuples on every redraw, so each set was
collected the moment it returned.

The items are now built once when the project list changes and held at
module level; the callback returns that list and allocates nothing, which
also makes a per-redraw callback free rather than merely correct.

Add-on 1.0.2.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-15 19:24:46 +02:00
twotalesanimation 3733c0c4fa fix(blender): send a real User-Agent so Cloudflare stops blocking the add-on
Deploy / deploy (push) Successful in 5m59s
Submitting failed with a 403 before the request reached the server:
Cloudflare error 1010, a browser-signature ban. Python's urllib
identifies itself as "Python-urllib/3.x", which is exactly the scripted
signature that rule targets. The AE panel was unaffected because curl
sends curl/8.x, and the worker because .NET sends its own.

Verified against the live zone, same request and token, only the agent
changed: Python-urllib/3.11 gets 403 while VFXReviewBlender/1.0.1 gets
200 — as do curl and a browser agent.

Naming the tool is also the honest thing: the studio's logs should say
what is calling them, and the version travels with it.

A Cloudflare block is also no longer reported to the artist as a wall of
JSON about browser signatures — it says the firewall stopped the request
before it reached the server, and to ask the pipeline TD.

Add-on 1.0.1.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-15 19:11:52 +02:00
twotalesanimation 70cf45ead4 feat(pipeline): standalone Blender renders on the same queue
Deploy / deploy (push) Successful in 7m2s
Blender work is not a shot submission: no Export, no version, no
validation, QC or delivery. It is "Ctrl+F12, but on the farm", so it is
modelled as what it is — a queue entry and nothing more.

That turned out to need very little. Claim, progress, fail and
complete-render already tolerated a job with no Export behind them, so a
Blender job reuses the whole lifecycle; RenderJob gains projectId, label
and submittedBy so a job with no shot code still has something to show.

Capability gating is new and was already missing: the claim now filters
job types by the machine's reported tools. Without it a workstation
without Blender would claim Blender work and fail it repeatedly, burning
the attempts while a machine that could have rendered it sat idle. The
worker asks for Blender jobs unconditionally and the server refuses them
— trusting the worker to self-select would have left the same hole.

The runner treats a clean exit with no saved frames as a failure:
Blender exits 0 when a frame range is empty or an output path is
unwritable, and a job that silently rendered nothing is the worst
outcome available.

Standalone jobs auto-requeue on a transient failure like any other work;
delivery builds are deliberately excluded, since a half-written package
wants a human first.

Adds the Blender add-on (BlenderPanel/) and its docs. The add-on refuses
to submit an unsaved file — the farm opens the .blend from disk, so
unsaved changes would render the previous state without warning. Its
payload is pinned by a contract test, since add-on and server only ever
meet over JSON.

Worker 1.5.0. Adds migration 20260815000000_blender_render_jobs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-15 18:53:19 +02:00
twotalesanimation bada122f42 feat(pipeline): per-project AE templates, and a workspace that fits any show
Deploy / deploy (push) Successful in 7m4s
Initialise Workspace built UNG_101..UNG_117 from a hardcoded range and
imported one hardcoded AEP, and fourteen findComp calls named UNG's comps
literally. None of it worked for a second show.

Comp names now follow a convention derived from the show id —
{showId}_VFX_OVERLAY, {showId}_EXPORT_TEMPLATE, _SHOW LUT — which
reproduces UNG's existing names exactly, so nothing changes for the show
it was written for. A project whose template departs from the pattern can
override any of the three.

Paths cannot be derived: UNG's show id is UNG while its folder is
UNGO_VFX. Those live on Project.pipelineConfig and are edited under
Project → Settings → Pipeline. They are resolved server-side and handed
to the panel with the project list, and read by buildPreviewManifest for
the headless build, so the panel and the farm cannot disagree about which
template — or which show LUT — a shot was built with. That mattered more
than the folder names: a preview rendered through another show's LUT is
quietly the wrong colour rather than obviously broken.

Episode folders come from the project's episode list, falling back to the
folders under its footage root for a show whose episodes are not entered
yet.

Panel 2.5.0. Adds migration 20260814010000_project_pipeline_config.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-15 08:24:40 +02:00
twotalesanimation 483db65eb3 fix(connector): build shots at the shot's frame rate, not a hardcoded 24
Deploy / deploy (push) Successful in 6m23s
Shot.fps existed, the lookup API returned it, and one button honoured it
— Set Start Timecode — while the shot builder ignored it entirely. Comps
were created at 24 and every plate conformed to 24.

DH2 is a 25 fps show. Its plates carry framesPerSecond 25/1, so comps
built at 24 conform every plate to the wrong speed and compute every
frame-from-timecode sum against the wrong rate.

The builder now takes the rate from the shot record, which is the show's
delivery rate and therefore the authority; a plate's own rate is whatever
happens to be on disk. Import Renders follows the comp it imports into,
and Import EXR follows the shot.

Validation gains plate_fps, comparing the render against the timing
plate. timecode_fps only compares the render to its manifest and both
come from the comp, so a shot built at the wrong rate agrees with itself
and passes; the plate is the independent witness. It is a WARN, never a
FAIL: sampling DH2 found one plate at 50 fps against a 25 fps show, a
deliberate over-crank, so a whole-number multiple is reported as exactly
that and anything else as a probable rate mistake.

Note this does not fix the data: all 175 DH2 shots still carry fps 24
from the create-time default and need correcting before their comps are
rebuilt.

Panel 2.4.0, worker 1.4.0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-14 13:10:10 +02:00
twotalesanimation 41ee826700 fix(pipeline): keep an urgent export urgent through a validation override
Deploy / deploy (push) Successful in 6m11s
Overriding a failed validation queued the preview at priority 50
regardless. It took its rank from the export's last PREVIEW_ONLY job —
but validation runs before the preview stage, so a VALIDATION_FAILED
export has never had one, and the missing row fell through to a
hardcoded normal priority. An urgent shot lost its urgency at exactly
the moment someone was standing over it waiting.

Every preview now derives its rank from the export's AE_RENDER priority
rather than from a previous preview. That fixes the missing-row case and
also removes a slow drift: a preview's priority is already boosted, so
re-deriving from it moved an export a step up the queue on every retry.

createPreviewJob takes the render priority and the attempt number, so the
first build, a retry, a regenerate and an override all rank identically.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-14 12:19:19 +02:00
twotalesanimation c9b0f25bb2 fix(pipeline): let a finished render's preview outrank pending renders
Deploy / deploy (push) Successful in 6m11s
Urgent already propagated — a preview inherits its render's priority, so
an urgent export stays ahead all the way to QC. The complaint was the
other half: at equal priority previews always ran last.

The queue orders by priority then age, and a preview job is only created
when its render finishes, so it is always newer than the renders queued
beside it. Ten shots ran as ten renders and then ten previews, and
nothing was reviewable until the end of the batch.

render.previewPriorityBoost (default 1) subtracts from the render's
priority when the preview is created, so a shot finishes end to end
before the next render starts. The boost never promotes a job across the
urgent threshold: a normal preview must not inherit permission to run
outside the render window that its render never had. Set it to 0 for the
old behaviour.

Worth knowing separately: a worker will not claim preview jobs at all
while an artist has AE open on that machine, which during the day is the
larger reason previews appear to wait.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-14 12:11:49 +02:00
twotalesanimation 4642ecb11f feat(pipeline): skip the preview build and inherit the previous one
Deploy / deploy (push) Successful in 7m8s
Some exports are deliberately framed differently from their review —
unscaled or un-punched-in EXRs — and a preview rebuilt from those frames
would be the wrong picture. The previous export's MOV is the correct one.

skipPreview renders the EXRs and goes straight to READY_FOR_QC. Available
at Queue Export (a "No preview" checkbox in the panel, E1 field) and as an
option when overriding a validation failure.

The inheritance is as important as the skip: deliveryMovPath, the review
MP4, the thumbnail and the Version are carried over from the newest
earlier export of that shot which has them. Without it the delivery
builder — which takes its MOV from deliveryMovPath — would package EXRs
with no MOV at all. Where there is nothing to inherit, the export still
reaches QC and the timeline says it has no review media.

QC is untouched by any of this: a skipped preview still needs a human
pass before the export can be delivered.

Panel 2.3.0. Adds migration 20260814000000_export_skip_preview.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-14 11:28:14 +02:00
twotalesanimation e66e4868ea feat(validation): manual override for a failed run
Deploy / deploy (push) Successful in 6m13s
Checks fail on renders that are genuinely fine — a plate the engine
cannot reach, an expectation that does not apply to this shot — and a
VALIDATION_FAILED export was a dead end, blocking delivery on a shot a
human can see is correct.

Override validation on the Export detail page resumes the pipeline where
a pass would have handed off: preview, then READY_FOR_QC. It never skips
QC and never delivers directly, so the frames are still looked at — the
override waives the automated check, not the human one.

The failed ValidationResult rows are left untouched rather than rewritten,
so the QC queue keeps listing them as warnings and whoever QCs the shot
sees what was waved through. The reason is required and recorded with the
checks it covered on the export's timeline, and the validation panel
keeps an "overridden" badge long after the event scrolls away.

Restricted to admin/producer/supervisor: waving a failed check through is
a supervisor's call.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-14 11:19:45 +02:00
twotalesanimation af810258e6 perf(delivery): stop re-reading hard links to verify them
Deploy / deploy (push) Successful in 6m25s
A 25-shot episode took about an hour to package when the linking itself
is instant. All of it was verification: every delivered file was read
back and hashed, and at ~100 MB/s over SMB one 2.8 GB shot costs 30 s.

Re-hashing a hard link cannot disagree with validation. The entry is a
second name for the same data, so it re-reads the exact bytes that were
already hashed — half an hour per episode to prove something that cannot
be false. Verification is now proportional to what was actually done:
copies are read back in full, links carry over the validation-time digest.

Linking has one gap hashing covered incidentally: a source changed after
it passed QC, which a link would carry faithfully. Source timestamps are
now checked against the export's validation time, which costs a stat per
file rather than a full read.

"verifyMode": "always-hash" restores unconditional read-back for a
production that requires it.

Worker 1.3.0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-14 09:29:04 +02:00
twotalesanimation 991abe072c fix(validation): anchor the timecode check on a delivered plate
Deploy / deploy (push) Successful in 6m12s
UNG_110_030_010 v002 failed with a 461614-frame offset on a render whose
timecode was correct. Two causes, both in how the plate reference was
recorded.

The comp held three same-length elements and the timing plate was picked
by duration alone, so a PRERENDER won on layer order. Using a pre-render
as the timecode reference is circular anyway: it was rendered from this
comp, so it can only ever agree with it — including when both are wrong.
Only footage under the Footage Root is now eligible; among those, longest
still wins.

The offset itself came from the plate's frameStart. AE writes renders as
"..._PRERENDER_01001.exr" while delivered plates use "....01001.exr", and
the parser only handled the dot form, so the number fell back to the
comp's frame range — 462615 against a render numbered from 1001. Both
separators now parse, and an unparseable name omits the field rather than
filling it with a number from the wrong coordinate system.

Verified against the real manifest: the BG01 plate is now chosen over
both pre-renders, and all three filenames parse to 1001.

Panel 2.2.1, worker 1.2.1.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-14 08:56:18 +02:00
twotalesanimation 1163bd6455 feat(preview): burn the production name into the slate and the overlay
Deploy / deploy (push) Successful in 5m57s
The preview manifest now carries the show name, taken from the project's
name rather than its code — a slate is read by a human, so "Ungovernable"
beats "UNG_S1".

Both the worker's headless build and the panel's own preview set it, so a
farm-generated preview and an artist-built one still match. The panel
writes it whenever it touches an overlay, not only when building a
preview, so existing comps pick it up on the next Add Overlay.

The slate's other properties are title case ("Date", "Scene") while the
overlay's are upper ("DATE", "SHOT NAME"), so both spellings of SHOW are
attempted; a template exposing neither reports its actual property names
as a build warning rather than failing silently, matching how the VFX
Scope and Submission Note fields already behave.

Panel 2.2.0, worker 1.2.0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-14 01:42:37 +02:00
twotalesanimation 37f73a2bd7 fix(validation): separate output file numbering from comp frame numbers
Deploy / deploy (push) Successful in 6m13s
A render carries frame numbers in two unrelated systems. The comp is
anchored to its plate's timecode, so its timeline runs 1247792-1247896;
the output module names files from 1001. Validation compared the file
numbers against the comp range and failed every correctly-rendered shot
by ~1.2 million frames — first_frame, last_frame and missing_frames all
reporting a defect that was not there.

The manifest now carries outputFrameStart (the output module's starting
number, house convention 1001) alongside the comp range. Count and
contiguity are measured on the output numbering; first/last compare
against outputFrameStart and are SKIPPED on older manifests, where the
count and gap checks still hold on their own.

The same conflation broke the API timecode fallback: it anchored on the
comp's frameStart while the render's first frame is 1001, producing a
+1246791 frame "offset". Shot.timecodeStart is the edit in-point and the
plate carries handleFrames of head handle, so the reference is the API
value less handles, anchored on the render's own first frame.

Verified on the shot that reported it: UNG_107_051_010 v004 now passes
count, contiguity and a plate-anchored timecode match. Regression tests
cover both coordinate systems, including that a genuine +8 handle offset
still fails.

Panel 2.1.2.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 23:26:39 +02:00
twotalesanimation 4929db45a2 fix(connector): try every matching path mapping, not just the first
Deploy / deploy (push) Successful in 6m5s
A studio whose render output root changed carries both conventions in the
database permanently — changing render.outputRoot only affects new
exports, so old rows keep the path they were queued with. On UNG that is
//SAN/renders/{projectCode}/... for older exports and //SAN/{showId}/...
for current ones, living side by side under one Export Root.

applyPathMappings returned only the first prefix match, so one rewrite
had to serve both and could not. It now returns every match and
resolveServerPath tests each for existence, which is what the candidate
ordering was there for.

Verified against the live drive: with "//SAN/=V:/_EXPORTS/UNG/" the
legacy export resolves via the mapping and current ones via the Export
Root re-base; with both rewrites mapped, all three resolve directly.

Panel 2.1.1.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 19:20:14 +02:00
twotalesanimation c4a85bac2b docs: delivery packages workflow guide
Deploy / deploy (push) Successful in 5m59s
RenderPipeline2.md §11 carries the design and the normative rules, but
there was nothing telling someone how to actually build and ship a
package. DELIVERY_WORKFLOW.md covers the path from "QC passed" to "client
has it": eligibility, building, what lands on disk, verification and its
failure modes, marking delivered, and configuration.

It explains hard links properly — a second name for the same data, not a
copy or a shortcut — since that is the part most likely to worry someone
looking at a package that appeared instantly and used no disk.

Also documents the DELIVERY_BUILD stage in the worker README, which
previously mentioned deliveries only in passing, and adds a
documentation index to the root README.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:47:54 +02:00
twotalesanimation f4a2fee492 fix(connector): resolve server render paths on the workstation
Deploy / deploy (push) Successful in 6m4s
QC's Open Render used the server's outputDir verbatim. The server
addresses renders from its own root (render.outputRoot, e.g. //SAN),
which the render worker translates via its own pathMappings because it
runs as a service account — the panel had no equivalent, so Open Render
failed on any machine that could not resolve that root.

Resolution now tries, in order: an optional Path Mappings setting, the
server path as given, then re-basing on Export Root. The last one is why
this usually needs no configuration at all: both sides lay renders out as
{root}/{showId}/{episode}/{shot}/{version}, so the tail can simply be
re-attached. A failure names every candidate it tried rather than
reporting one path that was never going to work.

Diagnostics gained the same check against a real folder from the QC
queue, since "Export Root exists" and "this machine can reach a render
the server wrote" are different questions and only the second one breaks
QC.

Verified against the live V: drive: a //SAN path, a backslash variant and
an explicitly-mapped path all resolve to the real render folder, while an
unknown root and a different show correctly resolve to nothing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:39:03 +02:00
twotalesanimation ce7b73dd38 chore(worker): stop tracking published packages
Deploy / deploy (push) Successful in 7m8s
The 29 MB VFXReviewWorker_<date>.zip was swept into the previous commit
by the .gitignore change that started tracking worker source. It is a
build artifact: reproducible from any commit via scripts/publish.ps1,
and the version stamp (1.1.0+a4f8226) already traces a deployed exe back
to its source, so the zip carries no information the repo lacks — while
costing ~29 MB of permanent history per publish.

Untracked and ignored. The file stays on disk for copying to
workstations; only git stops following it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:10:08 +02:00
twotalesanimation ca9a004d56 fix(worker): package the preview script reliably on an incremental publish
The .NET 10 SDK cleans the publish directory, and an incremental build
then skips copying content into it — so a second publish produced a
package with the exe but no scripts\vfxr_build_preview.jsx. The exe loads
that script from its own folder at runtime, so the package would have
installed cleanly and failed every preview job.

The Content item now sets CopyToPublishDirectory explicitly
(CopyToOutputDirectory only governs the build folder), and publish.ps1
copies the script itself rather than trusting the SDK, keeping the
existing verification as the backstop that caught this.

Verified by publishing twice in a row: the incremental second run, which
previously failed, now produces a complete package and zip.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 15:19:47 +02:00
twotalesanimation a4f8226f3f feat(pipeline): report deployed tool versions from the tools themselves
"What is running where" was answerable only by asking someone. Each tool
now reports its own version on startup into a ToolVersion registry, shown
on Pipeline → Machines.

The worker's version moves out of config.json and into the assembly:
a hand-maintained string on each machine is exactly the thing that goes
stale, and a machine reporting a version it is not running is worse than
no version at all. publish.ps1 stamps the git SHA via SourceRevisionId,
so a deployed exe traces back to a commit (1.1.0+feb1c7b).

The panel gains PANEL_VERSION, shown in its title and every diagnostics
report, and pings on load.

Staleness is derived rather than declared: the newest version seen for a
tool is the benchmark, so updating one machine is what flags the rest.
There is no expected-version list to keep in sync — which would have been
one more thing to forget.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 15:13:44 +02:00
twotalesanimation feb1c7b3e9 feat(render-pipeline): validation, QC and delivery builder
Completes RenderPipeline2 phases 3-5. Additive throughout: with
validation.enabled=false the pipeline behaves exactly as before.

Validation (§8) runs on the worker straight after a render, while it
still holds the job and the files are local. Everything is read from the
EXR header — one 64 KB read per sampled frame, no pixel decode — so the
engine needs no oiiotool. The render job deliberately stays open through
the stage, so a worker that dies there is reaped and retried instead of
stranding the export in VALIDATING.

Timecode is the primary check and is anchored on the plate, never the
API: measured on the live show, Shot.timecodeStart is the editorial
in-point and sits one handle-length (8f) ahead of the plate, so checking
against it would pass the defective exports and fail the correct ones.
Reference precedence is manifest timing plate -> plate found on disk ->
API value, and the API rank is WARN-only. The panel now resolves plate
provenance by walking the comp's own footage layers, so the worker never
guesses which element carries the comp's timing.

Verified against real studio renders via the new --validate mode: it
catches both defect classes seen in shipped work — the +8 handle offset
and frame-derived timecode (00:00:41:17 = frame 1001 at 24fps).

QC (§10) is one service behind two front doors, API-key for the panel
and session for the web. PASS means ready to upload and nothing else;
FAIL sets the comp task to CHANGES. The panel gains a QC section that
imports the real EXR sequence at full res rather than the H.264.

Delivery (§11) rides the existing queue as a DELIVERY_BUILD job: hard
links with a copy fallback, verification by re-hashing delivered bytes
against the validation-time digest, manifest.json and the CSV report.
fsutil hardlink list is unavailable over SMB, so link identity is never
queried — reading the bytes back covers links and copies alike.

Also fixes ApiClient.ProgressAsync throwing on transport failure, which
would have aborted work in flight during a brief server outage; progress
reporting is best-effort by contract.

Removes the stale RenderWorker/ rule from the root .gitignore. The
worker's source is tracked like the rest of the repo and its own
.gitignore already covers bin/, obj/ and publish/; the rule silently
excluded new files while the existing 20 stayed tracked.

Not yet applied: migration 20260813000000 was hand-written because the
dev database was unavailable — run prisma migrate deploy and verify
before relying on it. None of this has run against a live server.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 13:49:51 +02:00
twotalesanimation 7f2f5e1005 feat(connector): resolve footage per project type, anchor parsing on showId
Build Shot only ever worked on UNG. Two assumptions were baked in: that a shot's
plates sit flat in a folder named after the episode, and that a shot code is
three letters followed by three 3-digit tokens. DH2_VFX breaks both -- it groups
a shot's plates under a {shotCode}/ folder, has no episode level, and its showId
contains a digit and an underscore.

- findSequenceFolders prefers {group}/{shotCode}/ and falls back to UNG's flat
  {group}/{shotCode}_* scan, so both layouts work with no migration -- moving
  delivered footage would break the links in every AE project pointing at it. An
  existing-but-empty shot folder returns nothing rather than falling through, so
  stray plate folders sitting beside a shot cannot be read as its footage.
  Underscore-prefixed folders are never shots or plates.
- getFootageGroupFolder replaces getEpisodeRootFolder: the {showId}_{episode}
  folder for episodic shows, the show root otherwise. A scene filters the shot
  list, it is not a directory -- which is why Build Shot on DH2 was looking in
  V:/_FOOTAGE/DH2/027.
- Shot codes are now parsed by stripping the known showId prefix
  ({showId}_{episode}_{scene}_{shot} for episodic, {showId}_{scene}_{shot} for
  standard) rather than matching /[A-Z]{3}_.../ or counting underscores.
  extractShotCode keeps the old pattern as a fallback so a comp from a different
  show than the selected one still reads. Same anchoring in deriveEpisodeCode
  (no more hardcoded "UNG_"), deriveEpisodeAPIValue, isEpisodeCode and the
  getShotExportDir episode fallback.
- Two positional cuts of the same class, found on the way: the DELIVERY path and
  Pull Picture Lock's episode-prefix match both used shotCode.substring(0, 7).
  Both now go through getEpisodePrefix(). Output is identical for UNG and DH2
  (DH2_VFX happens to be 7 characters); the one behaviour change is that
  standard shows no longer get a constant group level under DELIVERY/, and DH2
  has no delivery history to move.

Verified against the live V:/_FOOTAGE tree by running the real functions under a
Folder stub: UNG_102_019_010 resolves its BG01/FG01 plates via the flat scan, and
DH2_VFX_027_010 and DH2_VFX_066_380 resolve theirs via the grouped layout. Not
yet exercised in After Effects.

Initialise Workspace is untouched and still hardcoded to UNG -- next.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 18:15:42 +02:00
twotalesanimation 0ce41123c5 feat(render-pipeline): regenerate previews without re-rendering EXRs
Deploy / deploy (push) Successful in 5m58s
A slate or burn-in mistake is usually caught after a preview has already
succeeded, and there was no way back: retryPreview required PREVIEW_FAILED, and
READY_FOR_QC only led on to QC_FAILED/READY_FOR_DELIVERY/SUPERSEDED. The only
recourse was a whole new export, re-rendering every EXR and burning a version
number to fix a typo.

- transitions: READY_FOR_QC and QC_FAILED can now go back to GENERATING_PREVIEW.
- regeneratePreview() rebuilds the manifest from scratch rather than patching
  anything, so shot code, episode/scene, frame count, slate date and burn-ins
  are all re-derived exactly as on a first-time preview. Validated EXRs are
  reused and the version number is untouched -- this re-delivers the same
  version, it does not make a new one.
- vfxScope and submissionNote are frozen onto the Export at submission time, so
  regenerating refreshes that snapshot from the shot's slate fields (explicit
  override wins, same precedence as createExport). Slate text edited on the web
  app's Slate tab is therefore picked up.
- finalizePreview replaces the media on the export's existing Version instead of
  stacking a second row, so the version number stays put and reviewer notes and
  annotations survive the reslate. First-time previews are unaffected.
- POST /api/ext/exports/{id}/regenerate-preview exposes it to the panel.
- Panel: Regenerate Previews button, gated on the same statuses as the server,
  with a confirm covering what is and is not reused.

Also fixes the slate description source: the Slate tab authors
shot.slateDescription (falling back to shot.description) but the preview
manifest only ever read shot.description, so edits made there never reached the
rendered slate.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 11:02:23 +02:00
twotalesanimation 783e82eaf5 feat(render-pipeline): sync task title to preview version, fill slate ShotName
finalizePreview now retitles the export's task so its version suffix matches the
preview that was just uploaded (UNG_102_019_010_cmp_TT_v004 -> _v005), which is
the rename the manual batch upload already does on rename-and-upload. The new
nextTaskTitle helper mirrors nextExrOutputBase so the task title, EXR base and
preview filename all derive the suffix the same way. It uses the export's
versionString rather than versionNumber, since the DB number is bumped to stay
monotonic per task while the filename follows the shot's shotVersion.

The rename only fires when a Version was actually created, runs in the same
transaction, and is recorded in the ExportEvent note; the finalize response now
returns the task id, title and whether it changed. Task status is deliberately
untouched (pipeline renders must not resurface in the review flow, S10.0).

The headless preview build was addressing the slate's identity fields by index
only, so ShotName was never filled on the farm. setSlateIdentity writes both the
named property and the index -- the name-with-index-fallback pattern the panel
already uses for VersionName -- and warns with the template's actual property
names when neither resolves, instead of failing silently.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 10:30:47 +02:00
twotalesanimation c4abda2d63 feat(connector): per-shot/version export folders, scene filter
Panel export paths now mirror the server's layout
({exportRoot}/{showId}/[{episode} if episodic]/{shotCode}/{version}) via a new
getShotExportDir helper, so farm and local renders land in the same folder.
Folder creation moves into the per-shot loop so one unwritable path no longer
aborts the whole queue.

Also adds an optional `scene` query param to the ext shots endpoint.
2026-08-12 10:29:51 +02:00
twotalesanimation 7dcb9303e5 updated export paths
Deploy / deploy (push) Successful in 6m32s
2026-08-07 12:07:16 +02:00
twotalesanimation 7caf41e17c Slates
Deploy / deploy (push) Successful in 6m17s
2026-08-07 07:34:10 +02:00
twotalesanimation 2f2e286adb Merge develop: render queue feature
Deploy / deploy (push) Failing after 18m31s
2026-08-06 15:56:37 +02:00
100 changed files with 11333 additions and 537 deletions
+2 -2
View File
@@ -32,5 +32,5 @@ yarn-error.log*
*.tsbuildinfo
next-env.d.ts
# Local tooling
RenderWorker/
# RenderWorker build output is covered by RenderWorker/.gitignore (bin/, obj/,
# publish/) — the worker's source is tracked like the rest of the repo.
+96
View File
@@ -0,0 +1,96 @@
# VFXReview — Blender Submit
A Blender add-on that queues the open `.blend` on the studio render farm instead
of rendering it locally. Ctrl+F12, but on the farm.
---
## What a Blender job is (and is not)
Deliberately the simplest thing in the pipeline: **a queue entry and nothing
more**. It has no Export, takes no shot version, and is never validated, QC'd or
delivered. The `.blend` is expected to be ready to render — output path, format
and frame range already set — and the farm just runs it.
That is the whole difference from an After Effects export, which is a shot
submission and carries the full lifecycle behind it.
---
## Install
1. **Edit → Preferences → Add-ons → Install…** and pick `vfxreview_submit.py`.
2. Enable **Render: VFXReview — Submit Render**.
3. Expand its preferences and set:
| Setting | Value |
|---|---|
| **Server URL** | `https://review.twotalesvfx.com` |
| **API Key** | matches `API_SECRET_KEY` on the server (same key the AE panel uses) |
| **Artist Email** | recorded against the job so the queue shows who submitted it |
The panel appears under **Properties → Output → VFXReview**.
---
## Submitting
1. **Refresh Projects** (the circular arrow) and pick the project.
2. Optionally set a **Label** — defaults to the `.blend` filename, and is what
the render queue shows, since there is no shot code.
3. **Urgent** makes the job claimable outside the render window, ahead of normal
work.
4. **Submit to Render Farm**.
The panel shows the frame range, engine and output path it will send, read from
the file as saved. Nothing is changed on submission.
**The file must be saved first.** The farm opens the `.blend` from disk, so
unsaved changes would render the previous state without warning — the add-on
refuses to submit a dirty file rather than let that happen.
Track the job on the web app under **Pipeline → Blender renders**: live
progress, current frame, ETA and the machine running it, with cancel and requeue.
---
## Which machines can render it
Only workers with `blenderPath` set in their `config.json` and the executable
present. The worker reports Blender at registration and the server hands
`BLENDER_RENDER` jobs only to machines that have it — a machine without Blender
can never claim work it could only fail.
Verify on a worker with:
```powershell
.\VFXReviewWorker.exe --check
```
Blender is listed as optional there: a machine without it stays perfectly valid
for After Effects work.
---
## Notes
**Paths must resolve on the render machine.** The `.blend` path and its output
path are submitted as the artist sees them; the worker applies its own
`pathMappings` before opening the file. A path on a drive letter the render
account cannot see is the most common reason a job fails immediately.
**Renders as saved.** The add-on sends the scene's own settings. The manifest
supports overrides (samples, resolution %, device, engine) for future use, but
nothing in the UI sets them today — one place for render settings is the point.
**Exit code 0 with no frames is treated as a failure.** Blender exits cleanly
when a frame range is empty or an output path is unwritable, so the worker
checks that frames were actually saved before reporting success.
**The add-on sends its own User-Agent** (`VFXReviewBlender/<version>`). Python's
`urllib` otherwise identifies itself as `Python-urllib/3.x`, which Cloudflare
blocks outright as a scripted signature — a 403 with error 1010 before the
request ever reaches the server. Verified against the live zone: `Python-urllib`
gets 403, the add-on's own agent gets 200. If a future Cloudflare rule blocks it
anyway, the add-on says so in plain language rather than showing the raw JSON,
and the fix is a WAF allow rule on the agent or on `/api/ext/*`.
+289
View File
@@ -0,0 +1,289 @@
bl_info = {
"name": "VFXReview — Submit Render",
"author": "Two Tales",
"version": (1, 0, 2),
"blender": (3, 6, 0),
"location": "Properties > Output > VFXReview",
"description": "Queue this .blend on the studio render farm instead of rendering locally",
"category": "Render",
}
import json
import os
import urllib.error
import urllib.request
import bpy
from bpy.props import BoolProperty, EnumProperty, StringProperty
from bpy.types import AddonPreferences, Operator, Panel
# ── Preferences (per artist machine, like the AE panel's Settings) ────────────
class VFXRPreferences(AddonPreferences):
bl_idname = __name__
server_url: StringProperty(
name="Server URL",
default="https://review.twotalesvfx.com",
)
api_key: StringProperty(
name="API Key",
subtype="PASSWORD",
description="Matches API_SECRET_KEY on the server",
)
artist_email: StringProperty(
name="Artist Email",
description="Recorded against the job so the queue shows who submitted it",
)
def draw(self, context):
col = self.layout.column()
col.prop(self, "server_url")
col.prop(self, "api_key")
col.prop(self, "artist_email")
def prefs():
return bpy.context.preferences.addons[__name__].preferences
ADDON_VERSION = ".".join(str(n) for n in bl_info["version"])
USER_AGENT = "VFXReviewBlender/%s (Blender %s)" % (ADDON_VERSION, bpy.app.version_string)
# ── API ───────────────────────────────────────────────────────────────────────
def api_request(path, payload=None, method="GET"):
"""Minimal JSON client. urllib keeps the add-on dependency-free."""
p = prefs()
if not p.server_url or not p.api_key:
raise RuntimeError("Set the server URL and API key in Add-on Preferences")
url = p.server_url.rstrip("/") + path
data = json.dumps(payload).encode("utf-8") if payload is not None else None
req = urllib.request.Request(url, data=data, method=method)
req.add_header("Authorization", "Bearer " + p.api_key)
req.add_header("Accept", "application/json")
# urllib identifies itself as "Python-urllib/3.x" by default, which
# Cloudflare blocks outright as a scripted signature (error 1010). Sending a
# real name for this tool is also the honest thing: the studio's logs should
# say what is calling them.
req.add_header("User-Agent", USER_AGENT)
if data:
req.add_header("Content-Type", "application/json")
try:
with urllib.request.urlopen(req, timeout=30) as res:
return json.loads(res.read().decode("utf-8"))
except urllib.error.HTTPError as e:
body = e.read().decode("utf-8", "replace")
try:
parsed = json.loads(body)
except Exception:
parsed = {}
# A Cloudflare block is not a pipeline error and reads nothing like one,
# so say what it actually is rather than showing the artist a wall of
# JSON about browser signatures.
if parsed.get("cloudflare_error") or parsed.get("error_code") == 1010:
raise RuntimeError(
"Blocked by Cloudflare before reaching the server (error %s). "
"The studio's firewall needs to allow this add-on — ask the pipeline TD."
% parsed.get("error_code", e.code)
)
message = parsed.get("error", body) if parsed else body
raise RuntimeError("Server said %s: %s" % (e.code, message))
except urllib.error.URLError as e:
raise RuntimeError("Could not reach %s (%s)" % (url, e.reason))
_project_cache = []
# Blender does not copy the strings an EnumProperty callback returns — Python
# must keep a reference to them or the UI renders freed memory, which shows up
# as garbled labels rather than as a crash. So the items are built once when the
# project list changes and held here; the callback only ever returns this list.
_enum_items = [("", "Refresh projects...", "")]
def rebuild_enum_items():
global _enum_items
if _project_cache:
_enum_items = [
(p["code"], "%s - %s" % (p["code"], p["name"]), "")
for p in _project_cache
]
else:
_enum_items = [("", "Refresh projects...", "")]
return _enum_items
def project_items(self, context):
"""Called on every redraw, so it does no work and allocates nothing."""
return _enum_items
# ── Scene → job ───────────────────────────────────────────────────────────────
def scene_summary(scene):
"""
Everything the farm needs, read from the file as saved. The .blend is
expected to be ready to render, so nothing here changes settings — it only
reports them.
"""
return {
"blendFile": bpy.data.filepath.replace("\\", "/"),
"scene": scene.name,
"frameStart": scene.frame_start,
"frameEnd": scene.frame_end,
"outputPath": bpy.path.abspath(scene.render.filepath).replace("\\", "/"),
"engine": scene.render.engine,
"blenderVersion": bpy.app.version_string,
}
class VFXR_OT_refresh_projects(Operator):
bl_idname = "vfxreview.refresh_projects"
bl_label = "Refresh Projects"
bl_description = "Load the project list from the server"
def execute(self, context):
global _project_cache
try:
data = api_request("/api/ext/projects")
except RuntimeError as err:
self.report({"ERROR"}, str(err))
return {"CANCELLED"}
_project_cache = data.get("projects", [])
rebuild_enum_items()
self.report({"INFO"}, "%d project(s) loaded" % len(_project_cache))
return {"FINISHED"}
class VFXR_OT_submit(Operator):
bl_idname = "vfxreview.submit"
bl_label = "Submit to Render Farm"
bl_description = "Queue this .blend on the farm instead of rendering locally"
def execute(self, context):
scene = context.scene
settings = scene.vfxreview
if not bpy.data.filepath:
self.report({"ERROR"}, "Save the .blend first — the farm opens it from disk")
return {"CANCELLED"}
if bpy.data.is_dirty:
# Unsaved changes would render the previous state without warning.
self.report({"ERROR"}, "Unsaved changes — save the file before submitting")
return {"CANCELLED"}
if not settings.project_code:
self.report({"ERROR"}, "Pick a project (Refresh Projects first)")
return {"CANCELLED"}
manifest = scene_summary(scene)
if manifest["frameEnd"] < manifest["frameStart"]:
self.report({"ERROR"}, "Frame end is before frame start")
return {"CANCELLED"}
label = settings.label.strip() or os.path.splitext(os.path.basename(bpy.data.filepath))[0]
try:
result = api_request(
"/api/ext/render/blender",
{
"projectCode": settings.project_code,
"label": label,
"manifest": manifest,
"submittedByEmail": prefs().artist_email or None,
"urgent": settings.urgent,
},
method="POST",
)
except RuntimeError as err:
self.report({"ERROR"}, str(err))
return {"CANCELLED"}
job = result.get("job", {})
self.report(
{"INFO"},
"Queued '%s' — %d frames%s" % (label, job.get("frames", 0), " (urgent)" if settings.urgent else ""),
)
return {"FINISHED"}
class VFXRSceneSettings(bpy.types.PropertyGroup):
project_code: EnumProperty(name="Project", items=project_items)
label: StringProperty(
name="Label",
description="Shown in the render queue. Defaults to the .blend filename",
)
urgent: BoolProperty(
name="Urgent",
description="Claimable outside the render window, ahead of normal jobs",
default=False,
)
# ── UI ────────────────────────────────────────────────────────────────────────
class VFXR_PT_submit(Panel):
bl_label = "VFXReview"
bl_space_type = "PROPERTIES"
bl_region_type = "WINDOW"
bl_context = "output"
def draw(self, context):
scene = context.scene
settings = scene.vfxreview
col = self.layout.column()
row = col.row(align=True)
row.prop(settings, "project_code", text="")
row.operator("vfxreview.refresh_projects", text="", icon="FILE_REFRESH")
col.prop(settings, "label")
col.prop(settings, "urgent")
box = col.box()
box.label(text="Renders as saved:", icon="INFO")
box.label(text="Frames %d–%d (%d)" % (
scene.frame_start, scene.frame_end, scene.frame_end - scene.frame_start + 1))
box.label(text="Engine: %s" % scene.render.engine)
output = bpy.path.abspath(scene.render.filepath)
box.label(text="Output: %s" % (output[-48:] if len(output) > 48 else output))
if bpy.data.is_dirty or not bpy.data.filepath:
warn = col.row()
warn.alert = True
warn.label(text="Save the file before submitting", icon="ERROR")
col.separator()
col.operator("vfxreview.submit", icon="RENDER_ANIMATION")
classes = (
VFXRPreferences,
VFXRSceneSettings,
VFXR_OT_refresh_projects,
VFXR_OT_submit,
VFXR_PT_submit,
)
def register():
for cls in classes:
bpy.utils.register_class(cls)
bpy.types.Scene.vfxreview = bpy.props.PointerProperty(type=VFXRSceneSettings)
def unregister():
del bpy.types.Scene.vfxreview
for cls in reversed(classes):
bpy.utils.unregister_class(cls)
if __name__ == "__main__":
register()
+238
View File
@@ -0,0 +1,238 @@
# Delivery Packages — Workflow Guide
How a finished shot becomes a dated folder ready to upload to the client.
This is the operational guide. The design rationale and normative rules live in
[RenderPipeline2.md](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`.
```json
{
"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.
+30
View File
@@ -24,6 +24,30 @@ X-Api-Key: <API_SECRET_KEY>
| `POST` | `/api/ext/shots` | Create a new shot |
| `PATCH` | `/api/ext/shots/{shotId}` | Update shot fields (e.g. increment version) |
### Render pipeline (RenderPipeline2)
| # | Method | Path | Caller | Description |
|---|--------|------|--------|-------------|
| E1 | `POST` | `/api/ext/exports` | panel | Queue Export — creates Export + RenderJob |
| E2 | `GET` | `/api/ext/exports/latest` | panel | Latest export + live status for the panel header |
| E3 | `GET` | `/api/ext/exports/{exportId}` | panel/worker | Export detail incl. validations and QC |
| E4 | `POST` | `/api/ext/exports/{exportId}/qc` | panel | QC Pass / QC Fail |
| E5 | `GET` | `/api/ext/qc/queue` | panel | Exports in READY_FOR_QC |
| E6 | `POST` | `/api/ext/workers/register` | worker | Register machine, receive tuning |
| E7 | `POST` | `/api/ext/workers/{machineId}/heartbeat` | worker | Heartbeat + cancel channel |
| E8 | `POST` | `/api/ext/render/jobs/claim` | worker | Atomically claim the next job |
| E9 | `PATCH` | `/api/ext/render/jobs/{jobId}/progress` | worker | Progress/ETA; renews the lease |
| E10 | `POST` | `/api/ext/render/jobs/{jobId}/fail` | worker | Report failure |
| E11 | `POST` | `/api/ext/render/jobs/{jobId}/complete-render` | worker | aerender finished → VALIDATING |
| E12 | `POST` | `/api/ext/render/jobs/{jobId}/validation` | worker | Report all validation results |
| E13 | `POST` | `/api/ext/render/jobs/{jobId}/finalize` | worker | Preview artifacts done → READY_FOR_QC |
| E14 | `POST` | `/api/ext/exports/{exportId}/retry` | panel | Retry a failed export |
| E20 | `POST` | `/api/ext/render/jobs/{jobId}/artifact-presign` | worker | Presigned upload URL |
| — | `POST` | `/api/ext/render/jobs/{jobId}/delivery` | worker | Report a DELIVERY_BUILD result |
Session-authenticated twins for the web UI live under `/api/render/*` and
`/api/deliveries/*` — same service layer, no API key.
---
## Shot Status Values
@@ -513,3 +537,9 @@ For reference, the endpoints called by `VFXReviewConnector.jsx`:
| Populate Shot dropdown | `GET /api/ext/projects/{PROJECT_CODE}/shots?episode={value}` |
| All shot operations (overlay, queue, preview, delivery) | `GET /api/ext/shots/lookup?shotCode={code}&projectCode={PROJECT_CODE}` |
| Increment Shot Version | `PATCH /api/ext/shots/{shot.id}` with `{ "shotVersion": "v00X" }` |
| Queue Export | `POST /api/ext/exports` (E1) |
| Refresh Status / poll | `GET /api/ext/exports/latest` (E2) |
| Retry Export | `POST /api/ext/exports/{id}/retry` (E14) |
| Regenerate Previews | `POST /api/ext/exports/{id}/regenerate-preview` |
| Load QC Queue | `GET /api/ext/qc/queue?projectCode={PROJECT_CODE}` (E5) |
| QC Pass / QC Fail | `POST /api/ext/exports/{id}/qc` (E4) |
+14
View File
@@ -166,6 +166,20 @@ prisma/ — schema.prisma, seed.ts
---
## Documentation
| Doc | Covers |
|---|---|
| [RenderPipeline2.md](RenderPipeline2.md) | Render pipeline specification — normative design, state machine, API contracts |
| [DELIVERY_WORKFLOW.md](DELIVERY_WORKFLOW.md) | Building and shipping delivery packages (how-to) |
| [VFXReviewConnector.md](VFXReviewConnector.md) | After Effects panel — setup, Shot Builder, QC, diagnostics |
| [RenderWorker/README.md](RenderWorker/README.md) | Render worker service — packaging, install, validation, delivery builds |
| [BlenderPanel/README.md](BlenderPanel/README.md) | Blender add-on — queueing a .blend on the farm |
| [EXT_API_REFERENCE.md](EXT_API_REFERENCE.md) | External API (`/api/ext/*`) used by the panel and workers |
| [Shot task workflow.md](Shot%20task%20workflow.md) | Shot and task lifecycle in the web app |
---
## License
MIT
+96 -3
View File
@@ -579,6 +579,19 @@ Uploaded by the AE panel on Queue Export; snapshotted verbatim into `RenderJob.m
"alpha": false,
"timecodeStart": "00:59:49:12"
},
"source": {
"startSource": "footage metadata",
"handleFrames": 8,
"timingPlate": {
"path": "V:/_FOOTAGE/UNG/UNG_106/UNG_106_010_020_BG01_TT_v001/UNG_106_010_020_BG01_TT_v001.01001.exr",
"frameStart": 1001,
"frameEnd": 1120
},
"plates": [
{ "element": "BG01_TT_v001", "path": "V:/_FOOTAGE/UNG/UNG_106/UNG_106_010_020_BG01_TT_v001/UNG_106_010_020_BG01_TT_v001.01001.exr", "frameStart": 1001, "frameEnd": 1120 },
{ "element": "FG01_TT_v001", "path": "V:/_FOOTAGE/UNG/UNG_106/UNG_106_010_020_FG01_TT_v001/UNG_106_010_020_FG01_TT_v001.01001.exr", "frameStart": 1001, "frameEnd": 1120 }
]
},
"preview": {
"template": "default",
"burnins": true
@@ -588,6 +601,15 @@ Uploaded by the AE panel on Queue Export; snapshotted verbatim into `RenderJob.m
The server validates the manifest with Zod, cross-checks `shotId`/`shotCode`/frame range against the DB, and **the server (not the panel) decides the new version number** — race-free single source of truth.
**`source` (required from manifestVersion 2)** — the plate provenance the timecode check depends on (§8.1a). The panel resolves these from the *comp's own footage layers*, not by re-deriving paths, so the manifest records what was actually comped:
- `timingPlate` — the delivered plate the render's timecode is checked against. A shot's elements routinely carry unrelated camera timecodes, so "the plate" must be named explicitly rather than guessed by the worker. **Only footage under the Footage Root qualifies**: a comp usually also holds pre-renders and CG passes of identical length, and anchoring on one of those is circular — it was rendered from this comp, so it can only ever agree with it, including when both are wrong. Among delivered plates, longest duration wins.
- `frameStart`/`frameEnd` on a plate are its **own file numbering**, and are omitted when the filename carries no frame number. They are never filled from the comp's frame range: the render's first frame is in output numbering, so a comp-frame anchor skews the comparison by the gap between the two systems.
- `startSource` — verbatim from the panel's existing start-frame resolution: `"footage metadata"` (probed from the plate, trustworthy) or `"API timecode …"` (fallback, suspect). This is known at queue time, so an export built from the API fallback can be flagged **before** it burns render hours.
- `plates[]` — every element imported into the comp, for the record and for cross-element diagnostics.
Manifests without `source` (manifestVersion 1) are still accepted; the timecode check degrades per §8.1a.
### 6.3 Endpoint summary
| # | Method | Path | Auth | Caller | Purpose |
@@ -1009,15 +1031,62 @@ Runs on the worker immediately after a successful render (Export = VALIDATING).
| `exr_type` | header: scanline vs tiled, compression | ≠ `expected.exrCompression` (WARN if compression differs but readable; FAIL if not valid EXR) |
| `alpha_channel` | channel list contains A | presence ≠ `expected.alpha` |
| `colourspace` | EXR metadata (`chromaticities` / ACES container flag / colorspace attr written by AE OCIO) | ≠ `expected.colorspace` (working space is linear ACES2065-1 per 18.1-Q4); `colorPipeline` is required per project (18.1-Q12), so SKIPPED only on legacy projects predating pipeline enablement |
| `timecode_consistency` | EXR `timeCode` attr across sampled frames | non-monotonic, or first frame ≠ `expected.timecodeStart` when set |
| `timecode_plate_match` | **primary check — see §8.1a** | render `timeCode` ≠ the timing plate's `timeCode` at the corresponding frame |
| `timecode_consistency` | EXR `timeCode` attr across sampled frames | non-monotonic (gap, repeat, or frozen value) |
| `timecode_fps` | EXR `framesPerSecond` on the render vs manifest `fps` | any disagreement |
| `plate_fps` | EXR `framesPerSecond` on the render vs **the timing plate's** | WARN on any difference — never FAIL: a whole-number multiple is a legitimate over-crank (50 fps plate on a 25 fps show), and anything else is reported as a probable rate mistake |
| `zero_byte / corrupt` | every file size > 0; oiiotool header-read on sampled frames (first, last, every Nth) | any zero-byte or unreadable file |
Full-sequence checks (count, gaps, names, sizes) run on every file; header checks sample first/middle/last + every 25th frame (fast, catches systemic issues; per-frame full decode is not worth minutes per shot — tunable via `SystemConfig: validation.sampleEvery`).
**Two coordinate systems, never conflated.** A render carries frame numbers in two unrelated systems, and every check states which one it uses:
| | Meaning | Example |
|---|---|---|
| `frameStart`/`frameEnd` | The **comp's timeline**, handed to aerender as `-s`/`-e`. A comp anchored to its plate's timecode starts at the absolute frame that timecode represents. | `1247792`–`1247896` |
| `outputFrameStart` | The number the **first output file** carries, set by the output module template. House convention: every sequence starts at 1001. | `1001` |
`file_count`, `missing_frames` and `duplicate_frames` are measured on the *output* numbering; `first_frame`/`last_frame` compare against `outputFrameStart` and are SKIPPED when a manifest predates the field, since the count and contiguity checks still hold. Comparing file numbers against comp frames fails every correctly-rendered shot by ~1.2 million frames, and the timecode reference must be anchored on the render's own first frame for the same reason.
### 8.1a Timecode: the primary check (studio decision)
Timecode is the check this engine exists for. It is validated **against the source plate**, never against the API, because the API and the plate do not agree by design.
**Measured on the live show (2026-08-13, 85 rendered sequences + 106 delivered sequences on `V:/`):**
- AE-written EXRs *do* carry `timeCode` (plus a `timeCodeString` mirror) and `framesPerSecond` — the §17.3 "metadata may be absent" risk does not apply to the studio's current EXR output module. A render whose TC is absent means the output module changed, and is a FAIL.
- `Shot.timecodeStart` from the API is the **editorial in-point**; the plate on disk starts `handleFrames` earlier. Measured on three shots, the API value was consistently the plate's TC **+8 frames** — the exact handle count. Validating a render against the API would therefore **pass the defective exports and fail the correct ones**: on `UNG_102_019_010` the correctly-built render (`18:58:57:12`, matching its BG01 plate) differs from the API value (`18:58:57:20`), while on `UNG_102_040_010` the *defective* render matches the API exactly and is 8 frames off its plate.
- 95 of 106 delivered sequences match their plate's timecode exactly. The 11 that do not fall into three classes this check catches: **+8 handle offset** (comp anchored to the editorial in-point instead of the plate head), **frame-derived TC** (`00:00:41:17` = frame 1001 at 24 fps, i.e. a comp with no source timecode at all — also seen as `00:00:00:00`), and **one timecode shared across four different shots** in a single delivery package.
**Reference precedence** — the check records which source it used and never silently substitutes a weaker one:
| Rank | Source | Verdict semantics |
|---|---|---|
| 1 | `source.timingPlate` from the manifest — the element the comp was actually anchored to | PASS / FAIL, authoritative |
| 2 | Plate re-derived on the worker from the footage root + shot code (manifestVersion 1, or a timing plate that no longer resolves). If elements disagree, the one matching the render's frame count wins; still ambiguous → WARN, never PASS | PASS / FAIL, `reference: "derived"` |
| 3 | API `Shot.timecodeStart` **minus `handleFrames`** | **WARN only, never PASS** — `reference: "api"`, message states the plate could not be read |
Rank 3 is a diagnostic, not a verification: it depends on the show's handle count being correct for that specific plate, which is exactly the assumption the defects above violate.
**Comparison, given the plate reference:**
```
expectedTc = plateTc + (render.frameStart - plate.frameStart) // frames, at manifest fps
```
The offset term matters — a shot may render a sub-range of a long plate (observed: 37 rendered frames from a 709-frame plate). Sampled frames must then increment by exactly one frame each; a constant value across the sequence is the frame-derived-TC defect, not a rounding artifact. `timeCodeString` is cross-checked against the packed `timeCode` as a writer sanity check.
**Queue-time pre-flight.** The panel already knows whether it read the start time from the plate's metadata or fell back to the API (`source.startSource`). When the manifest says the API fallback was used, the Export is flagged at queue time — the render is very likely to fail this check, and there is no point spending machine hours to find out.
**Delivery-package cross-check (Phase 5).** Within one package, two shots sharing a first-frame timecode is a FAIL on the package: it is cheap, and it is precisely the defect that reached a built delivery package above.
**Tooling note.** `timeCode`, `timeCodeString` and `framesPerSecond` live in the EXR header, so this check needs one 64 KB read per sampled frame and no pixel decode — the header parse is ~40 lines (attribute list: `name\0 type\0 int32 size data`; `timeCode` is two `uint32`, the first packed SMPTE 12M BCD, which reads back as its own hex digits: `0x18585712` → `18:58:57:12`). It does **not** depend on oiiotool, so the timecode check can ship ahead of the OIIO-based resolution/bit-depth/channel checks.
### 8.2 Semantics
- Any FAIL → whole run FAIL → Export = VALIDATION_FAILED, pipeline stops, exact reasons in `ValidationResult` rows (E12 example above shows a missing-frame report).
- WARN never stops the pipeline but is shown in QC and delivery UIs.
- **Manual override.** A check can fail on a render that is genuinely fine — an unreachable plate, an expectation that does not apply to this shot — so a VALIDATION_FAILED export is not a dead end. An admin/producer/supervisor can override it from the Export detail page with a **required reason**, and the pipeline resumes exactly where a pass would have handed off: preview, then READY_FOR_QC. **An override never skips QC and never delivers directly** — a human still looks at the frames. The failed `ValidationResult` rows are left untouched, so the QC queue keeps listing them as warnings, and the reason plus the checks waved through are recorded on the Export's timeline.
- Checksum: xxHash64 per file, sequence digest = xxHash64 of sorted per-file digests; stored on `Export.checksum` and reused by the delivery builder for copy verification (MD5 available for the client-facing manifest per 18.1-Q13).
---
@@ -1063,6 +1132,26 @@ Cost note: the AE preview pass roughly doubles machine time per export. This mat
Finalize (E13) then creates the `Version` row server-side (Section 6.4) in pipeline mode — visible internally, never client-shared, no task/shot status changes.
**Re-exports inherit approval, and carry no artist-facing text.** A shot is routinely re-exported after client approval — most often for an unscaled/un-punched-in delivery pass — and that must not read as new work awaiting review. The new `Version.approvalStatus` is copied from the task's previous latest version rather than left at its `PENDING_REVIEW` default; an export that starts a task's history has nothing to inherit and gets `PENDING_REVIEW` as before. `Version.notes` is left unset rather than stamped with an internal description: `notes` is the artist's message to reviewers and is rendered verbatim in the client portal and the review player, so pipeline provenance belongs on the Export and its `ExportEvent` timeline — where a human would go looking for it — not in a field a client can read.
**Known gap:** `shareWithClient` (and the per-task share action) promote whichever `Version` is `isLatest` for a task to `isClientVisible: true`, with no awareness that a pipeline-created version is meant to stay internal permanently (this section, "never client-shared"). Re-sharing a shot after a pipeline re-export will currently expose the internal version if it is the task's latest. Closing this needs a way to identify a pipeline-origin version at the share call sites — `Export.versionId` is presently a one-way scalar with no inverse relation on `Version` — and is not yet implemented.
### 9.3a Where a preview sits in the queue
The queue is ordered `priority ASC, createdAt ASC`, and a preview job is only created when its render *finishes* — so at equal priority it sorts behind every render queued alongside it. Ten shots queued together would run as ten renders and then ten previews, with nothing reviewable until the end.
`SystemConfig: render.previewPriorityBoost` (default 1) subtracts from the render's priority when the preview job is created, so a finished shot completes before the next render starts. Priority is otherwise inherited, which is what keeps an urgent export urgent all the way to READY_FOR_QC. The boost never promotes a job across `render.urgentPriorityThreshold`: a normal preview must not gain permission to run outside the render window that its render never had. Set the boost to `0` for the old phase behaviour.
Independently of priority, a worker **does not claim `PREVIEW_ONLY` jobs while an interactive After Effects is running** on that machine (§9.1) — a headless launch would hijack the artist's session. During the working day previews therefore queue regardless of rank, which is usually the larger effect on when they run.
### 9.4 Skipping the preview (`Export.skipPreview`)
Not every export is framed like its review. A deliverable rendered unscaled or without the punch-in shares a shot and a version history with the review, but a preview rebuilt from *its* frames would show the wrong picture — the earlier export's MOV is the correct one.
`skipPreview` (set at Queue Export, or per-action when overriding a validation failure) renders the EXRs and goes straight to READY_FOR_QC, **inheriting** `deliveryMovPath`, `previewMovKey`, `thumbnailKey` and `versionId` from the newest earlier export of that shot which has them. Inheritance matters as much as the skip: the delivery builder takes its MOV from `deliveryMovPath`, so an export with none would package EXRs alone. QC is unaffected — the export still needs a human pass before it can be delivered.
With no earlier export to inherit from, the export still reaches READY_FOR_QC and the timeline records that it has no review media.
---
## 10. QC Workflow
@@ -1126,7 +1215,11 @@ Tokens: `{showId} {episode} {yymmdd} {yyyymmdd} {packageName} {packageDir} {shot
### 11.3 Hard links vs copying
**Recommendation: hard link when `deliveryRoot` and render root share an NTFS volume; transparent fallback to copy otherwise (cross-volume links are impossible).** Hard links make an 18-shot EXR package near-instant and ~zero extra disk; the risk (mutating a linked file changes both) is acceptable because rendered EXR versions are immutable by pipeline design — a version is never re-rendered in place (new version → new directory). Post-link verification: link target identity check; post-copy verification: size + xxHash against validation-time values. `DeliveryItem.status` → VERIFIED per item. Config override `"copyMode": "always-copy"` for productions that mandate physical separation.
**Recommendation: hard link when `deliveryRoot` and render root share an NTFS volume; transparent fallback to copy otherwise (cross-volume links are impossible).** Hard links make an 18-shot EXR package near-instant and ~zero extra disk; the risk (mutating a linked file changes both) is acceptable because rendered EXR versions are immutable by pipeline design — a version is never re-rendered in place (new version → new directory).
**Verified on the studio volume (2026-08-13):** `V:` is `\\TRUENAS\vfx` over SMB, and hard links work on it — `mklink /H` succeeds and a write through one name is visible through the other. Renders (`V:/_EXPORTS/UNG/{ep}/{shot}/{ver}`) and the delivery root (`V:/_EXPORTS/UNG/DELIVERY`) are on the same share, so the fast path applies to real deliveries today.
**Implementation trap:** `fsutil hardlink list` fails over SMB (`Error 50: The request is not supported`), so the builder **cannot enumerate links to verify them** on a network volume. Verify instead by hashing the delivery-side file and comparing against the validation-time xxHash — that reads the same bytes whether the entry is a link or a copy, so one verification path covers both modes. Post-copy verification is the same check plus size. `DeliveryItem.status` → VERIFIED per item. Config override `"copyMode": "always-copy"` for productions that mandate physical separation.
### 11.4 Manifest and delivery report
@@ -1278,7 +1371,7 @@ Five independently deployable phases. Each phase leaves the previous workflow fu
| API | E12; transitions T3→T7/T8 activated (Phase 2 interim: complete-render goes straight to a provisional READY_FOR_QC; Phase 3 inserts VALIDATING between) |
| UI | Validation table on Export detail; Validation Results browser; failure badge in queue |
| Worker | Validation engine (oiiotool integration, all Section 8.1 checks, checksums); oiiotool bundled with installer |
| Risks | Colourspace/timecode metadata may be absent in AE-written EXRs → those checks SKIPPED until per-project expectations configured (18.2-Q1); false FAILs block artists → per-check severity override in SystemConfig (`validation.overrides: {"exr_type": "warn"}`) |
| Risks | ~~Timecode metadata may be absent in AE-written EXRs~~ — disproved on the live show (§8.1a): AE writes `timeCode`, so absence is now itself a FAIL. Colourspace metadata may still be absent → that check SKIPPED until per-project expectations configured (18.2-Q1); false FAILs block artists → per-check severity override in SystemConfig (`validation.overrides: {"exr_type": "warn"}`). **The timecode check is the phase's priority and ships first** — it needs no oiiotool, and 11 of 106 delivered sequences on the current show would have been caught by it |
| Testing | Golden EXR fixture sets: complete, gapped, duplicate, wrong-res, wrong-depth, no-alpha, corrupt, zero-byte; checksum determinism; large-sequence perf (500 frames < 60 s) |
| Migration | Additive; existing in-flight exports unaffected (transition map keys off manifest version) |
+5
View File
@@ -2,3 +2,8 @@ bin/
obj/
publish/
*.user
# Published packages — rebuildable from any commit with scripts/publish.ps1,
# and the version stamp (e.g. 1.1.0+a4f8226) already traces a deployed exe
# back to its source. Keeping ~29 MB per publish in history buys nothing.
VFXReviewWorker_*.zip
+86 -2
View File
@@ -60,8 +60,82 @@ the artist's AEP (then it is pure `aerender`), or the ffmpeg engine.
are never resumed — the next attempt clears its own output files and re-renders.
- Durable reporting: complete/fail reports spool to disk and replay in order with backoff —
rendering continues while the server is down.
- **Validation (Phase 3)**: after a successful render the worker checks the sequence it just
produced and reports every result in one call (E12). See below.
Preview generation (Phase 4) and validation (Phase 3) plug into this same service later.
## Validation stage
Runs on the worker straight after the render, while it still holds the job and the files are
local. The Export sits in `VALIDATING` until the report lands; the server decides what the
results mean (any FAIL → `VALIDATION_FAILED`, otherwise the preview stage is queued).
Checks: `file_count`, `missing_frames`, `duplicate_frames`, `first_frame`, `last_frame`,
`filename_consistency`, `zero_byte`, `corrupt`, `resolution`, `bit_depth`, `alpha_channel`,
`exr_type`, `timecode_plate_match`, `timecode_consistency`, `timecode_fps`.
**No oiiotool needed.** Everything is read from the EXR header — one 64 KB read per sampled
frame, no pixel decode. Full-sequence checks (count, gaps, names, sizes) touch every file;
header checks sample first/middle/last plus every Nth frame (`validation.sampleEvery`).
**Timecode is the primary check** (spec §8.1a) and is compared against *the plate*, in this
order: the timing plate named in the manifest → a plate found under `plateSearchRoots` →
the API timecode minus handles, which is **WARN-only** because the API stores the editorial
in-point and is a handle-length ahead of the plate by design.
Checksums are xxHash64 per file, with a sequence digest stored on the Export and reused by
the delivery builder to verify what it packaged.
Server-side switches (SystemConfig, no worker redeploy): `validation.enabled`,
`validation.sampleEvery`, `validation.handleFrames`, and `validation.overrides` for per-check
severity, e.g. `{"exr_type":"warn"}`.
## Blender renders
The worker also claims `BLENDER_RENDER` jobs: standalone renders submitted from
the Blender add-on, with no Export behind them — nothing to validate, preview or
QC. It runs `blender -b file.blend -s N -e M -a`, parses `Fra:`/`Saved:` output
for progress, and reports complete or failed like any other job.
Set `blenderPath` in `config.json` to make a machine eligible. The version is
reported at registration and **the server only hands Blender jobs to machines
that have it**, so a workstation without Blender can never claim work it could
only fail. A machine without it stays perfectly valid for After Effects work.
Blender exits 0 when a frame range is empty or an output path is unwritable, so
a run that saves no frames is reported as a failure rather than a success.
See [BlenderPanel/README.md](../BlenderPanel/README.md).
## Delivery builds
The same service also claims `DELIVERY_BUILD` jobs: creating a dated package
folder, hard-linking (or copying) each shot's EXRs and delivery MOV into it,
verifying every file against the validation-time checksum, and writing
`manifest.json` plus the CSV report.
No After Effects involved, so these are claimed **even while an artist has AE
open** — and at priority 10, inside the urgent threshold, so they run during the
day rather than waiting for the render window. Someone is usually waiting on the
folder.
`deliveryRoot` has to be reachable from this machine under the service account:
`--check` verifies `pathMappings` targets, which is where a build most often
falls over.
Full workflow: [DELIVERY_WORKFLOW.md](../DELIVERY_WORKFLOW.md).
### Checking a render by hand
```powershell
.\VFXReviewWorker.exe --validate "V:\_EXPORTS\UNG\102\UNG_102_019_010\v005" --plate "V:\_FOOTAGE\UNG\UNG_102\UNG_102_019_010_BG01_TT_v001\UNG_102_019_010_BG01_TT_v001.01001.exr"
```
Runs the whole engine over an existing folder with no server, job or queue, and prints the
report. The frame range, pattern and resolution are inferred from the files. Exits non-zero
if any check fails, so it also works in a script. Useful for auditing work that predates the
pipeline, and for proving the checks on real shots before turning the stage on.
Preview generation (Phase 4) plugs into this same service.
## Packaging for another machine
@@ -117,14 +191,24 @@ Create `C:\ProgramData\VFXReviewWorker\config.json` (§7.8):
"aerenderPath": "C:\\Program Files\\Adobe\\Adobe After Effects 2026\\Support Files\\aerender.exe",
"aeVersion": "24.3",
"ffmpegPath": "C:\\pipeline\\bin\\ffmpeg.exe",
"blenderPath": "C:\\Program Files\\Blender Foundation\\Blender 4.2\\blender.exe",
"plateSearchRoots": ["V:/_FOOTAGE/UNG"],
"pathMappings": [
{ "from": "//SAN/", "to": "S:/" }
]
}
```
There is no `workerVersion` key: the version is stamped into the exe at build time and
read back from the assembly, so a machine can never report a version it is not running.
`publish.ps1` appends the git commit, giving `1.1.0+feb1c7b`. Bump `<Version>` in
`VFXReviewWorker.csproj` when publishing a change; the worker reports it on startup and
**Pipeline → Machines** flags any machine still on an older one.
`pathMappings` translate the manifest's canonical UNC paths to this machine's drive
mappings. Everything tunable (poll interval, lease, stall timeout, max attempts) lives in
mappings. `plateSearchRoots` is optional: it is only consulted when a manifest carries no
timing plate (older panel versions), to find the shot's plates for the timecode check.
Everything tunable (poll interval, lease, stall timeout, max attempts, validation) lives in
the server's SystemConfig and arrives at registration — no per-machine tuning files.
## Run interactively (first-time smoke test)
@@ -0,0 +1,92 @@
using System.Text;
using VFXReviewWorker;
using Xunit;
namespace VFXReviewWorker.Tests;
/// <summary>
/// Blender writes its render status with a carriage return so it overwrites one
/// line in the terminal, and only emits a newline when a frame is saved. A
/// reader that splits on newlines alone therefore sees nothing at all while a
/// long frame renders — which had the stall watchdog killing healthy jobs.
/// </summary>
public class BlenderProgressParserTests
{
[Theory]
[InlineData("Fra:1042 Mem:512.00M (Peak 640.00M) | Time:00:12.34 | Path Tracing Sample 12/128", 1042)]
[InlineData("Fra:1 Mem:64.00M | Syncing Cube", 1)]
[InlineData("Saved: 'X:/renders/frame_1042.exr'", null)]
[InlineData("Blender quit", null)]
public void ParsesTheFrameBeingRendered(string line, int? expected)
{
Assert.Equal(expected, BlenderProgressParser.ParseFrame(line));
}
[Theory]
[InlineData("Saved: 'X:/renders/frame_1042.exr'", "X:/renders/frame_1042.exr")]
[InlineData(" Saved: 'nope'", null)] // leading space: not the real form
[InlineData("Fra:1042 Mem:512.00M", null)]
public void ParsesSavedFrames(string line, string? expected)
{
Assert.Equal(expected, BlenderProgressParser.ParseSaved(line));
}
[Fact]
public void TreatsAMissingBlendAsNonRetryable()
{
const string line = "Error: Cannot read file 'X:/gone.blend': No such file or directory";
Assert.True(BlenderProgressParser.IsErrorLine(line));
Assert.True(BlenderProgressParser.IsNonRetryableError(line));
}
[Fact]
public void TreatsAnUnknownFailureAsRetryable()
{
const string line = "Error: CUDA device lost, out of memory";
Assert.True(BlenderProgressParser.IsErrorLine(line));
Assert.False(BlenderProgressParser.IsNonRetryableError(line));
}
/// <summary>
/// The regression itself: a realistic stdout chunk where progress is
/// separated by CR and only the saved lines end in LF.
/// </summary>
[Fact]
public void CarriageReturnProgressIsSeenWithoutWaitingForANewline()
{
var stdout =
"Fra:1001 Mem:64.00M | Sample 1/128\r" +
"Fra:1001 Mem:120.00M | Sample 64/128\r" +
"Fra:1001 Mem:128.00M | Sample 128/128\r" +
"\nSaved: 'X:/renders/frame_1001.exr'\n" +
"Fra:1002 Mem:128.00M | Sample 1/128\r";
var lines = SplitLikeThePump(stdout);
var frames = lines.Select(BlenderProgressParser.ParseFrame).Where(f => f is not null).ToList();
var saved = lines.Select(BlenderProgressParser.ParseSaved).Where(s => s is not null).ToList();
// Four status updates and one saved frame; splitting on "\n" alone
// would have yielded a single unusable blob and no progress at all.
Assert.Equal(4, frames.Count);
Assert.Single(saved);
Assert.Equal(1002, frames[^1]);
}
/// <summary>Mirrors BlenderRunner.PumpAsync: CR and LF both end a line.</summary>
private static List<string> SplitLikeThePump(string text)
{
var lines = new List<string>();
var current = new StringBuilder();
foreach (var c in text)
{
if (c == '\r' || c == '\n')
{
if (current.Length > 0) { lines.Add(current.ToString()); current.Clear(); }
}
else current.Append(c);
}
if (current.Length > 0) lines.Add(current.ToString());
return lines;
}
}
@@ -0,0 +1,341 @@
using Microsoft.Extensions.Logging.Abstractions;
using VFXReviewWorker;
using Xunit;
namespace VFXReviewWorker.Tests;
/// <summary>
/// Packaging is the last step before files leave the studio, so the parts that
/// could silently ship the wrong thing — checksum verification, frame-count
/// drift, hard-link vs copy — are pinned here.
/// </summary>
public class DeliveryStageTests : IDisposable
{
private readonly string _root = Path.Combine(Path.GetTempPath(), $"vfxr_delivery_{Guid.NewGuid():N}");
private readonly string _sourceDir;
private readonly string _packageDir;
public DeliveryStageTests()
{
_sourceDir = Path.Combine(_root, "renders", "SHOT_001", "v001");
_packageDir = Path.Combine(_root, "DELIVERY", "101", "260813_Delivery");
Directory.CreateDirectory(_sourceDir);
}
public void Dispose()
{
try { Directory.Delete(_root, recursive: true); } catch { }
}
private void WriteFrames(int count, int startFrame = 1001)
{
for (var i = 0; i < count; i++)
{
var name = $"SHOT_001_cmp_TT_v001.{startFrame + i:D5}.exr";
File.WriteAllText(Path.Combine(_sourceDir, name), $"frame {startFrame + i} pixels");
}
}
private DeliveryManifest Manifest(string? checksum = null, int fileCount = 3, string copyMode = "auto") => new()
{
PackageId = "pkg1",
PackageName = "260813_Delivery",
PackageNumber = 1,
Episode = "101",
PackageDir = _packageDir,
ReportFile = Path.Combine(_packageDir, "260813_Delivery_report.csv"),
CopyMode = copyMode,
Items = new List<DeliveryManifestItem>
{
new()
{
ItemId = "item1",
ExportId = "exp1",
ShotCode = "SHOT_001",
VersionString = "v001",
SourceDir = _sourceDir,
OutputPattern = "SHOT_001_cmp_TT_v001.[#####].exr",
FrameStart = 1001,
FrameEnd = 1000 + fileCount,
FileCount = fileCount,
Checksum = checksum,
ShotDir = Path.Combine(_packageDir, "SHOT_001"),
},
},
};
private DeliveryStage NewStage() => new(
new WorkerOptions { ServerUrl = "n/a", ApiKey = "n/a" },
new ApiClient(new WorkerOptions { ServerUrl = "http://localhost:1", ApiKey = "x" }, NullLogger<ApiClient>.Instance),
NullLogger<DeliveryStage>.Instance);
[Fact]
public async Task PackagesFramesAndWritesReport()
{
WriteFrames(3);
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, Manifest(), "machine1",
CancellationToken.None, CancellationToken.None);
Assert.True(result.Ok);
var item = Assert.Single(result.Items);
Assert.Equal("VERIFIED", item.Status);
Assert.Equal(3, item.FileCount);
var delivered = Directory.GetFiles(Path.Combine(_packageDir, "SHOT_001"), "*.exr");
Assert.Equal(3, delivered.Length);
Assert.True(File.Exists(Path.Combine(_packageDir, "manifest.json")));
var report = File.ReadAllText(Path.Combine(_packageDir, "260813_Delivery_report.csv"));
Assert.Contains("Shot,Version,FrameStart", report);
Assert.Contains("SHOT_001,v001,1001,1003,3,3", report);
}
[Fact]
public async Task HardLinksOnTheSameVolumeSoNoExtraBytesAreWritten()
{
WriteFrames(2);
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, Manifest(fileCount: 2), "machine1",
CancellationToken.None, CancellationToken.None);
Assert.Equal("hardlink", result.Items[0].LinkMode);
// A hard link is the same file: writing through one name is visible via
// the other. That is what makes packaging near-instant and free.
var source = Path.Combine(_sourceDir, "SHOT_001_cmp_TT_v001.01001.exr");
var linked = Path.Combine(_packageDir, "SHOT_001", "SHOT_001_cmp_TT_v001.01001.exr");
File.WriteAllText(source, "rewritten");
Assert.Equal("rewritten", File.ReadAllText(linked));
}
[Fact]
public async Task AlwaysCopyModeProducesIndependentFiles()
{
WriteFrames(2);
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, Manifest(fileCount: 2, copyMode: "always-copy"),
"machine1", CancellationToken.None, CancellationToken.None);
Assert.Equal("copy", result.Items[0].LinkMode);
var source = Path.Combine(_sourceDir, "SHOT_001_cmp_TT_v001.01001.exr");
var copied = Path.Combine(_packageDir, "SHOT_001", "SHOT_001_cmp_TT_v001.01001.exr");
File.WriteAllText(source, "rewritten");
Assert.NotEqual("rewritten", File.ReadAllText(copied));
}
[Fact]
public async Task ChecksumMismatchFailsACopiedItem()
{
WriteFrames(3);
var manifest = Manifest(checksum: "deadbeefdeadbeef", copyMode: "always-copy");
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.False(result.Ok);
Assert.Equal("FAILED", result.Items[0].Status);
Assert.Contains("Checksum mismatch", result.Items[0].ErrorMessage!);
}
[Fact]
public async Task HardLinkedItemsAreNotReadBack()
{
// A hard link is the same data as the source, so re-hashing it re-reads
// the exact bytes validation already hashed — half an hour per episode
// over SMB to prove something that cannot be false. A deliberately wrong
// recorded checksum is therefore not consulted on the linked path, and
// the validation-time digest carries over unchanged.
WriteFrames(3);
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" },
Manifest(checksum: "deadbeefdeadbeef"), "machine1", CancellationToken.None, CancellationToken.None);
Assert.True(result.Ok);
Assert.Equal("VERIFIED", result.Items[0].Status);
Assert.Equal("hardlink", result.Items[0].LinkMode);
Assert.Equal("deadbeefdeadbeef", result.Items[0].Checksum);
}
[Fact]
public async Task AlwaysHashForcesReadBackEvenWhenLinked()
{
WriteFrames(3);
var manifest = Manifest(checksum: "deadbeefdeadbeef");
manifest.VerifyMode = "always-hash";
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.False(result.Ok);
Assert.Contains("Checksum mismatch", result.Items[0].ErrorMessage!);
}
[Fact]
public async Task SourceTouchedAfterValidationFailsTheLinkedItem()
{
// The one thing linking cannot rule out: the source changing after it
// passed QC. The link would faithfully carry the new bytes.
WriteFrames(3);
var manifest = Manifest();
manifest.Items[0].ValidatedAt = DateTimeOffset.UtcNow.AddHours(-2);
File.SetLastWriteTimeUtc(
Path.Combine(_sourceDir, "SHOT_001_cmp_TT_v001.01002.exr"), DateTime.UtcNow);
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.False(result.Ok);
Assert.Contains("modified after validation", result.Items[0].ErrorMessage!);
}
[Fact]
public async Task UntouchedSourcesPassTheValidationTimestampCheck()
{
WriteFrames(3);
var manifest = Manifest();
manifest.Items[0].ValidatedAt = DateTimeOffset.UtcNow.AddHours(1);
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.True(result.Ok);
}
[Fact]
public async Task FrameCountDriftSinceQcFailsTheItem()
{
// The export recorded 3 frames at validation; the folder now has 2.
WriteFrames(2);
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, Manifest(fileCount: 3), "machine1",
CancellationToken.None, CancellationToken.None);
Assert.False(result.Ok);
Assert.Contains("the render changed since QC", result.Items[0].ErrorMessage!);
}
[Fact]
public async Task MissingSourceFolderFailsWithThePath()
{
var manifest = Manifest();
manifest.Items[0].SourceDir = Path.Combine(_root, "does-not-exist");
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.False(result.Ok);
Assert.Contains("Source folder not found", result.Items[0].ErrorMessage!);
}
[Fact]
public async Task ChecksumMatchesTheValidationTimeDigestForIdenticalContent()
{
WriteFrames(3);
var first = await NewStage().RunAsync(new ClaimedJob { Id = "job1" },
Manifest(copyMode: "always-copy"), "machine1", CancellationToken.None, CancellationToken.None);
// Feeding the recorded digest back in must verify, which is exactly what
// the delivery builder does against Export.checksum on the copy path.
Directory.Delete(_packageDir, recursive: true);
var second = await NewStage().RunAsync(new ClaimedJob { Id = "job1" },
Manifest(checksum: first.Items[0].Checksum, copyMode: "always-copy"), "machine1",
CancellationToken.None, CancellationToken.None);
Assert.True(second.Ok);
}
[Fact]
public async Task NoClientCodeKeepsTheInternalRenderFilenames()
{
// Regression pin: DeliveredBaseName defaults to "" for a shot with no
// client code, and delivery must render byte-identical to before this
// feature existed.
WriteFrames(2);
var manifest = Manifest(fileCount: 2);
Assert.Equal("", manifest.Items[0].DeliveredBaseName);
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.True(result.Ok);
Assert.True(File.Exists(Path.Combine(_packageDir, "SHOT_001", "SHOT_001_cmp_TT_v001.01001.exr")));
Assert.True(File.Exists(Path.Combine(_packageDir, "SHOT_001", "SHOT_001_cmp_TT_v001.01002.exr")));
}
[Fact]
public async Task ClientCodeRenamesDeliveredFramesPreservingNumberAndPadding()
{
WriteFrames(3, startFrame: 1001);
var manifest = Manifest(fileCount: 3);
manifest.Items[0].DeliveredBaseName = "SNV_101_0461_CP_CAMF_PL_v001";
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.True(result.Ok);
var deliveredDir = Path.Combine(_packageDir, "SHOT_001");
Assert.True(File.Exists(Path.Combine(deliveredDir, "SNV_101_0461_CP_CAMF_PL_v001.01001.exr")));
Assert.True(File.Exists(Path.Combine(deliveredDir, "SNV_101_0461_CP_CAMF_PL_v001.01002.exr")));
Assert.True(File.Exists(Path.Combine(deliveredDir, "SNV_101_0461_CP_CAMF_PL_v001.01003.exr")));
// The internal shotCode-based name must not leak into the delivery.
Assert.False(File.Exists(Path.Combine(deliveredDir, "SHOT_001_cmp_TT_v001.01001.exr")));
Assert.Equal(3, Directory.GetFiles(deliveredDir, "*.exr").Length);
}
[Fact]
public async Task ClientCodeRenamesTheDeliveryMov()
{
WriteFrames(2);
var movSrc = Path.Combine(_sourceDir, "SHOT_001_cmp_TT_v001.mov");
File.WriteAllText(movSrc, "mov bytes");
var manifest = Manifest(fileCount: 2);
manifest.IncludeMovs = true;
manifest.Items[0].DeliveryMovPath = movSrc;
manifest.Items[0].DeliveredBaseName = "SNV_101_0461_CP_CAMF_PL_v001";
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.True(result.Ok);
var deliveredDir = Path.Combine(_packageDir, "SHOT_001");
Assert.True(File.Exists(Path.Combine(deliveredDir, "SNV_101_0461_CP_CAMF_PL_v001.mov")));
Assert.Equal(Path.Combine(deliveredDir, "SNV_101_0461_CP_CAMF_PL_v001.mov"), result.Items[0].MovPath);
}
[Fact]
public async Task ClientCodeRenameStillVerifiesAgainstTheValidationTimeChecksum()
{
// Renaming must not change file *content*, so a checksum recorded at
// validation time (against the internal name) has to still match the
// delivered (renamed) files — the hash is content-based, not name-based.
WriteFrames(3);
var manifest = Manifest(copyMode: "always-copy");
manifest.Items[0].DeliveredBaseName = "SNV_101_0461_CP_CAMF_PL_v001";
var first = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.True(first.Ok);
Directory.Delete(_packageDir, recursive: true);
var replay = Manifest(checksum: first.Items[0].Checksum, copyMode: "always-copy");
replay.Items[0].DeliveredBaseName = "SNV_101_0461_CP_CAMF_PL_v001";
var second = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, replay, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.True(second.Ok);
}
[Fact]
public async Task UnparseableFrameNumberFallsBackToTheSourceFilename()
{
// A file that doesn't match the render's own numbering convention
// (shouldn't happen for a real render, but must never crash a delivery)
// is delivered under its original name rather than failing the item.
Directory.CreateDirectory(_sourceDir);
File.WriteAllText(Path.Combine(_sourceDir, "SHOT_001_cmp_TT_v001_no_frame_number.exr"), "junk");
var manifest = Manifest(fileCount: 1);
manifest.Items[0].OutputPattern = "SHOT_001_cmp_TT_v001_no_frame_number.exr";
manifest.Items[0].DeliveredBaseName = "SNV_101_0461_CP_CAMF_PL_v001";
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.True(result.Ok);
Assert.True(File.Exists(Path.Combine(_packageDir, "SHOT_001", "SHOT_001_cmp_TT_v001_no_frame_number.exr")));
}
}
@@ -0,0 +1,199 @@
using VFXReviewWorker;
using Xunit;
namespace VFXReviewWorker.Tests;
/// <summary>
/// The timecode check is the reason the validation engine exists (§8.1a), so
/// the header parse and the timecode arithmetic are pinned here against a
/// synthetic EXR built byte by byte.
/// </summary>
public class ExrHeaderTests
{
[Fact]
public void ReadsTimecodeResolutionChannelsAndFps()
{
var path = ExrFixture.Write(timecode: "18:58:57:12", width: 1920, height: 1080,
channels: new[] { ("A", 1), ("B", 1), ("G", 1), ("R", 1) }, fpsNum: 24, compression: 4);
try
{
var header = ExrHeader.Read(path);
Assert.Equal(new Timecode(18, 58, 57, 12, false), header.Timecode);
Assert.Equal(1920, header.DataWidth);
Assert.Equal(1080, header.DataHeight);
Assert.Equal(24, header.FramesPerSecond);
Assert.Equal("half", header.BitDepth);
Assert.True(header.HasAlpha);
Assert.Equal("PIZ", header.CompressionName);
}
finally { File.Delete(path); }
}
[Fact]
public void MissingTimecodeIsReportedAsAbsentNotAsZero()
{
var path = ExrFixture.Write(timecode: null, width: 1920, height: 1080,
channels: new[] { ("B", 1), ("G", 1), ("R", 1) }, fpsNum: 24, compression: 3);
try
{
var header = ExrHeader.Read(path);
Assert.Null(header.Timecode);
Assert.False(header.HasAlpha);
}
finally { File.Delete(path); }
}
[Fact]
public void NonExrFileThrows()
{
var path = Path.GetTempFileName();
try
{
File.WriteAllText(path, "this is not an exr at all, not even close");
Assert.Throws<InvalidDataException>(() => ExrHeader.Read(path));
Assert.Null(ExrHeader.TryRead(path));
}
finally { File.Delete(path); }
}
[Theory]
// The BCD packing means the raw value reads back as its own hex digits.
[InlineData(0x18585712u, 18, 58, 57, 12)]
[InlineData(0x00004117u, 0, 0, 41, 17)]
[InlineData(0x00000000u, 0, 0, 0, 0)]
public void DecodesPackedSmpteTimecode(uint packed, int hh, int mm, int ss, int ff)
{
Assert.Equal(new Timecode(hh, mm, ss, ff, false), Timecode.FromPacked(packed));
}
[Fact]
public void FrameArithmeticRoundTrips()
{
var tc = new Timecode(18, 58, 57, 12, false);
Assert.Equal(tc, Timecode.FromFrames(tc.ToFrames(24), 24));
// 133 frames on from 18:58:57:12 at 24 fps is 18:59:03:01 — the real
// first/last frame pair measured on UNG_102_019_010 v005.
Assert.Equal(new Timecode(18, 59, 3, 1, false), Timecode.FromFrames(tc.ToFrames(24) + 133, 24));
}
[Fact]
public void ApiTimecodeIsOneHandleAheadOfThePlate()
{
// The defect class from §8.1a: the API stores the editorial in-point and
// the plate starts 8 frames earlier, so a comp anchored to the API value
// renders 8 frames late.
var plate = Timecode.Parse("13:44:06:02")!.Value;
var api = Timecode.Parse("13:44:06:10")!.Value;
Assert.Equal(8, api.ToFrames(24) - plate.ToFrames(24));
}
[Fact]
public void FrameDerivedTimecodeIsFrameNumberOverFps()
{
// 00:00:41:17 is frame 1001 at 24 fps — the signature of a comp built
// with no source timecode at all.
Assert.Equal(1001, Timecode.Parse("00:00:41:17")!.Value.ToFrames(24));
}
[Theory]
[InlineData("UNG_102_019_010_cmp_TT_v005.01001.exr", 1001)]
[InlineData("UNG_108_030_010_cmp_TT_v003.01204.exr", 1204)]
// AE-written renders separate the frame with an underscore, and turn up as
// layers in a shot comp alongside dot-separated delivered plates.
[InlineData("UNG_110_030_010_PRERENDER_01001.exr", 1001)]
[InlineData("UNG_110_030_010_render_1001.exr", 1001)]
[InlineData("no_frame_number.exr", null)]
// A version suffix is not a frame number.
[InlineData("UNG_110_030_010_BG01_TT_v001.exr", null)]
public void ParsesFrameNumbersFromFilenames(string name, int? expected)
{
Assert.Equal(expected, SequencePattern.FrameFromName(name));
}
[Fact]
public void ParsesOutputPattern()
{
var p = SequencePattern.FromOutputPattern("UNG_102_019_010_cmp_TT_v005.[#####].exr");
Assert.Equal("UNG_102_019_010_cmp_TT_v005", p.Prefix);
Assert.Equal(".exr", p.Extension);
Assert.Equal(5, p.Padding);
}
}
/// <summary>Builds a minimal but structurally real EXR header on disk.</summary>
internal static class ExrFixture
{
public static string Write(string? timecode, int width, int height,
(string Name, int PixelType)[] channels, int fpsNum, byte compression)
{
var path = Path.Combine(Path.GetTempPath(), $"vfxr_test_{Guid.NewGuid():N}.exr");
using var fs = new FileStream(path, FileMode.Create, FileAccess.Write);
using var w = new BinaryWriter(fs);
w.Write(ExrHeader.Magic);
w.Write(2); // version 2, no flags
// channels (chlist)
using (var chData = new MemoryStream())
using (var cw = new BinaryWriter(chData))
{
foreach (var (name, pixelType) in channels)
{
WriteCString(cw, name);
cw.Write(pixelType);
cw.Write((byte)0); // pLinear
cw.Write(new byte[3]); // reserved
cw.Write(1); // xSampling
cw.Write(1); // ySampling
}
cw.Write((byte)0); // list terminator
WriteAttr(w, "channels", "chlist", chData.ToArray());
}
WriteAttr(w, "compression", "compression", new[] { compression });
var window = new byte[16];
BitConverter.GetBytes(0).CopyTo(window, 0);
BitConverter.GetBytes(0).CopyTo(window, 4);
BitConverter.GetBytes(width - 1).CopyTo(window, 8);
BitConverter.GetBytes(height - 1).CopyTo(window, 12);
WriteAttr(w, "dataWindow", "box2i", window);
WriteAttr(w, "displayWindow", "box2i", window);
var rational = new byte[8];
BitConverter.GetBytes(fpsNum).CopyTo(rational, 0);
BitConverter.GetBytes(1u).CopyTo(rational, 4);
WriteAttr(w, "framesPerSecond", "rational", rational);
if (timecode is not null)
{
var parts = timecode.Split(':');
uint Bcd(int v) => (uint)((v / 10) * 16 + v % 10);
var packed = (Bcd(int.Parse(parts[0])) << 24) | (Bcd(int.Parse(parts[1])) << 16)
| (Bcd(int.Parse(parts[2])) << 8) | Bcd(int.Parse(parts[3]));
var tcData = new byte[8];
BitConverter.GetBytes(packed).CopyTo(tcData, 0);
WriteAttr(w, "timeCode", "timecode", tcData);
WriteAttr(w, "timeCodeString", "string", System.Text.Encoding.ASCII.GetBytes(timecode));
}
w.Write((byte)0); // end of header
return path;
}
private static void WriteAttr(BinaryWriter w, string name, string type, byte[] data)
{
WriteCString(w, name);
WriteCString(w, type);
w.Write(data.Length);
w.Write(data);
}
private static void WriteCString(BinaryWriter w, string s)
{
w.Write(System.Text.Encoding.ASCII.GetBytes(s));
w.Write((byte)0);
}
}
@@ -0,0 +1,194 @@
using Microsoft.Extensions.Logging.Abstractions;
using VFXReviewWorker;
using Xunit;
namespace VFXReviewWorker.Tests;
/// <summary>
/// Regression cover for the two coordinate systems a render lives in, taken
/// from a real failure on UNG_107_051_010 v004:
///
/// comp frames 1247792-1247896 (anchored to the plate's timecode 14:26:31:08)
/// file numbers 1001-1105 (the output module's starting number)
///
/// Checking file numbers against comp frames failed every render, and using
/// the comp range as the timecode anchor produced a million-frame offset.
/// </summary>
public class ValidationStageTests : IDisposable
{
private readonly string _dir = Path.Combine(Path.GetTempPath(), $"vfxr_val_{Guid.NewGuid():N}");
public ValidationStageTests() => Directory.CreateDirectory(_dir);
public void Dispose()
{
try { Directory.Delete(_dir, recursive: true); } catch { }
}
/// <summary>Writes a sequence numbered from 1001 with a plate-derived timecode.</summary>
private void WriteSequence(int count, string startTimecode, int firstFrame = 1001, int fps = 24)
{
var start = Timecode.Parse(startTimecode)!.Value.ToFrames(fps);
for (var i = 0; i < count; i++)
{
var tc = Timecode.FromFrames(start + i, fps);
var path = Path.Combine(_dir, $"UNG_107_051_010_cmp_TT_v004.{firstFrame + i:D5}.exr");
File.Move(ExrFixture.Write(tc.ToString(), 3840, 2160, new[] { ("B", 1), ("G", 1), ("R", 1) }, fps, 4), path);
}
}
private static RenderManifest Manifest(string dir, string? apiTimecode, int? outputFrameStart) => new()
{
ShotCode = "UNG_107_051_010",
OutputDir = dir,
OutputPattern = "UNG_107_051_010_cmp_TT_v004.[#####].exr",
// The comp is anchored to the plate timecode, so its frames are absolute.
FrameStart = 1247792,
FrameEnd = 1247896,
OutputFrameStart = outputFrameStart,
Fps = 24,
Width = 3840,
Height = 2160,
Expected = apiTimecode is null ? null : new ManifestExpected { TimecodeStart = apiTimecode },
};
private ValidationStage NewStage() =>
new(new WorkerOptions { ServerUrl = "n/a", ApiKey = "n/a" }, NullLogger<ValidationStage>.Instance);
private static ValidationCheck Check(ValidationOutcome o, string name) =>
o.Checks.Single(c => c.CheckName == name);
[Fact]
public void FileNumberingIsCheckedAgainstOutputStartNotCompFrames()
{
WriteSequence(105, "14:26:31:08");
var outcome = NewStage().Run(Manifest(_dir, "14:26:31:16", 1001), _dir, new ServerConfig());
Assert.Equal("PASS", Check(outcome, "file_count").Status);
Assert.Equal("PASS", Check(outcome, "first_frame").Status);
Assert.Equal("PASS", Check(outcome, "last_frame").Status);
Assert.Equal("PASS", Check(outcome, "missing_frames").Status);
Assert.Equal("1105", Check(outcome, "last_frame").Actual);
}
[Fact]
public void ApiTimecodeIsAnchoredOnTheRenderNotTheCompRange()
{
// Shot.timecodeStart is the edit in-point; the plate carries 8 frames of
// head handle, so the first rendered frame is 8 frames earlier.
WriteSequence(105, "14:26:31:08");
var outcome = NewStage().Run(Manifest(_dir, "14:26:31:16", 1001), _dir, new ServerConfig());
var tc = Check(outcome, "timecode_plate_match");
// WARN, never PASS: the API is a fallback reference (§8.1a).
Assert.Equal("WARN", tc.Status);
Assert.Equal("14:26:31:08", tc.Expected);
Assert.Equal("14:26:31:08", tc.Actual);
Assert.DoesNotContain("frames)", tc.Message ?? "");
}
[Fact]
public void RealTimecodeDefectStillFailsAgainstAPlate()
{
// Same shot, but rendered 8 frames late — the handle-offset defect.
WriteSequence(105, "14:26:31:16");
var plate = Path.Combine(_dir, "plate", "UNG_107_051_010_BG01_TT_v001.01001.exr");
Directory.CreateDirectory(Path.GetDirectoryName(plate)!);
File.Move(ExrFixture.Write("14:26:31:08", 3840, 2160, new[] { ("B", 1), ("G", 1), ("R", 1) }, 24, 4), plate);
var manifest = Manifest(_dir, "14:26:31:16", 1001);
manifest.Source = new ManifestSource
{
TimingPlate = new PlateRef { Path = plate, FrameStart = 1001 },
HandleFrames = 8,
};
var tc = Check(NewStage().Run(manifest, _dir, new ServerConfig()), "timecode_plate_match");
Assert.Equal("FAIL", tc.Status);
Assert.Contains("+8 frames", tc.Message);
Assert.Contains("8-frame handle", tc.Message);
}
[Fact]
public void APlateAtADifferentRateFailsPlateFps()
{
// The DH2 case: a 25 fps show whose shot records defaulted to 24, so
// every comp was built at 24. The render agrees with its own manifest,
// so only the plate can reveal it.
WriteSequence(105, "14:26:31:08");
var plate = Path.Combine(_dir, "plate", "UNG_107_051_010_BG01_TT_v001.01001.exr");
Directory.CreateDirectory(Path.GetDirectoryName(plate)!);
File.Move(ExrFixture.Write("14:26:31:08", 3840, 2160, new[] { ("B", 1), ("G", 1), ("R", 1) }, 25, 4), plate);
var manifest = Manifest(_dir, "14:26:31:16", 1001);
manifest.Source = new ManifestSource { TimingPlate = new PlateRef { Path = plate, FrameStart = 1001 } };
var outcome = NewStage().Run(manifest, _dir, new ServerConfig());
var fpsCheck = Check(outcome, "plate_fps");
Assert.Equal("WARN", fpsCheck.Status);
Assert.Equal("25", fpsCheck.Expected);
Assert.Equal("24", fpsCheck.Actual);
Assert.Contains("wrong rate", fpsCheck.Message);
// timecode_fps alone would not have caught it: the render and the
// manifest agree with each other at 24.
Assert.Equal("PASS", Check(outcome, "timecode_fps").Status);
}
[Fact]
public void AnOverCrankedPlateIsRecognisedRatherThanReportedAsAMistake()
{
// A 50 fps plate on a 25 fps show is deliberate slow motion, conformed
// on purpose — real on DH2, and it must not read as a rate error.
WriteSequence(105, "14:26:31:08", fps: 25);
var plate = Path.Combine(_dir, "plate", "DH2_PL01.01001.exr");
Directory.CreateDirectory(Path.GetDirectoryName(plate)!);
File.Move(ExrFixture.Write("14:26:31:08", 3840, 2160, new[] { ("B", 1), ("G", 1), ("R", 1) }, 50, 4), plate);
var manifest = Manifest(_dir, null, 1001);
manifest.Fps = 25;
manifest.Source = new ManifestSource { TimingPlate = new PlateRef { Path = plate, FrameStart = 1001 } };
var check = Check(NewStage().Run(manifest, _dir, new ServerConfig()), "plate_fps");
Assert.Equal("WARN", check.Status);
Assert.Contains("over-crank", check.Message);
Assert.DoesNotContain("wrong rate", check.Message);
}
[Fact]
public void MatchingRatesPassPlateFps()
{
WriteSequence(105, "14:26:31:08");
var plate = Path.Combine(_dir, "plate", "UNG_107_051_010_BG01_TT_v001.01001.exr");
Directory.CreateDirectory(Path.GetDirectoryName(plate)!);
File.Move(ExrFixture.Write("14:26:31:08", 3840, 2160, new[] { ("B", 1), ("G", 1), ("R", 1) }, 24, 4), plate);
var manifest = Manifest(_dir, "14:26:31:16", 1001);
manifest.Source = new ManifestSource { TimingPlate = new PlateRef { Path = plate, FrameStart = 1001 } };
Assert.Equal("PASS", Check(NewStage().Run(manifest, _dir, new ServerConfig()), "plate_fps").Status);
}
[Fact]
public void GapsAreStillCaughtWithinTheRun()
{
WriteSequence(105, "14:26:31:08");
File.Delete(Path.Combine(_dir, "UNG_107_051_010_cmp_TT_v004.01050.exr"));
var outcome = NewStage().Run(Manifest(_dir, "14:26:31:16", 1001), _dir, new ServerConfig());
Assert.Equal("FAIL", Check(outcome, "file_count").Status);
Assert.Equal("FAIL", Check(outcome, "missing_frames").Status);
Assert.Contains("1050", Check(outcome, "missing_frames").Message);
}
[Fact]
public void OldManifestsWithoutOutputNumberingSkipRatherThanFail()
{
WriteSequence(105, "14:26:31:08");
var outcome = NewStage().Run(Manifest(_dir, "14:26:31:16", null), _dir, new ServerConfig());
Assert.Equal("SKIPPED", Check(outcome, "first_frame").Status);
Assert.Equal("PASS", Check(outcome, "missing_frames").Status);
Assert.Contains("1001-1105", Check(outcome, "first_frame").Message);
}
}
@@ -0,0 +1,61 @@
using System.Text;
using VFXReviewWorker;
using Xunit;
namespace VFXReviewWorker.Tests;
/// <summary>
/// Reference vectors from the xxHash specification. The delivery builder
/// verifies packaged files against digests recorded here at validation time, so
/// a wrong implementation would not be caught by round-tripping our own code —
/// only by pinning the published values.
/// </summary>
public class XxHash64Tests
{
[Theory]
[InlineData("", 0xEF46DB3751D8E999UL)]
[InlineData("a", 0xD24EC4F1A98C6E5BUL)]
[InlineData("abc", 0x44BC2CF5AD770999UL)]
public void MatchesReferenceVectors(string input, ulong expected)
{
Assert.Equal(expected, XxHash64.Hash(Encoding.ASCII.GetBytes(input)));
}
[Fact]
public void StreamingInChunksMatchesSingleShot()
{
var data = new byte[1000];
new Random(42).NextBytes(data);
var oneShot = XxHash64.Hash(data);
// Chunk sizes deliberately straddle the 32-byte stripe boundary.
foreach (var chunk in new[] { 1, 7, 31, 32, 33, 64, 999 })
{
var state = new XxHash64.State(0);
for (var i = 0; i < data.Length; i += chunk)
{
state.Update(new ReadOnlySpan<byte>(data, i, Math.Min(chunk, data.Length - i)));
}
Assert.Equal(oneShot, state.Digest());
}
}
[Fact]
public void HashFileIsStableAndContentSensitive()
{
var path = Path.GetTempFileName();
try
{
File.WriteAllText(path, "frame data");
var first = XxHash64.HashFile(path);
Assert.Equal(first, XxHash64.HashFile(path));
File.WriteAllText(path, "frame datb");
Assert.NotEqual(first, XxHash64.HashFile(path));
}
finally
{
File.Delete(path);
}
}
}
+68 -4
View File
@@ -37,7 +37,20 @@ public sealed class ApiClient
hostname = Dns.GetHostName(),
workerVersion = o.WorkerVersion,
aeVersion = o.AeVersion,
capabilities = new { maxConcurrentJobs = 1, tools = new { ffmpeg = o.FfmpegPath != null, oiiotool = o.OiiotoolPath != null } },
// The server hands out BLENDER_RENDER work on the strength of the
// blender entry, so it reports the resolved path rather than a bare
// flag: a machine claiming Blender jobs it cannot run is worse than
// one that never claims them.
capabilities = new
{
maxConcurrentJobs = 1,
tools = new
{
ffmpeg = o.FfmpegPath != null,
oiiotool = o.OiiotoolPath != null,
blender = !string.IsNullOrWhiteSpace(o.BlenderPath) && File.Exists(o.BlenderPath) ? o.BlenderPath : null,
},
},
}, Json, ct);
res.EnsureSuccessStatusCode();
return (await res.Content.ReadFromJsonAsync<RegisterResponse>(Json, ct))!;
@@ -71,9 +84,14 @@ public sealed class ApiClient
return body?.Job;
}
// E9 — best-effort; failures are swallowed by the caller (lease/reaper covers us)
// E9 — best-effort by contract: a progress report is a nicety, and losing
// one must never abort work in flight. Transport failures return null here
// rather than throwing at the call site; the lease and the reaper are what
// actually protect the job.
public async Task<ProgressResponse?> ProgressAsync(string jobId, string machineId, double progress,
int? currentFrame, int? totalFrames, int? etaSeconds, string? logTail, CancellationToken ct)
{
try
{
using var req = new HttpRequestMessage(HttpMethod.Patch, $"api/ext/render/jobs/{jobId}/progress")
{
@@ -83,6 +101,16 @@ public sealed class ApiClient
if (!res.IsSuccessStatusCode) return null;
return await res.Content.ReadFromJsonAsync<ProgressResponse>(Json, ct);
}
catch (OperationCanceledException) when (ct.IsCancellationRequested)
{
throw; // a real shutdown still stops us
}
catch (Exception ex)
{
_log.LogDebug(ex, "Progress report failed for job {JobId} (non-fatal)", jobId);
return null;
}
}
// E10 / E11 — lifecycle reports, sent via the spooler for durability.
// Returns true when the server accepted (2xx) OR permanently rejected (409
@@ -93,16 +121,22 @@ public sealed class ApiClient
{
"fail" => $"api/ext/render/jobs/{jobId}/fail",
"complete-render" => $"api/ext/render/jobs/{jobId}/complete-render",
"validation" => $"api/ext/render/jobs/{jobId}/validation",
"delivery" => $"api/ext/render/jobs/{jobId}/delivery",
"finalize" => $"api/ext/render/jobs/{jobId}/finalize",
_ => throw new ArgumentOutOfRangeException(nameof(kind), kind, "unknown lifecycle report kind"),
};
var res = await _http.PostAsJsonAsync(path, payload, Json, ct);
if (res.IsSuccessStatusCode) return true;
if (res.StatusCode is HttpStatusCode.Conflict or HttpStatusCode.NotFound)
if (res.StatusCode is HttpStatusCode.Conflict or HttpStatusCode.NotFound or HttpStatusCode.UnprocessableEntity)
{
// Conflict/NotFound: contradictory or vanished report — nothing to retry.
// UnprocessableEntity: the server rejected the payload shape itself, so
// resending the same bytes can only ever produce the same 422 — retrying
// just spams the log forever instead of surfacing the real problem.
_log.LogWarning("Server permanently rejected {Kind} for job {JobId}: {Status} {Body}",
kind, jobId, (int)res.StatusCode, await res.Content.ReadAsStringAsync(ct));
return true; // don't retry contradictory/vanished reports
return true;
}
_log.LogWarning("Lifecycle report {Kind} for {JobId} failed with {Status}; will retry", kind, jobId, (int)res.StatusCode);
return false;
@@ -159,6 +193,36 @@ public sealed class ApiClient
public Task<string?> UploadLogAsync(string jobId, string machineId, string logFilePath, CancellationToken ct) =>
UploadArtifactAsync(jobId, machineId, "log", logFilePath, "text/plain", ct);
/// <summary>
/// Reports the deployed worker version so the web UI can show what is
/// running where. Fire-and-forget — never worth failing a startup over.
/// </summary>
public async Task ReportVersionAsync(WorkerOptions o, CancellationToken ct)
{
try
{
await _http.PostAsJsonAsync("api/ext/tools/ping", new
{
tool = "RENDER_WORKER",
machineName = o.MachineName,
version = o.WorkerVersion,
hostUser = Environment.UserName,
hostApp = $"{Environment.OSVersion.VersionString} ({Dns.GetHostName()})",
details = new
{
aeVersion = o.AeVersion,
aerenderPath = o.AerenderPath,
ffmpeg = o.FfmpegPath is not null,
plateSearchRoots = o.PlateSearchRoots,
},
}, Json, ct);
}
catch (Exception ex)
{
_log.LogDebug(ex, "Version ping failed (non-fatal)");
}
}
// E3 — used by crash-recovery reconcile (§7.5)
public async Task<ExportDetail?> GetExportAsync(string exportId, CancellationToken ct)
{
@@ -0,0 +1,68 @@
using System.Text.RegularExpressions;
namespace VFXReviewWorker;
/// <summary>
/// Parses `blender -b` stdout. Blender reports the frame it is working on in
/// its status lines ("Fra:1042 Mem:512.00M ...") and confirms each written file
/// with "Saved: '...'". The saved lines are the reliable signal — a frame can
/// be reported for a long time while it renders — so progress counts those and
/// falls back to Fra: for a first sign of life.
/// </summary>
public static partial class BlenderProgressParser
{
[GeneratedRegex(@"^Fra:(\d+)", RegexOptions.Compiled)]
private static partial Regex FrameLine();
[GeneratedRegex(@"^Saved:\s*'(.+)'", RegexOptions.Compiled)]
private static partial Regex SavedLine();
[GeneratedRegex(@"^(Error|Warning): |^Error: ", RegexOptions.Compiled | RegexOptions.IgnoreCase)]
private static partial Regex ErrorLine();
/// <summary>
/// Failures that will repeat identically on another machine — a missing
/// file, an unknown scene, an unwritable output. Retrying these burns the
/// queue for nothing; a human has to fix the .blend or the path.
/// </summary>
private static readonly string[] NonRetryablePatterns =
{
"cannot read file",
"file not found",
"unable to open",
"is not a blend file",
"failed to read blend file",
"unknown scene",
"scene not found",
"unable to create directory",
"cannot write file",
"no camera",
"python script fail",
"unknown argument",
};
/// <summary>The frame Blender is currently working on, or null.</summary>
public static int? ParseFrame(string line)
{
var m = FrameLine().Match(line);
return m.Success && int.TryParse(m.Groups[1].Value, out var f) ? f : null;
}
/// <summary>The path of a frame Blender has just written, or null.</summary>
public static string? ParseSaved(string line)
{
var m = SavedLine().Match(line);
return m.Success ? m.Groups[1].Value : null;
}
public static bool IsErrorLine(string line) => ErrorLine().IsMatch(line);
public static bool IsNonRetryableError(string line)
{
foreach (var p in NonRetryablePatterns)
{
if (line.Contains(p, StringComparison.OrdinalIgnoreCase)) return true;
}
return false;
}
}
@@ -0,0 +1,313 @@
using System.Diagnostics;
using System.Text;
using Microsoft.Extensions.Logging;
namespace VFXReviewWorker;
/// <summary>
/// Standalone Blender renders: `blender -b file.blend -s N -e M -a`.
///
/// The .blend is expected to be ready to render — output path, format and
/// frame range already set by whoever built it. Overrides are only applied
/// when the submission asked for them, so this stays "Ctrl+F12 on the farm"
/// rather than a second place where render settings can drift.
/// </summary>
public sealed class BlenderRunner
{
private readonly WorkerOptions _options;
private readonly ApiClient _api;
private readonly ILogger<BlenderRunner> _log;
public BlenderRunner(WorkerOptions options, ApiClient api, ILogger<BlenderRunner> log)
{
_options = options;
_api = api;
_log = log;
}
public async Task<RenderResult> RunAsync(
ClaimedJob job,
BlenderManifest m,
string machineId,
ServerConfig config,
CancellationToken cancelJob,
CancellationToken shutdown)
{
var mapper = new PathMapper(_options.PathMappings);
var blendLocal = mapper.Map(m.BlendFile);
var totalFrames = m.TotalFrames;
if (!File.Exists(blendLocal))
{
return new RenderResult(false, -1, Retryable: false,
$"Blend file not found on this machine: {blendLocal}", "", "", 0);
}
// Argument order matters to Blender: everything before -a configures the
// render, and -a must come last or it renders with the old settings.
// -noaudio: a render node has no sound device, and initialising audio
// under a session-less service account is a known way to hang at startup.
var args = new List<string> { "-b", blendLocal, "-noaudio" };
if (!string.IsNullOrWhiteSpace(m.Scene)) { args.Add("-S"); args.Add(m.Scene!); }
if (!string.IsNullOrWhiteSpace(m.OutputPath))
{
args.Add("-o");
args.Add(mapper.Map(m.OutputPath!));
}
if (!string.IsNullOrWhiteSpace(m.Engine)) { args.Add("-E"); args.Add(m.Engine!); }
var pythonOverrides = BuildOverrideExpression(m);
if (pythonOverrides is not null) { args.Add("--python-expr"); args.Add(pythonOverrides); }
args.Add("-s"); args.Add(m.FrameStart.ToString());
args.Add("-e"); args.Add(m.FrameEnd.ToString());
args.Add("-a");
_log.LogInformation("Rendering {Label}: {Blend} frames {Start}-{End}",
job.Label ?? job.Id, blendLocal, m.FrameStart, m.FrameEnd);
return await ExecuteAsync(job.Id, machineId, args, totalFrames, m.FrameStart, config,
$"blender_{job.Id}.log", cancelJob, shutdown);
}
/// <summary>
/// Settings Blender has no command-line flag for. Returns null when the
/// submission asked for no overrides, so the file renders exactly as saved.
/// </summary>
private static string? BuildOverrideExpression(BlenderManifest m)
{
var parts = new List<string>();
if (m.Samples is int samples)
{
parts.Add($"getattr(S.cycles, 'samples', None) and setattr(S.cycles, 'samples', {samples})");
}
if (m.ResolutionPercent is int pct)
{
parts.Add($"setattr(S.render, 'resolution_percentage', {pct})");
}
if (!string.IsNullOrWhiteSpace(m.Device))
{
var deviceValue = m.Device!.Equals("GPU", StringComparison.OrdinalIgnoreCase) ? "GPU" : "CPU";
parts.Add($"hasattr(S, 'cycles') and setattr(S.cycles, 'device', '{deviceValue}')");
}
if (parts.Count == 0) return null;
return "import bpy; S = bpy.context.scene; " + string.Join("; ", parts);
}
private async Task<RenderResult> ExecuteAsync(
string jobId,
string machineId,
List<string> args,
int totalFrames,
int frameStart,
ServerConfig config,
string logFileName,
CancellationToken cancelJob,
CancellationToken shutdown)
{
var fullLogPath = Path.Combine(WorkerOptions.LogsDir, logFileName);
Directory.CreateDirectory(WorkerOptions.LogsDir);
var psi = new ProcessStartInfo
{
FileName = _options.BlenderPath,
RedirectStandardOutput = true,
RedirectStandardError = true,
UseShellExecute = false,
CreateNoWindow = true,
StandardOutputEncoding = Encoding.UTF8,
StandardErrorEncoding = Encoding.UTF8,
};
foreach (var a in args) psi.ArgumentList.Add(a);
var tail = new LogTail(200);
var eta = new EtaCalculator();
var sw = Stopwatch.StartNew();
var lastProgressAt = DateTimeOffset.UtcNow;
var lastReportAt = DateTimeOffset.MinValue;
var framesSaved = 0;
var currentFrame = frameStart;
string? firstError = null;
var nonRetryable = false;
var cancelledByServer = false;
using var process = new Process { StartInfo = psi };
await using var fullLog = new StreamWriter(fullLogPath, append: false, Encoding.UTF8);
var logLock = new object();
void HandleLine(string? line, bool isStderr)
{
if (line is null) return;
lock (logLock)
{
fullLog.WriteLine(line);
tail.Add(line);
}
// Any output at all means Blender is alive, which is what the stall
// watchdog is actually asking. Requiring a recognised progress line
// made the watchdog stricter than its own error message and killed
// healthy renders whose output we simply were not parsing.
lastProgressAt = DateTimeOffset.UtcNow;
var frame = BlenderProgressParser.ParseFrame(line);
if (frame is not null) currentFrame = frame.Value;
if (BlenderProgressParser.ParseSaved(line) is not null)
{
// Progress counts finished frames only: a frame emits hundreds
// of status updates while it renders.
framesSaved++;
eta.RecordFrame(DateTimeOffset.UtcNow);
}
if ((isStderr || BlenderProgressParser.IsErrorLine(line)) && !string.IsNullOrWhiteSpace(line))
{
if (BlenderProgressParser.IsErrorLine(line)) firstError ??= line.Trim();
if (BlenderProgressParser.IsNonRetryableError(line)) nonRetryable = true;
}
}
try
{
process.Start();
}
catch (Exception ex)
{
return new RenderResult(false, -1, Retryable: false,
$"Failed to launch Blender at {_options.BlenderPath}: {ex.Message}",
tail.ToString(), fullLogPath, 0);
}
// Deliberately not BeginOutputReadLine: that raises an event per
// newline, and Blender's render status is written with a carriage
// return so it overwrites one line in place. A frame that takes longer
// than the stall timeout would emit no newline for its whole duration
// and be killed as stalled while rendering perfectly well.
var pumps = new[]
{
PumpAsync(process.StandardOutput, line => HandleLine(line, isStderr: false)),
PumpAsync(process.StandardError, line => HandleLine(line, isStderr: true)),
};
while (!process.HasExited)
{
await Task.Delay(TimeSpan.FromSeconds(2), CancellationToken.None);
if (cancelJob.IsCancellationRequested || shutdown.IsCancellationRequested)
{
_log.LogWarning("Cancellation requested — killing Blender tree for job {JobId}", jobId);
KillTree(process);
cancelledByServer = cancelJob.IsCancellationRequested;
break;
}
if ((DateTimeOffset.UtcNow - lastProgressAt).TotalSeconds > config.StallTimeoutSeconds)
{
_log.LogError("Blender stalled ({Sec}s without output) — killing job {JobId}", config.StallTimeoutSeconds, jobId);
KillTree(process);
await WaitForExitSafe(process);
return new RenderResult(false, -2, Retryable: true,
$"Blender produced no output for {config.StallTimeoutSeconds}s (stall timeout)",
tail.ToString(), fullLogPath, sw.Elapsed.TotalSeconds);
}
if ((DateTimeOffset.UtcNow - lastReportAt).TotalSeconds >= 10)
{
lastReportAt = DateTimeOffset.UtcNow;
var progress = totalFrames > 0 ? Math.Min(1.0, (double)framesSaved / totalFrames) : 0;
var resp = await _api.ProgressAsync(jobId, machineId, progress, currentFrame, totalFrames,
eta.EstimateSeconds(totalFrames - framesSaved), tail.ToString(), shutdown);
if (resp?.CancelRequested == true)
{
_log.LogWarning("Server requested cancel for job {JobId}", jobId);
KillTree(process);
cancelledByServer = true;
break;
}
}
}
await WaitForExitSafe(process);
// Let the readers drain what is still buffered before judging the run —
// the last frame's "Saved:" often arrives after the process exits.
try { await Task.WhenAll(pumps).WaitAsync(TimeSpan.FromSeconds(10)); } catch { }
sw.Stop();
lock (logLock) { fullLog.Flush(); }
if (cancelledByServer)
{
return new RenderResult(false, -3, Retryable: false, "Cancelled", tail.ToString(), fullLogPath, sw.Elapsed.TotalSeconds);
}
var exitCode = process.ExitCode;
if (exitCode != 0)
{
return new RenderResult(false, exitCode, Retryable: !nonRetryable,
firstError ?? $"Blender exited with code {exitCode}",
tail.ToString(), fullLogPath, sw.Elapsed.TotalSeconds);
}
// Blender exits 0 having rendered nothing if the range is empty or the
// output path is unwritable, so a silent success is treated as failure.
if (framesSaved == 0)
{
return new RenderResult(false, 0, Retryable: false,
"Blender exited cleanly but saved no frames — check the output path and frame range in the .blend",
tail.ToString(), fullLogPath, sw.Elapsed.TotalSeconds);
}
_log.LogInformation("Job {JobId}: {Saved}/{Total} frames in {Sec:F0}s", jobId, framesSaved, totalFrames, sw.Elapsed.TotalSeconds);
return new RenderResult(true, 0, true, null, tail.ToString(), fullLogPath, sw.Elapsed.TotalSeconds);
}
/// <summary>
/// Reads a stream treating both CR and LF as line terminators, so
/// Blender's carriage-return progress updates are seen as they happen
/// rather than only when a newline eventually arrives.
/// </summary>
private static async Task PumpAsync(StreamReader reader, Action<string> onLine)
{
var buffer = new char[4096];
var current = new StringBuilder(256);
int read;
try
{
while ((read = await reader.ReadAsync(buffer, 0, buffer.Length)) > 0)
{
for (var i = 0; i < read; i++)
{
var c = buffer[i];
if (c == '\r' || c == '\n')
{
if (current.Length > 0)
{
onLine(current.ToString());
current.Clear();
}
}
else
{
current.Append(c);
}
}
}
if (current.Length > 0) onLine(current.ToString());
}
catch (Exception)
{
// The process died mid-read; the exit path reports what happened.
}
}
private static void KillTree(Process process)
{
try { if (!process.HasExited) process.Kill(entireProcessTree: true); } catch { }
}
private static async Task WaitForExitSafe(Process process)
{
try { await process.WaitForExitAsync(); } catch { }
}
}
@@ -0,0 +1,399 @@
using System.Globalization;
using System.Runtime.InteropServices;
using System.Text;
using System.Text.Json;
using Microsoft.Extensions.Logging;
namespace VFXReviewWorker;
/// <summary>
/// Delivery builder (RenderPipeline2 §11). Creates the dated package folder,
/// hard-links (or copies) each shot's EXRs and delivery MOV into it, verifies
/// what it wrote, and leaves a manifest + CSV report beside the shots.
///
/// Hard links make an 18-shot EXR package near-instant and cost no extra disk.
/// They are safe here because rendered versions are immutable by pipeline
/// design — a new version is a new directory, nothing ever rewrites an EXR in
/// place. Cross-volume targets fall back to copying automatically.
/// </summary>
public sealed class DeliveryStage
{
private readonly WorkerOptions _options;
private readonly ApiClient _api;
private readonly ILogger<DeliveryStage> _log;
public DeliveryStage(WorkerOptions options, ApiClient api, ILogger<DeliveryStage> log)
{
_options = options;
_api = api;
_log = log;
}
public async Task<DeliveryResult> RunAsync(
ClaimedJob job, DeliveryManifest manifest, string machineId, CancellationToken cancelJob, CancellationToken shutdown)
{
var mapper = new PathMapper(_options.PathMappings);
var packageDir = mapper.Map(manifest.PackageDir);
var results = new List<DeliveryItemResult>();
var manifestFiles = new List<object>();
var alwaysCopy = string.Equals(manifest.CopyMode, "always-copy", StringComparison.OrdinalIgnoreCase);
var alwaysHash = string.Equals(manifest.VerifyMode, "always-hash", StringComparison.OrdinalIgnoreCase);
_log.LogInformation("Building delivery package {Name} ({Count} shots) at {Dir}",
manifest.PackageName, manifest.Items.Count, packageDir);
Directory.CreateDirectory(packageDir);
for (var i = 0; i < manifest.Items.Count; i++)
{
if (cancelJob.IsCancellationRequested) break;
var item = manifest.Items[i];
await _api.ProgressAsync(job.Id, machineId, (double)i / manifest.Items.Count, i, manifest.Items.Count, null,
$"Packaging {item.ShotCode} {item.VersionString} ({i + 1}/{manifest.Items.Count})", shutdown);
var result = BuildItem(item, mapper, alwaysCopy, alwaysHash, manifestFiles);
results.Add(result);
if (result.Status == "FAILED")
{
_log.LogError("Delivery item {Shot} failed: {Error}", item.ShotCode, result.ErrorMessage);
}
}
var ok = results.Count == manifest.Items.Count && results.All(r => r.Status == "VERIFIED");
// The report is the client-facing document, so it is written even for a
// partial build — it is the fastest way to see what did and did not land.
string? reportPath = null;
try
{
reportPath = WriteReport(manifest, results, mapper);
WriteManifestJson(manifest, results, manifestFiles, packageDir);
}
catch (Exception ex)
{
_log.LogWarning(ex, "Could not write delivery report/manifest for {Name}", manifest.PackageName);
}
return new DeliveryResult(ok, results, packageDir, reportPath, manifestFiles);
}
private DeliveryItemResult BuildItem(
DeliveryManifestItem item, PathMapper mapper, bool alwaysCopy, bool alwaysHash, List<object> manifestFiles)
{
var sourceDir = mapper.Map(item.SourceDir);
var shotDir = mapper.Map(item.ShotDir);
try
{
if (!Directory.Exists(sourceDir))
{
return DeliveryItemResult.Failed(item, $"Source folder not found: {sourceDir}");
}
var pattern = SequencePattern.FromOutputPattern(item.OutputPattern);
var sources = Directory.EnumerateFiles(sourceDir)
.Where(f => Path.GetFileName(f).StartsWith(pattern.Prefix, StringComparison.OrdinalIgnoreCase)
&& Path.GetFileName(f).EndsWith(pattern.Extension, StringComparison.OrdinalIgnoreCase))
.OrderBy(f => f, StringComparer.Ordinal)
.ToList();
if (sources.Count == 0)
{
return DeliveryItemResult.Failed(item, $"No {pattern.Extension} files matching {pattern.Prefix}* in {sourceDir}");
}
if (item.FileCount is int expected && sources.Count != expected)
{
return DeliveryItemResult.Failed(item,
$"Source has {sources.Count} frames but the export recorded {expected} — the render changed since QC");
}
Directory.CreateDirectory(shotDir);
// Delivered names carry the client-facing base (or the studio's own
// convention when no client code is set), not the internal render
// filename — only the frame number and extension survive from the
// source. A frame whose number can't be parsed falls back to the
// source filename verbatim rather than failing the whole delivery.
var destNames = sources.ToDictionary(s => s, s => DeliveredFrameName(s, item, pattern));
long totalBytes = 0;
var usedCopy = false;
foreach (var src in sources)
{
var dest = Path.Combine(shotDir, destNames[src]);
if (Place(src, dest, alwaysCopy, out var copied) is string placeError)
{
return DeliveryItemResult.Failed(item, placeError);
}
usedCopy |= copied;
totalBytes += new FileInfo(dest).Length;
}
// Verification is proportional to what was actually done.
//
// A hard link is a second name for the same data, so hashing it
// re-reads the exact bytes validation already hashed — it cannot
// disagree, and at ~100 MB/s over SMB it costs half an hour for an
// episode to prove nothing. A copy is different: it can be
// truncated or corrupted, so it is read back in full.
string? digest;
string verifiedBy;
if (usedCopy || alwaysHash)
{
digest = SequenceChecksum(sources.Select(s => Path.Combine(shotDir, destNames[s])));
if (item.Checksum is { Length: > 0 } && !string.Equals(digest, item.Checksum, StringComparison.OrdinalIgnoreCase))
{
return DeliveryItemResult.Failed(item,
$"Checksum mismatch after packaging: expected {item.Checksum}, got {digest}");
}
verifiedBy = "hash";
}
else
{
// The one thing linking cannot rule out is the source having
// changed since it passed QC — the link would faithfully carry
// the new bytes. Timestamps answer that for the price of a stat.
if (item.ValidatedAt is DateTimeOffset validatedAt)
{
var touched = sources
.Select(s => new FileInfo(s))
.Where(f => f.LastWriteTimeUtc > validatedAt.UtcDateTime.AddSeconds(1))
.ToList();
if (touched.Count > 0)
{
return DeliveryItemResult.Failed(item,
$"{touched.Count} source file(s) were modified after validation " +
$"({touched[0].Name} at {touched[0].LastWriteTimeUtc:u}, validated {validatedAt.UtcDateTime:u}) — " +
"the render changed after it passed QC");
}
}
// Same data as the source, so the validation-time digest describes
// the delivered files exactly.
digest = item.Checksum;
verifiedBy = "link identity";
}
_log.LogDebug("{Shot}: verified by {How}", item.ShotCode, verifiedBy);
string? movDest = null;
if (!string.IsNullOrWhiteSpace(item.DeliveryMovPath))
{
var movSrc = mapper.Map(item.DeliveryMovPath!);
if (File.Exists(movSrc))
{
var movName = string.IsNullOrWhiteSpace(item.DeliveredBaseName)
? Path.GetFileName(movSrc)
: item.DeliveredBaseName + Path.GetExtension(movSrc);
movDest = Path.Combine(shotDir, movName);
if (Place(movSrc, movDest, alwaysCopy, out var movCopied) is string movError)
{
return DeliveryItemResult.Failed(item, movError);
}
usedCopy |= movCopied;
totalBytes += new FileInfo(movDest).Length;
}
else
{
// Not fatal: the EXRs are the deliverable, the MOV is a
// viewing copy. It is recorded so it is not silently absent.
_log.LogWarning("Delivery MOV missing for {Shot}: {Path}", item.ShotCode, movSrc);
}
}
foreach (var src in sources)
{
var name = destNames[src];
manifestFiles.Add(new
{
shotCode = item.ShotCode,
relativePath = Path.Combine(Path.GetFileName(shotDir), name).Replace('\\', '/'),
bytes = new FileInfo(Path.Combine(shotDir, name)).Length,
exportId = item.ExportId,
});
}
return new DeliveryItemResult
{
ItemId = item.ItemId,
ShotCode = item.ShotCode,
VersionString = item.VersionString,
Status = "VERIFIED",
ExrPath = shotDir,
MovPath = movDest,
FileCount = sources.Count,
TotalBytes = totalBytes,
Checksum = digest,
LinkMode = usedCopy ? "copy" : "hardlink",
FrameStart = item.FrameStart,
FrameEnd = item.FrameEnd,
};
}
catch (Exception ex)
{
return DeliveryItemResult.Failed(item, $"{ex.GetType().Name}: {ex.Message}");
}
}
/// <summary>
/// Hard-link when possible, copy when not. Returns null on success or the
/// error message. `copied` reports which happened, so the package records
/// what it actually did rather than what it intended.
/// </summary>
private string? Place(string source, string dest, bool alwaysCopy, out bool copied)
{
copied = false;
try
{
if (File.Exists(dest)) File.Delete(dest);
if (!alwaysCopy && CreateHardLink(dest, source, IntPtr.Zero))
{
return null;
}
// Cross-volume, a filesystem without link support, or always-copy.
File.Copy(source, dest, overwrite: true);
copied = true;
return null;
}
catch (Exception ex)
{
return $"Could not place {Path.GetFileName(source)}: {ex.Message}";
}
}
/// <summary>
/// The delivered filename for one source frame: DeliveredBaseName with the
/// frame number (re-padded to the render's own convention) and extension —
/// never the internal render filename it was copied from. Falls back to
/// the source filename verbatim (never fatal) when there's no client-facing
/// base to use, or the frame number can't be parsed out of the source name.
/// </summary>
internal string DeliveredFrameName(string src, DeliveryManifestItem item, SequencePattern pattern)
{
var sourceName = Path.GetFileName(src);
if (string.IsNullOrWhiteSpace(item.DeliveredBaseName))
{
return sourceName;
}
var frame = pattern.FrameNumberOf(sourceName);
if (frame is null)
{
_log.LogWarning("Could not parse a frame number out of {Name} for {Shot} — delivering under its original name",
sourceName, item.ShotCode);
return sourceName;
}
var padding = Math.Max(1, pattern.Padding);
return $"{item.DeliveredBaseName}.{frame.Value.ToString().PadLeft(padding, '0')}{pattern.Extension}";
}
private static string SequenceChecksum(IEnumerable<string> files)
{
var state = new XxHash64.State(0);
foreach (var f in files)
{
state.Update(Encoding.ASCII.GetBytes(XxHash64.HashFile(f)));
}
return state.Digest().ToString("x16");
}
/// <summary>
/// The client-facing delivery report (§11.4): one row per shot. Columns are
/// confirmed against the production's delivery spec before the first real
/// delivery (18.2-C2), which is why this is a plain, easily-edited writer.
/// </summary>
private string WriteReport(DeliveryManifest manifest, List<DeliveryItemResult> results, PathMapper mapper)
{
var path = mapper.Map(manifest.ReportFile);
var dir = Path.GetDirectoryName(path);
if (dir is not null) Directory.CreateDirectory(dir);
var sb = new StringBuilder();
sb.AppendLine("Shot,Version,FrameStart,FrameEnd,FrameCount,Files,Bytes,Checksum,MOV,Status");
foreach (var r in results)
{
sb.AppendLine(string.Join(",", new[]
{
Csv(r.ShotCode),
Csv(r.VersionString),
r.FrameStart.ToString(CultureInfo.InvariantCulture),
r.FrameEnd.ToString(CultureInfo.InvariantCulture),
(r.FrameEnd - r.FrameStart + 1).ToString(CultureInfo.InvariantCulture),
(r.FileCount ?? 0).ToString(CultureInfo.InvariantCulture),
(r.TotalBytes ?? 0).ToString(CultureInfo.InvariantCulture),
Csv(r.Checksum ?? ""),
Csv(r.MovPath is null ? "" : Path.GetFileName(r.MovPath)),
Csv(r.Status),
}));
}
File.WriteAllText(path, sb.ToString(), new UTF8Encoding(false));
_log.LogInformation("Wrote delivery report {Path}", path);
return path;
}
private void WriteManifestJson(
DeliveryManifest manifest, List<DeliveryItemResult> results, List<object> files, string packageDir)
{
var payload = new
{
package = manifest.PackageName,
packageNumber = manifest.PackageNumber,
episode = manifest.Episode,
builtAt = DateTimeOffset.UtcNow,
builtBy = Environment.MachineName,
checksumAlgo = manifest.ChecksumAlgo,
shots = results.Select(r => new
{
r.ShotCode,
r.VersionString,
r.FileCount,
r.TotalBytes,
r.Checksum,
r.LinkMode,
r.Status,
r.ErrorMessage,
}),
files,
};
var path = Path.Combine(packageDir, "manifest.json");
File.WriteAllText(path, JsonSerializer.Serialize(payload, WorkerOptions.JsonOpts), new UTF8Encoding(false));
}
private static string Csv(string value) =>
value.Contains(',') || value.Contains('"') ? "\"" + value.Replace("\"", "\"\"") + "\"" : value;
[DllImport("Kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
[return: MarshalAs(UnmanagedType.Bool)]
private static extern bool CreateHardLink(string lpFileName, string lpExistingFileName, IntPtr lpSecurityAttributes);
}
public sealed record DeliveryResult(
bool Ok, List<DeliveryItemResult> Items, string PackageDir, string? ReportPath, List<object> Files);
public sealed class DeliveryItemResult
{
public string ItemId { get; set; } = "";
public string ShotCode { get; set; } = "";
public string VersionString { get; set; } = "";
public string Status { get; set; } = "PENDING";
public string? ExrPath { get; set; }
public string? MovPath { get; set; }
public int? FileCount { get; set; }
public long? TotalBytes { get; set; }
public string? Checksum { get; set; }
public string? LinkMode { get; set; }
public string? ErrorMessage { get; set; }
public int FrameStart { get; set; }
public int FrameEnd { get; set; }
public static DeliveryItemResult Failed(DeliveryManifestItem item, string error) => new()
{
ItemId = item.ItemId,
ShotCode = item.ShotCode,
VersionString = item.VersionString,
Status = "FAILED",
ErrorMessage = error,
FrameStart = item.FrameStart,
FrameEnd = item.FrameEnd,
};
}
+132 -1
View File
@@ -26,6 +26,15 @@ public sealed class ServerConfig
public int LeaseSeconds { get; set; } = 300;
public int MaxAttempts { get; set; } = 3;
public int StallTimeoutSeconds { get; set; } = 600;
/// <summary>
/// Validation stage (§8). The server decides whether it runs, so turning it
/// off is a config change there rather than a redeploy of every worker.
/// </summary>
public bool ValidationEnabled { get; set; } = true;
public int ValidationSampleEvery { get; set; } = 25;
/// <summary>Head handles the plates carry; only used for the API timecode fallback (§8.1a).</summary>
public int ValidationHandleFrames { get; set; } = 8;
}
public sealed class ClaimResponse
@@ -40,6 +49,9 @@ public sealed class ClaimedJob
public int Attempt { get; set; }
public int MaxAttempts { get; set; }
public string? ExportId { get; set; }
public string? DeliveryId { get; set; }
/// <summary>Set for jobs with no shot behind them; shown instead of a shot code.</summary>
public string? Label { get; set; }
public DateTimeOffset? LeaseExpiresAt { get; set; }
/// <summary>Manifest shape depends on the job type — deserialize per stage.</summary>
@@ -52,6 +64,80 @@ public sealed class ClaimedJob
public PreviewManifest AsPreviewManifest() =>
Manifest.Deserialize<PreviewManifest>(WorkerOptions.JsonOpts)
?? throw new InvalidOperationException("Job manifest is not a preview manifest");
public DeliveryManifest AsDeliveryManifest() =>
Manifest.Deserialize<DeliveryManifest>(WorkerOptions.JsonOpts)
?? throw new InvalidOperationException("Job manifest is not a delivery manifest");
public BlenderManifest AsBlenderManifest() =>
Manifest.Deserialize<BlenderManifest>(WorkerOptions.JsonOpts)
?? throw new InvalidOperationException("Job manifest is not a Blender manifest");
}
/// <summary>
/// A standalone Blender render. Overrides are all optional: an unset value
/// leaves whatever the .blend was saved with, which is the point — the file is
/// expected to be ready to render.
/// </summary>
public sealed class BlenderManifest
{
public string Stage { get; set; } = "BLENDER";
public string BlendFile { get; set; } = "";
public string? Scene { get; set; }
public int FrameStart { get; set; }
public int FrameEnd { get; set; }
public string? OutputPath { get; set; }
public string? Engine { get; set; }
public string? Device { get; set; }
public int? Samples { get; set; }
public int? ResolutionPercent { get; set; }
public string? BlenderVersion { get; set; }
public int TotalFrames => FrameEnd - FrameStart + 1;
}
/// <summary>DELIVERY_BUILD manifest (server-built, RenderPipeline2 §11).</summary>
public sealed class DeliveryManifest
{
public string Stage { get; set; } = "DELIVERY";
public string PackageId { get; set; } = "";
public string PackageName { get; set; } = "";
public int PackageNumber { get; set; }
public string Episode { get; set; } = "";
public string PackageDir { get; set; } = "";
public string ReportFile { get; set; } = "";
public bool IncludeMovs { get; set; } = true;
public string CopyMode { get; set; } = "auto";
/// <summary>"auto" verifies copies by hash and links by identity; "always-hash" reads everything back.</summary>
public string VerifyMode { get; set; } = "auto";
public string ChecksumAlgo { get; set; } = "xxh64";
public List<string> ReportFormats { get; set; } = new();
public List<DeliveryManifestItem> Items { get; set; } = new();
}
public sealed class DeliveryManifestItem
{
public string ItemId { get; set; } = "";
public string ExportId { get; set; } = "";
public string ShotCode { get; set; } = "";
public string VersionString { get; set; } = "";
public string SourceDir { get; set; } = "";
public string OutputPattern { get; set; } = "";
public int FrameStart { get; set; }
public int FrameEnd { get; set; }
public int? FileCount { get; set; }
public string? Checksum { get; set; }
public string? DeliveryMovPath { get; set; }
public string ShotDir { get; set; } = "";
/// <summary>
/// Server-computed: "{clientCode}_{versionString}" when the shot has a
/// client naming code, else the studio's own "{shotCode}_cmp_TT_{versionString}".
/// The delivered EXR sequence and MOV are named from this, not the
/// internal render filename they're copied from.
/// </summary>
public string DeliveredBaseName { get; set; } = "";
/// <summary>When this export's validation ran — lets a linked package detect a source changed since QC.</summary>
public DateTimeOffset? ValidatedAt { get; set; }
}
/// <summary>PREVIEW_ONLY manifest (server-built, RenderPipeline2 §9).</summary>
@@ -88,6 +174,8 @@ public sealed class SlateInfo
public string? Description { get; set; }
public string? Notes { get; set; }
public string ShotCode { get; set; } = "";
/// <summary>Production name, burned into the slate and the overlay.</summary>
public string? Show { get; set; }
public string? Episode { get; set; }
public string? Scene { get; set; }
public string? VfxScope { get; set; }
@@ -107,17 +195,31 @@ public sealed class PreviewBuildResult
public int? Height { get; set; }
}
/// <summary>The Render Manifest (§6.2) — only the fields the Phase 2 render stage needs; the rest is preserved raw.</summary>
/// <summary>The Render Manifest (§6.2) — the fields the render and validation stages need; the rest is preserved raw.</summary>
public sealed class RenderManifest
{
public string ShotCode { get; set; } = "";
public string AepPath { get; set; } = "";
public string CompName { get; set; } = "";
public string OutputDir { get; set; } = "";
public string OutputPattern { get; set; } = "";
public string? OutputModuleTemplate { get; set; }
public string? RenderSettingsTemplate { get; set; }
/// <summary>Comp timeline range handed to aerender (-s/-e).</summary>
public int FrameStart { get; set; }
public int FrameEnd { get; set; }
/// <summary>
/// The number the *first output file* carries — the output module's
/// starting number (house convention 1001), which is deliberately not the
/// comp's frame range: a comp anchored to the plate's timecode starts in
/// the millions. Null on manifests predating this field.
/// </summary>
public int? OutputFrameStart { get; set; }
public double Fps { get; set; } = 24;
public int Width { get; set; }
public int Height { get; set; }
public ManifestExpected? Expected { get; set; }
public ManifestSource? Source { get; set; }
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
@@ -125,6 +227,35 @@ public sealed class RenderManifest
public int TotalFrames => FrameEnd - FrameStart + 1;
}
/// <summary>Per-project expectations the validation engine checks against (§8.1).</summary>
public sealed class ManifestExpected
{
public string? Colorspace { get; set; }
public string? BitDepth { get; set; }
public string? ExrCompression { get; set; }
public bool? Alpha { get; set; }
/// <summary>The API's editorial in-point — the rank 3 timecode fallback only (§8.1a).</summary>
public string? TimecodeStart { get; set; }
}
/// <summary>Plate provenance resolved by the panel from the comp's footage layers (§6.2).</summary>
public sealed class ManifestSource
{
public PlateRef? TimingPlate { get; set; }
public List<PlateRef> Plates { get; set; } = new();
public string? StartSource { get; set; }
public int? StartFrames { get; set; }
public int? HandleFrames { get; set; }
}
public sealed class PlateRef
{
public string? Element { get; set; }
public string Path { get; set; } = "";
public int? FrameStart { get; set; }
public int? FrameEnd { get; set; }
}
public sealed class ProgressResponse
{
public bool Ok { get; set; }
+234
View File
@@ -0,0 +1,234 @@
using System.Text;
namespace VFXReviewWorker;
/// <summary>
/// Minimal OpenEXR header reader (RenderPipeline2 §8.1a).
///
/// Everything validation needs — timecode, fps, resolution, channel types,
/// compression — lives in the header, so a check costs one 64 KB read and no
/// pixel decode. That is why the engine needs no oiiotool/OpenImageIO
/// dependency and can run on a bare workstation.
///
/// Header layout: magic(4) version(4) then attributes as
/// `name\0 type\0 int32 size data`, terminated by an empty name.
/// </summary>
public sealed class ExrHeader
{
public const uint Magic = 20000630;
private const int MaxHeaderBytes = 1 << 18; // 256 KB — far beyond any sane header
public int DataWidth { get; private init; }
public int DataHeight { get; private init; }
public int DisplayWidth { get; private init; }
public int DisplayHeight { get; private init; }
public IReadOnlyList<ExrChannel> Channels { get; private init; } = Array.Empty<ExrChannel>();
public byte? CompressionCode { get; private init; }
public Timecode? Timecode { get; private init; }
public string? TimecodeString { get; private init; }
public double? FramesPerSecond { get; private init; }
public bool HasChromaticities { get; private init; }
public bool IsTiled { get; private init; }
public IReadOnlyList<string> AttributeNames { get; private init; } = Array.Empty<string>();
public bool HasAlpha => Channels.Any(c => c.Name.Equals("A", StringComparison.Ordinal));
/// <summary>half / float / uint — the deepest channel type present.</summary>
public string? BitDepth
{
get
{
if (Channels.Count == 0) return null;
if (Channels.Any(c => c.PixelType == 2)) return "float";
if (Channels.Any(c => c.PixelType == 1)) return "half";
return "uint";
}
}
public string CompressionName => CompressionCode switch
{
0 => "none", 1 => "RLE", 2 => "ZIPS", 3 => "ZIP", 4 => "PIZ",
5 => "PXR24", 6 => "B44", 7 => "B44A", 8 => "DWAA", 9 => "DWAB",
null => "unknown",
_ => $"code {CompressionCode}",
};
/// <summary>Reads the header, or throws <see cref="InvalidDataException"/> when the file is not a readable EXR.</summary>
public static ExrHeader Read(string path)
{
using var fs = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite);
var buf = new byte[Math.Min(MaxHeaderBytes, Math.Max(1024, (int)Math.Min(fs.Length, MaxHeaderBytes)))];
var read = fs.Read(buf, 0, buf.Length);
if (read < 16) throw new InvalidDataException("File is too small to be an EXR");
var span = new ReadOnlySpan<byte>(buf, 0, read);
if (BitConverter.ToUInt32(span[..4]) != Magic) throw new InvalidDataException("Not an EXR (bad magic number)");
var version = BitConverter.ToInt32(span.Slice(4, 4));
int pos = 8;
var names = new List<string>();
var channels = new List<ExrChannel>();
int dataW = 0, dataH = 0, dispW = 0, dispH = 0;
byte? compression = null;
Timecode? tc = null;
string? tcString = null;
double? fps = null;
bool chroma = false;
while (pos < read)
{
var name = ReadCString(span, ref pos);
if (name.Length == 0) break; // end of header
var type = ReadCString(span, ref pos);
if (pos + 4 > read) throw new InvalidDataException("Truncated EXR header (attribute size)");
var size = BitConverter.ToInt32(span.Slice(pos, 4));
pos += 4;
if (size < 0 || pos + size > read) throw new InvalidDataException($"Truncated EXR header (attribute \"{name}\")");
var data = span.Slice(pos, size);
names.Add(name);
switch (name)
{
case "dataWindow" when size >= 16:
dataW = BitConverter.ToInt32(data.Slice(8, 4)) - BitConverter.ToInt32(data[..4]) + 1;
dataH = BitConverter.ToInt32(data.Slice(12, 4)) - BitConverter.ToInt32(data.Slice(4, 4)) + 1;
break;
case "displayWindow" when size >= 16:
dispW = BitConverter.ToInt32(data.Slice(8, 4)) - BitConverter.ToInt32(data[..4]) + 1;
dispH = BitConverter.ToInt32(data.Slice(12, 4)) - BitConverter.ToInt32(data.Slice(4, 4)) + 1;
break;
case "compression" when size >= 1:
compression = data[0];
break;
case "timeCode" when size >= 8:
tc = VFXReviewWorker.Timecode.FromPacked(
BitConverter.ToUInt32(data[..4]), BitConverter.ToUInt32(data.Slice(4, 4)));
break;
case "timeCodeString":
tcString = Encoding.ASCII.GetString(data).TrimEnd('\0');
break;
case "framesPerSecond" when size >= 8:
{
var num = BitConverter.ToInt32(data[..4]);
var den = BitConverter.ToUInt32(data.Slice(4, 4));
if (den != 0) fps = num / (double)den;
break;
}
case "chromaticities":
chroma = true;
break;
case "channels":
channels.AddRange(ReadChannels(data));
break;
}
pos += size;
}
return new ExrHeader
{
DataWidth = dataW,
DataHeight = dataH,
DisplayWidth = dispW,
DisplayHeight = dispH,
Channels = channels,
CompressionCode = compression,
Timecode = tc,
TimecodeString = tcString,
FramesPerSecond = fps,
HasChromaticities = chroma,
IsTiled = (version & 0x200) != 0,
AttributeNames = names,
};
}
/// <summary>Header read that returns null instead of throwing — for "is this file readable at all" checks.</summary>
public static ExrHeader? TryRead(string path)
{
try { return Read(path); }
catch { return null; }
}
private static IEnumerable<ExrChannel> ReadChannels(ReadOnlySpan<byte> data)
{
var result = new List<ExrChannel>();
int p = 0;
while (p < data.Length)
{
var name = ReadCString(data, ref p);
if (name.Length == 0) break; // null terminator ends the channel list
if (p + 16 > data.Length) break;
var pixelType = BitConverter.ToInt32(data.Slice(p, 4));
p += 16; // pixelType(4) + pLinear(1) + reserved(3) + xSampling(4) + ySampling(4)
result.Add(new ExrChannel(name, pixelType));
}
return result;
}
private static string ReadCString(ReadOnlySpan<byte> span, ref int pos)
{
int start = pos;
while (pos < span.Length && span[pos] != 0) pos++;
var s = Encoding.ASCII.GetString(span[start..pos]);
pos++; // skip the terminator
return s;
}
}
public readonly record struct ExrChannel(string Name, int PixelType)
{
public string TypeName => PixelType switch { 0 => "uint", 1 => "half", 2 => "float", _ => $"type {PixelType}" };
}
/// <summary>
/// SMPTE 12M timecode as stored in the EXR `timeCode` attribute: BCD-packed,
/// which is why the raw value reads back as its own hex digits
/// (0x18585712 → 18:58:57:12).
/// </summary>
public readonly record struct Timecode(int Hours, int Minutes, int Seconds, int Frames, bool DropFrame)
{
public static Timecode FromPacked(uint timeAndFlags, uint _userData = 0)
{
int Bits(int shift, int mask) => (int)((timeAndFlags >> shift) & (uint)mask);
return new Timecode(
Bits(24, 0xF) + Bits(28, 0x3) * 10,
Bits(16, 0xF) + Bits(20, 0x7) * 10,
Bits(8, 0xF) + Bits(12, 0x7) * 10,
Bits(0, 0xF) + Bits(4, 0x3) * 10,
Bits(6, 0x1) == 1);
}
public static Timecode? Parse(string? text, bool dropFrame = false)
{
if (string.IsNullOrWhiteSpace(text)) return null;
var parts = text.Trim().Split(':', ';');
if (parts.Length < 4) return null;
if (!int.TryParse(parts[0], out var hh) || !int.TryParse(parts[1], out var mm) ||
!int.TryParse(parts[2], out var ss) || !int.TryParse(parts[3], out var ff)) return null;
return new Timecode(hh, mm, ss, ff, dropFrame || text.Contains(';'));
}
/// <summary>
/// Non-drop frame count. The studio shoots 24 fps, so drop-frame never
/// applies; a drop-frame flag mismatch is reported as its own check rather
/// than silently changing this arithmetic.
/// </summary>
public long ToFrames(double fps)
{
var rate = (long)Math.Round(fps <= 0 ? 24 : fps);
return ((Hours * 60L + Minutes) * 60L + Seconds) * rate + Frames;
}
public static Timecode FromFrames(long frames, double fps)
{
var rate = (long)Math.Round(fps <= 0 ? 24 : fps);
if (rate <= 0) rate = 24;
var f = Math.Max(0, frames);
var ff = (int)(f % rate);
var totalSeconds = f / rate;
return new Timecode((int)(totalSeconds / 3600), (int)(totalSeconds / 60 % 60), (int)(totalSeconds % 60), ff, false);
}
public override string ToString() =>
$"{Hours:D2}:{Minutes:D2}:{Seconds:D2}{(DropFrame ? ';' : ':')}{Frames:D2}";
}
+231 -1
View File
@@ -14,15 +14,22 @@ public sealed class JobExecutor
private readonly ApiClient _api;
private readonly AerenderRunner _runner;
private readonly PreviewStage _preview;
private readonly ValidationStage _validation;
private readonly DeliveryStage _delivery;
private readonly BlenderRunner _blender;
private readonly ReportSpooler _spooler;
private readonly ILogger<JobExecutor> _log;
public JobExecutor(WorkerOptions options, ApiClient api, AerenderRunner runner, PreviewStage preview, ReportSpooler spooler, ILogger<JobExecutor> log)
public JobExecutor(WorkerOptions options, ApiClient api, AerenderRunner runner, PreviewStage preview,
ValidationStage validation, DeliveryStage delivery, BlenderRunner blender, ReportSpooler spooler, ILogger<JobExecutor> log)
{
_options = options;
_api = api;
_runner = runner;
_preview = preview;
_validation = validation;
_delivery = delivery;
_blender = blender;
_spooler = spooler;
_log = log;
}
@@ -35,6 +42,18 @@ public sealed class JobExecutor
return;
}
if (job.Type == "DELIVERY_BUILD")
{
await RunDeliveryAsync(job, machineId, cancelJob, shutdown);
return;
}
if (job.Type == "BLENDER_RENDER")
{
await RunBlenderAsync(job, machineId, config, cancelJob, shutdown);
return;
}
var manifest = job.AsRenderManifest();
var mapper = new PathMapper(_options.PathMappings);
var outputDirLocal = mapper.Map(manifest.OutputDir);
@@ -101,6 +120,15 @@ public sealed class JobExecutor
["exrFileCount"] = fileCount,
["exrTotalBytes"] = totalBytes,
});
// Validation runs here, while we still hold the job and the
// files are local. It is queued behind complete-render, and the
// spooler's in-order replay is what guarantees the server has
// moved the Export to VALIDATING before this lands (§8).
if (config.ValidationEnabled)
{
await RunValidationAsync(job, manifest, machineId, outputDirLocal, config, shutdown);
}
}
else if (result.ErrorMessage == "Cancelled")
{
@@ -149,6 +177,208 @@ public sealed class JobExecutor
}
}
/// <summary>
/// BLENDER_RENDER job: a standalone render with no Export behind it, so
/// there is nothing to validate, preview or QC — it finishes at
/// complete-render and that is the whole lifecycle.
/// </summary>
private async Task RunBlenderAsync(ClaimedJob job, string machineId, ServerConfig config,
CancellationToken cancelJob, CancellationToken shutdown)
{
var manifest = job.AsBlenderManifest();
WriteState(new CurrentJobState
{
JobId = job.Id,
ExportId = null,
MachineId = machineId,
OutputDirLocal = manifest.OutputPath ?? "",
ClaimedAt = DateTimeOffset.UtcNow,
});
try
{
var result = await _blender.RunAsync(job, manifest, machineId, config, cancelJob, shutdown);
var logKey = string.IsNullOrEmpty(result.FullLogPath)
? null
: await _api.UploadLogAsync(job.Id, machineId, result.FullLogPath, shutdown);
if (result.Success)
{
_log.LogInformation("Blender job {JobId} complete: {Frames} frames in {Sec:F0}s",
job.Id, manifest.TotalFrames, result.RenderSeconds);
_spooler.Enqueue("complete-render", job.Id, new Dictionary<string, object?>
{
["machineId"] = machineId,
["renderSeconds"] = (int)result.RenderSeconds,
["logFileKey"] = logKey,
["logTail"] = result.LogTail,
});
return;
}
_spooler.Enqueue("fail", job.Id, new Dictionary<string, object?>
{
["machineId"] = machineId,
["stage"] = "BLENDER",
["exitCode"] = result.ExitCode,
["errorMessage"] = result.ErrorMessage,
["logTail"] = result.LogTail,
["logFileKey"] = logKey,
["retryable"] = result.ErrorMessage == "Cancelled" ? false : result.Retryable,
});
}
catch (Exception ex)
{
_log.LogError(ex, "Unexpected Blender error for job {JobId}", job.Id);
_spooler.Enqueue("fail", job.Id, new Dictionary<string, object?>
{
["machineId"] = machineId,
["stage"] = "BLENDER",
["errorMessage"] = $"Worker exception: {ex.Message}",
["retryable"] = true,
});
}
finally
{
ClearState();
}
}
/// <summary>
/// DELIVERY_BUILD job: build the dated package folder from already-QC'd
/// exports. No AE involved — folders, links and verification only.
/// </summary>
private async Task RunDeliveryAsync(ClaimedJob job, string machineId, CancellationToken cancelJob, CancellationToken shutdown)
{
var manifest = job.AsDeliveryManifest();
WriteState(new CurrentJobState
{
JobId = job.Id,
ExportId = null,
MachineId = machineId,
OutputDirLocal = new PathMapper(_options.PathMappings).Map(manifest.PackageDir),
ClaimedAt = DateTimeOffset.UtcNow,
});
try
{
var result = await _delivery.RunAsync(job, manifest, machineId, cancelJob, shutdown);
_log.LogInformation("Delivery {Name}: {Ok} ({Verified}/{Total} shots verified)",
manifest.PackageName, result.Ok ? "READY" : "FAILED",
result.Items.Count(i => i.Status == "VERIFIED"), manifest.Items.Count);
string? reportKey = null;
if (result.ReportPath is not null)
{
reportKey = await _api.UploadArtifactAsync(job.Id, machineId, "report", result.ReportPath, "text/csv", shutdown);
}
_spooler.Enqueue("delivery", job.Id, new Dictionary<string, object?>
{
["machineId"] = machineId,
["ok"] = result.Ok,
["rootPath"] = result.PackageDir,
["reportKey"] = reportKey,
["items"] = result.Items.Select(i => new Dictionary<string, object?>
{
["itemId"] = i.ItemId,
["status"] = i.Status,
["exrPath"] = i.ExrPath,
["movPath"] = i.MovPath,
["fileCount"] = i.FileCount,
["totalBytes"] = i.TotalBytes,
["checksum"] = i.Checksum,
["linkMode"] = i.LinkMode,
["errorMessage"] = i.ErrorMessage,
}).ToList(),
["manifest"] = new Dictionary<string, object?>
{
["packageDir"] = result.PackageDir,
["reportPath"] = result.ReportPath,
["files"] = result.Files,
},
["errorMessage"] = result.Ok
? null
: string.Join("; ", result.Items.Where(i => i.Status == "FAILED").Select(i => $"{i.ShotCode}: {i.ErrorMessage}").Take(5)),
});
}
catch (Exception ex)
{
_log.LogError(ex, "Unexpected delivery error for job {JobId}", job.Id);
_spooler.Enqueue("delivery", job.Id, new Dictionary<string, object?>
{
["machineId"] = machineId,
["ok"] = false,
["items"] = new List<object>(),
["errorMessage"] = $"Worker exception: {ex.Message}",
});
}
finally
{
ClearState();
}
}
/// <summary>
/// Runs the validation engine and spools the E12 report. Deliberately
/// non-fatal on its own errors: a crash in the checks must not lose a
/// finished render, so it is reported as a failed validation run rather
/// than being allowed to escape.
/// </summary>
private async Task RunValidationAsync(
ClaimedJob job, RenderManifest manifest, string machineId, string outputDirLocal,
ServerConfig config, CancellationToken shutdown)
{
var started = DateTimeOffset.UtcNow;
try
{
// Keep the lease alive: the job stays open through validation.
await _api.ProgressAsync(job.Id, machineId, 1.0, manifest.FrameEnd, manifest.TotalFrames, 0,
"Validating rendered sequence…", shutdown);
var outcome = await Task.Run(() => _validation.Run(manifest, outputDirLocal, config), shutdown);
var seconds = (DateTimeOffset.UtcNow - started).TotalSeconds;
var failed = outcome.Checks.Where(c => c.Status == "FAIL").Select(c => c.CheckName).ToList();
if (failed.Count > 0)
{
_log.LogWarning("Job {JobId} validation FAILED in {Sec:F1}s: {Checks}", job.Id, seconds, string.Join(", ", failed));
}
else
{
_log.LogInformation("Job {JobId} validation passed in {Sec:F1}s ({Count} checks, {Files} files)",
job.Id, seconds, outcome.Checks.Count, outcome.FileCount);
}
_spooler.Enqueue("validation", job.Id, new Dictionary<string, object?>
{
["machineId"] = machineId,
["checks"] = outcome.Checks,
["checksum"] = outcome.Checksum,
["checksumAlgo"] = "xxh64",
["exrFileCount"] = outcome.FileCount,
["exrTotalBytes"] = outcome.TotalBytes,
["validationSeconds"] = (int)seconds,
});
}
catch (Exception ex)
{
_log.LogError(ex, "Validation engine error for job {JobId}", job.Id);
_spooler.Enqueue("validation", job.Id, new Dictionary<string, object?>
{
["machineId"] = machineId,
["checks"] = new[]
{
ValidationCheck.Fail("engine_error", "validation completes", "worker exception",
$"The validation engine threw: {ex.Message}"),
},
});
}
}
/// <summary>
/// PREVIEW_ONLY job: rebuild the shot around the rendered EXRs with slate
/// and burn-ins, render the delivery MOV + review MP4, upload the review
@@ -31,12 +31,18 @@ public static class Preflight
return 1;
}
Console.WriteLine($" worker version : {options.WorkerVersion}");
Console.WriteLine($" machine name : {options.MachineName}");
Console.WriteLine($" server : {options.ServerUrl}");
Console.WriteLine($" api key : {(string.IsNullOrWhiteSpace(options.ApiKey) ? "(missing)" : "set")}");
Console.WriteLine();
ok &= Report("aerender.exe", options.AerenderPath, File.Exists(options.AerenderPath));
// Not required: a machine without Blender simply never claims Blender
// jobs, so this reports rather than fails.
Report("blender.exe", options.BlenderPath ?? "(not configured)",
!string.IsNullOrWhiteSpace(options.BlenderPath) && File.Exists(options.BlenderPath),
"needed only for Blender render jobs");
var afterFx = options.ResolveAfterFxPath();
ok &= Report("AfterFX.com", afterFx, File.Exists(afterFx),
"needed for preview builds only");
+10
View File
@@ -10,6 +10,13 @@ using VFXReviewWorker;
// Run interactively for debugging: VFXReviewWorker.exe [path\to\config.json]
// Install as a service: see RenderWorker/README.md
// Dry-run the validation engine over an existing render folder. No server, no
// config, no queue — useful for checking work that predates the pipeline.
if (args.Any(a => a.Equals("--validate", StringComparison.OrdinalIgnoreCase)))
{
return ValidateCommand.Run(args);
}
var configPath = args.FirstOrDefault(a => !a.StartsWith('-'));
// Install verification on a new machine — resolves paths, checks tools and
@@ -32,6 +39,9 @@ builder.Services.AddSingleton<ApiClient>();
builder.Services.AddSingleton<ReportSpooler>();
builder.Services.AddSingleton<AerenderRunner>();
builder.Services.AddSingleton<PreviewStage>();
builder.Services.AddSingleton<ValidationStage>();
builder.Services.AddSingleton<DeliveryStage>();
builder.Services.AddSingleton<BlenderRunner>();
builder.Services.AddSingleton<JobExecutor>();
builder.Services.AddHostedService<WorkerService>();
@@ -9,6 +9,11 @@ namespace VFXReviewWorker;
/// order with exponential backoff (1 s → 60 s). Rendering continues during
/// server downtime; a report is deleted only once the server accepts it (or
/// permanently rejects it as contradictory).
///
/// Strict ordering is load-bearing beyond durability: the validation report
/// (E12) is only legal once complete-render (E11) has moved the Export to
/// VALIDATING, and in-order replay is what guarantees that, with no need for
/// the worker to wait on an ACK.
/// </summary>
public sealed class ReportSpooler
{
@@ -8,6 +8,14 @@
<AssemblyName>VFXReviewWorker</AssemblyName>
<!-- Single self-contained exe for render nodes: dotnet publish -r win-x64 (see README) -->
<InvariantGlobalization>true</InvariantGlobalization>
<!--
The version is a property of the build, not of the machine it lands on:
it is stamped here and read back from the assembly at runtime, so a
workstation cannot report a version it is not actually running. Bump on
every change that gets published. publish.ps1 appends the git SHA via
SourceRevisionId, giving "1.1.0+feb1c7b".
-->
<Version>1.5.1</Version>
</PropertyGroup>
<ItemGroup>
@@ -20,9 +28,16 @@
</ItemGroup>
<ItemGroup>
<!-- Headless AE build script ships beside the exe -->
<!--
Headless AE build script ships beside the exe. CopyToPublishDirectory is
set explicitly: CopyToOutputDirectory alone governs the build folder, and
an incremental publish then leaves the script out of a freshly-cleaned
publish directory. publish.ps1 copies it again and verifies, because the
exe cannot run a preview job without it.
-->
<Content Include="..\scripts\vfxr_build_preview.jsx" Link="scripts\vfxr_build_preview.jsx">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
<CopyToPublishDirectory>Always</CopyToPublishDirectory>
</Content>
</ItemGroup>
@@ -0,0 +1,98 @@
using Microsoft.Extensions.Logging.Abstractions;
namespace VFXReviewWorker;
/// <summary>
/// `VFXReviewWorker.exe --validate &lt;renderDir&gt; [--plate &lt;plateFile&gt;] [--fps 24]`
///
/// Runs the validation engine (§8) over a folder of already-rendered EXRs and
/// prints the report, without a server, a job or a queue. Two uses: proving the
/// checks against real work before the stage goes live, and answering "is this
/// delivery good?" for a sequence that predates the pipeline.
/// </summary>
public static class ValidateCommand
{
public static int Run(string[] args)
{
var dir = args.SkipWhile(a => !a.Equals("--validate", StringComparison.OrdinalIgnoreCase)).Skip(1).FirstOrDefault();
if (string.IsNullOrWhiteSpace(dir) || dir.StartsWith('-'))
{
Console.Error.WriteLine("Usage: VFXReviewWorker.exe --validate <renderDir> [--plate <plateFirstFrame.exr>] [--fps 24] [--sample 25]");
return 2;
}
if (!Directory.Exists(dir))
{
Console.Error.WriteLine($"Not a directory: {dir}");
return 2;
}
var plate = ArgValue(args, "--plate");
var fps = double.TryParse(ArgValue(args, "--fps"), out var f) ? f : 24;
var sample = int.TryParse(ArgValue(args, "--sample"), out var s) ? s : 25;
var files = Directory.EnumerateFiles(dir, "*.exr").OrderBy(x => x, StringComparer.Ordinal).ToList();
if (files.Count == 0)
{
Console.Error.WriteLine($"No .exr files in {dir}");
return 2;
}
// Infer what the manifest would have said from the files themselves.
var firstName = Path.GetFileName(files[0]);
var frames = files.Select(x => SequencePattern.FrameFromName(Path.GetFileName(x))).Where(x => x is not null).Select(x => x!.Value).ToList();
var prefix = firstName.Contains('.') ? firstName[..firstName.IndexOf('.')] : Path.GetFileNameWithoutExtension(firstName);
var header = ExrHeader.TryRead(files[0]);
var manifest = new RenderManifest
{
ShotCode = prefix.Split("_cmp_")[0],
OutputDir = dir,
OutputPattern = $"{prefix}.[#####].exr",
FrameStart = frames.Count > 0 ? frames.Min() : 1,
FrameEnd = frames.Count > 0 ? frames.Max() : files.Count,
Fps = fps,
Width = header?.DataWidth ?? 0,
Height = header?.DataHeight ?? 0,
Source = plate is null ? null : new ManifestSource
{
TimingPlate = new PlateRef { Path = plate, FrameStart = SequencePattern.FrameFromName(Path.GetFileName(plate)) },
StartSource = "supplied on the command line",
},
};
var options = new WorkerOptions { ServerUrl = "n/a", ApiKey = "n/a" };
var stage = new ValidationStage(options, NullLogger<ValidationStage>.Instance);
var outcome = stage.Run(manifest, dir, new ServerConfig { ValidationSampleEvery = sample });
Console.WriteLine();
Console.WriteLine($"{files.Count} files in {dir}");
Console.WriteLine($"inferred range {manifest.FrameStart}-{manifest.FrameEnd} at {fps} fps, pattern {manifest.OutputPattern}");
if (plate is not null) Console.WriteLine($"timing plate {plate}");
Console.WriteLine();
foreach (var c in outcome.Checks)
{
var mark = c.Status switch { "PASS" => " ok ", "FAIL" => " FAIL ", "WARN" => " warn ", _ => " skip " };
Console.WriteLine($"[{mark}] {c.CheckName,-24} {Describe(c)}");
}
Console.WriteLine();
Console.WriteLine($"checksum (xxh64): {outcome.Checksum ?? "(not computed)"}");
var failed = outcome.Checks.Count(c => c.Status == "FAIL");
Console.WriteLine(failed == 0 ? "PASSED" : $"FAILED — {failed} check(s)");
return failed == 0 ? 0 : 1;
}
private static string Describe(ValidationCheck c)
{
if (!string.IsNullOrWhiteSpace(c.Message)) return c.Message!;
if (c.Expected is null && c.Actual is null) return "";
return c.Expected == c.Actual ? c.Actual ?? "" : $"expected {c.Expected}, got {c.Actual}";
}
private static string? ArgValue(string[] args, string name)
{
var i = Array.FindIndex(args, a => a.Equals(name, StringComparison.OrdinalIgnoreCase));
return i >= 0 && i + 1 < args.Length ? args[i + 1] : null;
}
}
@@ -0,0 +1,659 @@
using System.Text.RegularExpressions;
using Microsoft.Extensions.Logging;
namespace VFXReviewWorker;
/// <summary>
/// Validation engine (RenderPipeline2 §8). Runs on the worker straight after a
/// successful render, while it still holds the job and the files are local.
/// It only ever *reports* — the server decides what the results mean.
///
/// Full-sequence checks (count, gaps, names, sizes) touch every file; header
/// checks sample first/middle/last plus every Nth frame.
/// </summary>
public sealed class ValidationStage
{
private readonly WorkerOptions _options;
private readonly ILogger<ValidationStage> _log;
public ValidationStage(WorkerOptions options, ILogger<ValidationStage> log)
{
_options = options;
_log = log;
}
public ValidationOutcome Run(RenderManifest manifest, string outputDirLocal, ServerConfig config)
{
var checks = new List<ValidationCheck>();
var files = EnumerateSequence(manifest, outputDirLocal, checks, out var frameNumbers, out var totalBytes);
if (files.Count == 0)
{
// Nothing to inspect: the sequence checks already recorded the FAIL.
return new ValidationOutcome(checks, 0, 0, null);
}
var sampleEvery = Math.Max(1, config.ValidationSampleEvery);
var sampled = PickSamples(files, sampleEvery);
var headers = ReadHeaders(sampled, checks);
if (headers.Count > 0)
{
CheckResolution(manifest, headers, checks);
CheckBitDepthAndChannels(manifest, headers, checks);
CheckCompression(manifest, headers, checks);
CheckTimecode(manifest, headers, frameNumbers, config, checks);
}
var checksum = ComputeSequenceChecksum(files);
return new ValidationOutcome(checks, files.Count, totalBytes, checksum);
}
// ── Sequence-level checks ────────────────────────────────────────────────
private List<string> EnumerateSequence(
RenderManifest manifest, string outputDirLocal, List<ValidationCheck> checks,
out List<int> frameNumbers, out long totalBytes)
{
frameNumbers = new List<int>();
totalBytes = 0;
var expectedCount = manifest.TotalFrames;
if (!Directory.Exists(outputDirLocal))
{
checks.Add(ValidationCheck.Fail("file_count", expectedCount.ToString(), "0",
$"Output directory does not exist on this machine: {outputDirLocal}"));
return new List<string>();
}
var pattern = SequencePattern.FromOutputPattern(manifest.OutputPattern);
var matched = new List<(int Frame, string Path)>();
var nonConforming = new List<string>();
foreach (var path in Directory.EnumerateFiles(outputDirLocal))
{
var name = Path.GetFileName(path);
if (!name.EndsWith(pattern.Extension, StringComparison.OrdinalIgnoreCase)) continue;
// Only files belonging to this render: a version folder can also hold
// the preview MOV/MP4, which are not part of the EXR sequence.
if (!name.StartsWith(pattern.Prefix, StringComparison.OrdinalIgnoreCase)) continue;
var frame = pattern.FrameNumberOf(name);
if (frame is null) { nonConforming.Add(name); continue; }
matched.Add((frame.Value, path));
}
matched.Sort((a, b) => a.Frame.CompareTo(b.Frame));
var files = matched.Select(m => m.Path).ToList();
frameNumbers = matched.Select(m => m.Frame).ToList();
// file_count
checks.Add(files.Count == expectedCount
? ValidationCheck.Pass("file_count", expectedCount.ToString(), files.Count.ToString())
: ValidationCheck.Fail("file_count", expectedCount.ToString(), files.Count.ToString(),
$"Expected {expectedCount} frames ({manifest.FrameStart}-{manifest.FrameEnd}), found {files.Count} in {outputDirLocal}"));
// filename_consistency
checks.Add(nonConforming.Count == 0
? ValidationCheck.Pass("filename_consistency", pattern.Describe(), "all files match")
: ValidationCheck.Fail("filename_consistency", pattern.Describe(), $"{nonConforming.Count} nonconforming",
"Files not matching the output pattern: " + string.Join(", ", nonConforming.Take(10)),
new { files = nonConforming.Take(50) }));
if (files.Count == 0) return files;
// Output files are numbered by the output module's starting number
// (house convention: every sequence starts at 1001), which is a
// different coordinate system from the comp's frame range — a comp
// anchored to the plate's timecode starts at 1247792. Checking file
// numbers against comp frames compares the two and fails every render,
// so the sequence is checked for the right *count* and *contiguity*,
// and its absolute start only where the manifest states it.
var expectedFirst = manifest.OutputFrameStart;
var seen = new HashSet<int>();
var duplicates = new List<int>();
foreach (var f in frameNumbers)
{
if (!seen.Add(f)) duplicates.Add(f);
}
// Gaps are found relative to the run the render actually produced: a
// hole in the middle is a real defect regardless of where it starts.
var runStart = expectedFirst ?? frameNumbers[0];
var runEnd = runStart + expectedCount - 1;
var missing = new List<int>();
for (var f = runStart; f <= runEnd; f++)
{
if (!seen.Contains(f)) missing.Add(f);
}
checks.Add(missing.Count == 0
? ValidationCheck.Pass("missing_frames", "none", "none")
: ValidationCheck.Fail("missing_frames", "none", $"{missing.Count} missing",
$"Missing frames in {runStart}-{runEnd}: " + Summarise(missing),
new { missing = missing.Take(500), runStart, runEnd }));
checks.Add(duplicates.Count == 0
? ValidationCheck.Pass("duplicate_frames", "none", "none")
: ValidationCheck.Fail("duplicate_frames", "none", $"{duplicates.Count} duplicated",
"Duplicate frame numbers (differing padding?): " + Summarise(duplicates),
new { duplicates = duplicates.Take(100) }));
if (expectedFirst is int first)
{
checks.Add(frameNumbers[0] == first
? ValidationCheck.Pass("first_frame", first.ToString(), frameNumbers[0].ToString())
: ValidationCheck.Fail("first_frame", first.ToString(), frameNumbers[0].ToString(),
$"Sequence starts at {frameNumbers[0]}, expected {first}"));
var expectedLast = first + expectedCount - 1;
checks.Add(frameNumbers[^1] == expectedLast
? ValidationCheck.Pass("last_frame", expectedLast.ToString(), frameNumbers[^1].ToString())
: ValidationCheck.Fail("last_frame", expectedLast.ToString(), frameNumbers[^1].ToString(),
$"Sequence ends at {frameNumbers[^1]}, expected {expectedLast}"));
}
else
{
// Old manifests carry no output numbering; the count and contiguity
// checks above still hold, so the run is reported rather than
// measured against a number that was never sent.
checks.Add(ValidationCheck.Skipped("first_frame",
$"manifest carries no output frame numbering — sequence runs {frameNumbers[0]}-{frameNumbers[^1]}"));
}
// zero_byte — every file, it is only a directory stat
var zeroByte = new List<string>();
foreach (var path in files)
{
var len = new FileInfo(path).Length;
totalBytes += len;
if (len == 0) zeroByte.Add(Path.GetFileName(path));
}
checks.Add(zeroByte.Count == 0
? ValidationCheck.Pass("zero_byte", "none", "none")
: ValidationCheck.Fail("zero_byte", "none", $"{zeroByte.Count} empty",
"Zero-byte files: " + string.Join(", ", zeroByte.Take(10)), new { files = zeroByte.Take(50) }));
return files;
}
// ── Header checks (sampled) ──────────────────────────────────────────────
private static List<string> PickSamples(List<string> files, int sampleEvery)
{
var picks = new SortedSet<int> { 0, files.Count / 2, files.Count - 1 };
for (var i = 0; i < files.Count; i += sampleEvery) picks.Add(i);
return picks.Where(i => i >= 0 && i < files.Count).Select(i => files[i]).ToList();
}
private List<(string Path, ExrHeader Header)> ReadHeaders(List<string> sampled, List<ValidationCheck> checks)
{
var headers = new List<(string, ExrHeader)>();
var unreadable = new List<string>();
foreach (var path in sampled)
{
try
{
headers.Add((path, ExrHeader.Read(path)));
}
catch (Exception ex)
{
unreadable.Add($"{Path.GetFileName(path)}: {ex.Message}");
_log.LogWarning("Unreadable EXR header: {Path} ({Error})", path, ex.Message);
}
}
checks.Add(unreadable.Count == 0
? ValidationCheck.Pass("corrupt", "all sampled frames readable", $"{headers.Count} sampled")
: ValidationCheck.Fail("corrupt", "all sampled frames readable", $"{unreadable.Count} unreadable",
"Unreadable EXR headers: " + string.Join("; ", unreadable.Take(5)), new { files = unreadable.Take(50) }));
return headers;
}
private static void CheckResolution(RenderManifest m, List<(string Path, ExrHeader H)> headers, List<ValidationCheck> checks)
{
if (m.Width <= 0 || m.Height <= 0)
{
checks.Add(ValidationCheck.Skipped("resolution", "manifest carries no expected resolution"));
return;
}
var expected = $"{m.Width}x{m.Height}";
var bad = headers.Where(h => h.H.DataWidth != m.Width || h.H.DataHeight != m.Height).ToList();
checks.Add(bad.Count == 0
? ValidationCheck.Pass("resolution", expected, expected)
: ValidationCheck.Fail("resolution", expected, $"{bad[0].H.DataWidth}x{bad[0].H.DataHeight}",
$"{bad.Count} of {headers.Count} sampled frames are not {expected} (first: {Path.GetFileName(bad[0].Path)})"));
}
private static void CheckBitDepthAndChannels(RenderManifest m, List<(string Path, ExrHeader H)> headers, List<ValidationCheck> checks)
{
var expectedDepth = m.Expected?.BitDepth;
var actualDepth = headers[0].H.BitDepth ?? "unknown";
if (string.IsNullOrWhiteSpace(expectedDepth))
{
checks.Add(ValidationCheck.Skipped("bit_depth", $"no expected bit depth configured (rendered {actualDepth})"));
}
else
{
var mismatched = headers.Where(h => !string.Equals(h.H.BitDepth, expectedDepth, StringComparison.OrdinalIgnoreCase)).ToList();
checks.Add(mismatched.Count == 0
? ValidationCheck.Pass("bit_depth", expectedDepth, actualDepth)
: ValidationCheck.Fail("bit_depth", expectedDepth, mismatched[0].H.BitDepth ?? "unknown",
$"{mismatched.Count} of {headers.Count} sampled frames are not {expectedDepth}"));
}
var hasAlpha = headers[0].H.HasAlpha;
var channelList = string.Join(",", headers[0].H.Channels.Select(c => c.Name));
if (m.Expected?.Alpha is null)
{
checks.Add(ValidationCheck.Skipped("alpha_channel", $"no expectation configured (channels: {channelList})"));
}
else
{
checks.Add(hasAlpha == m.Expected.Alpha.Value
? ValidationCheck.Pass("alpha_channel", m.Expected.Alpha.Value ? "alpha present" : "no alpha", channelList)
: ValidationCheck.Fail("alpha_channel",
m.Expected.Alpha.Value ? "alpha present" : "no alpha",
hasAlpha ? "alpha present" : "no alpha",
$"Channel list is {channelList}"));
}
}
private static void CheckCompression(RenderManifest m, List<(string Path, ExrHeader H)> headers, List<ValidationCheck> checks)
{
var actual = headers[0].H.CompressionName;
if (headers[0].H.CompressionCode is null)
{
checks.Add(ValidationCheck.Fail("exr_type", "readable EXR", "no compression attribute",
"Sampled frame has no compression attribute — not a valid EXR header"));
return;
}
var expected = m.Expected?.ExrCompression;
if (string.IsNullOrWhiteSpace(expected))
{
checks.Add(ValidationCheck.Pass("exr_type", "valid EXR", $"{actual}{(headers[0].H.IsTiled ? ", tiled" : ", scanline")}"));
return;
}
// Compression differing but readable is a WARN, never a stop (§8.1).
checks.Add(string.Equals(actual, expected, StringComparison.OrdinalIgnoreCase)
? ValidationCheck.Pass("exr_type", expected, actual)
: ValidationCheck.Warn("exr_type", expected, actual,
$"Compression is {actual}, expected {expected} — readable, so not blocking"));
}
// ── Timecode: the primary check (§8.1a) ──────────────────────────────────
private void CheckTimecode(
RenderManifest m, List<(string Path, ExrHeader H)> headers, List<int> frameNumbers,
ServerConfig config, List<ValidationCheck> checks)
{
var fps = m.Fps > 0 ? m.Fps : 24;
var first = headers[0];
if (first.H.Timecode is null)
{
// AE's EXR output module writes timeCode; its absence means the
// output module changed, so this is a stop rather than a skip.
checks.Add(ValidationCheck.Fail("timecode_plate_match", "timecode present", "absent",
$"No timeCode attribute in {Path.GetFileName(first.Path)} — the EXR output module no longer writes timecode",
new { attributes = first.H.AttributeNames.Take(40) }));
return;
}
var renderTc = first.H.Timecode.Value;
var renderFirstFrame = frameNumbers.Count > 0 ? frameNumbers[0] : m.FrameStart;
// timecode_consistency — sampled frames must advance exactly one frame
// each. A constant value is the frame-derived-timecode defect.
var drift = new List<string>();
for (var i = 0; i < headers.Count; i++)
{
var h = headers[i].H;
if (h.Timecode is null) { drift.Add($"{Path.GetFileName(headers[i].Path)}: no timecode"); continue; }
var frameNo = SequencePattern.FrameFromName(Path.GetFileName(headers[i].Path)) ?? (renderFirstFrame + i);
var expectedTc = Timecode.FromFrames(renderTc.ToFrames(fps) + (frameNo - renderFirstFrame), fps);
if (h.Timecode.Value.ToFrames(fps) != expectedTc.ToFrames(fps))
{
drift.Add($"frame {frameNo}: {h.Timecode.Value} (expected {expectedTc})");
}
}
checks.Add(drift.Count == 0
? ValidationCheck.Pass("timecode_consistency", "monotonic, 1 frame per frame", $"{headers.Count} frames sampled")
: ValidationCheck.Fail("timecode_consistency", "monotonic, 1 frame per frame", $"{drift.Count} sampled frames off",
"Timecode does not advance with the frames: " + string.Join("; ", drift.Take(5)),
new { drift = drift.Take(50) }));
// timecode_fps
if (first.H.FramesPerSecond is double headerFps)
{
checks.Add(Math.Abs(headerFps - fps) < 0.01
? ValidationCheck.Pass("timecode_fps", fps.ToString("0.###"), headerFps.ToString("0.###"))
: ValidationCheck.Fail("timecode_fps", fps.ToString("0.###"), headerFps.ToString("0.###"),
$"EXR framesPerSecond is {headerFps:0.###} but the comp rendered at {fps:0.###}"));
}
else
{
checks.Add(ValidationCheck.Skipped("timecode_fps", "no framesPerSecond attribute in the rendered EXRs"));
}
// timecode_plate_match — reference precedence, rank 1 → 3.
var reference = ResolveTimecodeReference(m, config, renderFirstFrame);
if (reference is null)
{
checks.Add(ValidationCheck.Warn("timecode_plate_match", "plate timecode", renderTc.ToString(),
"No plate reference available: the manifest carries no timing plate, none was found on disk, " +
"and no API timecode was supplied. Render timecode is unverified.",
new { renderTimecode = renderTc.ToString() }));
return;
}
// plate_fps — the render's rate against the plate's own.
//
// timecode_fps only compares the render to the manifest, and both come
// from the comp: a shot built at the wrong rate agrees with itself and
// passes. The plate is the independent witness. A 25 fps show whose
// shot records defaulted to 24 renders every shot at 24, and this is
// what names that rather than leaving it to surface as an off-by-N
// timecode error.
if (reference.PlateFps is double plateFps && first.H.FramesPerSecond is double renderFps)
{
var ratio = renderFps > 0 ? plateFps / renderFps : 0;
var overcrank = ratio > 1.5 && Math.Abs(ratio - Math.Round(ratio)) < 0.01;
checks.Add(Math.Abs(plateFps - renderFps) < 0.01
? ValidationCheck.Pass("plate_fps", plateFps.ToString("0.###"), renderFps.ToString("0.###"))
// Never a FAIL: a plate deliberately shot at a multiple of the
// show rate is a legitimate over-crank, conformed on purpose.
// Anything else is a rate mistake, and the wording says which.
: ValidationCheck.Warn("plate_fps", plateFps.ToString("0.###"), renderFps.ToString("0.###"),
overcrank
? $"The plate is {plateFps:0.###} fps against a {renderFps:0.###} fps render — a {Math.Round(ratio)}x over-crank, conformed as expected."
: $"The plate is {plateFps:0.###} fps but this rendered at {renderFps:0.###} — not a whole-number over-crank, so the comp was probably built at the wrong rate (check the shot's fps in the database).",
new { platePath = reference.PlatePath, reference = reference.Kind, ratio }));
}
var expectedFrames = reference.PlateTimecode.ToFrames(fps) + (renderFirstFrame - reference.PlateFirstFrame);
var expected = Timecode.FromFrames(expectedFrames, fps);
var actualFrames = renderTc.ToFrames(fps);
var deltaFrames = actualFrames - expectedFrames;
var details = new
{
reference = reference.Kind,
platePath = reference.PlatePath,
plateTimecode = reference.PlateTimecode.ToString(),
plateFirstFrame = reference.PlateFirstFrame,
renderFirstFrame,
deltaFrames,
};
if (deltaFrames == 0)
{
// The API fallback proves nothing on its own (§8.1a): it is the
// editorial in-point minus a handle count that may not be this
// plate's, so a match is reported as a WARN, never a PASS.
checks.Add(reference.Kind == "api"
? ValidationCheck.Warn("timecode_plate_match", expected.ToString(), renderTc.ToString(),
"Matches the API timecode less handles, but the plate itself could not be read — unverified.", details)
: ValidationCheck.Pass("timecode_plate_match", expected.ToString(), renderTc.ToString(),
$"Matches {reference.Kind} plate {Path.GetFileName(reference.PlatePath ?? "")}", details));
return;
}
var message =
$"Render starts at {renderTc} but the {reference.Kind} plate says it should be {expected} " +
$"({(deltaFrames > 0 ? "+" : "")}{deltaFrames} frames). " +
(Math.Abs(deltaFrames) == reference.HandleFrames && reference.HandleFrames > 0
? $"That is exactly the {reference.HandleFrames}-frame handle: the comp was anchored to the editorial in-point instead of the plate's first frame."
: renderTc.Hours == 0 && renderTc.Minutes == 0
? "A near-zero timecode means the comp had no source timecode at all and AE derived it from the frame number."
: "");
checks.Add(reference.Kind == "api"
? ValidationCheck.Warn("timecode_plate_match", expected.ToString(), renderTc.ToString(),
message + " (checked against the API value, not the plate — treat as advisory)", details)
: ValidationCheck.Fail("timecode_plate_match", expected.ToString(), renderTc.ToString(), message, details));
}
/// <summary>
/// Reference precedence (§8.1a): manifest timing plate → plate found under a
/// configured search root → API timecode minus handles (advisory only).
/// </summary>
private TimecodeReference? ResolveTimecodeReference(RenderManifest m, ServerConfig config, int renderFirstFrame)
{
var mapper = new PathMapper(_options.PathMappings);
var handleFrames = m.Source?.HandleFrames ?? config.ValidationHandleFrames;
// Rank 1 — the plate the comp was actually built from.
var timing = m.Source?.TimingPlate;
if (timing is not null && !string.IsNullOrWhiteSpace(timing.Path))
{
var local = mapper.Map(timing.Path);
var header = File.Exists(local) ? ExrHeader.TryRead(local) : null;
if (header?.Timecode is not null)
{
// The plate's own file numbering, never the comp's frame range:
// the render's first frame is in output numbering, so anchoring
// on a comp frame skews the comparison by the gap between them.
var frame = SequencePattern.FrameFromName(Path.GetFileName(local))
?? timing.FrameStart
?? renderFirstFrame;
return new TimecodeReference("manifest", local, header.Timecode.Value, frame, handleFrames,
header.FramesPerSecond);
}
_log.LogWarning("Timing plate from manifest is unreadable: {Path}", local);
}
// Rank 2 — derive the plate from a configured search root.
var derived = FindPlateOnDisk(m, mapper);
if (derived is not null) return derived with { HandleFrames = handleFrames };
// Rank 3 — the API's editorial in-point, less handles. Advisory only.
//
// Shot.timecodeStart is the *edit* in-point; the plate is delivered with
// handleFrames of head handle, so the first delivered frame sits that
// much earlier. The anchor is the render's own first frame, which is in
// the same numbering as the files on disk — not the manifest's frame
// range, which is the comp's timeline and a different coordinate system
// entirely (mixing the two produced a nonsense million-frame offset).
var apiTc = Timecode.Parse(m.Expected?.TimecodeStart);
if (apiTc is not null)
{
var fps = m.Fps > 0 ? m.Fps : 24;
var plateStart = Timecode.FromFrames(apiTc.Value.ToFrames(fps) - handleFrames, fps);
return new TimecodeReference("api", null, plateStart, renderFirstFrame, handleFrames);
}
return null;
}
/// <summary>
/// Rank 2: look for the shot's plate folders under the configured roots,
/// mirroring the panel's two on-disk layouts ({shotCode}/{element}/ and
/// {shotCode}_{element}/). Ambiguity is resolved by frame count; still
/// ambiguous means no reference rather than a guess.
/// </summary>
private TimecodeReference? FindPlateOnDisk(RenderManifest m, PathMapper mapper)
{
if (_options.PlateSearchRoots.Count == 0 || string.IsNullOrWhiteSpace(m.ShotCode)) return null;
var candidates = new List<(string Dir, int Count)>();
foreach (var rootRaw in _options.PlateSearchRoots)
{
var root = mapper.Map(rootRaw);
if (!Directory.Exists(root)) continue;
// The show/episode level is unknown here, so scan the root and one
// level below it — bounded, and enough for both layouts.
var levels = new List<string> { root };
try { levels.AddRange(Directory.EnumerateDirectories(root)); } catch { }
foreach (var level in levels)
{
try
{
var grouped = Path.Combine(level, m.ShotCode);
if (Directory.Exists(grouped))
{
foreach (var element in Directory.EnumerateDirectories(grouped))
{
AddCandidate(candidates, element);
}
}
foreach (var element in Directory.EnumerateDirectories(level, m.ShotCode + "_*"))
{
AddCandidate(candidates, element);
}
}
catch { /* unreadable branch — keep scanning the rest */ }
}
}
if (candidates.Count == 0) return null;
// Prefer the element whose frame count matches the render: that is the
// one the comp's timing came from.
var exact = candidates.Where(c => c.Count == m.TotalFrames).ToList();
(string Dir, int Count)? chosen =
exact.Count == 1 ? exact[0]
: exact.Count == 0 && candidates.Count == 1 ? candidates[0]
: null;
if (chosen is null)
{
_log.LogWarning("Plate reference ambiguous for {Shot}: {Candidates}",
m.ShotCode, string.Join(", ", candidates.Select(c => Path.GetFileName(c.Dir))));
return null;
}
var firstFile = Directory.EnumerateFiles(chosen.Value.Dir, "*.exr").OrderBy(f => f, StringComparer.Ordinal).FirstOrDefault();
if (firstFile is null) return null;
var header = ExrHeader.TryRead(firstFile);
if (header?.Timecode is null) return null;
var frame = SequencePattern.FrameFromName(Path.GetFileName(firstFile)) ?? m.FrameStart;
return new TimecodeReference("derived", firstFile, header.Timecode.Value, frame, 0, header.FramesPerSecond);
}
private static void AddCandidate(List<(string Dir, int Count)> candidates, string dir)
{
try
{
var count = Directory.EnumerateFiles(dir, "*.exr").Count();
if (count > 0) candidates.Add((dir, count));
}
catch { }
}
// ── Checksums ────────────────────────────────────────────────────────────
/// <summary>
/// Sequence digest = xxHash64 over the per-file digests in frame order
/// (§8.2). Reused by the delivery builder to verify what it linked/copied.
/// </summary>
private string? ComputeSequenceChecksum(List<string> files)
{
try
{
var state = new XxHash64.State(0);
foreach (var f in files)
{
var digest = XxHash64.HashFile(f);
state.Update(System.Text.Encoding.ASCII.GetBytes(digest));
}
return state.Digest().ToString("x16");
}
catch (Exception ex)
{
_log.LogWarning(ex, "Sequence checksum failed");
return null;
}
}
private static string Summarise(IEnumerable<int> numbers)
{
var list = numbers.Take(12).ToList();
var text = string.Join(", ", list);
return numbers.Count() > 12 ? text + ", …" : text;
}
}
public sealed record TimecodeReference(
string Kind, string? PlatePath, Timecode PlateTimecode, int PlateFirstFrame, int HandleFrames,
double? PlateFps = null);
public sealed record ValidationOutcome(
List<ValidationCheck> Checks, int FileCount, long TotalBytes, string? Checksum)
{
public bool HasFailure => Checks.Any(c => c.Status == "FAIL");
}
/// <summary>One row of the E12 report.</summary>
public sealed class ValidationCheck
{
public string CheckName { get; set; } = "";
public string Status { get; set; } = "PASS";
public string? Expected { get; set; }
public string? Actual { get; set; }
public string? Message { get; set; }
public object? Details { get; set; }
public static ValidationCheck Pass(string name, string? expected = null, string? actual = null, string? message = null, object? details = null) =>
new() { CheckName = name, Status = "PASS", Expected = expected, Actual = actual, Message = message, Details = details };
public static ValidationCheck Fail(string name, string? expected, string? actual, string message, object? details = null) =>
new() { CheckName = name, Status = "FAIL", Expected = expected, Actual = actual, Message = message, Details = details };
public static ValidationCheck Warn(string name, string? expected, string? actual, string message, object? details = null) =>
new() { CheckName = name, Status = "WARN", Expected = expected, Actual = actual, Message = message, Details = details };
public static ValidationCheck Skipped(string name, string message) =>
new() { CheckName = name, Status = "SKIPPED", Message = message };
}
/// <summary>
/// Parses `{base}.[#####].exr` output patterns and the filenames they produce.
/// </summary>
public sealed class SequencePattern
{
public string Prefix { get; private init; } = "";
public string Extension { get; private init; } = ".exr";
public int Padding { get; private init; }
// Delivered plates separate the frame number with a dot
// ("..._BG01_TT_v001.01001.exr"); AE-written renders use an underscore
// ("..._PRERENDER_01001.exr"). Both appear as layers in a shot comp, so
// both have to parse — a plate whose number cannot be read gets anchored on
// a fallback, and a wrong anchor silently skews the timecode check.
private static readonly Regex FrameInName = new(@"[._](\d{2,9})\.[A-Za-z0-9]+$", RegexOptions.Compiled);
public static SequencePattern FromOutputPattern(string outputPattern)
{
var pattern = outputPattern ?? "";
var ext = Path.GetExtension(pattern);
if (string.IsNullOrEmpty(ext)) ext = ".exr";
var hashStart = pattern.IndexOf('[');
var prefix = hashStart > 0 ? pattern[..hashStart].TrimEnd('.') : Path.GetFileNameWithoutExtension(pattern);
var padding = 0;
foreach (var ch in pattern)
{
if (ch == '#') padding++;
}
return new SequencePattern { Prefix = prefix, Extension = ext, Padding = padding };
}
public int? FrameNumberOf(string fileName) => FrameFromName(fileName);
/// <summary>`UNG_102_019_010_cmp_TT_v005.01001.exr` → 1001.</summary>
public static int? FrameFromName(string fileName)
{
var m = FrameInName.Match(fileName);
if (!m.Success) return null;
return int.TryParse(m.Groups[1].Value, out var n) ? n : null;
}
public string Describe() => $"{Prefix}.[{new string('#', Math.Max(1, Padding))}]{Extension}";
}
+25 -1
View File
@@ -1,3 +1,4 @@
using System.Reflection;
using System.Text.Json;
using System.Text.Json.Serialization;
@@ -19,9 +20,32 @@ public sealed class WorkerOptions
/// <summary>vfxr_build_preview.jsx — defaults to scripts\ beside the worker exe.</summary>
public string? PreviewScriptPath { get; set; }
public string? FfmpegPath { get; set; }
/// <summary>
/// blender.exe. Its presence is what makes this machine eligible for
/// Blender jobs: the version is reported at registration and the server
/// only hands BLENDER_RENDER work to machines that have it.
/// </summary>
public string? BlenderPath { get; set; }
public string? OiiotoolPath { get; set; }
public List<PathMapping> PathMappings { get; set; } = new();
public string WorkerVersion { get; set; } = "1.0.0";
/// <summary>
/// Optional footage roots searched for a shot's plates when a manifest
/// carries no timing plate (rank 2 of §8.1a) — e.g. ["V:/_FOOTAGE/UNG"].
/// Leave empty and old manifests simply fall through to the API fallback.
/// </summary>
public List<string> PlateSearchRoots { get; set; } = new();
/// <summary>
/// Read from the assembly, not from config.json: a hand-maintained version
/// string is exactly the thing that goes stale, and a machine reporting a
/// version it is not running is worse than no version at all.
/// Includes the git SHA when publish.ps1 stamped one ("1.1.0+feb1c7b").
/// </summary>
public string WorkerVersion =>
typeof(WorkerOptions).Assembly
.GetCustomAttribute<System.Reflection.AssemblyInformationalVersionAttribute>()?.InformationalVersion
?? typeof(WorkerOptions).Assembly.GetName().Version?.ToString()
?? "unknown";
public string? AeVersion { get; set; }
public static string DataDir =>
@@ -40,6 +40,7 @@ public sealed class WorkerService : BackgroundService
_ = Task.Run(() => _spooler.RunAsync(stoppingToken), stoppingToken);
await RegisterWithRetryAsync(stoppingToken);
await _api.ReportVersionAsync(_options, stoppingToken);
await _executor.ReconcileAsync(_machineId!, stoppingToken);
_ = Task.Run(() => HeartbeatLoopAsync(stoppingToken), stoppingToken);
@@ -61,9 +62,13 @@ public sealed class WorkerService : BackgroundService
: "No interactive After Effects — preview jobs enabled");
_lastAeOpen = aeOpen;
}
// Delivery builds are file work with no AE involvement, so they
// are always claimable — someone is usually waiting on the folder.
// Blender is asked for unconditionally; the server refuses it to
// machines whose capabilities do not include Blender.
var types = aeOpen
? new[] { "AE_RENDER" }
: new[] { "AE_RENDER", "PREVIEW_ONLY" };
? new[] { "AE_RENDER", "DELIVERY_BUILD", "BLENDER_RENDER" }
: new[] { "AE_RENDER", "PREVIEW_ONLY", "DELIVERY_BUILD", "BLENDER_RENDER" };
var job = await _api.ClaimAsync(_machineId!, types, stoppingToken);
if (job is not null)
+158
View File
@@ -0,0 +1,158 @@
namespace VFXReviewWorker;
/// <summary>
/// xxHash64 (§8.2 `checksumAlgo: "xxh64"`). Implemented here rather than taken
/// from System.IO.Hashing so the worker stays a dependency-free single-file
/// publish for offline workstation installs. Verified against the reference
/// test vectors in XxHash64Tests.
/// </summary>
public static class XxHash64
{
private const ulong Prime1 = 11400714785074694791UL;
private const ulong Prime2 = 14029467366897019727UL;
private const ulong Prime3 = 1609587929392839161UL;
private const ulong Prime4 = 9650029242287828579UL;
private const ulong Prime5 = 2870177450012600261UL;
public static ulong Hash(ReadOnlySpan<byte> data, ulong seed = 0)
{
var state = new State(seed);
state.Update(data);
return state.Digest();
}
public static string HashFile(string path, int bufferSize = 1 << 20)
{
var state = new State(0);
using var fs = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite, bufferSize, FileOptions.SequentialScan);
var buffer = new byte[bufferSize];
int read;
while ((read = fs.Read(buffer, 0, buffer.Length)) > 0)
{
state.Update(new ReadOnlySpan<byte>(buffer, 0, read));
}
return state.Digest().ToString("x16");
}
/// <summary>Streaming state so multi-GB sequences hash without being held in memory.</summary>
public struct State
{
private ulong _v1, _v2, _v3, _v4;
private readonly ulong _seed;
private ulong _length;
private readonly byte[] _buffer;
private int _bufferLen;
public State(ulong seed)
{
_seed = seed;
_v1 = seed + Prime1 + Prime2;
_v2 = seed + Prime2;
_v3 = seed;
_v4 = seed - Prime1;
_length = 0;
_buffer = new byte[32];
_bufferLen = 0;
}
public void Update(ReadOnlySpan<byte> data)
{
_length += (ulong)data.Length;
if (_bufferLen > 0)
{
var need = Math.Min(32 - _bufferLen, data.Length);
data[..need].CopyTo(_buffer.AsSpan(_bufferLen));
_bufferLen += need;
data = data[need..];
if (_bufferLen < 32) return;
ProcessStripe(_buffer);
_bufferLen = 0;
}
while (data.Length >= 32)
{
ProcessStripe(data[..32]);
data = data[32..];
}
if (data.Length > 0)
{
data.CopyTo(_buffer.AsSpan(0));
_bufferLen = data.Length;
}
}
private void ProcessStripe(ReadOnlySpan<byte> stripe)
{
_v1 = Round(_v1, BitConverter.ToUInt64(stripe[..8]));
_v2 = Round(_v2, BitConverter.ToUInt64(stripe.Slice(8, 8)));
_v3 = Round(_v3, BitConverter.ToUInt64(stripe.Slice(16, 8)));
_v4 = Round(_v4, BitConverter.ToUInt64(stripe.Slice(24, 8)));
}
public ulong Digest()
{
ulong h;
if (_length >= 32)
{
h = RotateLeft(_v1, 1) + RotateLeft(_v2, 7) + RotateLeft(_v3, 12) + RotateLeft(_v4, 18);
h = MergeRound(h, _v1);
h = MergeRound(h, _v2);
h = MergeRound(h, _v3);
h = MergeRound(h, _v4);
}
else
{
h = _seed + Prime5;
}
h += _length;
var tail = new ReadOnlySpan<byte>(_buffer, 0, _bufferLen);
int i = 0;
while (i + 8 <= tail.Length)
{
h ^= Round(0, BitConverter.ToUInt64(tail.Slice(i, 8)));
h = RotateLeft(h, 27) * Prime1 + Prime4;
i += 8;
}
if (i + 4 <= tail.Length)
{
h ^= BitConverter.ToUInt32(tail.Slice(i, 4)) * Prime1;
h = RotateLeft(h, 23) * Prime2 + Prime3;
i += 4;
}
while (i < tail.Length)
{
h ^= tail[i] * Prime5;
h = RotateLeft(h, 11) * Prime1;
i++;
}
h ^= h >> 33;
h *= Prime2;
h ^= h >> 29;
h *= Prime3;
h ^= h >> 32;
return h;
}
private static ulong Round(ulong acc, ulong input)
{
acc += input * Prime2;
acc = RotateLeft(acc, 31);
acc *= Prime1;
return acc;
}
private static ulong MergeRound(ulong acc, ulong val)
{
acc ^= Round(0, val);
acc = acc * Prime1 + Prime4;
return acc;
}
private static ulong RotateLeft(ulong value, int bits) => (value << bits) | (value >> (64 - bits));
}
}
+24 -3
View File
@@ -20,13 +20,34 @@ $ErrorActionPreference = "Stop"
$root = Split-Path $PSScriptRoot -Parent
if (-not $OutDir) { $OutDir = Join-Path $root "publish\win-x64" }
# Stamp the commit into the version so a deployed exe can be traced back to
# source ("1.1.0+feb1c7b"). Absent git, the plain version still publishes.
$sha = ""
try { $sha = (& git -C $root rev-parse --short HEAD 2>$null) } catch { }
if ($LASTEXITCODE -ne 0) { $sha = "" }
Write-Host "Publishing self-contained worker..." -ForegroundColor Cyan
& dotnet publish (Join-Path $root "VFXReviewWorker\VFXReviewWorker.csproj") `
-c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -o $OutDir
$publishArgs = @(
(Join-Path $root "VFXReviewWorker\VFXReviewWorker.csproj")
"-c"; "Release"; "-r"; "win-x64"
"--self-contained"; "true"
"-p:PublishSingleFile=true"
"-o"; $OutDir
)
if ($sha) { $publishArgs += "-p:SourceRevisionId=$sha" }
& dotnet publish @publishArgs
if ($LASTEXITCODE -ne 0) { throw "dotnet publish failed" }
# The exe reads scripts\vfxr_build_preview.jsx from its own folder at runtime.
# The exe reads scripts\vfxr_build_preview.jsx from its own folder at runtime,
# so it is copied here unconditionally rather than trusted to the SDK: an
# incremental publish into a cleaned output directory silently skips content
# copying, which produced a package that looked fine and could not build a
# preview. Copy, then verify.
$scriptSrc = Join-Path $PSScriptRoot "vfxr_build_preview.jsx"
$scriptOut = Join-Path $OutDir "scripts\vfxr_build_preview.jsx"
if (-not (Test-Path $scriptSrc)) { throw "Preview build script not found in source: $scriptSrc" }
New-Item -ItemType Directory -Force (Split-Path $scriptOut) | Out-Null
Copy-Item $scriptSrc $scriptOut -Force
if (-not (Test-Path $scriptOut)) { throw "Preview build script missing from output: $scriptOut" }
Remove-Item (Join-Path $OutDir "*.pdb") -ErrorAction SilentlyContinue
+1 -1
View File
@@ -15,7 +15,7 @@
and then quit it.
.EXAMPLE
.\test-preview-build.ps1 -ExrDir "V:\_EXPORTS\UNG\renders\UNG_S1\111\UNG_111_001_030\v002" `
.\test-preview-build.ps1 -ExrDir "V:\_EXPORTS\UNG_S1\111\UNG_111_001_030\v002" `
-ShotCode "UNG_111_001_030" -Version "v002"
.EXAMPLE
+50 -4
View File
@@ -230,6 +230,26 @@
return names;
}
// Slate identity fields (version name, shot name). Current templates expose
// these under a stable name, older ones only positionally, and the two do
// not always line up — so write both. Setting the same property twice is
// harmless; the panel uses the same name-with-index-fallback pattern.
function setSlateIdentity(layer, propName, index, value, label) {
var byName;
var byIndex;
if (value === null || value === undefined || value === "") {
return; // leave the template's own default
}
byName = setEssentialProperty(layer, propName, value);
byIndex = setEssentialPropertyByIndex(layer, index, value);
if (!byName && !byIndex) {
warn(label + ": neither Essential Property \"" + propName + "\" nor index " +
index + " could be set. Available: " +
listEssentialPropertyNames(layer).join(", "));
}
}
// Per-submission fields (VFX Scope / Submission Note). The property names
// come from config; if one does not exist, report the template's actual
// property names so it can be corrected without another build.
@@ -246,6 +266,27 @@
}
}
// The production name, burned into both the slate and the overlay. The
// slate's other fields are title case ("Date", "Scene") while the overlay's
// are upper ("DATE", "SHOT NAME"), so both spellings are attempted rather
// than assuming which template uses which — and a template that exposes
// neither reports its actual property names instead of failing silently.
function setShowField(layer, value, label) {
var candidates = ["SHOW", "Show"];
var i;
if (value === null || value === undefined || value === "") {
return;
}
for (i = 0; i < candidates.length; i += 1) {
if (setEssentialProperty(layer, candidates[i], value)) {
return;
}
}
warn(label + ": no Essential Property named " + candidates.join(" or ") +
". Available: " + listEssentialPropertyNames(layer).join(", "));
}
function setCompStartFrame(comp, frameNumber) {
try {
comp.displayStartFrame = frameNumber;
@@ -417,6 +458,7 @@
overlayLayer.enabled = true;
setEssentialProperty(overlayLayer, "DATE", ctx.slate.date);
setEssentialProperty(overlayLayer, "SHOT NAME", ctx.slate.versionName);
setShowField(overlayLayer, ctx.slate.show, "Overlay SHOW");
} else {
warn("Overlay comp \"" + ctx.overlayComp + "\" not found — rendering without burn-ins");
}
@@ -439,15 +481,19 @@
var slateLayer = previewComp.layer("NETFLIX_SLATE");
if (slateLayer) {
// Index-addressed properties match the panel exactly (3 = version
// name, 10 = shot code); the rest are addressed by name.
setEssentialPropertyByIndex(slateLayer, 3, ctx.slate.versionName);
// Identity fields match the panel's indices (3 = version name,
// 10 = shot name) and are also written by name; the rest are
// addressed by name only.
// VersionName carries the full "{shotCode}_cmp_TT_{version}";
// ShotName is the bare shot code, with no version suffix.
setSlateIdentity(slateLayer, "VersionName", 3, ctx.slate.versionName, "Version Name");
setSlateIdentity(slateLayer, "ShotName", 10, ctx.slate.shotCode, "Shot Name");
setEssentialProperty(slateLayer, "Date", ctx.slate.date);
setEssentialProperty(slateLayer, "Desc", ctx.slate.description);
setEssentialPropertyByIndex(slateLayer, 10, ctx.slate.shotCode);
setEssentialProperty(slateLayer, "Episode", ctx.slate.episode);
setEssentialProperty(slateLayer, "Scene", ctx.slate.scene);
setEssentialProperty(slateLayer, "Frames", result.frameCount);
setShowField(slateLayer, ctx.slate.show, "Slate SHOW");
setSlateField(slateLayer, ctx.slateScopeProp, ctx.slate.vfxScope, "VFX Scope");
// The slate's Notes field carries this submission's note; when the
+2121 -229
View File
File diff suppressed because it is too large Load Diff
+332 -20
View File
@@ -6,7 +6,161 @@ A dockable ScriptUI panel for Adobe After Effects 2024+ that integrates with the
## Configuration
At the top of the script, four global variables control how the panel connects to your project:
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) |
| **Path Mappings** | *Optional.* Rewrites paths the **server** supplies — see below |
### Server paths vs. this machine
The server addresses render folders from its own root (`render.outputRoot`,
e.g. `//SAN`), which a workstation may not resolve — the render worker
translates them with its own `pathMappings` because it runs as a service
account. The panel needs the same translation to open a render for QC.
It resolves this itself in most cases, trying in order:
1. **Path Mappings**, if configured — format `//SAN/=V:/_EXPORTS/`, several
separated by `;`.
2. **The server path as given** — correct when `render.outputRoot` is already
a path this machine can reach.
3. **Re-based on Export Root** — the server's export layout mirrors the panel's
from the show folder down (`{root}/{showId}/{episode}/{shot}/{version}`), so
the tail is simply re-attached to Export Root.
Step 3 is why this usually needs no configuration. **Diagnostics** checks the
whole thing against a real render folder from the QC queue and names every path
it tried when it fails.
### More than one on-disk convention
Every candidate is tested for existence and the first that resolves wins, so a
studio whose output root changed at some point can map the **same prefix more
than once** and let the panel work out which applies per export:
```
//SAN/=V:/_EXPORTS/;//SAN/=V:/_EXPORTS/UNG/
```
Older exports keep whatever path was stored on them when they were queued —
changing `render.outputRoot` on the server only affects new ones — so mixed
conventions in one database are normal and permanent. Add a mapping per
convention rather than trying to make one rewrite cover them all.
---
## 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
```
### Frame rate
Comps are built at the **shot record's `fps`**, and plates are conformed to it.
That value is the show's delivery rate and the authority; a plate's own rate is
whatever happens to be on disk.
`fps` defaults to 24 when a shot is created, so **check it after importing a
show that is not 24** — every shot carries its own value, and a wrong one
produces comps at the wrong rate, plates conformed to the wrong speed, and
timecode-to-frame sums that are quietly off.
A plate at a whole-number multiple of the show rate (50 fps on a 25 fps show) is
a deliberate over-crank and is conformed as intended. Validation reports the
difference either way, saying which of the two it looks like.
**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 |
|---|---|---|
@@ -21,13 +175,15 @@ At the top of the script, four global variables control how the panel connects t
## Panel Layout
The panel is divided into five sections:
The panel is divided into seven 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
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
---
@@ -52,6 +208,51 @@ Constructs a full shot composite in the open AE project from the episode and sho
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](#diagnostics-and-logging).
---
## Render Pipeline
### Queue Export
Saves the project, builds the render manifest from the selected comp and the
shot record, and submits it to the farm.
| Option | Effect |
|---|---|
| **Urgent** | Priority 20 — claimable outside the render window, ahead of normal jobs |
| **No preview** | Renders the EXRs but builds no preview, inheriting the previous export's MOV, review MP4 and thumbnail |
**No preview** exists for deliverables framed differently from the review —
unscaled or un-punched-in EXRs. A preview rebuilt from those frames would be
the wrong picture, while the earlier export's MOV is already correct, so it
carries over instead. The export still goes through QC, and the delivery
package still gets a MOV.
Leave it unticked for an ordinary submission: the preview is what QC and the
client review see.
---
## 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
@@ -64,7 +265,7 @@ Updates the **Status** panel to show the current count of selected `CompItem`s.
### 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`).
- Shot codes are read by anchoring on the selected project's showId — see [Shot Code Convention](#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.
@@ -160,7 +361,7 @@ Imports a picture-lock (offline cut) video file and trims it to the correct sequ
**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`).
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.
@@ -172,17 +373,37 @@ Imports a picture-lock (offline cut) video file and trims it to the correct sequ
## Workspace
### Per-project templates
Each show has its own template AEP — its overlay, slate/export template and,
most importantly, its **show LUT**. These are configured per project on the web
app under **Project → Settings → Pipeline**, not in the panel, because the
render farm's headless preview build reads the same values: if the two
disagreed, a farm preview would be quietly the wrong colour.
| Setting | Purpose |
|---|---|
| **Template project (.aep)** | Imported by Initialise Workspace and by every headless preview build |
| **Renders root** | Where per-shot pre-renders live; the panel appends the shot code (Import Renders) |
| **Overlay / Slate / LUT comp** | Only needed when a template departs from the naming convention |
Comp names default to a convention derived from the show ID:
`{showId}_VFX_OVERLAY`, `{showId}_EXPORT_TEMPLATE`, `_SHOW LUT`. A show whose
template follows the pattern needs no comp configuration at all — leave the
fields blank and they follow the convention, including any later change to it.
### Initialise Workspace
One-time setup that creates the standard project folder hierarchy, imports the slate/overlay template AEP, and configures color settings.
Works for any project: the episode folders and the template both come from the
selected project rather than being fixed to one show.
**Folder structure created:**
```
__SHOTS/
UNG_101/
UNG_102/
…
UNG_117/
{EPISODE_CODE}/ ← one per episode, from the project's episode list
… (episodic shows only; standard shows get none)
_PREVIEWS/
_PRECOMPS/
_PICLOCKS/
@@ -192,8 +413,15 @@ _RENDERS/
_UTILITIES/
```
Episodes come from `GET /api/ext/projects/{code}/episodes`. If a show has none
entered yet, the folders found under its footage root are used instead, so the
button still does something useful on day one.
**Template import:**
Imports `X:/shared_projects_2026/UNGO_VFX/production/working_files/UNG_VFXOVERLAY_SLATE_TEMPLATE.aep` as a project merge.
Imports the project's **Template project (.aep)** as a project merge — see
[Per-project templates](#per-project-templates). If none is configured the
folders and colour settings are still applied, and the status line says the
template was not set.
**Color settings (applied outside the undo group):**
- Sets project bit depth to **32-bit**.
@@ -246,15 +474,19 @@ Accept: application/json
## 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`)
Shot codes are the project's **showId** followed by three-digit tokens:
Example: `UNG_106_010_020`
| 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`) |
Episode codes follow the pattern `AAA_NNN` (e.g. `UNG_106`).
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`).
---
@@ -296,3 +528,83 @@ The **Status** panel at the bottom of the UI shows two lines:
- **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.
---
## Versions
The panel's version is the `PANEL_VERSION` constant at the top of
`VFXReviewConnector.jsx`. It appears in the panel title, in every diagnostics
report, and is sent to the server when the panel loads.
**Pipeline → Machines → Deployed tool versions** then shows which version each
workstation is running, alongside the render workers. Anything behind the newest
version seen for that tool is flagged `→ rebuild to vX` — so updating one
machine is what surfaces the ones still to do. No expected-version list to keep
in sync; the newest thing reporting in is the benchmark.
**Bump `PANEL_VERSION` whenever you copy the .jsx to a workstation.** If two
machines report the same version but behave differently, one of them was copied
without the bump.
---
## 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.
+13 -1
View File
@@ -4,7 +4,8 @@ import { auth } from "@/auth";
import { db } from "@/lib/db";
import { revalidatePath } from "next/cache";
import { z } from "zod";
import { ProjectStatus } from "@prisma/client";
import { Prisma, ProjectStatus } from "@prisma/client";
import { pipelineConfigSchema } from "@/lib/render-pipeline/project-templates";
const createProjectSchema = z.object({
name: z.string().min(1).max(100),
@@ -76,6 +77,8 @@ const updateProjectSchema = z.object({
startDate: z.string().optional().nullable(),
slackWebhook: z.string().url().optional().or(z.literal("")).nullable(),
slackChannel: z.string().optional().nullable(),
/** Per-production AE workspace: template AEP, renders root, comp overrides. */
pipelineConfig: pipelineConfigSchema.optional().nullable(),
});
export async function updateProject(data: z.infer<typeof updateProjectSchema>) {
@@ -103,6 +106,15 @@ export async function updateProject(data: z.infer<typeof updateProjectSchema>) {
...(rest.startDate !== undefined && { startDate: rest.startDate ? new Date(rest.startDate) : null }),
...(rest.slackWebhook !== undefined && { slackWebhook: rest.slackWebhook || null }),
...(rest.slackChannel !== undefined && { slackChannel: rest.slackChannel || null }),
// Blank fields are dropped rather than stored as empty strings, so a comp
// name left blank keeps following the convention instead of pinning "".
...(rest.pipelineConfig !== undefined && {
pipelineConfig: rest.pipelineConfig
? (Object.fromEntries(
Object.entries(rest.pipelineConfig).filter(([, v]) => typeof v === "string" && v.trim())
) as Prisma.InputJsonValue)
: Prisma.DbNull,
}),
},
});
+36
View File
@@ -489,6 +489,42 @@ export async function updateShotNotes(shotId: string, notes: string) {
return { success: true };
}
// ── Update Shot Slate Fields ──────────────────────────────────────────────────
export async function updateShotSlate(
shotId: string,
data: {
slateType?: string | null;
slateDescription?: string | null;
slateVfxScope?: string | null;
slateSubmissionNote?: string | null;
clientCode?: string | null;
}
) {
const session = await auth();
if (!session?.user) throw new Error("Unauthorized");
if (!["ADMIN", "PRODUCER", "SUPERVISOR"].includes(session.user.role)) {
throw new Error("Insufficient permissions");
}
const shot = await db.shot.findUnique({ where: { id: shotId }, select: { projectId: true } });
if (!shot) throw new Error("Shot not found");
await db.shot.update({
where: { id: shotId },
data: {
slateType: data.slateType !== undefined ? (data.slateType?.trim() || null) : undefined,
slateDescription: data.slateDescription !== undefined ? (data.slateDescription?.trim() || null) : undefined,
slateVfxScope: data.slateVfxScope !== undefined ? (data.slateVfxScope?.trim() || null) : undefined,
slateSubmissionNote: data.slateSubmissionNote !== undefined ? (data.slateSubmissionNote?.trim() || null) : undefined,
clientCode: data.clientCode !== undefined ? (data.clientCode?.trim() || null) : undefined,
},
});
revalidatePath(`/projects/${shot.projectId}`);
return { success: true };
}
// ── Toggle Key Shot ───────────────────────────────────────────────────────────
export async function toggleKeyShot(shotId: string, isKeyShot: boolean) {
@@ -4,7 +4,7 @@ import { useState } from "react";
import Link from "next/link";
import { useQuery, useQueryClient } from "@tanstack/react-query";
import { useSession } from "next-auth/react";
import { RefreshCw, RotateCcw, XCircle, CheckCircle2, Server } from "lucide-react";
import { RefreshCw, RotateCcw, XCircle, CheckCircle2, Server, Package } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Progress } from "@/components/ui/progress";
import {
@@ -112,6 +112,18 @@ export function PipelineQueueClient({ projects }: Props) {
</p>
</div>
<div className="flex items-center gap-2">
<Link href="/pipeline/deliveries">
<Button variant="outline" size="sm">
<Package className="h-4 w-4 mr-2" />
Deliveries
</Button>
</Link>
<Link href="/pipeline/deliveries">
<Button variant="outline" size="sm">
<Package className="h-4 w-4 mr-2" />
Deliveries
</Button>
</Link>
<Link href="/pipeline/machines">
<Button variant="outline" size="sm">
<Server className="h-4 w-4 mr-2" />
@@ -268,6 +280,124 @@ export function PipelineQueueClient({ projects }: Props) {
</tbody>
</table>
</div>
<BlenderQueue projectId={projectId} />
</div>
);
}
interface BlenderJobRow {
id: string;
label: string | null;
status: string;
attempt: number;
maxAttempts: number;
progress: number;
currentFrame: number | null;
totalFrames: number | null;
etaSeconds: number | null;
errorMessage: string | null;
machineName: string | null;
submittedBy: string | null;
projectCode: string | null;
blendFile: string | null;
frameStart: number | null;
frameEnd: number | null;
createdAt: string;
}
const BLENDER_STATUS_STYLES: Record<string, string> = {
QUEUED: "bg-zinc-500/15 text-zinc-300 border-zinc-500/30",
CLAIMED: "bg-blue-500/15 text-blue-400 border-blue-500/30",
RUNNING: "bg-blue-500/15 text-blue-400 border-blue-500/30",
COMPLETED: "bg-emerald-500/15 text-emerald-400 border-emerald-500/30",
FAILED: "bg-red-500/15 text-red-400 border-red-500/30",
CANCELLED: "bg-zinc-500/10 text-zinc-500 border-zinc-600/30",
EXPIRED: "bg-red-500/15 text-red-400 border-red-500/30",
};
/**
* Standalone Blender renders. They have no Export behind them, so they cannot
* appear in the table above — but they share the queue, and a render nobody can
* see is a render nobody can retry.
*/
function BlenderQueue({ projectId }: { projectId: string }) {
const { toast } = useToast();
const queryClient = useQueryClient();
const { data } = useQuery({
queryKey: ["blender-jobs", projectId],
queryFn: async () => {
const qs = projectId && projectId !== "all" ? `?projectId=${encodeURIComponent(projectId)}` : "";
const res = await fetch(`/api/render/blender${qs}`);
if (!res.ok) throw new Error("Failed to load Blender jobs");
return res.json() as Promise<{ jobs: BlenderJobRow[] }>;
},
refetchInterval: 5000,
});
async function jobAction(id: string, verb: "cancel" | "retry") {
const res = await fetch(`/api/render/blender/${id}?action=${verb}`, { method: "POST" });
if (!res.ok) {
const body = await res.json().catch(() => ({}));
toast({ title: `${verb} failed`, description: body.error ?? res.statusText, variant: "destructive" });
}
queryClient.invalidateQueries({ queryKey: ["blender-jobs"] });
}
const jobs = data?.jobs ?? [];
if (jobs.length === 0) return null;
return (
<div className="rounded-lg border border-zinc-800 bg-zinc-900/40">
<div className="px-4 py-2.5 border-b border-zinc-800 text-sm font-medium text-white">
Blender renders
</div>
<div className="divide-y divide-zinc-800/60">
{jobs.map((j) => (
<div key={j.id} className="px-4 py-3 text-sm">
<div className="flex items-center gap-3 flex-wrap">
<span className="text-zinc-200">{j.label ?? "(untitled)"}</span>
<span className={cn("rounded-full border px-2 py-0.5 text-xs", BLENDER_STATUS_STYLES[j.status] ?? "")}>
{j.status.toLowerCase()}
</span>
{j.projectCode && <span className="text-xs text-zinc-500">{j.projectCode}</span>}
{j.frameStart != null && (
<span className="text-xs text-zinc-500">
frames {j.frameStart}–{j.frameEnd}
</span>
)}
{j.status === "RUNNING" && (
<span className="text-xs text-blue-400">
{Math.round(j.progress * 100)}%
{j.currentFrame != null ? ` · frame ${j.currentFrame}` : ""}
{j.etaSeconds ? ` · ETA ${formatEta(j.etaSeconds)}` : ""}
</span>
)}
{j.machineName && <span className="text-xs text-zinc-500">{j.machineName}</span>}
{j.attempt > 1 && (
<span className="text-xs text-zinc-500">
attempt {j.attempt}/{j.maxAttempts}
</span>
)}
<span className="ml-auto flex items-center gap-1">
{["QUEUED", "CLAIMED", "RUNNING"].includes(j.status) && (
<Button variant="ghost" size="icon-sm" title="Cancel" onClick={() => jobAction(j.id, "cancel")}>
<XCircle className="h-4 w-4 text-red-400" />
</Button>
)}
{["FAILED", "CANCELLED", "EXPIRED"].includes(j.status) && (
<Button variant="ghost" size="icon-sm" title="Requeue" onClick={() => jobAction(j.id, "retry")}>
<RotateCcw className="h-4 w-4 text-amber-400" />
</Button>
)}
</span>
</div>
{j.blendFile && <div className="mt-1 text-xs text-zinc-600 break-all">{j.blendFile}</div>}
{j.errorMessage && <div className="mt-1 text-xs text-red-400">{j.errorMessage}</div>}
</div>
))}
</div>
</div>
);
}
@@ -0,0 +1,328 @@
"use client";
import { useState } from "react";
import Link from "next/link";
import { useQuery, useQueryClient } from "@tanstack/react-query";
import { ArrowLeft, Package, CheckCircle2, XCircle, RefreshCw } from "lucide-react";
import { Button } from "@/components/ui/button";
import { useToast } from "@/components/ui/use-toast";
import { cn } from "@/lib/utils";
import { DELIVERY_STATUS_STYLES, statusLabel } from "../status-colors";
interface ReadyExport {
exportId: string;
shotCode: string;
episode: string;
versionString: string;
fileCount: number | null;
totalBytes: number | null;
deliveryMovPath: string | null;
hasChecksum: boolean;
qc: { result: string; reviewer: string | null; at: string } | null;
}
interface ReadyResponse {
episodes: { episode: string; count: number; exports: ReadyExport[] }[];
}
interface PackageRow {
id: string;
packageNumber: number;
name: string;
episode: string;
status: string;
rootPath: string | null;
errorMessage: string | null;
projectName: string;
createdAt: string;
builtAt: string | null;
deliveredAt: string | null;
itemCount: number;
verifiedCount: number;
items: {
id: string;
shotCode: string;
versionString: string;
status: string;
fileCount: number | null;
linkMode: string | null;
errorMessage: string | null;
}[];
}
interface ProjectOption {
id: string;
name: string;
code: string;
}
function formatBytes(bytes: number | null): string {
if (bytes == null) return "—";
const gb = bytes / 1_073_741_824;
return gb >= 1 ? `${gb.toFixed(1)} GB` : `${(bytes / 1_048_576).toFixed(0)} MB`;
}
export function DeliveriesClient({ canBuild }: { canBuild: boolean }) {
const { toast } = useToast();
const queryClient = useQueryClient();
const [projectId, setProjectId] = useState<string>("");
const [episode, setEpisode] = useState<string>("");
const [building, setBuilding] = useState(false);
const { data: projects } = useQuery({
queryKey: ["pipeline-projects"],
queryFn: async () => {
const res = await fetch("/api/projects");
if (!res.ok) throw new Error("Failed to load projects");
const body = await res.json();
return (body.projects ?? body) as ProjectOption[];
},
});
const { data: ready, isLoading: readyLoading } = useQuery({
queryKey: ["delivery-ready", projectId],
queryFn: async () => {
const res = await fetch(`/api/deliveries/ready?projectId=${encodeURIComponent(projectId)}`);
if (!res.ok) throw new Error((await res.json().catch(() => ({})))?.error ?? "Failed to load ready exports");
return res.json() as Promise<ReadyResponse>;
},
enabled: Boolean(projectId),
});
const { data: packages } = useQuery({
queryKey: ["delivery-packages", projectId],
queryFn: async () => {
const res = await fetch(`/api/deliveries${projectId ? `?projectId=${encodeURIComponent(projectId)}` : ""}`);
if (!res.ok) throw new Error("Failed to load packages");
return res.json() as Promise<{ packages: PackageRow[] }>;
},
// A build is a queued job like any other — poll while one is in flight.
refetchInterval: 5000,
});
async function build(ep: string) {
if (!projectId) return;
setBuilding(true);
try {
const res = await fetch("/api/deliveries", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ projectId, episode: ep || null }),
});
const body = await res.json().catch(() => ({}));
if (!res.ok) {
toast({ title: "Build failed", description: body.error ?? res.statusText, variant: "destructive" });
} else {
toast({
title: `Package #${body.package.packageNumber} queued`,
description: `${body.package.itemCount} shots → ${body.package.rootPath}`,
});
queryClient.invalidateQueries({ queryKey: ["delivery-packages"] });
queryClient.invalidateQueries({ queryKey: ["delivery-ready"] });
}
} finally {
setBuilding(false);
}
}
async function packageAction(id: string, verb: "delivered" | "cancel") {
const res = await fetch(`/api/deliveries/${id}/${verb}`, { method: "POST" });
const body = await res.json().catch(() => ({}));
if (!res.ok) {
toast({ title: `${verb} failed`, description: body.error ?? res.statusText, variant: "destructive" });
}
queryClient.invalidateQueries({ queryKey: ["delivery-packages"] });
queryClient.invalidateQueries({ queryKey: ["delivery-ready"] });
}
const episodes = ready?.episodes ?? [];
const shown = episode ? episodes.filter((e) => e.episode === episode) : episodes;
return (
<div className="p-6 space-y-6 max-w-6xl">
<div className="flex items-center gap-3">
<Link href="/pipeline">
<Button variant="ghost" size="icon-sm">
<ArrowLeft className="h-4 w-4" />
</Button>
</Link>
<h1 className="text-xl font-semibold text-white">Delivery packages</h1>
</div>
{/* Picker */}
<div className="flex items-center gap-3 flex-wrap">
<select
value={projectId}
onChange={(e) => {
setProjectId(e.target.value);
setEpisode("");
}}
className="rounded-md border border-zinc-800 bg-zinc-900 px-3 py-1.5 text-sm text-zinc-200"
>
<option value="">Select a project…</option>
{(projects ?? []).map((p) => (
<option key={p.id} value={p.id}>
{p.name} ({p.code})
</option>
))}
</select>
{episodes.length > 0 && (
<select
value={episode}
onChange={(e) => setEpisode(e.target.value)}
className="rounded-md border border-zinc-800 bg-zinc-900 px-3 py-1.5 text-sm text-zinc-200"
>
<option value="">All episodes</option>
{episodes.map((e) => (
<option key={e.episode} value={e.episode}>
{e.episode || "(no episode)"} — {e.count} ready
</option>
))}
</select>
)}
</div>
{/* Ready to build */}
{projectId && (
<div className="rounded-lg border border-zinc-800 bg-zinc-900/40">
<div className="px-4 py-2.5 border-b border-zinc-800 text-sm font-medium text-white">
Ready for delivery
</div>
{readyLoading && <div className="p-4 text-sm text-zinc-500">Loading…</div>}
{!readyLoading && shown.length === 0 && (
<div className="p-4 text-sm text-zinc-500">
Nothing has passed QC yet. Exports appear here once QC passes them.
</div>
)}
{shown.map((ep) => (
<div key={ep.episode} className="border-b border-zinc-800/60 last:border-0">
<div className="flex items-center justify-between gap-4 px-4 py-3 flex-wrap">
<div>
<span className="text-white text-sm font-medium">
{ep.episode ? `Episode ${ep.episode}` : "No episode"}
</span>
<span className="ml-3 text-sm text-zinc-400">Ready: {ep.count} shots</span>
{ep.exports.some((x) => !x.hasChecksum) && (
<span className="ml-3 text-xs text-amber-400">
{ep.exports.filter((x) => !x.hasChecksum).length} without a validation checksum
</span>
)}
</div>
{canBuild && (
<Button size="sm" onClick={() => build(ep.episode)} disabled={building}>
<Package className="h-4 w-4 mr-2" />
Build delivery
</Button>
)}
</div>
<div className="px-4 pb-3 grid sm:grid-cols-2 lg:grid-cols-3 gap-x-6 gap-y-1">
{ep.exports.map((x) => (
<div key={x.exportId} className="flex items-center gap-2 text-xs">
<Link href={`/pipeline/exports/${x.exportId}`} className="text-zinc-300 hover:text-white">
{x.shotCode}
</Link>
<span className="text-zinc-500">{x.versionString}</span>
<span className="text-zinc-600">{x.fileCount ?? "?"} frames</span>
<span className="text-zinc-600">{formatBytes(x.totalBytes)}</span>
{!x.deliveryMovPath && <span className="text-amber-500/80">no MOV</span>}
</div>
))}
</div>
</div>
))}
</div>
)}
{/* History — packages are permanent (§11.5) */}
<div className="rounded-lg border border-zinc-800 bg-zinc-900/40">
<div className="px-4 py-2.5 border-b border-zinc-800 text-sm font-medium text-white">Packages</div>
<div className="divide-y divide-zinc-800/60">
{(packages?.packages ?? []).map((p) => (
<details key={p.id} className="group">
<summary className="flex items-center gap-3 px-4 py-3 cursor-pointer hover:bg-zinc-900/60 flex-wrap">
<span className="text-sm text-white font-medium">#{p.packageNumber}</span>
<span className="text-sm text-zinc-300">{p.name}</span>
<span
className={cn(
"rounded-full border px-2 py-0.5 text-xs",
DELIVERY_STATUS_STYLES[p.status] ?? ""
)}
>
{statusLabel(p.status)}
</span>
<span className="text-xs text-zinc-500">
{p.episode ? `episode ${p.episode} · ` : ""}
{p.verifiedCount}/{p.itemCount} shots
</span>
<span className="text-xs text-zinc-600">{new Date(p.createdAt).toLocaleDateString()}</span>
{p.status === "BUILDING" && <RefreshCw className="h-3.5 w-3.5 text-blue-400 animate-spin" />}
<span className="ml-auto flex items-center gap-2">
{canBuild && p.status === "READY" && (
<Button
size="sm"
variant="outline"
onClick={(e) => {
e.preventDefault();
packageAction(p.id, "delivered");
}}
>
<CheckCircle2 className="h-4 w-4 mr-2 text-emerald-400" />
Mark delivered
</Button>
)}
{canBuild && ["QUEUED", "FAILED", "DRAFT"].includes(p.status) && (
<Button
size="sm"
variant="outline"
onClick={(e) => {
e.preventDefault();
packageAction(p.id, "cancel");
}}
>
<XCircle className="h-4 w-4 mr-2 text-red-400" />
Cancel
</Button>
)}
</span>
</summary>
<div className="px-4 pb-4 space-y-2">
{p.rootPath && <div className="text-xs text-zinc-500 break-all">{p.rootPath}</div>}
{p.errorMessage && <div className="text-xs text-red-400">{p.errorMessage}</div>}
{p.deliveredAt && (
<div className="text-xs text-emerald-400">
Delivered {new Date(p.deliveredAt).toLocaleString()}
</div>
)}
<div className="grid sm:grid-cols-2 lg:grid-cols-3 gap-x-6 gap-y-1">
{p.items.map((item) => (
<div key={item.id} className="flex items-center gap-2 text-xs">
<span
className={cn(
item.status === "VERIFIED"
? "text-emerald-400"
: item.status === "FAILED"
? "text-red-400"
: "text-zinc-500"
)}
>
{item.status === "VERIFIED" ? "✓" : item.status === "FAILED" ? "✕" : "·"}
</span>
<span className="text-zinc-300">{item.shotCode}</span>
<span className="text-zinc-500">{item.versionString}</span>
{item.fileCount != null && <span className="text-zinc-600">{item.fileCount}f</span>}
{item.linkMode && <span className="text-zinc-600">{item.linkMode}</span>}
{item.errorMessage && <span className="text-red-400">{item.errorMessage}</span>}
</div>
))}
</div>
</div>
</details>
))}
{(packages?.packages ?? []).length === 0 && (
<div className="p-4 text-sm text-zinc-500">No packages built yet</div>
)}
</div>
</div>
</div>
);
}
@@ -0,0 +1,12 @@
import { auth } from "@/auth";
import { redirect } from "next/navigation";
import { DeliveriesClient } from "./DeliveriesClient";
export const dynamic = "force-dynamic";
export default async function DeliveriesPage() {
const session = await auth();
if (!session?.user) redirect("/login");
if (session.user.role === "CLIENT") redirect("/dashboard");
return <DeliveriesClient canBuild={["ADMIN", "PRODUCER", "SUPERVISOR"].includes(session.user.role as string)} />;
}
@@ -1,8 +1,9 @@
"use client";
import { useState } from "react";
import Link from "next/link";
import { useQuery, useQueryClient } from "@tanstack/react-query";
import { ArrowLeft, RotateCcw, XCircle } from "lucide-react";
import { ArrowLeft, RotateCcw, XCircle, ShieldAlert } from "lucide-react";
import { Button } from "@/components/ui/button";
import { useToast } from "@/components/ui/use-toast";
import { cn } from "@/lib/utils";
@@ -66,12 +67,49 @@ interface ExportDetail {
note: string | null;
createdAt: string;
}[];
validations: {
id: string;
renderJobId: string;
checkName: string;
status: string;
expected: string | null;
actual: string | null;
message: string | null;
details: unknown;
createdAt: string;
}[];
qcReviews: {
id: string;
result: string;
notes: string | null;
reviewerName: string | null;
source: string;
createdAt: string;
}[];
deliveryItems: {
id: string;
status: string;
exrPath: string | null;
linkMode: string | null;
package: { id: string; name: string; episode: string; status: string; packageNumber: number };
}[];
};
}
const CHECK_STYLES: Record<string, string> = {
PASS: "text-emerald-400",
FAIL: "text-red-400",
WARN: "text-amber-400",
SKIPPED: "text-zinc-500",
};
export function ExportDetailClient({ exportId }: { exportId: string }) {
const { toast } = useToast();
const queryClient = useQueryClient();
const [overrideOpen, setOverrideOpen] = useState(false);
const [overrideReason, setOverrideReason] = useState("");
const [overrideSkipPreview, setOverrideSkipPreview] = useState(false);
const [overriding, setOverriding] = useState(false);
const { data, isLoading, error } = useQuery({
queryKey: ["pipeline-export", exportId],
@@ -92,6 +130,31 @@ export function ExportDetailClient({ exportId }: { exportId: string }) {
queryClient.invalidateQueries({ queryKey: ["pipeline-export", exportId] });
}
async function overrideValidation() {
setOverriding(true);
try {
const res = await fetch(`/api/render/exports/${exportId}/override-validation`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ reason: overrideReason, skipPreview: overrideSkipPreview }),
});
const body = await res.json().catch(() => ({}));
if (!res.ok) {
toast({ title: "Override failed", description: body.error ?? res.statusText, variant: "destructive" });
return;
}
toast({
title: "Validation overridden",
description: `${(body.overridden ?? []).join(", ") || "No failed checks recorded"} — continuing to preview and QC`,
});
setOverrideOpen(false);
setOverrideReason("");
queryClient.invalidateQueries({ queryKey: ["pipeline-export", exportId] });
} finally {
setOverriding(false);
}
}
if (isLoading) return <div className="p-6 text-zinc-500">Loading…</div>;
if (error || !data) {
return (
@@ -145,6 +208,11 @@ export function ExportDetailClient({ exportId }: { exportId: string }) {
<RotateCcw className="h-4 w-4 mr-2 text-amber-400" /> Retry
</Button>
)}
{e.status === "VALIDATION_FAILED" && !overrideOpen && (
<Button variant="outline" size="sm" onClick={() => setOverrideOpen(true)}>
<ShieldAlert className="h-4 w-4 mr-2 text-amber-400" /> Override validation
</Button>
)}
{ACTIVE_STATUSES.includes(e.status) && (
<Button variant="outline" size="sm" onClick={() => action("cancel")}>
<XCircle className="h-4 w-4 mr-2 text-red-400" /> Cancel
@@ -153,6 +221,64 @@ export function ExportDetailClient({ exportId }: { exportId: string }) {
</div>
</div>
{/* Override — a human overruling the checks, so the reason is required
and kept on the export's timeline. */}
{overrideOpen && (
<div className="rounded-lg border border-amber-500/30 bg-amber-500/5 p-4 space-y-3">
<div className="text-sm text-amber-200">
Override the failed validation for {e.shot.shotCode} {e.versionString}?
</div>
<p className="text-xs text-zinc-400">
The render continues to preview and then QC — it is not delivered directly, and the failed
checks stay on record and still show up in the QC queue. Say why, so the next person
reading this export knows what was waved through.
</p>
<textarea
value={overrideReason}
onChange={(ev) => setOverrideReason(ev.target.value)}
rows={2}
autoFocus
placeholder="e.g. plate unreachable from the render node; timecode checked by hand against the EDL"
className="w-full rounded-md border border-zinc-800 bg-zinc-950 px-3 py-2 text-sm text-zinc-200 placeholder:text-zinc-600"
/>
<label className="flex items-start gap-2 text-xs text-zinc-300">
<input
type="checkbox"
checked={overrideSkipPreview}
onChange={(ev) => setOverrideSkipPreview(ev.target.checked)}
className="mt-0.5"
/>
<span>
Skip the preview build and reuse the previous export&apos;s review media.
<span className="block text-zinc-500">
For EXRs framed differently from the review — unscaled or un-punched-in — where a
preview rebuilt from these frames would be the wrong picture.
</span>
</span>
</label>
<div className="flex items-center gap-2">
<Button
size="sm"
onClick={overrideValidation}
disabled={overrideReason.trim().length < 3 || overriding}
>
{overriding ? "Overriding…" : "Override and continue"}
</Button>
<Button
variant="ghost"
size="sm"
onClick={() => {
setOverrideOpen(false);
setOverrideReason("");
setOverrideSkipPreview(false);
}}
>
Cancel
</Button>
</div>
</div>
)}
{/* Manifest */}
<div className="rounded-lg border border-zinc-800 bg-zinc-900/40">
<div className="px-4 py-2.5 border-b border-zinc-800 text-sm font-medium text-white">Manifest</div>
@@ -189,6 +315,100 @@ export function ExportDetailClient({ exportId }: { exportId: string }) {
</div>
)}
{/* Validation results — newest run first */}
{e.validations.length > 0 && (
<div className="rounded-lg border border-zinc-800 bg-zinc-900/40">
<div className="px-4 py-2.5 border-b border-zinc-800 text-sm font-medium text-white flex items-center gap-3">
Validation
{/* A waved-through failure must stay visible long after the event
scrolls down the timeline. */}
{e.events.some((ev) => ev.note?.startsWith("Validation overridden")) && (
<span className="rounded-full border border-amber-500/30 bg-amber-500/15 px-2 py-0.5 text-xs text-amber-400">
overridden
</span>
)}
{(() => {
const latestRun = e.validations[e.validations.length - 1].renderJobId;
const rows = e.validations.filter((v) => v.renderJobId === latestRun);
const failed = rows.filter((v) => v.status === "FAIL").length;
const warned = rows.filter((v) => v.status === "WARN").length;
return (
<span className={cn("text-xs", failed ? "text-red-400" : warned ? "text-amber-400" : "text-emerald-400")}>
{failed ? `${failed} failed` : warned ? `${warned} warning${warned > 1 ? "s" : ""}` : "all checks passed"}
</span>
);
})()}
</div>
<div className="divide-y divide-zinc-800/60">
{(() => {
const latestRun = e.validations[e.validations.length - 1].renderJobId;
// Failures first: the reason the export stopped should not need scrolling for.
const order = { FAIL: 0, WARN: 1, PASS: 2, SKIPPED: 3 } as Record<string, number>;
return e.validations
.filter((v) => v.renderJobId === latestRun)
.slice()
.sort((a, b) => (order[a.status] ?? 9) - (order[b.status] ?? 9))
.map((v) => (
<div key={v.id} className="px-4 py-2 text-sm flex items-start gap-3">
<span className={cn("w-16 shrink-0 text-xs font-medium", CHECK_STYLES[v.status] ?? "")}>
{v.status}
</span>
<span className="w-48 shrink-0 text-zinc-300 font-mono text-xs pt-0.5">{v.checkName}</span>
<span className="text-zinc-400 text-xs pt-0.5">
{v.message ??
(v.expected === v.actual ? v.actual : `expected ${v.expected ?? "—"}, got ${v.actual ?? "—"}`)}
</span>
</div>
));
})()}
</div>
</div>
)}
{/* QC history — latest decision is the authoritative one */}
{e.qcReviews.length > 0 && (
<div className="rounded-lg border border-zinc-800 bg-zinc-900/40">
<div className="px-4 py-2.5 border-b border-zinc-800 text-sm font-medium text-white">QC</div>
<div className="divide-y divide-zinc-800/60">
{e.qcReviews.map((q) => (
<div key={q.id} className="px-4 py-2.5 text-sm">
<div className="flex items-center gap-3 flex-wrap">
<span className={cn("text-xs font-medium", q.result === "PASS" ? "text-emerald-400" : "text-red-400")}>
QC {q.result}
</span>
<span className="text-xs text-zinc-400">{q.reviewerName ?? "unknown reviewer"}</span>
<span className="text-xs text-zinc-500">{q.source === "AE_PANEL" ? "AE panel" : "web"}</span>
<span className="text-xs text-zinc-500">{new Date(q.createdAt).toLocaleString()}</span>
</div>
{q.notes && <div className="mt-1 text-xs text-zinc-400 whitespace-pre-wrap">{q.notes}</div>}
</div>
))}
</div>
</div>
)}
{/* Delivery membership */}
{e.deliveryItems.length > 0 && (
<div className="rounded-lg border border-zinc-800 bg-zinc-900/40">
<div className="px-4 py-2.5 border-b border-zinc-800 text-sm font-medium text-white">Deliveries</div>
<div className="divide-y divide-zinc-800/60">
{e.deliveryItems.map((d) => (
<div key={d.id} className="px-4 py-2.5 text-sm flex items-center gap-3 flex-wrap">
<Link href="/pipeline/deliveries" className="text-zinc-200 hover:text-white">
#{d.package.packageNumber} · {d.package.name}
</Link>
<span className="text-xs text-zinc-500">episode {d.package.episode || "—"}</span>
<span className="text-xs text-zinc-400">{d.package.status}</span>
<span className="text-xs text-zinc-500">
item {d.status.toLowerCase()}
{d.linkMode ? ` · ${d.linkMode}` : ""}
</span>
</div>
))}
</div>
</div>
)}
{/* Render attempts */}
<div className="rounded-lg border border-zinc-800 bg-zinc-900/40">
<div className="px-4 py-2.5 border-b border-zinc-800 text-sm font-medium text-white">
@@ -201,6 +201,77 @@ export function MachinesClient() {
})}
</div>
)}
<ToolVersions />
</div>
);
}
interface ToolRow {
id: string;
tool: string;
toolLabel: string;
machineName: string;
version: string;
buildRef: string | null;
hostUser: string | null;
hostApp: string | null;
lastSeenAt: string;
newestVersion: string;
outdated: boolean;
}
/**
* What is deployed where. Each tool reports its own version on startup, and
* anything behind the newest version seen for that tool is flagged — so
* updating one machine is what surfaces the ones still to do.
*/
function ToolVersions() {
const { data } = useQuery({
queryKey: ["tool-versions"],
queryFn: async () => {
const res = await fetch("/api/tools");
if (!res.ok) throw new Error("Failed to load tool versions");
return res.json() as Promise<{ tools: ToolRow[] }>;
},
refetchInterval: 30000,
});
const tools = data?.tools ?? [];
const stale = tools.filter((t) => t.outdated).length;
return (
<div className="rounded-lg border border-zinc-800 bg-zinc-900/40">
<div className="px-4 py-2.5 border-b border-zinc-800 text-sm font-medium text-white flex items-center gap-3">
Deployed tool versions
{stale > 0 && (
<span className="text-xs text-amber-400">
{stale} machine{stale > 1 ? "s" : ""} behind
</span>
)}
</div>
<div className="divide-y divide-zinc-800/60">
{tools.map((t) => (
<div key={t.id} className="px-4 py-2.5 text-sm flex items-center gap-3 flex-wrap">
<span className="w-44 shrink-0 text-zinc-300">{t.toolLabel}</span>
<span className="w-40 shrink-0 text-zinc-400 text-xs font-mono">{t.machineName}</span>
<span className={cn("text-xs font-mono", t.outdated ? "text-amber-400" : "text-emerald-400")}>
v{t.version}
</span>
{t.outdated && <span className="text-xs text-amber-400/80">→ rebuild to v{t.newestVersion}</span>}
{t.buildRef && <span className="text-xs text-zinc-600 font-mono">{t.buildRef}</span>}
{t.hostUser && <span className="text-xs text-zinc-600">{t.hostUser}</span>}
<span className="ml-auto text-xs text-zinc-600">
seen {new Date(t.lastSeenAt).toLocaleString()}
</span>
</div>
))}
{tools.length === 0 && (
<div className="p-4 text-sm text-zinc-500">
Nothing has reported yet. Versions appear as each panel and worker starts up.
</div>
)}
</div>
</div>
);
}
+10
View File
@@ -18,6 +18,16 @@ export const EXPORT_STATUS_STYLES: Record<string, string> = {
CANCELLED: "bg-zinc-500/10 text-zinc-500 border-zinc-600/30",
};
export const DELIVERY_STATUS_STYLES: Record<string, string> = {
DRAFT: "bg-zinc-500/15 text-zinc-300 border-zinc-500/30",
QUEUED: "bg-zinc-500/15 text-zinc-300 border-zinc-500/30",
BUILDING: "bg-blue-500/15 text-blue-400 border-blue-500/30",
READY: "bg-green-500/15 text-green-400 border-green-500/30",
DELIVERED: "bg-emerald-500/15 text-emerald-300 border-emerald-500/30",
FAILED: "bg-red-500/15 text-red-400 border-red-500/30",
CANCELLED: "bg-zinc-500/10 text-zinc-500 border-zinc-600/30",
};
export const FAILED_STATUSES = ["RENDER_FAILED", "VALIDATION_FAILED", "PREVIEW_FAILED", "QC_FAILED"];
export const ACTIVE_STATUSES = ["QUEUED", "RENDERING", "VALIDATING", "GENERATING_PREVIEW"];
@@ -58,6 +58,13 @@ interface ProjectTabsClientProps {
startDate: Date | null;
slackWebhook: string | null;
slackChannel: string | null;
pipelineConfig: {
templateAep?: string | null;
rendersRoot?: string | null;
overlayComp?: string | null;
previewComp?: string | null;
lutComp?: string | null;
} | null;
};
clients: Client[];
teamMembers: TeamMember[];
+7
View File
@@ -201,6 +201,13 @@ export default async function ProjectPage({ params }: { params: Promise<{ id: st
startDate: project.startDate,
slackWebhook: project.slackWebhook,
slackChannel: project.slackChannel,
pipelineConfig: project.pipelineConfig as {
templateAep?: string | null;
rendersRoot?: string | null;
overlayComp?: string | null;
previewComp?: string | null;
lutComp?: string | null;
} | null,
}}
clients={clients}
teamMembers={teamMembers}
@@ -30,11 +30,13 @@ import {
FileVideo,
Pencil,
Check,
LayoutList,
} from "lucide-react";
import { Input } from "@/components/ui/input";
import type { ShotWithDetails } from "@/types";
import { ShotSettingsTab } from "@/components/shots/ShotSettingsTab";
import { ShotExportsTab } from "@/components/shots/ShotExportsTab";
import { ShotSlateTab } from "@/components/shots/ShotSlateTab";
import { FootageViewer } from "@/components/shots/FootageViewer";
import { HighResUploadDialog } from "@/components/shots/HighResUploadDialog";
import { duplicateShot, internallyApproveShot, shareWithClient, unshareFromClient, unapproveShot, updateShotVersion } from "@/actions/shots";
@@ -90,7 +92,7 @@ export default function ShotDetailPage() {
const [isDuplicating, setIsDuplicating] = useState(false);
const [isActioning, setIsActioning] = useState(false);
const [highResDialogOpen, setHighResDialogOpen] = useState(false);
const [activeTab, setActiveTab] = useState<"tasks" | "reviews" | "footage" | "exports" | "settings">("tasks");
const [activeTab, setActiveTab] = useState<"tasks" | "slate" | "reviews" | "footage" | "exports" | "settings">("tasks");
const [editingVersion, setEditingVersion] = useState(false);
const [versionInput, setVersionInput] = useState("");
const [savingVersion, setSavingVersion] = useState(false);
@@ -520,6 +522,18 @@ export default function ShotDetailPage() {
<ListTodo className="h-4 w-4" />
Tasks
</button>
<button
onClick={() => setActiveTab("slate")}
className={cn(
"flex items-center gap-2 px-4 py-2.5 text-sm font-medium border-b-2 transition-colors -mb-px",
activeTab === "slate"
? "border-amber-500 text-amber-400"
: "border-transparent text-zinc-500 hover:text-zinc-300"
)}
>
<LayoutList className="h-4 w-4" />
Slate
</button>
<button
onClick={() => setActiveTab("reviews")}
className={cn(
@@ -583,6 +597,10 @@ export default function ShotDetailPage() {
/>
)}
{activeTab === "slate" && (
<ShotSlateTab shot={shot} projectName={projectName} onSaved={fetchShot} />
)}
{activeTab === "reviews" && (
<div className="space-y-3">
{tasks.length === 0 ? (
-2
View File
@@ -68,7 +68,6 @@ export async function GET(
fps: true,
duration: true,
thumbnailUrl: true,
notes: true,
createdAt: true,
},
},
@@ -100,7 +99,6 @@ export async function GET(
fps: true,
duration: true,
thumbnailUrl: true,
notes: true,
createdAt: true,
},
},
@@ -0,0 +1,23 @@
import { NextRequest, NextResponse } from "next/server";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { requirePipelineAdmin } from "@/lib/render-pipeline/session-auth";
import { cancelDeliveryPackage } from "@/lib/render-pipeline/deliveries";
// ── POST /api/deliveries/{id}/cancel ─────────────────────────────────────────
//
// Packages are never deleted (§11.5); a mistaken one is cancelled.
export async function POST(
_req: NextRequest,
{ params }: { params: Promise<{ packageId: string }> }
) {
try {
const user = await requirePipelineAdmin();
const { packageId } = await params;
const result = await cancelDeliveryPackage(packageId, user.id);
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
@@ -0,0 +1,24 @@
import { NextRequest, NextResponse } from "next/server";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { requirePipelineAdmin } from "@/lib/render-pipeline/session-auth";
import { markDelivered } from "@/lib/render-pipeline/deliveries";
// ── POST /api/deliveries/{id}/delivered (E19) ────────────────────────────────
//
// The folder has been uploaded to the client. Moves every packaged export to
// DELIVERED — the end of the pipeline.
export async function POST(
_req: NextRequest,
{ params }: { params: Promise<{ packageId: string }> }
) {
try {
const user = await requirePipelineAdmin();
const { packageId } = await params;
const result = await markDelivered(packageId, user.id);
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
+24
View File
@@ -0,0 +1,24 @@
import { NextRequest, NextResponse } from "next/server";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { requirePipelineUser } from "@/lib/render-pipeline/session-auth";
import { getReadyForDelivery } from "@/lib/render-pipeline/deliveries";
// ── GET /api/deliveries/ready?projectId=&episode= (E18) ──────────────────────
//
// READY_FOR_DELIVERY exports grouped by episode — "Episode 101 — Ready: 18 shots".
export async function GET(req: NextRequest) {
try {
await requirePipelineUser();
const { searchParams } = new URL(req.url);
const projectId = searchParams.get("projectId");
if (!projectId) {
return NextResponse.json({ error: "projectId is required" }, { status: 400 });
}
const result = await getReadyForDelivery(projectId, searchParams.get("episode"));
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
+54
View File
@@ -0,0 +1,54 @@
import { NextRequest, NextResponse } from "next/server";
import { DeliveryStatus } from "@prisma/client";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { requirePipelineUser, requirePipelineAdmin } from "@/lib/render-pipeline/session-auth";
import {
createDeliveryPackage,
createDeliverySchema,
listDeliveryPackages,
} from "@/lib/render-pipeline/deliveries";
// ── GET /api/deliveries (E17) · POST /api/deliveries (E16) ───────────────────
export async function GET(req: NextRequest) {
try {
await requirePipelineUser();
const { searchParams } = new URL(req.url);
const status = searchParams.get("status");
const result = await listDeliveryPackages({
projectId: searchParams.get("projectId") ?? undefined,
episode: searchParams.get("episode") ?? undefined,
status: status ? (status as DeliveryStatus) : undefined,
});
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
export async function POST(req: NextRequest) {
try {
// Building a package writes to the delivery volume and locks versions —
// producer/supervisor territory, not any signed-in user.
const user = await requirePipelineAdmin();
let raw: unknown;
try {
raw = await req.json();
} catch {
return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
}
const parsed = createDeliverySchema.safeParse(raw);
if (!parsed.success) {
return NextResponse.json({ error: "Invalid delivery request", details: parsed.error.issues }, { status: 422 });
}
const result = await createDeliveryPackage(parsed.data, user.id);
return NextResponse.json(result, { status: 201 });
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
@@ -0,0 +1,39 @@
import { NextRequest, NextResponse } from "next/server";
import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { qcSubmitSchema, submitQCReview } from "@/lib/render-pipeline/qc";
// ── POST /api/ext/exports/{exportId}/qc (E4) ─────────────────────────────────
//
// QC Pass / QC Fail from the AE panel. PASS → READY_FOR_DELIVERY and nothing
// else; FAIL → QC_FAILED and the comp task back to CHANGES (§10.2).
export async function POST(
req: NextRequest,
{ params }: { params: Promise<{ exportId: string }> }
) {
if (!isExtAuthorized(req)) {
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
}
const { exportId } = await params;
let raw: unknown;
try {
raw = await req.json();
} catch {
return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
}
const parsed = qcSubmitSchema.safeParse(raw);
if (!parsed.success) {
return NextResponse.json({ error: "Invalid QC submission", details: parsed.error.issues }, { status: 422 });
}
try {
const result = await submitQCReview(exportId, parsed.data, { source: "AE_PANEL" });
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
@@ -0,0 +1,49 @@
import { NextRequest, NextResponse } from "next/server";
import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { regeneratePreview } from "@/lib/render-pipeline/preview";
// ── POST /api/ext/exports/{exportId}/regenerate-preview (E15b) ───────────────
//
// Rebuild the preview MOV/MP4 for an export that already delivered one, after a
// slate or burn-in mistake was caught. Reuses the validated EXRs and keeps the
// version number; slate text edited on the web app's Slate tab is picked up.
//
// Body (all optional):
// vfxScope per-export override; omit to re-read the shot's slate field
// submissionNote same
// note audit note for the ExportEvent
export async function POST(
req: NextRequest,
{ params }: { params: Promise<{ exportId: string }> }
) {
if (!isExtAuthorized(req)) {
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
}
const { exportId } = await params;
let body: {
vfxScope?: string | null;
submissionNote?: string | null;
note?: string;
} = {};
try {
const parsed = await req.json();
if (parsed && typeof parsed === "object") body = parsed;
} catch {
// empty body is fine — everything falls back to the shot's slate fields
}
try {
const result = await regeneratePreview(exportId, {
...(body.vfxScope !== undefined ? { vfxScope: body.vfxScope } : {}),
...(body.submissionNote !== undefined ? { submissionNote: body.submissionNote } : {}),
note: typeof body.note === "string" ? body.note : "Regenerate preview from AE panel",
});
return NextResponse.json(result);
} catch (err) {
const { body: errBody, status } = toErrorResponse(err);
return NextResponse.json(errBody, { status });
}
}
+3 -1
View File
@@ -5,7 +5,7 @@ import { createExport } from "@/lib/render-pipeline/exports";
// ── POST /api/ext/exports (E1 — Queue Export) ────────────────────────────────
//
// Body: { manifest: RenderManifest, submittedByEmail?, priority?, force? }
// Body: { manifest: RenderManifest, submittedByEmail?, priority?, force?, skipPreview? }
// The server decides the new version number, updates Shot.shotVersion/exrOutput,
// supersedes older non-terminal exports, and creates Export(QUEUED) + RenderJob.
@@ -20,6 +20,7 @@ export async function POST(req: NextRequest) {
force?: boolean;
vfxScope?: string | null;
submissionNote?: string | null;
skipPreview?: boolean;
};
try {
body = await req.json();
@@ -38,6 +39,7 @@ export async function POST(req: NextRequest) {
// undefined inherits the shot's previous export values
vfxScope: body.vfxScope,
submissionNote: body.submissionNote,
skipPreview: body.skipPreview === true,
});
return NextResponse.json(result, { status: 201 });
} catch (err) {
@@ -18,6 +18,7 @@ function isAuthorized(req: NextRequest): boolean {
//
// Query params (all optional):
// episode e.g. 108
// scene e.g. 022
// sequence e.g. 004
// status e.g. IN_PROGRESS
// page (default 1)
@@ -39,6 +40,7 @@ export async function GET(
const { searchParams } = new URL(req.url);
const episode = searchParams.get("episode")?.trim() || undefined;
const scene = searchParams.get("scene")?.trim() || undefined;
const sequence = searchParams.get("sequence")?.trim() || undefined;
const status = searchParams.get("status")?.trim() || undefined;
const page = Math.max(1, parseInt(searchParams.get("page") ?? "1", 10));
@@ -59,6 +61,7 @@ export async function GET(
where: {
projectId: project.id,
...(episode ? { episode } : {}),
...(scene ? { scene } : {}),
...(sequence ? { sequence } : {}),
...(status ? { status: status as never } : {}),
},
@@ -98,6 +101,7 @@ export async function GET(
where: {
projectId: project.id,
...(episode ? { episode } : {}),
...(scene ? { scene } : {}),
...(sequence ? { sequence } : {}),
...(status ? { status: status as never } : {}),
},
+13 -1
View File
@@ -1,5 +1,6 @@
import { NextRequest, NextResponse } from "next/server";
import { db } from "@/lib/db";
import { resolveProjectTemplates } from "@/lib/render-pipeline/project-templates";
// ── Auth ─────────────────────────────────────────────────────────────────────
@@ -50,11 +51,22 @@ export async function GET(req: NextRequest) {
status: true,
startDate: true,
dueDate: true,
pipelineConfig: true,
_count: {
select: { shots: true },
},
},
});
return NextResponse.json({ projects, total: projects.length });
// Templates are resolved here rather than in the panel so that the panel and
// the headless preview build cannot disagree about which template, or which
// show LUT, a shot was built with.
const withTemplates = await Promise.all(
projects.map(async ({ pipelineConfig, ...project }) => ({
...project,
templates: await resolveProjectTemplates({ ...project, pipelineConfig }),
}))
);
return NextResponse.json({ projects: withTemplates, total: withTemplates.length });
}
+28
View File
@@ -0,0 +1,28 @@
import { NextRequest, NextResponse } from "next/server";
import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { getQCQueue } from "@/lib/render-pipeline/qc";
// ── GET /api/ext/qc/queue?projectCode=&episode= (E5) ─────────────────────────
//
// Exports sitting in READY_FOR_QC, oldest first, with everything the panel
// needs to import the real EXR sequence for full-res QC.
export async function GET(req: NextRequest) {
if (!isExtAuthorized(req)) {
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
}
const { searchParams } = new URL(req.url);
try {
const result = await getQCQueue({
projectCode: searchParams.get("projectCode"),
episode: searchParams.get("episode"),
limit: searchParams.get("limit") ? Number(searchParams.get("limit")) : undefined,
});
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
+36
View File
@@ -0,0 +1,36 @@
import { NextRequest, NextResponse } from "next/server";
import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { createBlenderJob, createBlenderJobSchema } from "@/lib/render-pipeline/blender";
// ── POST /api/ext/render/blender ─────────────────────────────────────────────
//
// Queue a standalone Blender render from the Blender add-on. No Export, no shot
// version, no validation or QC — the .blend is already set up to render, and
// this puts it on the farm instead of on the artist's machine.
export async function POST(req: NextRequest) {
if (!isExtAuthorized(req)) {
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
}
let raw: unknown;
try {
raw = await req.json();
} catch {
return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
}
const parsed = createBlenderJobSchema.safeParse(raw);
if (!parsed.success) {
return NextResponse.json({ error: "Invalid Blender job", details: parsed.error.issues }, { status: 422 });
}
try {
const result = await createBlenderJob(parsed.data);
return NextResponse.json(result, { status: 201 });
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
@@ -5,8 +5,10 @@ import { completeRender } from "@/lib/render-pipeline/jobs";
// ── POST /api/ext/render/jobs/{jobId}/complete-render (E11) ──────────────────
//
// aerender finished with exit 0. Phase 2 interim: Export goes to a provisional
// READY_FOR_QC; Phase 3 inserts VALIDATING between (§17.3).
// aerender finished with exit 0 → Export goes to VALIDATING and the worker
// keeps the job to run the checks (E12). With validation disabled the preview
// stage is queued directly. `validationRequired` in the response tells the
// worker which of the two happened.
export async function POST(
req: NextRequest,
@@ -0,0 +1,39 @@
import { NextRequest, NextResponse } from "next/server";
import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { deliveryReportSchema, reportDeliveryBuild } from "@/lib/render-pipeline/deliveries";
// ── POST /api/ext/render/jobs/{jobId}/delivery ───────────────────────────────
//
// The worker finished (or gave up on) a DELIVERY_BUILD job: per-item results,
// the manifest it wrote, and whether the package as a whole is good.
export async function POST(
req: NextRequest,
{ params }: { params: Promise<{ jobId: string }> }
) {
if (!isExtAuthorized(req)) {
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
}
const { jobId } = await params;
let raw: unknown;
try {
raw = await req.json();
} catch {
return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
}
const parsed = deliveryReportSchema.safeParse(raw);
if (!parsed.success) {
return NextResponse.json({ error: "Delivery report is malformed", details: parsed.error.issues }, { status: 422 });
}
try {
const result = await reportDeliveryBuild(jobId, parsed.data);
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
@@ -0,0 +1,43 @@
import { NextRequest, NextResponse } from "next/server";
import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { reportValidation, validationReportSchema } from "@/lib/render-pipeline/validation";
// ── POST /api/ext/render/jobs/{jobId}/validation (E12) ───────────────────────
//
// The worker reports every check from one validation run in a single call.
// Any FAIL stops the pipeline (Export → VALIDATION_FAILED); otherwise the
// preview stage is queued.
export async function POST(
req: NextRequest,
{ params }: { params: Promise<{ jobId: string }> }
) {
if (!isExtAuthorized(req)) {
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
}
const { jobId } = await params;
let raw: unknown;
try {
raw = await req.json();
} catch {
return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
}
const parsed = validationReportSchema.safeParse(raw);
if (!parsed.success) {
return NextResponse.json(
{ error: "Validation report is malformed", details: parsed.error.issues },
{ status: 422 }
);
}
try {
const result = await reportValidation(jobId, parsed.data);
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
+35
View File
@@ -0,0 +1,35 @@
import { NextRequest, NextResponse } from "next/server";
import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { recordToolVersion, toolPingSchema } from "@/lib/render-pipeline/tools";
// ── POST /api/ext/tools/ping ─────────────────────────────────────────────────
//
// A studio tool reporting its own version on startup. Fire-and-forget by
// design: callers must not fail if this errors.
export async function POST(req: NextRequest) {
if (!isExtAuthorized(req)) {
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
}
let raw: unknown;
try {
raw = await req.json();
} catch {
return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
}
const parsed = toolPingSchema.safeParse(raw);
if (!parsed.success) {
return NextResponse.json({ error: "Invalid tool ping", details: parsed.error.issues }, { status: 422 });
}
try {
const result = await recordToolVersion(parsed.data);
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
+28
View File
@@ -0,0 +1,28 @@
import { NextRequest, NextResponse } from "next/server";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { requirePipelineUser } from "@/lib/render-pipeline/session-auth";
import { cancelBlenderJob, retryBlenderJob } from "@/lib/render-pipeline/blender";
// ── POST /api/render/blender/{jobId}?action=cancel|retry ─────────────────────
export async function POST(
req: NextRequest,
{ params }: { params: Promise<{ jobId: string }> }
) {
try {
const user = await requirePipelineUser();
const { jobId } = await params;
const action = new URL(req.url).searchParams.get("action");
if (action === "retry") {
return NextResponse.json(await retryBlenderJob(jobId));
}
if (action === "cancel") {
return NextResponse.json(await cancelBlenderJob(jobId, user.id));
}
return NextResponse.json({ error: "action must be cancel or retry" }, { status: 400 });
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
+24
View File
@@ -0,0 +1,24 @@
import { NextRequest, NextResponse } from "next/server";
import { RenderJobStatus } from "@prisma/client";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { requirePipelineUser } from "@/lib/render-pipeline/session-auth";
import { listBlenderJobs } from "@/lib/render-pipeline/blender";
// ── GET /api/render/blender?projectId=&status= ───────────────────────────────
export async function GET(req: NextRequest) {
try {
await requirePipelineUser();
const { searchParams } = new URL(req.url);
const status = searchParams.get("status");
const result = await listBlenderJobs({
projectId: searchParams.get("projectId") ?? undefined,
status: status ? (status as RenderJobStatus) : undefined,
limit: searchParams.get("limit") ? Number(searchParams.get("limit")) : undefined,
});
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
@@ -0,0 +1,44 @@
import { NextRequest, NextResponse } from "next/server";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { requirePipelineAdmin } from "@/lib/render-pipeline/session-auth";
import { overrideValidation, overrideValidationSchema } from "@/lib/render-pipeline/validation";
// ── POST /api/render/exports/{exportId}/override-validation ──────────────────
//
// A human overruling a failed validation run. Resumes the pipeline at the
// preview stage, so the export still goes through QC; the failed checks stay on
// record and keep showing up as warnings in the QC queue.
export async function POST(
req: NextRequest,
{ params }: { params: Promise<{ exportId: string }> }
) {
try {
// Waving a failed check through is a supervisor's call, not any user's.
const user = await requirePipelineAdmin();
const { exportId } = await params;
let raw: unknown;
try {
raw = await req.json();
} catch {
return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
}
const parsed = overrideValidationSchema.safeParse(raw);
if (!parsed.success) {
return NextResponse.json({ error: "A reason is required", details: parsed.error.issues }, { status: 422 });
}
const result = await overrideValidation(exportId, {
reason: parsed.data.reason,
skipPreview: parsed.data.skipPreview,
userId: user.id,
userName: user.name ?? user.email ?? null,
});
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
@@ -0,0 +1,40 @@
import { NextRequest, NextResponse } from "next/server";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { requirePipelineUser } from "@/lib/render-pipeline/session-auth";
import { qcSubmitSchema, submitQCReview } from "@/lib/render-pipeline/qc";
// ── POST /api/render/exports/{exportId}/qc ───────────────────────────────────
//
// Web twin of E4 — same service, session auth. QC is not locked to AE (§10.2).
export async function POST(
req: NextRequest,
{ params }: { params: Promise<{ exportId: string }> }
) {
try {
const user = await requirePipelineUser();
const { exportId } = await params;
let raw: unknown;
try {
raw = await req.json();
} catch {
return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
}
const parsed = qcSubmitSchema.safeParse(raw);
if (!parsed.success) {
return NextResponse.json({ error: "Invalid QC submission", details: parsed.error.issues }, { status: 422 });
}
const result = await submitQCReview(exportId, parsed.data, {
source: "WEB",
userId: user.id,
name: user.name ?? user.email ?? null,
});
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
+24
View File
@@ -0,0 +1,24 @@
import { NextRequest, NextResponse } from "next/server";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { requirePipelineUser } from "@/lib/render-pipeline/session-auth";
import { getQCQueue } from "@/lib/render-pipeline/qc";
// ── GET /api/render/qc/queue?projectId=&episode= ─────────────────────────────
//
// Web twin of E5 for the QC page.
export async function GET(req: NextRequest) {
try {
await requirePipelineUser();
const { searchParams } = new URL(req.url);
const result = await getQCQueue({
projectId: searchParams.get("projectId"),
episode: searchParams.get("episode"),
limit: searchParams.get("limit") ? Number(searchParams.get("limit")) : undefined,
});
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
+20
View File
@@ -0,0 +1,20 @@
import { NextResponse } from "next/server";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { requirePipelineUser } from "@/lib/render-pipeline/session-auth";
import { listToolVersions } from "@/lib/render-pipeline/tools";
// ── GET /api/tools ───────────────────────────────────────────────────────────
//
// What version of each studio tool is deployed where, with anything behind the
// newest seen version flagged.
export async function GET() {
try {
await requirePipelineUser();
const result = await listToolVersions();
return NextResponse.json(result);
} catch (err) {
const { body, status } = toErrorResponse(err);
return NextResponse.json(body, { status });
}
}
-16
View File
@@ -35,7 +35,6 @@ interface ClientVersion {
fps: number;
duration: number | null;
thumbnailUrl: string | null;
notes: string | null;
createdAt: string;
}
@@ -744,11 +743,6 @@ export default function ClientPortalPage({
<p className="text-xs text-zinc-500">
{TASK_TYPE_LABELS[task.type] ?? task.type}
</p>
{ver?.notes && (
<p className="text-xs text-zinc-500 truncate italic mt-0.5">
&ldquo;{ver.notes}&rdquo;
</p>
)}
</div>
{ver ? (
<span
@@ -919,11 +913,6 @@ export default function ClientPortalPage({
<p className="text-xs text-zinc-500">
{TASK_TYPE_LABELS[task.type] ?? task.type}
</p>
{ver?.notes && (
<p className="text-xs text-zinc-500 truncate italic mt-0.5">
&ldquo;{ver.notes}&rdquo;
</p>
)}
</div>
{ver ? (
<div className="flex items-center gap-3 shrink-0">
@@ -1028,11 +1017,6 @@ export default function ClientPortalPage({
)}
</button>
</div>
{ver?.notes && (
<p className="text-xs text-zinc-500 truncate italic mt-0.5">
&ldquo;{ver.notes}&rdquo;
</p>
)}
</div>
{ver ? (
<div className="flex items-center gap-3 shrink-0">
+93 -1
View File
@@ -19,7 +19,7 @@ import {
} from "@/components/ui/select";
import { updateProject } from "@/actions/projects";
import { useToast } from "@/components/ui/use-toast";
import { Settings, Building2, Users, Webhook } from "lucide-react";
import { Settings, Building2, Users, Webhook, Clapperboard } from "lucide-react";
const settingsSchema = z.object({
name: z.string().min(1, "Name is required").max(100),
@@ -35,6 +35,12 @@ const settingsSchema = z.object({
startDate: z.string().optional(),
slackWebhook: z.string().optional(),
slackChannel: z.string().optional(),
// Pipeline — see the Pipeline section for why only paths are required here.
templateAep: z.string().optional(),
rendersRoot: z.string().optional(),
overlayComp: z.string().optional(),
previewComp: z.string().optional(),
lutComp: z.string().optional(),
});
type SettingsFormValues = z.infer<typeof settingsSchema>;
@@ -67,6 +73,13 @@ interface ProjectSettingsTabProps {
startDate: Date | null;
slackWebhook: string | null;
slackChannel: string | null;
pipelineConfig: {
templateAep?: string | null;
rendersRoot?: string | null;
overlayComp?: string | null;
previewComp?: string | null;
lutComp?: string | null;
} | null;
};
clients: Client[];
teamMembers: TeamMember[];
@@ -109,9 +122,19 @@ export function ProjectSettingsTab({ project, clients, teamMembers }: ProjectSet
startDate: toDateInput(project.startDate),
slackWebhook: project.slackWebhook ?? "",
slackChannel: project.slackChannel ?? "",
templateAep: project.pipelineConfig?.templateAep ?? "",
rendersRoot: project.pipelineConfig?.rendersRoot ?? "",
overlayComp: project.pipelineConfig?.overlayComp ?? "",
previewComp: project.pipelineConfig?.previewComp ?? "",
lutComp: project.pipelineConfig?.lutComp ?? "",
},
});
// Blank comp-name fields mean "use the convention", so they are shown as
// placeholders rather than pre-filled: a project that follows the pattern
// should have nothing stored, and inherit any future change to it.
const showId = watch("showId") || project.showId;
const onSubmit = async (data: SettingsFormValues) => {
setIsSubmitting(true);
try {
@@ -130,6 +153,13 @@ export function ProjectSettingsTab({ project, clients, teamMembers }: ProjectSet
startDate: data.startDate || null,
slackWebhook: data.slackWebhook || null,
slackChannel: data.slackChannel || null,
pipelineConfig: {
templateAep: data.templateAep?.trim() || null,
rendersRoot: data.rendersRoot?.trim() || null,
overlayComp: data.overlayComp?.trim() || null,
previewComp: data.previewComp?.trim() || null,
lutComp: data.lutComp?.trim() || null,
},
});
toast({ title: "Project settings saved" });
router.refresh();
@@ -338,6 +368,68 @@ export function ProjectSettingsTab({ project, clients, teamMembers }: ProjectSet
</div>
</section>
{/* ── Pipeline ── */}
<section className="space-y-4">
<div className="flex items-center gap-2">
<Clapperboard className="h-4 w-4 text-zinc-400" />
<h2 className="text-sm font-semibold text-zinc-200">Pipeline</h2>
</div>
<Separator />
<p className="text-xs text-zinc-500">
Where this show&apos;s After Effects template lives. Used by the connector panel and by the
render farm&apos;s preview build alike, so both work from the same template — and, above
all, the same show LUT.
</p>
<div className="grid grid-cols-2 gap-4">
<div className="space-y-1.5 col-span-2">
<Label htmlFor="templateAep">Template project (.aep)</Label>
<Input
id="templateAep"
placeholder="X:/shared_projects_2026/UNGO_VFX/production/working_files/UNG_VFXOVERLAY_SLATE_TEMPLATE.aep"
{...register("templateAep")}
/>
<p className="text-xs text-zinc-500">
Holds the overlay, the slate/export template and the show LUT. Imported by
Initialise Workspace and by every headless preview build.
</p>
</div>
<div className="space-y-1.5 col-span-2">
<Label htmlFor="rendersRoot">Renders root</Label>
<Input
id="rendersRoot"
placeholder="X:/shared_projects_2026/UNGO_VFX/production/renders"
{...register("rendersRoot")}
/>
<p className="text-xs text-zinc-500">
Where per-shot pre-renders live; the panel appends the shot code. Used by Import Renders.
</p>
</div>
</div>
<div className="space-y-1.5">
<p className="text-xs text-zinc-400">
Comp names default to the convention below and only need filling in when this show&apos;s
template departs from it. Leave blank to follow the convention.
</p>
<div className="grid grid-cols-3 gap-4 pt-1">
<div className="space-y-1.5">
<Label htmlFor="overlayComp">Overlay comp</Label>
<Input id="overlayComp" placeholder={`${showId}_VFX_OVERLAY`} {...register("overlayComp")} />
</div>
<div className="space-y-1.5">
<Label htmlFor="previewComp">Slate / export comp</Label>
<Input id="previewComp" placeholder={`${showId}_EXPORT_TEMPLATE`} {...register("previewComp")} />
</div>
<div className="space-y-1.5">
<Label htmlFor="lutComp">Show LUT comp</Label>
<Input id="lutComp" placeholder="_SHOW LUT" {...register("lutComp")} />
</div>
</div>
</div>
</section>
{/* Save */}
<div className="flex justify-end pt-2">
<Button type="submit" disabled={isSubmitting || !isDirty} className="min-w-[120px]">
+206
View File
@@ -0,0 +1,206 @@
"use client";
import { useState, useTransition } from "react";
import Image from "next/image";
import { Film, Save } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Textarea } from "@/components/ui/textarea";
import { useToast } from "@/components/ui/use-toast";
import { updateShotSlate } from "@/actions/shots";
import type { ShotWithDetails } from "@/types";
interface Props {
shot: ShotWithDetails;
projectName: string;
onSaved: () => void;
}
/** Left-side slate row: label + editable/static value */
function SlateRow({ label, children }: { label: string; children: React.ReactNode }) {
return (
<div className="flex gap-0 border-b border-zinc-800/60 last:border-0">
<div className="w-36 shrink-0 py-3 px-4 text-right text-[11px] font-semibold text-zinc-500 uppercase tracking-widest self-start pt-3.5">
{label}
</div>
<div className="flex-1 py-2.5 px-3 text-sm text-zinc-100">
{children}
</div>
</div>
);
}
/** Right-side metadata row */
function MetaRow({ label, value }: { label: string; value: string }) {
return (
<div className="flex items-center justify-between border-b border-zinc-800/50 last:border-0 py-1.5 px-3">
<span className="text-[11px] text-zinc-500">{label}</span>
<span className="text-[11px] text-zinc-300 text-right max-w-[55%] truncate">{value || "—"}</span>
</div>
);
}
export function ShotSlateTab({ shot, projectName, onSaved }: Props) {
const { toast } = useToast();
const [isPending, startTransition] = useTransition();
const [slateType, setSlateType] = useState(shot.slateType ?? "");
const [slateDescription, setSlateDescription] = useState(shot.slateDescription ?? shot.description ?? "");
const [slateVfxScope, setSlateVfxScope] = useState(shot.slateVfxScope ?? "");
const [slateSubmissionNote, setSlateSubmissionNote] = useState(shot.slateSubmissionNote ?? "");
const [clientCode, setClientCode] = useState(shot.clientCode ?? "");
const today = new Date();
const dateStr = `${today.getFullYear()}/${String(today.getMonth() + 1).padStart(2, "0")}/${String(today.getDate()).padStart(2, "0")}`;
// Client code, when set, replaces shotCode in what the client actually
// sees (slate, overlay burn-in, delivered names) — just their own naming
// with our version appended, no "_cmp_TT_" studio jargon mixed in.
const versionName = clientCode.trim()
? `${clientCode.trim()}_${shot.shotVersion ?? "v001"}`
: `${shot.shotCode}_cmp_TT_${shot.shotVersion ?? "v001"}`;
const frames =
shot.frameStart != null && shot.frameEnd != null
? String(shot.frameEnd - shot.frameStart + 1)
: "—";
const handleSave = () => {
startTransition(async () => {
try {
await updateShotSlate(shot.id, {
slateType: slateType.trim() || null,
slateDescription: slateDescription.trim() || null,
slateVfxScope: slateVfxScope.trim() || null,
slateSubmissionNote: slateSubmissionNote.trim() || null,
clientCode: clientCode.trim() || null,
});
toast({ title: "Slate saved" });
onSaved();
} catch (e) {
toast({ title: "Failed to save", description: e instanceof Error ? e.message : undefined, variant: "destructive" });
}
});
};
return (
<div className="space-y-4">
{/* Slate document */}
<div className="rounded-xl overflow-hidden border border-zinc-800 bg-zinc-950 max-w-4xl">
{/* Top accent bar */}
<div className="h-1 bg-red-600" />
<div className="flex">
{/* ── Left column: editorial data ─────────────────────────────── */}
<div className="flex-1 border-r border-zinc-800">
{/* Header row */}
<div className="flex border-b border-zinc-800">
<div className="flex-1 px-4 py-3 border-r border-zinc-800">
<p className="text-[10px] text-zinc-500 uppercase tracking-widest mb-0.5">Show</p>
<p className="text-base font-bold text-white tracking-wide">{projectName.toUpperCase()}</p>
</div>
<div className="px-4 py-3 flex items-center gap-2">
<p className="text-[10px] text-zinc-500 uppercase tracking-widest">Submitting For</p>
<span className="ml-1 px-2 py-0.5 rounded bg-red-600/20 border border-red-600/40 text-red-400 text-xs font-bold tracking-widest">REVIEW</span>
</div>
</div>
{/* Auto-filled rows */}
<SlateRow label="Version Name">
<span className="font-mono text-amber-400">{versionName}</span>
</SlateRow>
<SlateRow label="Date">
<span className="text-zinc-300">{dateStr}</span>
</SlateRow>
{/* Editable rows */}
<SlateRow label="Client Code">
<Input
value={clientCode}
onChange={(e) => setClientCode(e.target.value)}
placeholder={`Leave blank to use ${shot.shotCode}`}
className="h-7 bg-zinc-900 border-zinc-700 text-sm font-mono text-zinc-100 placeholder:text-zinc-600 placeholder:font-sans"
/>
</SlateRow>
<SlateRow label="Shot Type">
<Input
value={slateType}
onChange={(e) => setSlateType(e.target.value)}
placeholder="e.g. 2D COMP"
className="h-7 bg-zinc-900 border-zinc-700 text-sm font-medium text-zinc-100 placeholder:text-zinc-600"
/>
</SlateRow>
<SlateRow label="Shot Description">
<Textarea
value={slateDescription}
onChange={(e) => setSlateDescription(e.target.value)}
placeholder={shot.description ?? "Shot description for slate…"}
rows={2}
className="bg-zinc-900 border-zinc-700 text-sm text-zinc-100 placeholder:text-zinc-600 resize-none min-h-[56px]"
/>
</SlateRow>
<SlateRow label="VFX Scope">
<Textarea
value={slateVfxScope}
onChange={(e) => setSlateVfxScope(e.target.value)}
placeholder="VFX scope of work…"
rows={3}
className="bg-zinc-900 border-zinc-700 text-sm text-zinc-100 placeholder:text-zinc-600 resize-none min-h-[72px]"
/>
</SlateRow>
<SlateRow label="Submission Note">
<Input
value={slateSubmissionNote}
onChange={(e) => setSlateSubmissionNote(e.target.value)}
placeholder="e.g. Done"
className="h-7 bg-zinc-900 border-zinc-700 text-sm text-zinc-100 placeholder:text-zinc-600"
/>
</SlateRow>
</div>
{/* ── Right column: thumbnail + metadata ──────────────────────── */}
<div className="w-56 shrink-0 flex flex-col">
{/* Thumbnail */}
<div className="aspect-video bg-zinc-900 border-b border-zinc-800 overflow-hidden flex items-center justify-center">
{shot.thumbnailUrl ? (
<Image
src={shot.thumbnailUrl}
alt={shot.shotCode}
width={224}
height={126}
className="object-cover w-full h-full"
/>
) : (
<Film className="h-8 w-8 text-zinc-700" />
)}
</div>
{/* Metadata */}
<div className="flex-1 text-right">
<div className="px-3 py-2 border-b border-zinc-800">
<p className="text-[10px] text-zinc-500 mb-0.5">Vendor</p>
<p className="text-[11px] text-zinc-200 font-medium leading-tight">TWO TALES ANIMATION (PTY) LTD</p>
</div>
<MetaRow label="Shot Name" value={shot.shotCode} />
<MetaRow label="Episode" value={shot.episode ?? "—"} />
<MetaRow label="Seq Name" value={shot.sequence ?? "—"} />
<MetaRow label="Scene" value={shot.scene} />
<MetaRow label="Frames" value={frames} />
<MetaRow label="Media Color" value="w/SHOW LUT" />
</div>
</div>
</div>
</div>
{/* Save button */}
<div className="flex justify-end max-w-4xl">
<Button onClick={handleSave} disabled={isPending} className="gap-2">
<Save className="h-4 w-4" />
{isPending ? "Saving…" : "Save Slate"}
</Button>
</div>
</div>
);
}
+50
View File
@@ -0,0 +1,50 @@
import { describe, it, expect } from "vitest";
import { blenderManifestSchema, createBlenderJobSchema } from "@/lib/render-pipeline/blender";
/**
* The add-on and the server are separate codebases that only meet over JSON,
* so the exact payload the add-on builds is pinned here. A field renamed on
* either side otherwise surfaces as a 422 in front of an artist.
*/
describe("Blender submission contract", () => {
// Verbatim shape of scene_summary() in BlenderPanel/vfxreview_submit.py
const addonManifest = {
blendFile: "X:/shows/UNG/cg/UNG_110_030_010_smoke.blend",
scene: "Scene",
frameStart: 1001,
frameEnd: 1110,
outputPath: "X:/shows/UNG/cg/renders/smoke/frame_",
engine: "CYCLES",
blenderVersion: "4.2.1",
};
it("accepts what the add-on sends", () => {
const parsed = blenderManifestSchema.safeParse(addonManifest);
expect(parsed.success).toBe(true);
});
it("accepts the full submission body", () => {
const parsed = createBlenderJobSchema.safeParse({
projectCode: "UNG_S1",
label: "UNG_110_030_010_smoke",
manifest: addonManifest,
submittedByEmail: "chris@twotalesanimation.com",
urgent: false,
});
expect(parsed.success).toBe(true);
});
it("defaults the stage so the add-on need not send it", () => {
const parsed = blenderManifestSchema.parse(addonManifest);
expect(parsed.stage).toBe("BLENDER");
});
it("rejects a backwards frame range rather than queueing a no-op render", () => {
const parsed = blenderManifestSchema.safeParse({ ...addonManifest, frameEnd: 900 });
expect(parsed.success).toBe(false);
});
it("accepts EEVEE, which is what the add-on reports on a non-Cycles scene", () => {
expect(blenderManifestSchema.safeParse({ ...addonManifest, engine: "BLENDER_EEVEE_NEXT" }).success).toBe(true);
});
});
+189
View File
@@ -0,0 +1,189 @@
import { Prisma, RenderJobStatus } from "@prisma/client";
import { z } from "zod";
import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { getConfigNumber } from "./config";
/**
* Standalone Blender renders.
*
* Deliberately the simplest thing in the pipeline: a queue entry and nothing
* more. No Export, no shot version, no validation, QC or delivery — the .blend
* is already set up to render, and this is "Ctrl+F12, but on the farm". Every
* lifecycle call it needs (claim, progress, fail, complete) already tolerates a
* job with no Export behind it.
*/
export const blenderManifestSchema = z.object({
stage: z.literal("BLENDER").default("BLENDER"),
blendFile: z.string().min(1),
/** Blank renders the .blend's active scene, which is usually what is wanted. */
scene: z.string().max(200).optional().nullable(),
frameStart: z.number().int(),
frameEnd: z.number().int(),
/**
* Read from the .blend at submission and passed through only so the queue can
* show where frames will land. Left unset, the file's own output path is used
* — the file is expected to be ready to render.
*/
outputPath: z.string().max(1000).optional().nullable(),
/** Overrides, all optional: an unset value leaves the .blend's own setting. */
engine: z.enum(["CYCLES", "BLENDER_EEVEE_NEXT", "BLENDER_EEVEE", "BLENDER_WORKBENCH"]).optional().nullable(),
device: z.enum(["CPU", "GPU"]).optional().nullable(),
samples: z.number().int().positive().max(100000).optional().nullable(),
resolutionPercent: z.number().int().min(1).max(100).optional().nullable(),
/** Blender version this was authored in, for diagnosing a farm-vs-desk difference. */
blenderVersion: z.string().max(50).optional().nullable(),
}).refine((m) => m.frameEnd >= m.frameStart, {
message: "frameEnd must be >= frameStart",
path: ["frameEnd"],
});
export type BlenderManifest = z.infer<typeof blenderManifestSchema>;
export const createBlenderJobSchema = z.object({
projectCode: z.string().min(1),
label: z.string().min(1).max(200),
manifest: blenderManifestSchema,
submittedByEmail: z.string().max(200).optional().nullable(),
urgent: z.boolean().optional(),
});
export type CreateBlenderJobInput = z.infer<typeof createBlenderJobSchema>;
export async function createBlenderJob(input: CreateBlenderJobInput) {
const project = await db.project.findUnique({
where: { code: input.projectCode },
select: { id: true, code: true, name: true },
});
if (!project) throw new PipelineError(404, `Project not found: ${input.projectCode}`);
const [maxAttempts, urgentThreshold] = await Promise.all([
getConfigNumber("render.maxAttempts"),
getConfigNumber("render.urgentPriorityThreshold"),
]);
const job = await db.renderJob.create({
data: {
type: "BLENDER_RENDER",
projectId: project.id,
label: input.label.trim(),
submittedBy: input.submittedByEmail?.trim() || null,
attempt: 1,
maxAttempts,
priority: input.urgent ? urgentThreshold : 50,
manifest: input.manifest as unknown as Prisma.InputJsonValue,
},
});
return {
job: {
id: job.id,
label: job.label,
status: job.status,
priority: job.priority,
frames: input.manifest.frameEnd - input.manifest.frameStart + 1,
},
project: { code: project.code, name: project.name },
};
}
export interface BlenderJobFilter {
projectId?: string;
status?: RenderJobStatus;
limit?: number;
}
export async function listBlenderJobs(filter: BlenderJobFilter = {}) {
const jobs = await db.renderJob.findMany({
where: {
type: "BLENDER_RENDER",
...(filter.projectId ? { projectId: filter.projectId } : {}),
...(filter.status ? { status: filter.status } : {}),
},
orderBy: [{ createdAt: "desc" }],
take: Math.min(200, Math.max(1, filter.limit ?? 50)),
include: { machine: { select: { name: true } } },
});
const projectIds = [...new Set(jobs.map((j) => j.projectId).filter((id): id is string => !!id))];
const projects = projectIds.length
? await db.project.findMany({ where: { id: { in: projectIds } }, select: { id: true, code: true, name: true } })
: [];
const byId = new Map(projects.map((p) => [p.id, p]));
return {
jobs: jobs.map((j) => {
const m = j.manifest as unknown as Partial<BlenderManifest>;
return {
id: j.id,
label: j.label,
status: j.status,
attempt: j.attempt,
maxAttempts: j.maxAttempts,
priority: j.priority,
progress: j.progress,
currentFrame: j.currentFrame,
totalFrames: j.totalFrames,
etaSeconds: j.etaSeconds,
errorMessage: j.errorMessage,
machineName: j.machine?.name ?? null,
submittedBy: j.submittedBy,
createdAt: j.createdAt,
startedAt: j.startedAt,
finishedAt: j.finishedAt,
projectCode: j.projectId ? byId.get(j.projectId)?.code ?? null : null,
blendFile: m.blendFile ?? null,
outputPath: m.outputPath ?? null,
frameStart: m.frameStart ?? null,
frameEnd: m.frameEnd ?? null,
};
}),
};
}
/** Cancel a queued or running Blender job. The worker learns via its progress report. */
export async function cancelBlenderJob(jobId: string, actorId?: string) {
const job = await db.renderJob.findUnique({ where: { id: jobId }, select: { id: true, type: true, status: true } });
if (!job) throw new PipelineError(404, "Render job not found");
if (job.type !== "BLENDER_RENDER") throw new PipelineError(422, "Not a Blender job");
if (!["QUEUED", "CLAIMED", "RUNNING"].includes(job.status)) {
throw new PipelineError(409, `Job is ${job.status} — only a queued or running job can be cancelled`);
}
const updated = await db.renderJob.update({
where: { id: job.id },
data: {
status: "CANCELLED",
errorMessage: `Cancelled by user${actorId ? ` ${actorId}` : ""}`,
// A claimed job keeps finishedAt null until the worker acknowledges, so a
// render still winding down is not reported as already stopped.
...(job.status === "QUEUED" ? { finishedAt: new Date() } : {}),
},
});
return { job: { id: updated.id, status: updated.status } };
}
/** Requeue a failed Blender job as a fresh attempt, reusing its manifest. */
export async function retryBlenderJob(jobId: string) {
const job = await db.renderJob.findUnique({ where: { id: jobId } });
if (!job) throw new PipelineError(404, "Render job not found");
if (job.type !== "BLENDER_RENDER") throw new PipelineError(422, "Not a Blender job");
if (!["FAILED", "CANCELLED", "EXPIRED"].includes(job.status)) {
throw new PipelineError(409, `Job is ${job.status} — only a finished-unsuccessfully job can be retried`);
}
const next = await db.renderJob.create({
data: {
type: "BLENDER_RENDER",
projectId: job.projectId,
label: job.label,
submittedBy: job.submittedBy,
attempt: job.attempt + 1,
maxAttempts: job.maxAttempts,
priority: job.priority,
manifest: job.manifest as Prisma.InputJsonValue,
},
});
return { job: { id: next.id, attempt: next.attempt, status: next.status } };
}
+35 -4
View File
@@ -11,8 +11,29 @@ export const PIPELINE_CONFIG_DEFAULTS = {
"render.maxAttempts": 3,
"render.stallTimeoutSeconds": 600,
"render.urgentPriorityThreshold": 20,
"render.outputRoot": "//SAN/renders",
/**
* How far a preview job outranks the render it follows. A preview is only
* created when its render finishes, so at equal priority it sorts behind
* every render queued alongside it — 10 shots run as 10 renders then 10
* previews, and nothing is reviewable until the end. A boost of 1 finishes
* shots end to end instead. Set to 0 for the old phase behaviour.
*/
"render.previewPriorityBoost": 1,
"render.outputRoot": "//SAN",
// Validation stage (§8). Disabling it restores the pre-Phase-3 flow
// (render → preview) without a redeploy, for a bad engine release.
"validation.enabled": "true",
"validation.sampleEvery": 25,
/** Per-check severity overrides, e.g. {"exr_type":"warn"} (§17.3). */
"validation.overrides": "{}",
/** Frames of head handle the plates carry; only used for the API timecode fallback (§8.1a). */
"validation.handleFrames": 8,
/**
* Studio-wide delivery defaults (§11.2). A project's own `deliveryConfig`
* column overrides these key by key; `{}` falls through to the built-ins in
* lib/render-pipeline/deliveries.ts.
*/
"delivery.defaultConfig": "{}",
"preview.maxWidth": 1920,
// Preview stage (§9): headless AE rebuild of the render with slate/burn-ins
"preview.enabled": "true",
@@ -71,13 +92,23 @@ export async function getPreviewConfig() {
/** Worker-facing config bundle returned by E6 registration. */
export async function getWorkerConfig() {
const [pollSeconds, heartbeatSeconds, leaseSeconds, maxAttempts, stallTimeoutSeconds] =
await Promise.all([
const [
pollSeconds, heartbeatSeconds, leaseSeconds, maxAttempts, stallTimeoutSeconds,
validationEnabled, validationSampleEvery, validationHandleFrames,
] = await Promise.all([
getConfigNumber("render.pollSeconds"),
getConfigNumber("render.heartbeatSeconds"),
getConfigNumber("render.leaseSeconds"),
getConfigNumber("render.maxAttempts"),
getConfigNumber("render.stallTimeoutSeconds"),
getConfigBoolean("validation.enabled"),
getConfigNumber("validation.sampleEvery"),
getConfigNumber("validation.handleFrames"),
]);
return { pollSeconds, heartbeatSeconds, leaseSeconds, maxAttempts, stallTimeoutSeconds };
return {
pollSeconds, heartbeatSeconds, leaseSeconds, maxAttempts, stallTimeoutSeconds,
// Whether the validation stage runs is the server's call, so switching it
// off is a config change here rather than a redeploy of every worker (§8).
validationEnabled, validationSampleEvery, validationHandleFrames,
};
}
+647
View File
@@ -0,0 +1,647 @@
import { DeliveryStatus, Prisma } from "@prisma/client";
import { z } from "zod";
import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { applyTransition } from "./transitions";
import { getConfigNumber, getConfigValue } from "./config";
/**
* Delivery builder (RenderPipeline2 §11). The web app decides *what* goes in a
* package and records it; a worker does the file work through the same queue
* and claim path as a render.
*
* Version locking: a package references Export rows and denormalises
* shotCode/versionString at creation, so a later re-render can never mutate
* delivery history.
*/
// ── Config (§11.2) ───────────────────────────────────────────────────────────
export interface DeliveryConfig {
packageNameTemplate: string;
layout: { packageDir: string; shotDir: string; reportFile: string };
deliveryRoot: string;
includeMovs: boolean;
checksumAlgo: string;
reportFormats: string[];
copyMode: "auto" | "always-copy";
/**
* "auto" verifies copies by hash and hard links by identity — a link is the
* same data as the source, so re-reading it cannot disagree with what
* validation already hashed, and at SAN speeds costs ~30 s per shot to prove
* nothing. "always-hash" reads every delivered file back regardless.
*/
verifyMode: "auto" | "always-hash";
}
export const DELIVERY_CONFIG_DEFAULT: DeliveryConfig = {
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",
};
/**
* Project config → SystemConfig default → built-in. Merged shallowly per top
* level key so a project can override just `deliveryRoot` without restating the
* whole layout.
*/
export async function resolveDeliveryConfig(projectDeliveryConfig: unknown): Promise<DeliveryConfig> {
let systemDefault: Partial<DeliveryConfig> = {};
const raw = await getConfigValue("delivery.defaultConfig");
if (raw?.trim() && raw.trim() !== "{}") {
try {
systemDefault = JSON.parse(raw) as Partial<DeliveryConfig>;
} catch {
console.error("[render-pipeline] delivery.defaultConfig is not valid JSON — ignoring");
}
}
const project = (projectDeliveryConfig ?? {}) as Partial<DeliveryConfig>;
return {
...DELIVERY_CONFIG_DEFAULT,
...systemDefault,
...project,
layout: {
...DELIVERY_CONFIG_DEFAULT.layout,
...(systemDefault.layout ?? {}),
...(project.layout ?? {}),
},
};
}
export interface TokenValues {
showId: string;
episode: string;
yymmdd: string;
yyyymmdd: string;
packageName: string;
packageDir: string;
deliveryRoot: string;
shotCode: string;
versionString: string;
packageNumber: string;
}
export function applyTokens(template: string, tokens: Partial<TokenValues>): string {
return template.replace(/\{(\w+)\}/g, (whole, key: string) => {
const value = (tokens as Record<string, string | undefined>)[key];
return value === undefined ? whole : value;
});
}
export function dateTokens(date: Date) {
const yyyy = String(date.getFullYear());
const mm = String(date.getMonth() + 1).padStart(2, "0");
const dd = String(date.getDate()).padStart(2, "0");
return { yymmdd: `${yyyy.slice(2)}${mm}${dd}`, yyyymmdd: `${yyyy}${mm}${dd}` };
}
// ── E18: what is ready ───────────────────────────────────────────────────────
/**
* READY_FOR_DELIVERY exports grouped by episode. Only the newest ready export
* per shot is offered: an older ready version of the same shot is history, not
* a second thing to ship.
*/
export async function getReadyForDelivery(projectId: string, episode?: string | null) {
const rows = await db.export.findMany({
where: {
projectId,
status: "READY_FOR_DELIVERY",
...(episode ? { shot: { episode } } : {}),
},
orderBy: [{ shotId: "asc" }, { versionNumber: "desc" }],
include: {
shot: { select: { id: true, shotCode: true, episode: true } },
qcReviews: { orderBy: { createdAt: "desc" }, take: 1, select: { result: true, reviewerName: true, createdAt: true } },
},
});
const newestPerShot = new Map<string, (typeof rows)[number]>();
for (const row of rows) {
if (!newestPerShot.has(row.shotId)) newestPerShot.set(row.shotId, row);
}
const byEpisode = new Map<string, ReturnType<typeof serialiseReady>[]>();
for (const row of newestPerShot.values()) {
const key = row.shot.episode ?? "";
if (!byEpisode.has(key)) byEpisode.set(key, []);
byEpisode.get(key)!.push(serialiseReady(row));
}
return {
episodes: [...byEpisode.entries()]
.sort((a, b) => a[0].localeCompare(b[0]))
.map(([ep, exports]) => ({
episode: ep,
count: exports.length,
exports: exports.sort((a, b) => a.shotCode.localeCompare(b.shotCode)),
})),
};
}
function serialiseReady(row: {
id: string;
versionString: string;
outputDir: string;
exrFileCount: number | null;
exrTotalBytes: bigint | null;
deliveryMovPath: string | null;
checksum: string | null;
frameStart: number;
frameEnd: number;
shot: { id: string; shotCode: string; episode: string | null };
qcReviews: { result: string; reviewerName: string | null; createdAt: Date }[];
}) {
return {
exportId: row.id,
shotId: row.shot.id,
shotCode: row.shot.shotCode,
episode: row.shot.episode ?? "",
versionString: row.versionString,
outputDir: row.outputDir,
frameStart: row.frameStart,
frameEnd: row.frameEnd,
fileCount: row.exrFileCount,
totalBytes: row.exrTotalBytes == null ? null : Number(row.exrTotalBytes),
deliveryMovPath: row.deliveryMovPath,
hasChecksum: row.checksum != null,
qc: row.qcReviews[0]
? { result: row.qcReviews[0].result, reviewer: row.qcReviews[0].reviewerName, at: row.qcReviews[0].createdAt }
: null,
};
}
// ── E16: create a package ────────────────────────────────────────────────────
export const createDeliverySchema = z.object({
projectId: z.string().min(1),
episode: z.string().max(50).optional().nullable(),
/** Omitted → every ready export in the episode. */
exportIds: z.array(z.string().min(1)).max(500).optional(),
options: z
.object({
date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
name: z.string().max(120).optional(),
includeMovs: z.boolean().optional(),
copyMode: z.enum(["auto", "always-copy"]).optional(),
})
.optional(),
});
export type CreateDeliveryInput = z.infer<typeof createDeliverySchema>;
export async function createDeliveryPackage(input: CreateDeliveryInput, userId: string) {
const project = await db.project.findUnique({
where: { id: input.projectId },
select: { id: true, code: true, showId: true, deliveryConfig: true },
});
if (!project) throw new PipelineError(404, "Project not found");
const config = await resolveDeliveryConfig(project.deliveryConfig);
if (input.options?.includeMovs !== undefined) config.includeMovs = input.options.includeMovs;
if (input.options?.copyMode) config.copyMode = input.options.copyMode;
const buildDate = input.options?.date ? new Date(`${input.options.date}T00:00:00`) : new Date();
if (Number.isNaN(buildDate.getTime())) throw new PipelineError(422, "options.date is not a valid date");
const maxAttempts = await getConfigNumber("render.maxAttempts");
return db.$transaction(async (tx) => {
const exports = await tx.export.findMany({
where: {
projectId: project.id,
status: "READY_FOR_DELIVERY",
...(input.exportIds?.length ? { id: { in: input.exportIds } } : {}),
...(input.episode ? { shot: { episode: input.episode } } : {}),
},
include: { shot: { select: { id: true, shotCode: true, clientCode: true, episode: true } } },
orderBy: { shotId: "asc" },
});
if (exports.length === 0) {
throw new PipelineError(422, "No READY_FOR_DELIVERY exports match — nothing to package");
}
if (input.exportIds?.length && exports.length !== input.exportIds.length) {
const found = new Set(exports.map((e) => e.id));
throw new PipelineError(
409,
"Some exports are no longer ready for delivery (re-rendered or already packaged?)",
{ missing: input.exportIds.filter((id) => !found.has(id)) }
);
}
// One export per shot: two versions of the same shot in one package is
// always a mistake, and it is cheaper to refuse than to ship it.
const shotIds = new Set<string>();
for (const e of exports) {
if (shotIds.has(e.shotId)) {
throw new PipelineError(422, `Two versions of ${e.shot.shotCode} selected — pick one`);
}
shotIds.add(e.shotId);
}
const episode = input.episode ?? exports[0].shot.episode ?? "";
const dates = dateTokens(buildDate);
const showId = project.showId || project.code;
const lastNumber = await tx.deliveryPackage.aggregate({
where: { projectId: project.id },
_max: { packageNumber: true },
});
const packageNumber = (lastNumber._max.packageNumber ?? 0) + 1;
const tokens: TokenValues = {
showId,
episode,
...dates,
packageName: "",
packageDir: "",
deliveryRoot: config.deliveryRoot,
shotCode: "",
versionString: "",
packageNumber: String(packageNumber),
};
tokens.packageName = input.options?.name ?? applyTokens(config.packageNameTemplate, tokens);
tokens.packageDir = applyTokens(config.layout.packageDir, tokens);
const pkg = await tx.deliveryPackage.create({
data: {
projectId: project.id,
episode,
name: tokens.packageName,
packageNumber,
status: "QUEUED",
rootPath: tokens.packageDir,
// Snapshot: historic packages always show the rules they were built with.
configSnapshot: { ...config, tokens } as unknown as Prisma.InputJsonValue,
createdById: userId,
},
});
await tx.deliveryItem.createMany({
data: exports.map((e) => ({
packageId: pkg.id,
exportId: e.id,
shotId: e.shotId,
shotCode: e.shot.shotCode,
clientCode: e.shot.clientCode,
versionString: e.versionString,
})),
});
const manifest = await buildDeliveryJobManifest(tx, pkg.id);
const job = await tx.renderJob.create({
data: {
type: "DELIVERY_BUILD",
deliveryId: pkg.id,
attempt: 1,
maxAttempts,
// Deliveries are interactive: someone is waiting on the folder, and the
// work is file copying rather than hours of CPU, so it jumps renders.
priority: 10,
manifest: manifest as unknown as Prisma.InputJsonValue,
},
});
return {
package: {
id: pkg.id,
name: pkg.name,
packageNumber,
episode,
status: pkg.status,
rootPath: pkg.rootPath,
itemCount: exports.length,
},
renderJob: { id: job.id },
};
});
}
// ── The DELIVERY_BUILD manifest ──────────────────────────────────────────────
export interface DeliveryManifestItem {
itemId: string;
exportId: string;
shotCode: string;
versionString: string;
sourceDir: string;
outputPattern: string;
frameStart: number;
frameEnd: number;
fileCount: number | null;
checksum: string | null;
deliveryMovPath: string | null;
shotDir: string;
/**
* `{clientCode}_{versionString}` when the shot has a client code, else the
* studio's own `{shotCode}_cmp_TT_{versionString}` — what the worker names
* the delivered EXR sequence and MOV as, replacing the internal render
* filename it copies from.
*/
deliveredBaseName: string;
/** When validation last ran for this export; null when it never did. */
validatedAt: string | null;
}
export interface DeliveryManifest {
stage: "DELIVERY";
packageId: string;
packageName: string;
packageNumber: number;
episode: string;
packageDir: string;
reportFile: string;
includeMovs: boolean;
copyMode: string;
verifyMode: string;
checksumAlgo: string;
reportFormats: string[];
items: DeliveryManifestItem[];
}
export async function buildDeliveryJobManifest(
tx: Prisma.TransactionClient,
packageId: string
): Promise<DeliveryManifest> {
const pkg = await tx.deliveryPackage.findUniqueOrThrow({
where: { id: packageId },
include: {
items: {
include: {
export: {
include: {
// Newest validation run: a linked package uses it to detect a
// source file changed after it passed QC.
validations: { orderBy: { createdAt: "desc" }, take: 1, select: { createdAt: true } },
},
},
},
},
project: { select: { code: true, showId: true } },
},
});
const snapshot = pkg.configSnapshot as unknown as DeliveryConfig & { tokens: TokenValues };
const baseTokens: TokenValues = {
...snapshot.tokens,
packageName: pkg.name,
packageDir: pkg.rootPath ?? snapshot.tokens.packageDir,
episode: pkg.episode,
};
return {
stage: "DELIVERY",
packageId: pkg.id,
packageName: pkg.name,
packageNumber: pkg.packageNumber,
episode: pkg.episode,
packageDir: baseTokens.packageDir,
reportFile: applyTokens(snapshot.layout.reportFile, baseTokens),
includeMovs: snapshot.includeMovs,
copyMode: snapshot.copyMode ?? "auto",
verifyMode: snapshot.verifyMode ?? "auto",
checksumAlgo: snapshot.checksumAlgo,
reportFormats: snapshot.reportFormats,
items: pkg.items.map((item) => ({
itemId: item.id,
exportId: item.exportId,
shotCode: item.shotCode,
versionString: item.versionString,
sourceDir: item.export.outputDir,
outputPattern: item.export.outputPattern,
frameStart: item.export.frameStart,
frameEnd: item.export.frameEnd,
fileCount: item.export.exrFileCount,
checksum: item.export.checksum,
deliveryMovPath: snapshot.includeMovs ? item.export.deliveryMovPath : null,
validatedAt: item.export.validations[0]?.createdAt.toISOString() ?? null,
// Client code substitutes for shotCode in what the client sees; folder
// naming follows the same rule as the delivered filenames themselves.
shotDir: applyTokens(snapshot.layout.shotDir, {
...baseTokens,
shotCode: item.clientCode || item.shotCode,
versionString: item.versionString,
}),
deliveredBaseName: item.clientCode
? `${item.clientCode}_${item.versionString}`
: `${item.shotCode}_cmp_TT_${item.versionString}`,
})),
};
}
// ── Worker reporting ─────────────────────────────────────────────────────────
export const deliveryReportSchema = z.object({
machineId: z.string().min(1),
items: z
.array(
z.object({
itemId: z.string().min(1),
status: z.enum(["COPIED", "VERIFIED", "FAILED"]),
exrPath: z.string().max(1000).optional().nullable(),
movPath: z.string().max(1000).optional().nullable(),
fileCount: z.number().int().nonnegative().optional().nullable(),
totalBytes: z.number().nonnegative().optional().nullable(),
checksum: z.string().max(200).optional().nullable(),
linkMode: z.enum(["hardlink", "copy"]).optional().nullable(),
errorMessage: z.string().max(2000).optional().nullable(),
})
)
.max(500),
manifest: z.unknown().optional(),
reportKey: z.string().max(500).optional().nullable(),
rootPath: z.string().max(1000).optional().nullable(),
errorMessage: z.string().max(2000).optional().nullable(),
/** false → the package failed as a whole. */
ok: z.boolean(),
});
export type DeliveryReport = z.infer<typeof deliveryReportSchema>;
/**
* The worker finished (or gave up on) a DELIVERY_BUILD job. Exports move to
* PACKAGED only for items that actually verified — a package with a failed item
* is FAILED, and nothing about it is silently treated as delivered.
*/
export async function reportDeliveryBuild(jobId: string, body: DeliveryReport) {
return db.$transaction(async (tx) => {
const job = await tx.renderJob.findUnique({ where: { id: jobId } });
if (!job) throw new PipelineError(404, "Render job not found");
if (job.machineId !== body.machineId) {
throw new PipelineError(409, "Job is not held by this machine (lease reassigned?)");
}
if (!job.deliveryId) throw new PipelineError(422, "Job has no delivery package");
const pkg = await tx.deliveryPackage.findUnique({
where: { id: job.deliveryId },
include: { items: true },
});
if (!pkg) throw new PipelineError(404, "Delivery package not found");
if (pkg.status === "READY" || pkg.status === "DELIVERED") {
return { package: { id: pkg.id, status: pkg.status }, alreadyApplied: true };
}
await tx.renderJob.update({
where: { id: job.id },
data: {
status: body.ok ? "COMPLETED" : "FAILED",
progress: 1,
finishedAt: new Date(),
errorMessage: body.errorMessage ?? null,
},
});
for (const reported of body.items) {
await tx.deliveryItem.updateMany({
where: { id: reported.itemId, packageId: pkg.id },
data: {
status: reported.status,
exrPath: reported.exrPath ?? null,
movPath: reported.movPath ?? null,
fileCount: reported.fileCount ?? null,
totalBytes: reported.totalBytes == null ? null : BigInt(Math.round(reported.totalBytes)),
checksum: reported.checksum ?? null,
linkMode: reported.linkMode ?? null,
errorMessage: reported.errorMessage ?? null,
},
});
}
const verified = body.items.filter((i) => i.status === "VERIFIED");
const failed = body.items.filter((i) => i.status === "FAILED");
const success = body.ok && failed.length === 0 && verified.length === pkg.items.length;
if (success) {
for (const item of pkg.items) {
const exportRow = await tx.export.findUnique({ where: { id: item.exportId }, select: { id: true, status: true } });
if (exportRow?.status === "READY_FOR_DELIVERY") {
await applyTransition(tx, exportRow, "PACKAGED", {
type: "WORKER",
id: body.machineId,
note: `Packaged into #${pkg.packageNumber} ${pkg.name}`,
});
}
}
}
const updated = await tx.deliveryPackage.update({
where: { id: pkg.id },
data: {
status: success ? "READY" : "FAILED",
builtAt: new Date(),
rootPath: body.rootPath ?? pkg.rootPath,
manifest: (body.manifest ?? undefined) as Prisma.InputJsonValue | undefined,
reportKey: body.reportKey ?? pkg.reportKey,
errorMessage: success
? null
: (body.errorMessage ??
(failed.length ? `${failed.length} item(s) failed: ${failed.map((f) => f.itemId).join(", ")}` : "Build did not complete")),
},
});
return {
package: { id: updated.id, status: updated.status },
verified: verified.length,
failed: failed.length,
alreadyApplied: false,
};
});
}
// ── E17 / E19 / cancel ───────────────────────────────────────────────────────
export async function listDeliveryPackages(filter: { projectId?: string; episode?: string; status?: DeliveryStatus }) {
const packages = await db.deliveryPackage.findMany({
where: {
...(filter.projectId ? { projectId: filter.projectId } : {}),
...(filter.episode ? { episode: filter.episode } : {}),
...(filter.status ? { status: filter.status } : {}),
},
orderBy: { createdAt: "desc" },
include: {
items: { select: { id: true, shotCode: true, versionString: true, status: true, fileCount: true, linkMode: true, errorMessage: true } },
project: { select: { id: true, name: true, code: true } },
},
});
return {
packages: packages.map((p) => ({
id: p.id,
packageNumber: p.packageNumber,
name: p.name,
episode: p.episode,
status: p.status,
rootPath: p.rootPath,
errorMessage: p.errorMessage,
projectName: p.project.name,
projectCode: p.project.code,
createdAt: p.createdAt,
builtAt: p.builtAt,
deliveredAt: p.deliveredAt,
itemCount: p.items.length,
verifiedCount: p.items.filter((i) => i.status === "VERIFIED").length,
items: p.items,
})),
};
}
/** E19 — the human uploaded the folder to the client and is confirming it. */
export async function markDelivered(packageId: string, userId: string) {
return db.$transaction(async (tx) => {
const pkg = await tx.deliveryPackage.findUnique({ where: { id: packageId }, include: { items: true } });
if (!pkg) throw new PipelineError(404, "Delivery package not found");
if (pkg.status === "DELIVERED") {
return { package: { id: pkg.id, status: pkg.status }, alreadyApplied: true };
}
if (pkg.status !== "READY") {
throw new PipelineError(409, `Package is ${pkg.status} — only a READY package can be marked delivered`);
}
for (const item of pkg.items) {
const exportRow = await tx.export.findUnique({ where: { id: item.exportId }, select: { id: true, status: true } });
if (exportRow?.status === "PACKAGED") {
await applyTransition(tx, exportRow, "DELIVERED", {
type: "USER",
id: userId,
note: `Delivered in #${pkg.packageNumber} ${pkg.name}`,
});
}
}
const updated = await tx.deliveryPackage.update({
where: { id: pkg.id },
data: { status: "DELIVERED", deliveredAt: new Date(), deliveredById: userId },
});
return { package: { id: updated.id, status: updated.status }, alreadyApplied: false };
});
}
/** A mistaken package is cancelled, never deleted (§11.5). */
export async function cancelDeliveryPackage(packageId: string, userId: string) {
return db.$transaction(async (tx) => {
const pkg = await tx.deliveryPackage.findUnique({ where: { id: packageId } });
if (!pkg) throw new PipelineError(404, "Delivery package not found");
if (!["DRAFT", "QUEUED", "FAILED"].includes(pkg.status)) {
throw new PipelineError(409, `Package is ${pkg.status} — only DRAFT, QUEUED or FAILED packages can be cancelled`);
}
await tx.renderJob.updateMany({
where: { deliveryId: pkg.id, status: { in: ["QUEUED", "CLAIMED", "RUNNING"] } },
data: { status: "CANCELLED", finishedAt: new Date(), errorMessage: "Delivery package cancelled" },
});
const updated = await tx.deliveryPackage.update({
where: { id: pkg.id },
data: { status: "CANCELLED", errorMessage: `Cancelled by user ${userId}` },
});
return { package: { id: updated.id, status: updated.status } };
});
}
+47 -26
View File
@@ -1,7 +1,7 @@
import { ExportStatus, Prisma } from "@prisma/client";
import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { renderManifestSchema, type RenderManifest } from "./manifest";
import { describePlateProvenance, renderManifestSchema, type RenderManifest } from "./manifest";
import { applyTransition, type TransitionActor } from "./transitions";
import { getConfigNumber, getConfigValue } from "./config";
@@ -63,6 +63,13 @@ export interface CreateExportInput {
*/
vfxScope?: string | null;
submissionNote?: string | null;
/**
* Render the EXRs but build no preview, inheriting the previous export's
* review media. For deliverables framed differently from the review — an
* unscaled or un-punched-in export — rebuilding the preview from these
* frames would produce the wrong MOV.
*/
skipPreview?: boolean;
}
/**
@@ -81,7 +88,7 @@ export async function createExport(input: CreateExportInput) {
const shot = await db.shot.findUnique({
where: { id: manifest.shotId },
include: {
project: { select: { id: true, code: true, showId: true } },
project: { select: { id: true, code: true, showId: true, projectType: true } },
tasks: { where: { type: "COMP" }, orderBy: { sortOrder: "asc" }, take: 1, select: { id: true } },
},
});
@@ -137,26 +144,28 @@ export async function createExport(input: CreateExportInput) {
});
const freshShot = await tx.shot.findUniqueOrThrow({
where: { id: shot.id },
select: { shotVersion: true, exrOutput: true },
select: { shotVersion: true, exrOutput: true, slateVfxScope: true, slateSubmissionNote: true },
});
// Slate fields carry forward from the shot's previous submission
// unless the caller supplies new ones.
const previous = await tx.export.findFirst({
where: { shotId: shot.id },
orderBy: { versionNumber: "desc" },
select: { vfxScope: true, submissionNote: true },
});
const vfxScope = input.vfxScope !== undefined ? input.vfxScope : (previous?.vfxScope ?? null);
// vfxScope: caller override → shot's slate field
const vfxScope = input.vfxScope !== undefined ? input.vfxScope : (freshShot.slateVfxScope ?? null);
// submissionNote: caller override (per-export) → shot's slate default
const submissionNote =
input.submissionNote !== undefined ? input.submissionNote : (previous?.submissionNote ?? null);
const versionNumber =
Math.max(latest._max.versionNumber ?? 0, parseVersionString(freshShot.shotVersion)) + 1;
const versionString = formatVersionString(versionNumber);
input.submissionNote !== undefined ? input.submissionNote : (freshShot.slateSubmissionNote ?? null);
// versionNumber is an internal sequence for DB uniqueness only; output files
// use the shot's current (manually-set) shotVersion.
const versionNumber = (latest._max.versionNumber ?? 0) + 1;
const versionString = freshShot.shotVersion ?? formatVersionString(versionNumber);
const exrBase = nextExrOutputBase(freshShot.exrOutput, shot.shotCode, versionString);
// {root}/{showId}/[{episode} for episodic]/{shotCode}/{version}
const showSegment = shot.project.showId || shot.project.code;
const episodeSegment =
shot.project.projectType === "EPISODIC" && shot.episode?.trim() ? shot.episode.trim() : null;
const outputDir =
manifest.outputDir === "auto"
? [outputRoot, shot.project.code, ...(shot.episode ? [shot.episode] : []), shot.shotCode, versionString].join("/")
? [outputRoot, showSegment, episodeSegment, shot.shotCode, versionString]
.filter(Boolean)
.join("/")
: manifest.outputDir;
const outputPattern =
manifest.outputPattern === "auto"
@@ -195,6 +204,7 @@ export async function createExport(input: CreateExportInput) {
colorspace: manifest.expected?.colorspace ?? null,
vfxScope,
submissionNote,
skipPreview: input.skipPreview === true,
submittedById: submittedBy?.id ?? null,
submittedByName: submittedBy?.name ?? input.submittedByEmail ?? null,
},
@@ -225,6 +235,9 @@ export async function createExport(input: CreateExportInput) {
},
});
// Plate provenance is recorded at queue time so a suspect export is
// visible in the queue before it renders (§8.1a).
const provenance = describePlateProvenance(resolvedManifest);
await tx.exportEvent.create({
data: {
exportId: created.id,
@@ -232,17 +245,13 @@ export async function createExport(input: CreateExportInput) {
toStatus: "QUEUED",
actorType: "USER",
actorId: submittedBy?.id ?? null,
note: `Queue Export ${versionString}${input.force ? " (force)" : ""}`,
note:
`Queue Export ${versionString}${input.force ? " (force)" : ""}` +
`${input.skipPreview ? " (skip preview)" : ""} — ` +
`${provenance.ok ? "" : "WARNING: "}${provenance.note}`,
},
});
// Mirror the legacy panel PATCH: Shot stays the canonical "current version"
const updatedShot = await tx.shot.update({
where: { id: shot.id },
data: { shotVersion: versionString, exrOutput: exrBase },
select: { id: true, shotVersion: true, exrOutput: true },
});
return {
export: {
id: created.id,
@@ -256,7 +265,7 @@ export async function createExport(input: CreateExportInput) {
submissionNote,
},
renderJob: { id: renderJob.id, attempt: renderJob.attempt, priority: renderJob.priority },
shot: updatedShot,
shot: { id: shot.id, shotVersion: versionString, exrOutput: exrBase },
superseded: toSupersede.map((s) => s.id),
};
});
@@ -338,10 +347,22 @@ export async function getExportDetail(exportId: string) {
include: { machine: { select: { id: true, name: true } } },
},
events: { orderBy: { createdAt: "asc" } },
validations: { orderBy: { createdAt: "asc" } },
qcReviews: { orderBy: { createdAt: "desc" } },
deliveryItems: {
include: {
package: { select: { id: true, name: true, episode: true, status: true, packageNumber: true } },
},
},
},
});
if (!exp) throw new PipelineError(404, "Export not found");
return { export: serializeExport(exp) };
return {
export: {
...serializeExport(exp),
deliveryItems: exp.deliveryItems.map((i) => ({ ...i, totalBytes: i.totalBytes == null ? null : Number(i.totalBytes) })),
},
};
}
/**
+82 -14
View File
@@ -3,11 +3,11 @@ import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { applyTransition } from "./transitions";
import { getConfigBoolean, getConfigNumber } from "./config";
import { machineCanClaim } from "./machines";
import { machineCanClaim, machineSupportedTypes } from "./machines";
import { reapExpiredLeases } from "./reaper";
import { buildPreviewManifest, createPreviewJob } from "./preview";
import { buildPreviewManifest, createPreviewJob, inheritPreviewMedia } from "./preview";
const JOB_TYPES: RenderJobType[] = ["AE_RENDER", "PREVIEW_ONLY", "DELIVERY_BUILD"];
const JOB_TYPES: RenderJobType[] = ["AE_RENDER", "PREVIEW_ONLY", "DELIVERY_BUILD", "BLENDER_RENDER"];
/**
* E8 — atomically claim the next queued job (§6.4). `FOR UPDATE SKIP LOCKED`
@@ -22,10 +22,14 @@ export async function claimNextJob(machineId: string, types?: string[]) {
// Defensive sweep on each claim (studio decision 18.1-Q8)
await reapExpiredLeases().catch((err) => console.error("[render-pipeline] claim-time reap failed", err));
const claimTypes = (types?.length ? types : ["AE_RENDER", "PREVIEW_ONLY", "DELIVERY_BUILD"]).filter(
const requested = (types?.length ? types : ["AE_RENDER", "PREVIEW_ONLY", "DELIVERY_BUILD"]).filter(
(t): t is RenderJobType => (JOB_TYPES as string[]).includes(t)
);
if (claimTypes.length === 0) throw new PipelineError(422, "No valid job types requested");
// Enforced here rather than trusted to the worker: a machine without the tool
// installed must not be able to claim work it can only fail.
const claimTypes = machineSupportedTypes(machine, requested) as RenderJobType[];
if (requested.length === 0) throw new PipelineError(422, "No valid job types requested");
if (claimTypes.length === 0) return null;
const gate = machineCanClaim(machine, new Date());
if (gate === "none") return null;
@@ -74,6 +78,14 @@ export async function claimNextJob(machineId: string, types?: string[]) {
});
}
// Delivery packages have their own small lifecycle on the same queue.
if (job.deliveryId) {
await db.deliveryPackage.updateMany({
where: { id: job.deliveryId, status: "QUEUED" },
data: { status: "BUILDING" },
});
}
return {
job: {
id: job.id,
@@ -83,6 +95,7 @@ export async function claimNextJob(machineId: string, types?: string[]) {
priority: job.priority,
exportId: job.exportId,
deliveryId: job.deliveryId,
label: job.label,
leaseExpiresAt: job.leaseExpiresAt,
manifest: job.manifest,
},
@@ -181,6 +194,33 @@ export async function reportFail(
});
if (!job.export) {
// A standalone job (a Blender render) has no Export to move, but a
// transient failure should still be retried like any other work.
// Delivery builds are deliberately excluded: a half-written package
// folder wants a human to look at it before it is rebuilt.
const retryableStandalone =
!job.deliveryId && body.retryable !== false && job.attempt < job.maxAttempts;
if (retryableStandalone) {
const next = await tx.renderJob.create({
data: {
type: job.type,
projectId: job.projectId,
label: job.label,
submittedBy: job.submittedBy,
deliveryId: job.deliveryId,
attempt: job.attempt + 1,
maxAttempts: job.maxAttempts,
priority: job.priority,
manifest: job.manifest as Prisma.InputJsonValue,
},
});
return {
job: { id: job.id, status: "FAILED" },
export: null,
autoRequeued: true,
nextJob: { id: next.id, attempt: next.attempt },
};
}
return { job: { id: job.id, status: "FAILED" }, export: null, autoRequeued: false };
}
@@ -232,8 +272,11 @@ export async function reportFail(
/**
* E11 — aerender finished OK.
* Phase 2 interim (§17.3): transitions straight to a provisional READY_FOR_QC;
* Phase 3 will insert VALIDATING between (see transitions.ts note).
*
* Hands off to validation (§8) when it is enabled: the worker then runs the
* checks and reports them via E12, which queues the preview stage. With
* validation disabled the old direct handoff to the preview stage is used, so
* the kill switch restores the pre-Phase-3 flow exactly.
*/
export async function completeRender(
jobId: string,
@@ -255,12 +298,17 @@ export async function completeRender(
throw new PipelineError(409, `Job is ${job.status} — contradictory complete report rejected`);
}
// With validation to follow, the job deliberately stays open and keeps its
// lease: a worker that dies mid-validation is then reaped and retried like
// any other stalled job, instead of leaving the Export stuck in VALIDATING.
const validationEnabled = job.export ? await getConfigBoolean("validation.enabled") : false;
await tx.renderJob.update({
where: { id: job.id },
data: {
status: "COMPLETED",
status: validationEnabled ? "RUNNING" : "COMPLETED",
progress: 1,
finishedAt: new Date(),
...(validationEnabled ? {} : { finishedAt: new Date() }),
exitCode: 0,
logFileKey: body.logFileKey ?? job.logFileKey,
logTail: body.logTail?.slice(-20000) ?? job.logTail,
@@ -277,10 +325,27 @@ export async function completeRender(
...(body.exrTotalBytes != null ? { exrTotalBytes: BigInt(Math.round(body.exrTotalBytes)) } : {}),
};
// The EXR render is only the first stage: hand off to the preview stage
// (headless AE rebuild → delivery MOV + review MP4) when it is enabled.
// The EXR render is only the first stage. Validation comes next when
// enabled; the worker reports its results via E12 on the same job.
if (validationEnabled) {
const exp = await applyTransition(tx, job.export, "VALIDATING", {
type: "WORKER",
id: machineId,
note: `Render complete in ${body.renderSeconds ?? "?"}s — validating`,
}, stats);
return {
job: { id: job.id, status: "RUNNING" },
export: { id: exp.id, status: exp.status },
previewJob: null,
validationRequired: true,
alreadyApplied: false,
};
}
// Validation disabled: hand off to the preview stage (headless AE rebuild
// → delivery MOV + review MP4) exactly as before Phase 3.
const previewEnabled = await getConfigBoolean("preview.enabled");
if (previewEnabled) {
if (previewEnabled && !exportRow.skipPreview) {
const manifest = await buildPreviewManifest(exportRow);
const created = await createPreviewJob(tx, exportRow, manifest, job.maxAttempts, job.priority);
previewJob = { id: created.id, type: created.type };
@@ -291,11 +356,14 @@ export async function completeRender(
}, stats);
exportResult = { id: exp.id, status: exp.status };
} else {
const inherited = exportRow.skipPreview
? await inheritPreviewMedia(tx, exportRow)
: { data: {}, note: "preview stage disabled" };
const exp = await applyTransition(tx, job.export, "READY_FOR_QC", {
type: "WORKER",
id: machineId,
note: `Render complete in ${body.renderSeconds ?? "?"}s (preview stage disabled)`,
}, stats);
note: `Render complete in ${body.renderSeconds ?? "?"}s — ${inherited.note}`,
}, { ...stats, ...inherited.data });
exportResult = { id: exp.id, status: exp.status };
}
}
+13
View File
@@ -59,6 +59,19 @@ export function isInWindow(windows: AvailabilityWindow[], now: Date): boolean {
export type ClaimGate = "normal" | "urgent-only" | "none";
/**
* Job types a machine is equipped for. Capabilities are reported at
* registration; a machine without Blender installed must never be handed a
* Blender job, or it claims work it can only fail — repeatedly, until the
* attempts run out — while a machine that could have rendered it sits idle.
*/
export function machineSupportedTypes(machine: { capabilities: unknown }, requested: string[]): string[] {
const tools = ((machine.capabilities as { tools?: Record<string, unknown> } | null)?.tools ?? {}) as Record<string, unknown>;
const hasBlender = Boolean(tools.blender);
return requested.filter((type) => (type === "BLENDER_RENDER" ? hasBlender : true));
}
export function machineCanClaim(machine: Machine, now: Date): ClaimGate {
if (!machine.enabled) return "none";
if (machine.renderNowUntil && machine.renderNowUntil > now) return "normal";
+72
View File
@@ -9,6 +9,20 @@ import { z } from "zod";
* generates them from the shot's exrOutput convention and the NEW version
* number it decides (§6.4 E1).
*/
/**
* A plate element imported into the comp, resolved by the panel from the comp's
* own footage layers — not re-derived from a path convention (§6.2).
*/
export const plateRefSchema = z.object({
element: z.string().optional(),
/** First frame of the sequence on disk; the timecode reference file. */
path: z.string().min(1),
frameStart: z.number().int().optional(),
frameEnd: z.number().int().optional(),
});
export type PlateRef = z.infer<typeof plateRefSchema>;
export const renderManifestSchema = z
.object({
manifestVersion: z.number().int().min(1).default(1),
@@ -23,8 +37,16 @@ export const renderManifestSchema = z
outputPattern: z.string().min(1),
outputModuleTemplate: z.string().optional(),
renderSettingsTemplate: z.string().optional(),
/** Comp timeline range handed to aerender. */
frameStart: z.number().int(),
frameEnd: z.number().int(),
/**
* The number the first *output file* carries — the output module's starting
* number (house convention 1001). Deliberately separate from frameStart: a
* comp anchored to its plate's timecode starts in the millions, so file
* numbering and comp frames are different coordinate systems.
*/
outputFrameStart: z.number().int().optional(),
fps: z.number().positive(),
width: z.number().int().positive(),
height: z.number().int().positive(),
@@ -37,6 +59,30 @@ export const renderManifestSchema = z
timecodeStart: z.string().optional(),
})
.optional(),
/**
* Plate provenance for the timecode check (§8.1a). Optional so
* manifestVersion 1 panels keep working — validation then degrades to a
* worker-derived plate, and finally to the API value as a WARN.
*/
source: z
.object({
/**
* The element the comp's start time was anchored to (the panel's
* primaryFootage). A shot's elements carry unrelated camera timecodes,
* so the timing reference must be named rather than guessed.
*/
timingPlate: plateRefSchema.optional(),
plates: z.array(plateRefSchema).optional(),
/**
* Verbatim from the panel's start-frame resolution: "footage metadata"
* (trustworthy) or "API timecode …" (fallback, suspect). Known at queue
* time, so a suspect export is flagged before it burns render hours.
*/
startSource: z.string().optional(),
startFrames: z.number().int().optional(),
handleFrames: z.number().int().optional(),
})
.optional(),
preview: z
.object({
template: z.string().optional(),
@@ -50,3 +96,29 @@ export const renderManifestSchema = z
});
export type RenderManifest = z.infer<typeof renderManifestSchema>;
/**
* Queue-time read of the manifest's plate provenance (§8.1a). A comp whose
* start time came from the API rather than the plate's own metadata is very
* likely to fail the timecode check — worth recording before the render burns
* machine hours, not after.
*/
export function describePlateProvenance(manifest: RenderManifest): { ok: boolean; note: string } {
const src = manifest.source;
if (!src?.timingPlate?.path) {
return {
ok: false,
note: "no timing plate in manifest — timecode will be checked against a worker-derived plate",
};
}
// Only warn on a start source we positively know to be the API fallback. An
// absent startSource means the comp predates this session (an AEP opened from
// disk), which is normal — the worker still does the authoritative check.
if (src.startSource && /\bAPI\b/i.test(src.startSource)) {
return {
ok: false,
note: `comp start came from "${src.startSource}", not the plate's own metadata — timecode check likely to fail`,
};
}
return { ok: true, note: `timing plate ${src.timingPlate.element ?? src.timingPlate.path}` };
}
@@ -0,0 +1,40 @@
import { describe, it, expect } from "vitest";
import { previewPriority } from "./preview";
/**
* A preview job is created when its render finishes, so it is always newer than
* the renders queued beside it. With the queue ordered by priority then age,
* equal priority means every pending render goes first — a batch of ten shots
* runs as ten renders and then ten previews, and nothing is reviewable until
* the end.
*/
describe("previewPriority", () => {
const URGENT = 20;
it("outranks other work of the same priority so a shot finishes end to end", () => {
expect(previewPriority(50, 1, URGENT)).toBe(49);
});
it("keeps an urgent export's preview urgent", () => {
// Urgent renders may claim outside the render window; their previews have
// to be able to follow, or the shot stalls one step from being reviewable.
expect(previewPriority(20, 1, URGENT)).toBe(19);
expect(previewPriority(19, 1, URGENT)).toBeLessThanOrEqual(URGENT);
});
it("never promotes a normal job across the urgent line", () => {
// 21 - 1 would be 20, quietly granting the preview permission to run
// outside the render window that its render never had.
expect(previewPriority(21, 1, URGENT)).toBe(21);
expect(previewPriority(25, 10, URGENT)).toBe(21);
});
it("a boost of zero restores the old phase behaviour", () => {
expect(previewPriority(50, 0, URGENT)).toBe(50);
});
it("ignores a negative boost and never goes below zero", () => {
expect(previewPriority(50, -5, URGENT)).toBe(50);
expect(previewPriority(0, 5, URGENT)).toBe(0);
});
});
+32
View File
@@ -0,0 +1,32 @@
import { describe, it, expect } from "vitest";
import { nextTaskTitle } from "./preview";
describe("nextTaskTitle", () => {
it("swaps an existing version suffix", () => {
expect(nextTaskTitle("UNG_102_019_010_cmp_TT_v004", "v005")).toBe(
"UNG_102_019_010_cmp_TT_v005"
);
});
it("is idempotent when the title already matches", () => {
expect(nextTaskTitle("UNG_102_019_010_cmp_TT_v005", "v005")).toBe(
"UNG_102_019_010_cmp_TT_v005"
);
});
it("appends when the title carries no version yet", () => {
expect(nextTaskTitle("UNG_102_019_010_cmp_TT", "v005")).toBe(
"UNG_102_019_010_cmp_TT_v005"
);
});
it("only touches a trailing suffix, not a version inside the name", () => {
expect(nextTaskTitle("UNG_v001_019_010_cmp_TT_v004", "v005")).toBe(
"UNG_v001_019_010_cmp_TT_v005"
);
});
it("handles double-digit and uppercase suffixes", () => {
expect(nextTaskTitle("SHOT_cmp_TT_V12", "v013")).toBe("SHOT_cmp_TT_v013");
});
});
+347 -51
View File
@@ -1,8 +1,9 @@
import { Prisma } from "@prisma/client";
import { ExportStatus, Prisma } from "@prisma/client";
import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { applyTransition } from "./transitions";
import { getConfigNumber, getPreviewConfig } from "./config";
import { resolveProjectTemplates } from "./project-templates";
/** Slate date format used by the panel's getDateString (YYYY/MM/DD). */
function slateDate(d = new Date()): string {
@@ -37,6 +38,8 @@ export interface PreviewManifest {
description: string | null;
notes: string | null;
shotCode: string;
/** Production name, burned into the slate and the overlay. */
show: string | null;
episode: string | null;
scene: string | null;
vfxScope: string | null;
@@ -68,12 +71,30 @@ type ExportForPreview = {
export async function buildPreviewManifest(exportRow: ExportForPreview): Promise<PreviewManifest> {
const shot = await db.shot.findUnique({
where: { id: exportRow.shotId },
select: { shotCode: true, episode: true, scene: true, description: true, notes: true },
select: {
shotCode: true,
clientCode: true,
episode: true,
scene: true,
description: true,
notes: true,
slateDescription: true,
project: { select: { name: true, code: true, showId: true, pipelineConfig: true } },
},
});
if (!shot) throw new PipelineError(404, "Shot not found for export");
const cfg = await getPreviewConfig();
// Per-production templates: each show has its own slate/overlay AEP, and
// above all its own show LUT. Falling back to another show's would render a
// preview that is quietly the wrong colour.
const templates = await resolveProjectTemplates(shot.project);
const base = `${shot.shotCode}_cmp_TT_${exportRow.versionString}`;
// Client code, when set, replaces shotCode in everything the client sees —
// slate identity and (via ctx.slate.versionName) the overlay burn-in — but
// never in internal paths: movOutput/mp4Output below stay on `base`. Just
// their own naming with our version appended, no "_cmp_TT_" studio jargon.
const clientBase = shot.clientCode ? `${shot.clientCode}_${exportRow.versionString}` : base;
return {
stage: "PREVIEW",
@@ -85,22 +106,27 @@ export async function buildPreviewManifest(exportRow: ExportForPreview): Promise
frameStart: exportRow.frameStart,
frameEnd: exportRow.frameEnd,
fps: exportRow.fps,
templateAep: cfg.templateAep,
templateComp: cfg.templateComp,
overlayComp: cfg.overlayComp,
lutComp: cfg.lutComp,
movTemplate: cfg.movTemplate,
mp4Template: cfg.mp4Template,
templateAep: templates.templateAep,
templateComp: templates.previewComp,
overlayComp: templates.overlayComp,
lutComp: templates.lutComp,
movTemplate: templates.movTemplate,
mp4Template: templates.mp4Template,
movOutput: `${exportRow.outputDir}/${base}.mov`,
mp4Output: `${exportRow.outputDir}/${base}.mp4`,
slateScopeProp: cfg.slateScopeProp,
slateSubmissionProp: cfg.slateSubmissionProp,
slate: {
versionName: base,
versionName: clientBase,
date: slateDate(),
description: shot.description,
// The slate's own description is authored on the Shot's Slate tab and
// falls back to the general shot description — the same precedence the
// tab shows as its placeholder.
description: shot.slateDescription ?? shot.description,
notes: shot.notes,
shotCode: shot.shotCode,
shotCode: shot.clientCode || shot.shotCode,
// The production's own name, not its code: this is read off a slate.
show: shot.project?.name ?? shot.project?.code ?? null,
episode: shot.episode,
scene: shot.scene,
vfxScope: exportRow.vfxScope,
@@ -109,26 +135,137 @@ export async function buildPreviewManifest(exportRow: ExportForPreview): Promise
};
}
/** Creates the PREVIEW_ONLY job that follows a successful EXR render. */
/**
* Carries the previous export's review media onto one that skipped its own
* preview build (§9).
*
* An export whose framing differs from the review framing — unscaled or
* un-punched-in EXRs — must not have a preview rebuilt from its own frames:
* the earlier, correctly-framed MOV *is* the right preview. Inheriting it also
* keeps the delivery package whole, since the builder takes its MOV from
* `deliveryMovPath`.
*
* Returns the fields to apply and a note describing what happened, so the
* export's timeline records where its media came from.
*/
export async function inheritPreviewMedia(
tx: Prisma.TransactionClient,
exportRow: { id: string; shotId: string }
): Promise<{ data: Prisma.ExportUpdateInput; note: string }> {
const donor = await tx.export.findFirst({
where: {
shotId: exportRow.shotId,
id: { not: exportRow.id },
OR: [{ previewMovKey: { not: null } }, { deliveryMovPath: { not: null } }],
},
orderBy: { versionNumber: "desc" },
select: {
versionString: true,
deliveryMovPath: true,
previewMovKey: true,
thumbnailKey: true,
versionId: true,
},
});
if (!donor) {
return {
data: {},
note: "no preview built and no earlier export to inherit one from — this export has no review media",
};
}
return {
data: {
deliveryMovPath: donor.deliveryMovPath,
previewMovKey: donor.previewMovKey,
thumbnailKey: donor.thumbnailKey,
// The Version row stays attached to the export that actually produced the
// media; this one only points at the same files.
versionId: donor.versionId,
},
note: `preview skipped — review media inherited from ${donor.versionString}`,
};
}
/**
* How a preview job is ranked against the render it follows.
*
* The preview is created when the render finishes, so with equal priority it
* sorts behind every render queued at the same time — a batch runs as all the
* renders, then all the previews, and nothing is reviewable until the end. The
* boost lets a finished shot complete instead.
*/
export function previewPriority(renderPriority: number, boost: number, urgentThreshold: number): number {
const boosted = renderPriority - Math.max(0, boost);
// A boost must never promote a job across the urgent line: that would let it
// claim outside the render window, which whoever queued it did not ask for.
if (renderPriority > urgentThreshold && boosted <= urgentThreshold) return urgentThreshold + 1;
return Math.max(0, boosted);
}
/**
* The priority an export's work runs at: the one its render was queued with.
*
* Every preview for an export derives from this rather than from a previous
* preview job, for two reasons. A preview job may not exist yet — an export
* that failed validation never had one, and reading a missing row used to
* silently drop an urgent export to normal. And deriving from an already-
* boosted preview would boost again on each retry, drifting the export up the
* queue a step at a time.
*/
export async function renderPriorityFor(
tx: Prisma.TransactionClient,
exportId: string
): Promise<number> {
const job = await tx.renderJob.findFirst({
where: { exportId, type: "AE_RENDER" },
orderBy: { attempt: "desc" },
select: { priority: true },
});
return job?.priority ?? 50;
}
/**
* Creates a PREVIEW_ONLY job. `renderPriority` is the export's *render*
* priority; the queue rank is derived from it here so every path — first
* build, retry, regenerate, validation override — ranks identically.
*/
export async function createPreviewJob(
tx: Prisma.TransactionClient,
exportRow: ExportForPreview,
manifest: PreviewManifest,
maxAttempts: number,
priority: number
renderPriority: number,
attempt = 1
) {
const [boost, urgentThreshold] = await Promise.all([
getConfigNumber("render.previewPriorityBoost"),
getConfigNumber("render.urgentPriorityThreshold"),
]);
return tx.renderJob.create({
data: {
type: "PREVIEW_ONLY",
exportId: exportRow.id,
attempt: 1,
attempt,
maxAttempts,
priority,
priority: previewPriority(renderPriority, boost, urgentThreshold),
manifest: manifest as unknown as Prisma.InputJsonValue,
},
});
}
/**
* `UNG_102_019_010_cmp_TT_v004` + v005 → `UNG_102_019_010_cmp_TT_v005`.
* Mirrors `nextExrOutputBase` (exports.ts) so the task title, the EXR base and
* the preview filename all carry the same version suffix.
*/
export function nextTaskTitle(current: string, versionString: string): string {
if (/_v\d+$/i.test(current)) return current.replace(/_v\d+$/i, `_${versionString}`);
return `${current}_${versionString}`;
}
export interface FinalizeInput {
artifacts?: {
deliveryMovPath?: string;
@@ -167,6 +304,7 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
return {
export: { id: exportRow.id, status: exportRow.status },
version: { id: exportRow.versionId },
task: null,
alreadyApplied: true,
};
}
@@ -186,31 +324,10 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
});
let versionId: string | null = null;
let versionReplaced = false;
let inheritedApproval: string | null = null;
if (artifacts.previewMovKey) {
// Version numbering stays monotonic for the task (existing review flows
// rely on the newest version having the highest number) while matching
// the export version whenever it is ahead.
const taskMax = exportRow.taskId
? await tx.version.aggregate({
where: { taskId: exportRow.taskId },
_max: { versionNumber: true },
})
: { _max: { versionNumber: null as number | null } };
const versionNumber = Math.max((taskMax._max.versionNumber ?? 0) + 1, exportRow.versionNumber);
if (exportRow.taskId) {
await tx.version.updateMany({
where: { taskId: exportRow.taskId },
data: { isLatest: false },
});
}
const version = await tx.version.create({
data: {
versionNumber,
shotId: exportRow.shotId,
taskId: exportRow.taskId,
artistId: exportRow.submittedById,
const mediaFields = {
fileUrl: `/api/files/${artifacts.previewMovKey}`,
fileName: media.fileName ?? `${exportRow.versionString}.mp4`,
mimeType: "video/mp4",
@@ -219,12 +336,98 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
frameCount: media.frameCount ?? exportRow.frameEnd - exportRow.frameStart + 1,
width: media.width ?? exportRow.width,
height: media.height ?? exportRow.height,
notes: `Pipeline render ${exportRow.versionString} (internal only)`,
};
// Regenerating a preview (T11b) re-delivers the *same* export version, so
// it replaces the media on the Version already registered rather than
// stacking a second row: the version number stays put and any notes or
// annotations reviewers left on it survive the reslate.
const existing = exportRow.versionId
? await tx.version.findUnique({ where: { id: exportRow.versionId }, select: { id: true } })
: null;
if (existing) {
await tx.version.update({
where: { id: existing.id },
data: { ...mediaFields, isLatest: true },
});
versionId = existing.id;
versionReplaced = true;
} else {
// Version numbering stays monotonic for the task (existing review flows
// rely on the newest version having the highest number) while matching
// the export version whenever it is ahead.
// A re-export does not change the picture — it re-renders EXRs for
// delivery from a shot that has usually already been approved. A fresh
// Version defaults to PENDING_REVIEW, which is what the dashboard, the
// shot page and the client portal all read, so an approved shot would
// silently reappear as awaiting review. The approval carries over from
// the version this one supersedes.
const previousLatest = exportRow.taskId
? await tx.version.findFirst({
where: { taskId: exportRow.taskId },
orderBy: { versionNumber: "desc" },
select: { approvalStatus: true, versionNumber: true },
})
: null;
const taskMax = exportRow.taskId
? await tx.version.aggregate({
where: { taskId: exportRow.taskId },
_max: { versionNumber: true },
})
: { _max: { versionNumber: null as number | null } };
const versionNumber = Math.max((taskMax._max.versionNumber ?? 0) + 1, exportRow.versionNumber);
const version = await tx.version.create({
data: {
...mediaFields,
versionNumber,
shotId: exportRow.shotId,
taskId: exportRow.taskId,
artistId: exportRow.submittedById,
// `notes` is the artist's message to reviewers and is shown in the
// client portal, so the pipeline stays out of it. What this version
// is and where it came from lives on the Export and its timeline,
// which is where someone would go looking anyway.
approvalStatus: previousLatest?.approvalStatus ?? "PENDING_REVIEW",
isLatest: true,
isClientVisible: false, // never shared to the client portal (§10.0)
},
});
versionId = version.id;
inheritedApproval = previousLatest?.approvalStatus ?? null;
}
if (exportRow.taskId) {
await tx.version.updateMany({
where: { taskId: exportRow.taskId, id: { not: versionId } },
data: { isLatest: false },
});
}
}
// The task title carries the version it is showing (house convention:
// "UNG_102_019_010_cmp_TT_v004"). The preview just uploaded *is* the task's
// new latest version, so the title has to follow the file — the same rename
// the manual batch upload does on "rename-and-upload".
let taskTitle: string | null = null;
let taskRenamed = false;
if (versionId && exportRow.taskId) {
const task = await tx.task.findUnique({
where: { id: exportRow.taskId },
select: { title: true },
});
if (task) {
taskTitle = nextTaskTitle(task.title, exportRow.versionString);
taskRenamed = taskTitle !== task.title;
if (taskRenamed) {
await tx.task.update({
where: { id: exportRow.taskId },
data: { title: taskTitle },
});
}
}
}
const updated = await applyTransition(
@@ -234,7 +437,14 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
{
type: "WORKER",
id: machineId,
note: `Preview complete in ${body.renderStats?.previewSeconds ?? "?"}s${versionId ? " — review version created" : " — no preview media reported"}`,
note:
`Preview complete in ${body.renderStats?.previewSeconds ?? "?"}s` +
(versionId
? versionReplaced
? " — review version media replaced"
: ` — review version created (${inheritedApproval ?? "PENDING_REVIEW"})`
: " — no preview media reported") +
(taskRenamed ? ` — task renamed to ${taskTitle}` : ""),
},
{
...(versionId ? { versionId } : {}),
@@ -247,7 +457,8 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
return {
export: { id: updated.id, status: updated.status },
version: versionId ? { id: versionId } : null,
version: versionId ? { id: versionId, replaced: versionReplaced } : null,
task: exportRow.taskId ? { id: exportRow.taskId, title: taskTitle, renamed: taskRenamed } : null,
alreadyApplied: false,
};
});
@@ -268,18 +479,17 @@ export async function retryPreview(exportId: string, actorId?: string) {
const last = await tx.renderJob.findFirst({
where: { exportId, type: "PREVIEW_ONLY" },
orderBy: { attempt: "desc" },
select: { attempt: true },
});
const job = await tx.renderJob.create({
data: {
type: "PREVIEW_ONLY",
exportId,
attempt: (last?.attempt ?? 0) + 1,
const job = await createPreviewJob(
tx,
exportRow,
manifest,
maxAttempts,
priority: last?.priority ?? 50,
manifest: manifest as unknown as Prisma.InputJsonValue,
},
});
await renderPriorityFor(tx, exportId),
(last?.attempt ?? 0) + 1
);
const updated = await applyTransition(tx, exportRow, "GENERATING_PREVIEW", {
type: "USER",
@@ -293,3 +503,89 @@ export async function retryPreview(exportId: string, actorId?: string) {
};
});
}
/** Statuses a preview can be regenerated from — every state where the EXRs are known good. */
const REGENERATABLE_STATUSES: ExportStatus[] = ["READY_FOR_QC", "QC_FAILED", "PREVIEW_FAILED"];
export interface RegeneratePreviewInput {
/** Per-export override; omitted → re-read from the shot's slate fields. */
vfxScope?: string | null;
submissionNote?: string | null;
actorId?: string;
note?: string;
}
/**
* T11b — rebuild the preview for an export that already delivered one, after a
* slate or burn-in mistake was spotted in QC.
*
* Re-runs the *whole* preview stage rather than patching anything: the manifest
* is rebuilt from scratch, so the shot code, episode/scene, frame count, slate
* date and burn-ins are all re-derived from current data exactly as they are on
* a first-time preview. The validated EXRs are reused and the version number is
* untouched — this re-delivers the same version, it does not make a new one.
*
* Slate text authored on the web app's Slate tab (description, VFX scope,
* submission note) is picked up here: `vfxScope` and `submissionNote` are
* frozen onto the Export at submission time, so regenerating refreshes that
* snapshot from the shot unless the caller passes an explicit override.
*/
export async function regeneratePreview(exportId: string, input: RegeneratePreviewInput = {}) {
const maxAttempts = await getConfigNumber("render.maxAttempts");
return db.$transaction(async (tx) => {
const exportRow = await tx.export.findUnique({ where: { id: exportId } });
if (!exportRow) throw new PipelineError(404, "Export not found");
if (!REGENERATABLE_STATUSES.includes(exportRow.status)) {
throw new PipelineError(
409,
`Export is ${exportRow.status} — a preview can only be regenerated from ${REGENERATABLE_STATUSES.join(", ")}`
);
}
const shot = await tx.shot.findUniqueOrThrow({
where: { id: exportRow.shotId },
select: { slateVfxScope: true, slateSubmissionNote: true },
});
// Same precedence as createExport: explicit override → shot's slate field.
const vfxScope = input.vfxScope !== undefined ? input.vfxScope : (shot.slateVfxScope ?? null);
const submissionNote =
input.submissionNote !== undefined ? input.submissionNote : (shot.slateSubmissionNote ?? null);
const refreshed = { ...exportRow, vfxScope, submissionNote };
const manifest = await buildPreviewManifest(refreshed);
const last = await tx.renderJob.findFirst({
where: { exportId, type: "PREVIEW_ONLY" },
orderBy: { attempt: "desc" },
select: { attempt: true },
});
const job = await createPreviewJob(
tx,
refreshed,
manifest,
maxAttempts,
await renderPriorityFor(tx, exportId),
(last?.attempt ?? 0) + 1
);
const updated = await applyTransition(
tx,
exportRow,
"GENERATING_PREVIEW",
{
type: "USER",
id: input.actorId,
note: input.note ?? `Regenerate preview (attempt ${job.attempt})`,
},
{ vfxScope, submissionNote }
);
return {
export: { id: updated.id, status: updated.status },
renderJob: { id: job.id, attempt: job.attempt },
slate: { vfxScope, submissionNote, description: manifest.slate.description },
};
});
}
@@ -0,0 +1,34 @@
import { describe, it, expect } from "vitest";
import { conventionalNames } from "./project-templates";
/**
* The convention has to reproduce UNG's existing comp names exactly, or
* enabling per-project templates would silently break the show it was built
* for: every findComp in the panel resolves through it.
*/
describe("conventionalNames", () => {
it("reproduces UNG's existing template names", () => {
expect(conventionalNames("UNG")).toEqual({
overlayComp: "UNG_VFX_OVERLAY",
previewComp: "UNG_EXPORT_TEMPLATE",
lutComp: "_SHOW LUT",
});
});
it("derives names for a show with a longer id", () => {
const names = conventionalNames("DH2_VFX");
expect(names.overlayComp).toBe("DH2_VFX_VFX_OVERLAY");
expect(names.previewComp).toBe("DH2_VFX_EXPORT_TEMPLATE");
});
it("keeps the LUT comp name constant across shows", () => {
// What differs between shows is the LUT inside the comp, which is why the
// template AEP is per-project rather than the comp name.
expect(conventionalNames("SNV").lutComp).toBe("_SHOW LUT");
expect(conventionalNames("QTK").lutComp).toBe("_SHOW LUT");
});
it("falls back to a placeholder rather than producing _VFX_OVERLAY", () => {
expect(conventionalNames("").overlayComp).toBe("SHOW_VFX_OVERLAY");
});
});
+99
View File
@@ -0,0 +1,99 @@
import { z } from "zod";
import { getConfigValue } from "./config";
/**
* Per-production AE workspace configuration.
*
* Comp names follow a convention derived from the show — `UNG_VFX_OVERLAY`,
* `UNG_EXPORT_TEMPLATE`, `_SHOW LUT` — so a project that names its template
* comps to the pattern needs no configuration at all. Anything that cannot be
* derived is stated explicitly: paths, above all, since a show's folder rarely
* matches its show id (UNG lives under `UNGO_VFX`).
*
* Resolved server-side and handed to both the panel (via the ext projects list)
* and the worker (inside the preview manifest), so the two cannot disagree
* about which template a render was built from.
*/
export const pipelineConfigSchema = z.object({
/** The show's slate/overlay/LUT template AEP, imported by Initialise Workspace. */
templateAep: z.string().max(1000).optional().nullable(),
/** Where per-shot pre-renders live, imported by Import Renders. */
rendersRoot: z.string().max(1000).optional().nullable(),
/** Overrides for templates that depart from the {showId}_* convention. */
overlayComp: z.string().max(200).optional().nullable(),
previewComp: z.string().max(200).optional().nullable(),
lutComp: z.string().max(200).optional().nullable(),
/** AE output-module templates, when this show does not use the studio defaults. */
movTemplate: z.string().max(200).optional().nullable(),
mp4Template: z.string().max(200).optional().nullable(),
});
export type PipelineConfigInput = z.infer<typeof pipelineConfigSchema>;
export interface ResolvedTemplates {
templateAep: string;
rendersRoot: string;
overlayComp: string;
previewComp: string;
lutComp: string;
movTemplate: string;
mp4Template: string;
/** Which values came from the project rather than a convention or a default. */
explicit: string[];
}
/** The comp-name convention. UNG's existing templates already match it exactly. */
export function conventionalNames(showId: string) {
const prefix = showId?.trim() || "SHOW";
return {
overlayComp: `${prefix}_VFX_OVERLAY`,
previewComp: `${prefix}_EXPORT_TEMPLATE`,
// The LUT comp is named the same in every show's template; what differs is
// the LUT inside it, which is why the template AEP is per-project.
lutComp: "_SHOW LUT",
};
}
export async function resolveProjectTemplates(project: {
showId: string | null;
code: string;
pipelineConfig?: unknown;
}): Promise<ResolvedTemplates> {
const parsed = pipelineConfigSchema.safeParse(project.pipelineConfig ?? {});
const cfg: PipelineConfigInput = parsed.success ? parsed.data : {};
if (!parsed.success) {
console.error(`[render-pipeline] pipelineConfig for ${project.code} is malformed — using defaults`);
}
const showId = project.showId?.trim() || project.code;
const convention = conventionalNames(showId);
const explicit: string[] = [];
const pick = <K extends keyof PipelineConfigInput>(key: K, fallback: string): string => {
const value = cfg[key];
if (typeof value === "string" && value.trim()) {
explicit.push(key);
return value.trim();
}
return fallback;
};
const [defaultAep, defaultMov, defaultMp4] = await Promise.all([
getConfigValue("preview.templateAep"),
getConfigValue("preview.movTemplate"),
getConfigValue("preview.mp4Template"),
]);
return {
templateAep: pick("templateAep", defaultAep),
// No sensible studio-wide default: a renders root that points at another
// show's folder is worse than an empty one the panel can report.
rendersRoot: pick("rendersRoot", ""),
overlayComp: pick("overlayComp", convention.overlayComp),
previewComp: pick("previewComp", convention.previewComp),
lutComp: pick("lutComp", convention.lutComp),
movTemplate: pick("movTemplate", defaultMov),
mp4Template: pick("mp4Template", defaultMp4),
explicit,
};
}
+173
View File
@@ -0,0 +1,173 @@
import { Prisma, QCResult } from "@prisma/client";
import { z } from "zod";
import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { applyTransition } from "./transitions";
/**
* QC workflow (RenderPipeline2 §10) — technical/final-delivery QC on shots the
* client has usually already approved. One service, two front doors: the AE
* panel (API key) and the web QC page (session).
*
* PASS means "ready to upload" and nothing else: it never shares to the client
* portal, never changes approval state, never creates client-visible media
* (§10.0). FAIL does move the comp task to CHANGES — the shot genuinely needs
* rework, and the existing REVISIONS derivation should surface that.
*/
export const qcSubmitSchema = z.object({
result: z.enum(["PASS", "FAIL"]),
notes: z.string().max(4000).optional().nullable(),
/** Panel sends the artist's email; web callers pass the session user instead. */
reviewerEmail: z.string().email().optional().nullable(),
reviewerName: z.string().max(200).optional().nullable(),
});
export type QCSubmitInput = z.infer<typeof qcSubmitSchema>;
export interface QCActor {
source: "AE_PANEL" | "WEB";
userId?: string | null;
name?: string | null;
}
/** Statuses a QC decision can be recorded from. */
const QC_ELIGIBLE = ["READY_FOR_QC", "QC_FAILED", "READY_FOR_DELIVERY"] as const;
export async function submitQCReview(exportId: string, input: QCSubmitInput, actor: QCActor) {
const reviewer = input.reviewerEmail
? await db.user.findUnique({ where: { email: input.reviewerEmail }, select: { id: true, name: true } })
: null;
const reviewedById = actor.userId ?? reviewer?.id ?? null;
const reviewerName = actor.name ?? reviewer?.name ?? input.reviewerName ?? input.reviewerEmail ?? null;
return db.$transaction(async (tx) => {
const exportRow = await tx.export.findUnique({
where: { id: exportId },
include: { shot: { select: { shotCode: true } } },
});
if (!exportRow) throw new PipelineError(404, "Export not found");
if (!QC_ELIGIBLE.includes(exportRow.status as (typeof QC_ELIGIBLE)[number])) {
throw new PipelineError(
409,
`Export is ${exportRow.status} — QC can only be recorded on ${QC_ELIGIBLE.join(", ")}`
);
}
const result = input.result as QCResult;
const review = await tx.qCReview.create({
data: {
exportId,
result,
notes: input.notes?.trim() || null,
reviewedById,
reviewerName,
source: actor.source,
},
});
const who = reviewerName ?? "unknown reviewer";
let taskUpdated: { id: string; status: string } | null = null;
if (result === "PASS") {
// Re-passing an export that is already READY_FOR_DELIVERY is a no-op
// transition-wise; the QCReview row is still the record of the decision.
const updated =
exportRow.status === "READY_FOR_DELIVERY"
? exportRow
: await applyTransition(tx, exportRow, "READY_FOR_DELIVERY", {
type: "USER",
id: reviewedById,
note: `QC PASS by ${who}${input.notes ? ` — ${input.notes.slice(0, 200)}` : ""}`,
});
return {
export: { id: updated.id, status: updated.status },
review: { id: review.id, result, createdAt: review.createdAt },
task: null,
};
}
// FAIL — the shot needs rework, so the comp task goes back to CHANGES.
const updated =
exportRow.status === "QC_FAILED"
? exportRow
: await applyTransition(tx, exportRow, "QC_FAILED", {
type: "USER",
id: reviewedById,
note: `QC FAIL by ${who}${input.notes ? ` — ${input.notes.slice(0, 200)}` : ""}`,
});
if (exportRow.taskId) {
const task = await tx.task.findUnique({ where: { id: exportRow.taskId }, select: { id: true, status: true } });
if (task && task.status !== "CHANGES") {
await tx.task.update({ where: { id: task.id }, data: { status: "CHANGES" } });
taskUpdated = { id: task.id, status: "CHANGES" };
}
}
return {
export: { id: updated.id, status: updated.status },
review: { id: review.id, result, createdAt: review.createdAt },
task: taskUpdated,
};
});
}
export interface QCQueueFilter {
projectCode?: string | null;
projectId?: string | null;
episode?: string | null;
limit?: number;
}
/**
* E5 — everything waiting for a human. QC_FAILED is deliberately excluded: a
* failed export is the artist's problem until they queue a new version.
*/
export async function getQCQueue(filter: QCQueueFilter) {
const limit = Math.min(200, Math.max(1, filter.limit ?? 50));
const where: Prisma.ExportWhereInput = {
status: "READY_FOR_QC",
...(filter.projectId ? { projectId: filter.projectId } : {}),
...(filter.projectCode ? { shot: { project: { code: filter.projectCode } } } : {}),
...(filter.episode
? { shot: { ...(filter.projectCode ? { project: { code: filter.projectCode } } : {}), episode: filter.episode } }
: {}),
};
const rows = await db.export.findMany({
where,
orderBy: { statusChangedAt: "asc" }, // oldest first — nothing should sit in QC
take: limit,
include: {
shot: { select: { id: true, shotCode: true, episode: true, scene: true, project: { select: { code: true, name: true } } } },
validations: { where: { status: { in: ["FAIL", "WARN"] } }, select: { checkName: true, status: true, message: true } },
},
});
return {
queue: rows.map((e) => ({
exportId: e.id,
shotCode: e.shot.shotCode,
episode: e.shot.episode,
scene: e.shot.scene,
projectCode: e.shot.project.code,
versionString: e.versionString,
readySince: e.statusChangedAt,
// Everything the panel needs to import the actual EXRs for full-res QC
outputDir: e.outputDir,
outputPattern: e.outputPattern,
frameStart: e.frameStart,
frameEnd: e.frameEnd,
fps: e.fps,
deliveryMovPath: e.deliveryMovPath,
thumbnailUrl: e.thumbnailKey ? `/api/files/${e.thumbnailKey}` : null,
previewUrl: e.previewMovKey ? `/api/files/${e.previewMovKey}` : null,
// Warnings the automated pass raised — the human should look harder at these
warnings: e.validations.map((v) => ({ checkName: v.checkName, status: v.status, message: v.message })),
})),
};
}
+22 -4
View File
@@ -29,6 +29,21 @@ export async function reapExpiredLeases() {
where: { id: job.id },
data: { status: "EXPIRED", finishedAt: new Date(), errorMessage: "Lease expired (worker unreachable)" },
});
// A delivery build that died leaves a half-written folder, so it is
// failed rather than silently retried: someone should look at what
// landed on the delivery volume before it is rebuilt.
if (job.deliveryId) {
await tx.deliveryPackage.updateMany({
where: { id: job.deliveryId, status: "BUILDING" },
data: {
status: "FAILED",
errorMessage: "Worker became unreachable mid-build — check the package folder before rebuilding",
},
});
return;
}
if (!job.export) return;
if (job.attempt < job.maxAttempts) {
@@ -42,16 +57,19 @@ export async function reapExpiredLeases() {
manifest: job.manifest as Prisma.InputJsonValue,
},
});
if (job.export.status === "RENDERING") {
// VALIDATING counts too: the worker holds the same job through the
// validation stage, so dying there means the render must be redone —
// nothing was established about the EXRs either way.
if (["RENDERING", "VALIDATING"].includes(job.export.status)) {
await applyTransition(tx, job.export, "QUEUED", {
type: "SYSTEM",
note: `Lease expired on attempt ${job.attempt} — requeued as attempt ${next.attempt}`,
note: `Lease expired on attempt ${job.attempt} during ${job.export.status} — requeued as attempt ${next.attempt}`,
});
}
} else if (job.export.status === "RENDERING") {
} else if (["RENDERING", "VALIDATING"].includes(job.export.status)) {
await applyTransition(tx, job.export, "RENDER_FAILED", {
type: "SYSTEM",
note: `Lease expired on attempt ${job.attempt}/${job.maxAttempts} — no retries remain`,
note: `Lease expired on attempt ${job.attempt}/${job.maxAttempts} during ${job.export.status} — no retries remain`,
});
}
});
+104
View File
@@ -0,0 +1,104 @@
import { Prisma } from "@prisma/client";
import { z } from "zod";
import { db } from "@/lib/db";
/**
* Deployed-tool registry. Every studio tool reports its own version on
* startup, so "what is running where" is answered by the tools themselves
* rather than by a spreadsheet someone has to remember to update.
*
* Deliberately self-maintaining: nothing here declares what the *current*
* version ought to be. The newest version seen for a tool is treated as the
* benchmark, so updating one machine is what flags the others as stale.
*/
export const TOOL_LABELS: Record<string, string> = {
AE_PANEL: "AE connector panel",
RENDER_WORKER: "Render worker",
};
export const toolPingSchema = z.object({
tool: z.enum(["AE_PANEL", "RENDER_WORKER"]),
machineName: z.string().min(1).max(200),
version: z.string().min(1).max(50),
buildRef: z.string().max(100).optional().nullable(),
hostUser: z.string().max(200).optional().nullable(),
hostApp: z.string().max(200).optional().nullable(),
details: z.record(z.string(), z.unknown()).optional(),
});
export type ToolPing = z.infer<typeof toolPingSchema>;
export async function recordToolVersion(input: ToolPing) {
const now = new Date();
const row = await db.toolVersion.upsert({
where: { tool_machineName: { tool: input.tool, machineName: input.machineName } },
create: {
tool: input.tool,
machineName: input.machineName,
version: input.version,
buildRef: input.buildRef ?? null,
hostUser: input.hostUser ?? null,
hostApp: input.hostApp ?? null,
details: (input.details ?? undefined) as Prisma.InputJsonValue | undefined,
lastSeenAt: now,
},
update: {
version: input.version,
buildRef: input.buildRef ?? null,
hostUser: input.hostUser ?? null,
hostApp: input.hostApp ?? null,
details: (input.details ?? undefined) as Prisma.InputJsonValue | undefined,
lastSeenAt: now,
},
});
return { tool: row.tool, machineName: row.machineName, version: row.version, lastSeenAt: row.lastSeenAt };
}
/**
* Compares versions as dot-separated numbers, falling back to a string
* compare for anything non-numeric. Good enough to answer "is this one
* behind?", which is the only question being asked.
*/
export function compareVersions(a: string, b: string): number {
const parse = (v: string) => v.split(/[.+-]/).map((p) => (/^\d+$/.test(p) ? Number(p) : p));
const pa = parse(a);
const pb = parse(b);
for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
const x = pa[i] ?? 0;
const y = pb[i] ?? 0;
if (x === y) continue;
if (typeof x === "number" && typeof y === "number") return x < y ? -1 : 1;
return String(x) < String(y) ? -1 : 1;
}
return 0;
}
export async function listToolVersions() {
const rows = await db.toolVersion.findMany({ orderBy: [{ tool: "asc" }, { machineName: "asc" }] });
// Newest version seen per tool is the benchmark — update one machine and the
// rest light up as stale, with no "expected version" to keep in sync.
const newest = new Map<string, string>();
for (const row of rows) {
const current = newest.get(row.tool);
if (!current || compareVersions(row.version, current) > 0) newest.set(row.tool, row.version);
}
return {
tools: rows.map((row) => ({
id: row.id,
tool: row.tool,
toolLabel: TOOL_LABELS[row.tool] ?? row.tool,
machineName: row.machineName,
version: row.version,
buildRef: row.buildRef,
hostUser: row.hostUser,
hostApp: row.hostApp,
firstSeenAt: row.firstSeenAt,
lastSeenAt: row.lastSeenAt,
newestVersion: newest.get(row.tool) ?? row.version,
outdated: compareVersions(row.version, newest.get(row.tool) ?? row.version) < 0,
})),
};
}
+17 -9
View File
@@ -5,27 +5,35 @@ import { PipelineError } from "./errors";
* Export lifecycle state machine (RenderPipeline2 §4).
* The server is the sole authority on state; workers *request* transitions.
*
* NOTE (Phase 2 interim): RENDERING → READY_FOR_QC is temporarily legal.
* Phase 3 inserts VALIDATING between them (§17.3) — remove READY_FOR_QC from
* RENDERING's list when the validation engine ships.
* RENDERING → GENERATING_PREVIEW / READY_FOR_QC are the `validation.enabled=false`
* paths (the Phase 3 kill switch, §8), not interim edges: with validation on,
* a completed render always goes RENDERING → VALIDATING first.
*/
export const EXPORT_TRANSITIONS: Record<ExportStatus, ExportStatus[]> = {
QUEUED: ["RENDERING", "CANCELLED", "SUPERSEDED", "READY_FOR_QC"], // READY_FOR_QC: manual mark-done only
RENDERING: [
"VALIDATING",
"GENERATING_PREVIEW", // interim: preview stage runs before validation exists
"GENERATING_PREVIEW", // validation disabled
"RENDER_FAILED",
"QUEUED", // lease expiry / retryable fail with attempts remaining (T5)
"CANCELLED",
"READY_FOR_QC", // preview disabled / manual mark-done
"READY_FOR_QC", // preview + validation disabled / manual mark-done
],
RENDER_FAILED: ["QUEUED", "SUPERSEDED"],
VALIDATING: ["VALIDATION_FAILED", "GENERATING_PREVIEW"],
VALIDATION_FAILED: ["QUEUED", "SUPERSEDED"],
// QUEUED/RENDER_FAILED: the worker died *during* validation, so the render is
// retried — nothing was learned about the EXRs either way (reaper).
VALIDATING: ["VALIDATION_FAILED", "GENERATING_PREVIEW", "READY_FOR_QC", "QUEUED", "RENDER_FAILED", "CANCELLED"],
// GENERATING_PREVIEW / READY_FOR_QC: a human overruled the checks (§8.2).
// The override resumes where a pass would have handed off — it never skips
// QC, so the frames are still looked at before anything ships.
VALIDATION_FAILED: ["QUEUED", "SUPERSEDED", "GENERATING_PREVIEW", "READY_FOR_QC"],
GENERATING_PREVIEW: ["PREVIEW_FAILED", "READY_FOR_QC"],
PREVIEW_FAILED: ["GENERATING_PREVIEW", "SUPERSEDED"],
READY_FOR_QC: ["QC_FAILED", "READY_FOR_DELIVERY", "SUPERSEDED"],
QC_FAILED: ["SUPERSEDED"],
// GENERATING_PREVIEW: a slate/burn-in mistake is caught *after* a successful
// preview, so the preview stage must be re-runnable without re-rendering the
// validated EXRs or burning a version number (T11b).
READY_FOR_QC: ["GENERATING_PREVIEW", "QC_FAILED", "READY_FOR_DELIVERY", "SUPERSEDED"],
QC_FAILED: ["GENERATING_PREVIEW", "SUPERSEDED"],
READY_FOR_DELIVERY: ["PACKAGED", "SUPERSEDED"],
PACKAGED: ["DELIVERED"],
DELIVERED: ["ARCHIVED"],
+400
View File
@@ -0,0 +1,400 @@
import { Prisma, ValidationStatus } from "@prisma/client";
import { z } from "zod";
import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { applyTransition } from "./transitions";
import { getConfigBoolean, getConfigNumber, getConfigValue, getPreviewConfig } from "./config";
import { buildPreviewManifest, createPreviewJob, inheritPreviewMedia, renderPriorityFor } from "./preview";
/**
* Validation engine results (RenderPipeline2 §8). The worker runs the checks —
* it has the files — and reports every result in one call. The server decides
* what they mean: it is the only thing that moves an Export's state.
*/
export const validationCheckSchema = z.object({
checkName: z.string().min(1).max(64),
status: z.enum(["PASS", "FAIL", "WARN", "SKIPPED"]),
expected: z.string().max(500).optional().nullable(),
actual: z.string().max(500).optional().nullable(),
message: z.string().max(2000).optional().nullable(),
details: z.unknown().optional(),
});
export const validationReportSchema = z.object({
machineId: z.string().min(1),
checks: z.array(validationCheckSchema).min(1).max(200),
/** Sequence-level digest reused by the delivery builder for copy verification. */
checksum: z.string().max(200).optional(),
checksumAlgo: z.string().max(32).optional(),
exrFileCount: z.number().int().nonnegative().optional(),
exrTotalBytes: z.number().nonnegative().optional(),
validationSeconds: z.number().nonnegative().optional(),
});
export type ValidationReport = z.infer<typeof validationReportSchema>;
/**
* Per-check severity overrides, e.g. `{"exr_type":"warn"}` (§17.3 risk row).
* A false FAIL blocks an artist, so a check can be demoted without a redeploy.
* `timecode_plate_match` is deliberately overridable too — but demoting it
* should be a considered, temporary act: it is the check the engine exists for.
*/
async function getSeverityOverrides(): Promise<Record<string, ValidationStatus>> {
const raw = await getConfigValue("validation.overrides");
if (!raw?.trim()) return {};
try {
const parsed = JSON.parse(raw) as Record<string, string>;
const out: Record<string, ValidationStatus> = {};
for (const [check, level] of Object.entries(parsed)) {
const up = String(level).toUpperCase();
if (up === "PASS" || up === "FAIL" || up === "WARN" || up === "SKIPPED") {
out[check] = up as ValidationStatus;
}
}
return out;
} catch {
console.error("[render-pipeline] validation.overrides is not valid JSON — ignoring");
return {};
}
}
function summarise(checks: { checkName: string; status: ValidationStatus }[]): string {
const counts = { PASS: 0, FAIL: 0, WARN: 0, SKIPPED: 0 };
for (const c of checks) counts[c.status] += 1;
return `${counts.PASS} passed, ${counts.FAIL} failed, ${counts.WARN} warned, ${counts.SKIPPED} skipped`;
}
/**
* E12 — the worker reports every check from one validation run.
*
* Any FAIL stops the pipeline (§8.2): Export → VALIDATION_FAILED with the exact
* reasons queryable as rows. Otherwise the preview stage is queued, exactly as
* a successful render used to do directly.
*/
export async function reportValidation(jobId: string, body: ValidationReport) {
const overrides = await getSeverityOverrides();
const previewEnabled = (await getPreviewConfig()).enabled;
const effective = body.checks.map((c) => ({
...c,
status: (overrides[c.checkName] ?? c.status) as ValidationStatus,
overridden: overrides[c.checkName] != null && overrides[c.checkName] !== c.status,
}));
return db.$transaction(async (tx) => {
const job = await tx.renderJob.findUnique({
where: { id: jobId },
include: { export: true },
});
if (!job) throw new PipelineError(404, "Render job not found");
if (job.machineId !== body.machineId) {
throw new PipelineError(409, "Job is not held by this machine (lease reassigned?)");
}
const exportRow = job.export;
if (!exportRow) throw new PipelineError(422, "Job has no export to validate");
// Replayed report (worker retried the call after a network cut): the rows
// for this attempt already exist, so don't duplicate them or re-transition.
const existing = await tx.validationResult.count({
where: { exportId: exportRow.id, renderJobId: job.id },
});
if (existing > 0) {
return {
export: { id: exportRow.id, status: exportRow.status },
results: existing,
failed: exportRow.status === "VALIDATION_FAILED",
alreadyApplied: true,
};
}
if (exportRow.status !== "VALIDATING") {
throw new PipelineError(
409,
`Export is ${exportRow.status} — validation results are only accepted while VALIDATING`
);
}
// The render job was held open through validation (see completeRender) so a
// worker dying here is still reaped; the work is finished now.
await tx.renderJob.update({
where: { id: job.id },
data: { status: "COMPLETED", progress: 1, finishedAt: new Date() },
});
await tx.validationResult.createMany({
data: effective.map((c) => ({
exportId: exportRow.id,
renderJobId: job.id,
checkName: c.checkName,
status: c.status,
expected: c.expected ?? null,
actual: c.actual ?? null,
message: c.overridden
? `${c.message ?? "check reported " + c.status} [severity overridden by config]`
: (c.message ?? null),
details: (c.details ?? undefined) as Prisma.InputJsonValue | undefined,
})),
});
const failures = effective.filter((c) => c.status === "FAIL");
const stats = {
...(body.exrFileCount != null ? { exrFileCount: body.exrFileCount } : {}),
...(body.exrTotalBytes != null ? { exrTotalBytes: BigInt(Math.round(body.exrTotalBytes)) } : {}),
...(body.checksum ? { checksum: body.checksum } : {}),
};
const summary = summarise(effective);
if (failures.length > 0) {
const reasons = failures
.slice(0, 5)
.map((f) => `${f.checkName}: ${f.message ?? `expected ${f.expected}, got ${f.actual}`}`)
.join("; ");
const updated = await applyTransition(
tx,
exportRow,
"VALIDATION_FAILED",
{
type: "WORKER",
id: body.machineId,
note: `Validation failed (${summary}) — ${reasons}${failures.length > 5 ? ` (+${failures.length - 5} more)` : ""}`,
},
stats
);
return {
export: { id: updated.id, status: updated.status },
results: effective.length,
failed: true,
failures: failures.map((f) => f.checkName),
alreadyApplied: false,
};
}
// Passed: hand off to the preview stage, the same handoff completeRender
// used to make directly before validation existed.
if (!previewEnabled || exportRow.skipPreview) {
const inherited = exportRow.skipPreview
? await inheritPreviewMedia(tx, exportRow)
: { data: {}, note: "preview stage disabled" };
const updated = await applyTransition(
tx,
exportRow,
"READY_FOR_QC",
{ type: "WORKER", id: body.machineId, note: `Validation passed (${summary}); ${inherited.note}` },
{ ...stats, ...inherited.data }
);
return {
export: { id: updated.id, status: updated.status },
results: effective.length,
failed: false,
previewJob: null,
alreadyApplied: false,
};
}
const manifest = await buildPreviewManifest(exportRow);
const previewJob = await createPreviewJob(tx, exportRow, manifest, job.maxAttempts, job.priority);
const updated = await applyTransition(
tx,
exportRow,
"GENERATING_PREVIEW",
{ type: "WORKER", id: body.machineId, note: `Validation passed (${summary}) — queued preview build` },
stats
);
return {
export: { id: updated.id, status: updated.status },
results: effective.length,
failed: false,
previewJob: { id: previewJob.id, type: previewJob.type },
alreadyApplied: false,
};
});
}
/** Whether the validation stage runs at all (kill switch for a bad engine release). */
export async function isValidationEnabled(): Promise<boolean> {
return getConfigBoolean("validation.enabled");
}
export const overrideValidationSchema = z.object({
/**
* Required, and deliberately so: an override is a human overruling a check
* that exists to stop bad frames shipping, and "why" is the only part of
* that decision the next person cannot reconstruct.
*/
reason: z.string().trim().min(3, "A reason is required").max(2000),
/**
* Go straight to QC, inheriting the previous export's review media instead
* of building one. Correct when this export is framed differently from the
* review — unscaled or un-punched-in frames — so a preview rebuilt from it
* would be the wrong picture.
*/
skipPreview: z.boolean().optional(),
});
/**
* Manual override of a failed validation run.
*
* Some checks fail on renders that are genuinely fine — a plate the engine
* cannot reach, an expectation that does not apply to this shot. Rather than
* leaving those exports stranded, an override resumes the pipeline *at the
* point validation would have handed off*: the preview is built and the export
* lands in READY_FOR_QC. It never skips QC, so a human still looks at the
* frames before anything can be delivered.
*
* The failed ValidationResult rows are left exactly as they are — history is
* not rewritten, and the QC queue keeps surfacing them as warnings so whoever
* QCs the shot knows what was waved through.
*/
export async function overrideValidation(
exportId: string,
input: { reason: string; userId: string; userName?: string | null; skipPreview?: boolean }
) {
const previewEnabled = (await getPreviewConfig()).enabled;
const maxAttempts = await getConfigNumber("render.maxAttempts");
return db.$transaction(async (tx) => {
const exportRow = await tx.export.findUnique({ where: { id: exportId } });
if (!exportRow) throw new PipelineError(404, "Export not found");
if (exportRow.status !== "VALIDATION_FAILED") {
throw new PipelineError(
409,
`Export is ${exportRow.status} — only a VALIDATION_FAILED export can be overridden`
);
}
const failed = await tx.validationResult.findMany({
where: { exportId, status: "FAIL" },
orderBy: { createdAt: "desc" },
select: { checkName: true, renderJobId: true },
});
// Only the most recent run's failures are what is being waved through.
const latestRun = failed[0]?.renderJobId;
const waved = [...new Set(failed.filter((f) => f.renderJobId === latestRun).map((f) => f.checkName))];
const who = input.userName ?? "unknown user";
const note =
`Validation overridden by ${who}: ${input.reason.trim()}` +
(waved.length ? ` — waved: ${waved.join(", ")}` : "");
const skipPreview = input.skipPreview === true || exportRow.skipPreview;
if (!previewEnabled || skipPreview) {
const inherited = skipPreview
? await inheritPreviewMedia(tx, exportRow)
: { data: {}, note: "preview stage disabled" };
const updated = await applyTransition(
tx,
exportRow,
"READY_FOR_QC",
{ type: "USER", id: input.userId, note: `${note} — ${inherited.note}` },
inherited.data
);
return {
export: { id: updated.id, status: updated.status },
overridden: waved,
previewJob: null,
};
}
const manifest = await buildPreviewManifest(exportRow);
const last = await tx.renderJob.findFirst({
where: { exportId, type: "PREVIEW_ONLY" },
orderBy: { attempt: "desc" },
select: { attempt: true },
});
// An export that failed validation has never had a preview job — validation
// runs before the preview stage — so the rank comes from its render, which
// is what keeps an urgent export urgent through an override. Someone is
// usually standing over an urgent shot when they wave a check through.
const previewJob = await createPreviewJob(
tx,
exportRow,
manifest,
maxAttempts,
await renderPriorityFor(tx, exportId),
(last?.attempt ?? 0) + 1
);
const updated = await applyTransition(tx, exportRow, "GENERATING_PREVIEW", {
type: "USER",
id: input.userId,
note: `${note} — queued preview build`,
});
return {
export: { id: updated.id, status: updated.status },
overridden: waved,
previewJob: { id: previewJob.id, attempt: previewJob.attempt },
};
});
}
export interface ValidationBrowserFilter {
projectId?: string;
episode?: string;
checkName?: string;
status?: ValidationStatus;
page?: number;
limit?: number;
}
/**
* Cross-export browser (§13) — the point is spotting a systemic fault
* ("every shot this week failed timecode_plate_match"), not one bad render.
*/
export async function listValidationResults(filter: ValidationBrowserFilter) {
const page = Math.max(1, filter.page ?? 1);
const limit = Math.min(200, Math.max(1, filter.limit ?? 50));
const where: Prisma.ValidationResultWhereInput = {
...(filter.checkName ? { checkName: filter.checkName } : {}),
...(filter.status ? { status: filter.status } : { status: { in: ["FAIL", "WARN"] } }),
...(filter.projectId || filter.episode
? {
export: {
...(filter.projectId ? { projectId: filter.projectId } : {}),
...(filter.episode ? { shot: { episode: filter.episode } } : {}),
},
}
: {}),
};
const [total, rows] = await Promise.all([
db.validationResult.count({ where }),
db.validationResult.findMany({
where,
orderBy: { createdAt: "desc" },
skip: (page - 1) * limit,
take: limit,
include: {
export: {
select: {
id: true,
versionString: true,
status: true,
shot: { select: { shotCode: true, episode: true } },
},
},
},
}),
]);
return {
pagination: { page, limit, total, pages: Math.ceil(total / limit) },
results: rows.map((r) => ({
id: r.id,
checkName: r.checkName,
status: r.status,
expected: r.expected,
actual: r.actual,
message: r.message,
details: r.details,
createdAt: r.createdAt,
exportId: r.exportId,
versionString: r.export.versionString,
exportStatus: r.export.status,
shotCode: r.export.shot.shotCode,
episode: r.export.shot.episode,
})),
};
}
@@ -0,0 +1,5 @@
-- AlterTable: add Netflix slate fields to shots
ALTER TABLE "shots" ADD COLUMN "slateType" TEXT;
ALTER TABLE "shots" ADD COLUMN "slateDescription" TEXT;
ALTER TABLE "shots" ADD COLUMN "slateVfxScope" TEXT;
ALTER TABLE "shots" ADD COLUMN "slateSubmissionNote" TEXT;
@@ -0,0 +1,7 @@
-- Export paths are {outputRoot}/{showId}/[{episode}]/{shotCode}/{version}.
-- A stored "render.outputRoot" of "//SAN/renders" injected a stray "renders/"
-- segment; strip it so the root is just the SAN mount point.
UPDATE "system_config"
SET "value" = regexp_replace("value", '/+renders/*$', '')
WHERE "key" = 'render.outputRoot'
AND "value" ~ '/+renders/*$';
@@ -0,0 +1,110 @@
-- RenderPipeline2 Phase 3 (validation), Phase 4 QC half, Phase 5 (delivery).
-- Purely additive: no existing table is altered, no backfill needed.
-- CreateTable
CREATE TABLE "validation_results" (
"id" TEXT NOT NULL,
"exportId" TEXT NOT NULL,
"renderJobId" TEXT NOT NULL,
"checkName" TEXT NOT NULL,
"status" "ValidationStatus" NOT NULL,
"expected" TEXT,
"actual" TEXT,
"message" TEXT,
"details" JSONB,
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT "validation_results_pkey" PRIMARY KEY ("id")
);
-- CreateTable
CREATE TABLE "qc_reviews" (
"id" TEXT NOT NULL,
"exportId" TEXT NOT NULL,
"result" "QCResult" NOT NULL,
"notes" TEXT,
"reviewedById" TEXT,
"reviewerName" TEXT,
"source" TEXT NOT NULL,
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT "qc_reviews_pkey" PRIMARY KEY ("id")
);
-- CreateTable
CREATE TABLE "delivery_packages" (
"id" TEXT NOT NULL,
"projectId" TEXT NOT NULL,
"episode" TEXT NOT NULL,
"name" TEXT NOT NULL,
"packageNumber" INTEGER NOT NULL,
"status" "DeliveryStatus" NOT NULL DEFAULT 'DRAFT',
"rootPath" TEXT,
"configSnapshot" JSONB NOT NULL,
"manifest" JSONB,
"reportKey" TEXT,
"errorMessage" TEXT,
"createdById" TEXT NOT NULL,
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
"builtAt" TIMESTAMP(3),
"deliveredAt" TIMESTAMP(3),
"deliveredById" TEXT,
CONSTRAINT "delivery_packages_pkey" PRIMARY KEY ("id")
);
-- CreateTable
CREATE TABLE "delivery_items" (
"id" TEXT NOT NULL,
"packageId" TEXT NOT NULL,
"exportId" TEXT NOT NULL,
"shotId" TEXT NOT NULL,
"shotCode" TEXT NOT NULL,
"versionString" TEXT NOT NULL,
"exrPath" TEXT,
"movPath" TEXT,
"fileCount" INTEGER,
"totalBytes" BIGINT,
"checksum" TEXT,
"linkMode" TEXT,
"status" TEXT NOT NULL DEFAULT 'PENDING',
"errorMessage" TEXT,
CONSTRAINT "delivery_items_pkey" PRIMARY KEY ("id")
);
-- CreateIndex
CREATE INDEX "validation_results_exportId_renderJobId_idx" ON "validation_results"("exportId", "renderJobId");
-- CreateIndex
CREATE INDEX "qc_reviews_exportId_idx" ON "qc_reviews"("exportId");
-- CreateIndex
CREATE INDEX "delivery_packages_projectId_episode_idx" ON "delivery_packages"("projectId", "episode");
-- CreateIndex
CREATE INDEX "delivery_packages_status_idx" ON "delivery_packages"("status");
-- CreateIndex
CREATE UNIQUE INDEX "delivery_packages_projectId_packageNumber_key" ON "delivery_packages"("projectId", "packageNumber");
-- CreateIndex
CREATE INDEX "delivery_items_exportId_idx" ON "delivery_items"("exportId");
-- CreateIndex
CREATE UNIQUE INDEX "delivery_items_packageId_exportId_key" ON "delivery_items"("packageId", "exportId");
-- AddForeignKey
ALTER TABLE "validation_results" ADD CONSTRAINT "validation_results_exportId_fkey" FOREIGN KEY ("exportId") REFERENCES "exports"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "qc_reviews" ADD CONSTRAINT "qc_reviews_exportId_fkey" FOREIGN KEY ("exportId") REFERENCES "exports"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "delivery_packages" ADD CONSTRAINT "delivery_packages_projectId_fkey" FOREIGN KEY ("projectId") REFERENCES "projects"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "delivery_items" ADD CONSTRAINT "delivery_items_packageId_fkey" FOREIGN KEY ("packageId") REFERENCES "delivery_packages"("id") ON DELETE CASCADE ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "delivery_items" ADD CONSTRAINT "delivery_items_exportId_fkey" FOREIGN KEY ("exportId") REFERENCES "exports"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
@@ -0,0 +1,23 @@
-- Deployed tool versions, reported by the tools themselves on startup.
-- CreateTable
CREATE TABLE "tool_versions" (
"id" TEXT NOT NULL,
"tool" TEXT NOT NULL,
"machineName" TEXT NOT NULL,
"version" TEXT NOT NULL,
"buildRef" TEXT,
"hostUser" TEXT,
"hostApp" TEXT,
"details" JSONB,
"firstSeenAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
"lastSeenAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT "tool_versions_pkey" PRIMARY KEY ("id")
);
-- CreateIndex
CREATE INDEX "tool_versions_tool_idx" ON "tool_versions"("tool");
-- CreateIndex
CREATE UNIQUE INDEX "tool_versions_tool_machineName_key" ON "tool_versions"("tool", "machineName");
@@ -0,0 +1,5 @@
-- Exports that render EXRs without building a preview, inheriting the previous
-- export's review media (unscaled / un-punched-in deliverables).
-- AlterTable
ALTER TABLE "exports" ADD COLUMN "skipPreview" BOOLEAN NOT NULL DEFAULT false;
@@ -0,0 +1,5 @@
-- Per-production AE workspace config: template AEP, renders root, comp-name
-- overrides. Read by the panel and the headless preview build alike.
-- AlterTable
ALTER TABLE "projects" ADD COLUMN "pipelineConfig" JSONB;
@@ -0,0 +1,12 @@
-- Standalone Blender renders: a queue entry with no Export behind it.
-- AlterEnum
ALTER TYPE "RenderJobType" ADD VALUE 'BLENDER_RENDER';
-- AlterTable
ALTER TABLE "render_jobs" ADD COLUMN "projectId" TEXT;
ALTER TABLE "render_jobs" ADD COLUMN "label" TEXT;
ALTER TABLE "render_jobs" ADD COLUMN "submittedBy" TEXT;
-- CreateIndex
CREATE INDEX "render_jobs_projectId_status_idx" ON "render_jobs"("projectId", "status");
@@ -0,0 +1,6 @@
-- Automated picture-lock handling in the preview build stage: a per-export
-- override to skip it, and a key for the full-duration ungraded reference MP4.
-- AlterTable
ALTER TABLE "exports" ADD COLUMN "noPictureLock" BOOLEAN NOT NULL DEFAULT false;
ALTER TABLE "exports" ADD COLUMN "piclockRefKey" TEXT;
@@ -0,0 +1,9 @@
-- Client naming alias: substituted for shotCode only on slates, overlay
-- burn-ins, and delivered file/folder names. Internal paths, comp names and
-- DB lookups always use shotCode.
-- AlterTable
ALTER TABLE "shots" ADD COLUMN "clientCode" TEXT;
-- AlterTable
ALTER TABLE "delivery_items" ADD COLUMN "clientCode" TEXT;
+161
View File
@@ -149,6 +149,10 @@ enum RenderJobType {
AE_RENDER
PREVIEW_ONLY
DELIVERY_BUILD
/// A standalone Blender render: a queue entry and nothing more. It has no
/// Export, takes no shot version, and is not validated, QC'd or delivered —
/// it is "Ctrl+F12, but on the farm".
BLENDER_RENDER
}
enum ValidationStatus {
@@ -361,6 +365,12 @@ model Project {
/// Per-production delivery naming/layout templates (RenderPipeline2 §11.2);
/// falls back to SystemConfig defaults when null
deliveryConfig Json?
/// Per-production AE workspace: the show's slate/overlay template AEP, its
/// renders root, and any comp names that depart from the {showId}_* naming
/// convention. Read by both the panel and the headless preview build, which
/// is why it lives here rather than in per-machine panel settings.
pipelineConfig Json?
deliveryPackages DeliveryPackage[]
@@map("projects")
}
@@ -382,6 +392,10 @@ model EpisodeDueDate {
model Shot {
id String @id @default(cuid())
shotCode String
/// Client-supplied naming alias, used only for slates, overlay burn-ins,
/// and delivered file/folder names — never for internal paths, comp names
/// or DB lookups, which always use shotCode. Null = use shotCode as today.
clientCode String?
scene String @default("")
episode String?
shotNumber Int @default(0)
@@ -418,6 +432,11 @@ model Shot {
shotVersion String @default("v001")
// Key shot flag — highlighted for prioritisation
isKeyShot Boolean @default(false)
// Netflix slate fields — managed via the Slate tab, used by the preview pipeline
slateType String?
slateDescription String? @db.Text
slateVfxScope String? @db.Text
slateSubmissionNote String? @db.Text
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@ -865,18 +884,38 @@ model Export {
exrTotalBytes BigInt?
checksum String? // sequence-level digest (xxHash of per-file hashes)
/// Full-duration (handles included), ungraded MP4 of just the picture-lock
/// plate — a diagnostic reference to check back against, not a reviewable
/// deliverable, so it lives here rather than as a Version.
piclockRefKey String?
// Slate fields authored per submission (not per shot): they change from one
// delivery to the next, so each Export carries its own and new exports
// default to the previous export's values.
vfxScope String? @db.Text
submissionNote String? @db.Text
/// Render the EXRs but build no preview, inheriting the previous export's
/// review media instead. For an export whose framing differs from the review
/// framing — unscaled or un-punched-in plates — the earlier MOV is the
/// correct preview, and rebuilding it from these EXRs would be wrong.
skipPreview Boolean @default(false)
/// Skip picture-lock trimming and the picture-lock reference render for this
/// export — set when picture lock is missing or wrong for the shot, so the
/// preview build falls back to the untrimmed full render range instead of
/// trimming against bad data.
noPictureLock Boolean @default(false)
submittedById String? // resolved User, else null
submittedByName String? // free text from panel config as fallback
supersededById String? // newer Export that replaced this one
renderJobs RenderJob[]
events ExportEvent[]
validations ValidationResult[]
qcReviews QCReview[]
deliveryItems DeliveryItem[]
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@ -895,6 +934,13 @@ model RenderJob {
exportId String? // set for AE_RENDER / PREVIEW_ONLY
export Export? @relation(fields: [exportId], references: [id])
deliveryId String? // set for DELIVERY_BUILD (Phase 5)
/// Set for jobs that belong to a project but not to a shot — a standalone
/// Blender render. Lets the queue be filtered by production without
/// inventing an Export for work that has no shot.
projectId String?
/// Human label for such a job, since there is no shot code to show.
label String?
submittedBy String? // email/name of whoever queued it
attempt Int @default(1)
maxAttempts Int @default(3)
status RenderJobStatus @default(QUEUED)
@@ -922,6 +968,7 @@ model RenderJob {
@@index([status, priority, createdAt])
@@index([machineId, status])
@@index([projectId, status])
@@map("render_jobs")
}
@@ -979,6 +1026,120 @@ model WorkerHeartbeat {
@@map("worker_heartbeats")
}
/// What version of each studio tool is running where. Written by the tool
/// itself on startup, so it reflects what is *deployed* rather than what
/// someone remembered to write down. One row per (tool, machine).
model ToolVersion {
id String @id @default(cuid())
tool String // "AE_PANEL" | "RENDER_WORKER"
machineName String
version String // "2.1.0"
buildRef String? // git sha / build stamp, when the tool can report one
hostUser String? // artist email, or the worker's service account
hostApp String? // "After Effects 24.6" / OS build
details Json?
firstSeenAt DateTime @default(now())
lastSeenAt DateTime @default(now())
@@unique([tool, machineName])
@@index([tool])
@@map("tool_versions")
}
/// One row per check per validation run, so the UI shows exactly what failed
/// and history survives retries (§5.4).
model ValidationResult {
id String @id @default(cuid())
exportId String
export Export @relation(fields: [exportId], references: [id])
renderJobId String // which attempt produced this run
checkName String // "timecode_plate_match", "missing_frames", ...
status ValidationStatus
expected String?
actual String?
message String?
details Json? // e.g. list of missing frame numbers, or the timecode reference used
createdAt DateTime @default(now())
@@index([exportId, renderJobId])
@@map("validation_results")
}
/// Human technical QC on an Export (§5.5). Multiple rows allowed — the latest
/// is authoritative and drives T13/T14.
model QCReview {
id String @id @default(cuid())
exportId String
export Export @relation(fields: [exportId], references: [id])
result QCResult
notes String? @db.Text
reviewedById String? // resolved User where possible
reviewerName String? // fallback for API-key reviews from the panel
source String // "AE_PANEL" | "WEB"
createdAt DateTime @default(now())
@@index([exportId])
@@map("qc_reviews")
}
/// A dated delivery folder built from READY_FOR_DELIVERY exports (§5.7).
/// Never deleted — a mistaken package is CANCELLED or superseded.
model DeliveryPackage {
id String @id @default(cuid())
projectId String
project Project @relation(fields: [projectId], references: [id])
episode String // "101" — empty string on standard (non-episodic) shows
name String // "260805_Delivery"
packageNumber Int // sequential per project → "Package #15"
status DeliveryStatus @default(DRAFT)
rootPath String? // final path on the delivery volume
configSnapshot Json // naming template + options at build time (immutable record)
manifest Json? // built manifest: files, sizes, checksums
reportKey String? // delivery report in object storage; also written into the folder
errorMessage String?
createdById String
createdAt DateTime @default(now())
builtAt DateTime?
deliveredAt DateTime?
deliveredById String?
items DeliveryItem[]
@@unique([projectId, packageNumber])
@@index([projectId, episode])
@@index([status])
@@map("delivery_packages")
}
/// Version lock: the exact Export delivered. shotCode/versionString are
/// denormalised so a later shot rename or re-render never mutates history.
model DeliveryItem {
id String @id @default(cuid())
packageId String
package DeliveryPackage @relation(fields: [packageId], references: [id], onDelete: Cascade)
exportId String
export Export @relation(fields: [exportId], references: [id])
shotId String
shotCode String
/// Snapshot of Shot.clientCode at package build time — same immutability
/// rule as shotCode/versionString: a later shot edit must not retroactively
/// change already-built delivery history.
clientCode String?
versionString String
exrPath String? // path inside the package
movPath String?
fileCount Int?
totalBytes BigInt?
checksum String?
linkMode String? // "hardlink" | "copy" — what the builder actually did
status String @default("PENDING") // PENDING | COPIED | VERIFIED | FAILED
errorMessage String?
@@unique([packageId, exportId])
@@index([exportId])
@@map("delivery_items")
}
model SketchTemplate {
id String @id @default(cuid())
name String
+7
View File
@@ -148,6 +148,8 @@ export interface VersionWithDetails {
export interface ShotWithDetails {
id: string;
shotCode: string;
/** Client-supplied naming alias — slates/overlays/delivery only, never internal paths. */
clientCode: string | null;
scene: string;
episode: string | null;
shotNumber: number;
@@ -181,6 +183,11 @@ export interface ShotWithDetails {
highResFilename: string | null;
// Shot-level version tracking
shotVersion: string;
// Netflix slate fields
slateType: string | null;
slateDescription: string | null;
slateVfxScope: string | null;
slateSubmissionNote: string | null;
shotGroup: { id: string; name: string } | null;
footagePlates: {
id: string;