38 Commits

Author SHA1 Message Date
twotalesanimation 59af7959e6 fix(connector): request the full QC queue instead of the default 50
Deploy / deploy (push) Successful in 6m41s
loadQCQueue called /api/ext/qc/queue with no limit, so it always got the
endpoint's default page of 50. The query orders oldest-first, so a project
with more than 50 exports in READY_FOR_QC showed only the oldest 50 with
nothing to say the list was short.

Ask for 200 — the server's hard ceiling in getQCQueue — and say so in the
status line when the count comes back at the cap, so a truncated queue is
visible rather than silent.

The diagnostics call in checkServerPathReachable stays on the default: it
only reads entries[0].

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-01 07:24:21 +02:00
twotalesanimation a6ee1917e7 fix(connector): cancel the export poll when the panel closes or reloads
Deploy / deploy (push) Successful in 6m46s
app.scheduleTask outlives the panel instance that armed it. The repeating task
id was held in the pipelineState closure, so closing or reloading the panel took
the id with it and left nothing able to cancel the task: it kept firing every
15 s for the rest of the AE session, and every tick landing while a modal dialog
was open raised "Cannot run a script while a modal dialog is waiting for
response."

The id now lives in global scope beside the tick function that scheduleTask
already evaluates there, so the next panel instance can still reach it.
getPollTaskId and setPollTaskId wrap the access and treat anything that is not a
positive number as no task. Panel startup cancels whatever a previous instance
left armed before pointing the tick at itself, rather than letting the old task
fire into a fresh, empty state whose shot code went with the closure that armed
it, and panel.onClose stops the poll on the way out.

The export is unaffected either way: it runs on the farm, and the header picks
its status back up from the server on the next Refresh. Section 12.1 of
RenderPipeline2.md records that.

PANEL_VERSION goes to 2.6.1 per the documented rule, so Pipeline → Machines does
not show two workstations on one version behaving differently.

This change was authored in the working tree, not by Claude; it is committed
here alongside the status and client-portal work at the author's request, and
the message was written from reading the diff. It has not been exercised in a
live After Effects session as part of this commit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-31 18:18:08 +02:00
twotalesanimation 28e8c47907 feat(client-portal): let a reviewer edit and delete their own notes
Notes left through a review link were write-once. A client who mistyped a
timecode or changed their mind had no way to correct it and had to add a second
note contradicting the first, which the studio then had to reconcile by hand.

PATCH and DELETE on comment/[commentId] cover both. Only the reviewer's own
notes are touchable: the studio's comments and those of every other review
session are read-only through a link, whatever the holder sends. Ownership is
re-checked server-side on every write, so the canEdit flag now returned by the
versions route only decides whether to offer the controls and grants nothing.

Refusals are 404 rather than 403 throughout, since a link holder has no business
learning which comment ids exist outside their own notes.

Only the text is editable. The frame a note is pinned to is what the studio
works from, so moving it would silently repoint feedback someone may already
have actioned; a note about a different frame is a new note. Deleting a drawing
note also removes its strokes, mirroring deleteComment in actions/comments.ts,
and the page reloads the player afterwards so the frame does not keep showing
marks that no longer exist. Delete goes through a confirmation that shows the
note and says plainly that it disappears for the studio too.

Worth knowing before this reaches a show: everyone holding the same review link
is the same author. A ReviewSession with no email resolves to a token-derived
guest user, so one link sent to three people gives all three one identity and
any of them can now edit or delete the others' notes. That model is not new,
which is why their comments already showed as one name, but edit and delete is
the first feature where it grants real power rather than muddling attribution.
Per-reviewer links with email set are the fix if that is not wanted, and that is
a change to how links are issued rather than to this code. The scope is
documented on reviewClientEmail so the next reader meets it before it surprises
them.

getOrCreateClientUser was copy-pasted into the comment and approve routes with
the fallback-email expression spelled out in three places. It is one set of
helpers in review-auth.ts now, including findReviewUser, a read-only variant so
that merely opening a review link does not conjure a User row just to answer
"is this theirs?", and ownsComment, the single rule shared by the route that
offers the controls and the route that enforces them.

Nine tests cover that rule directly: internal users' notes stay read-only, a
session that has never posted owns nothing, and an authorless comment — one
whose User was deleted, since Comment.authorId is SetNull — cannot be claimed by
anyone. The routes themselves are not covered, so exercise edit and delete
against a real review link before handing one to a client.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-31 18:17:40 +02:00
twotalesanimation 94792279c5 fix(status): reset review state on a new version, and derive shot status everywhere
Requesting changes on a shot and then re-rendering it through the render queue
left every layer of the app still showing the old verdict. Three independent
causes, all on the pipeline path.

finalizePreview inherited the superseded version's approvalStatus
unconditionally. The carry-over exists so a re-export of a signed-off shot does
not reappear as awaiting review, but it applied equally to NEEDS_CHANGES and
REJECTED, so the render queued to address a note arrived already wearing that
note and nothing registered that the work had been redone. carryApproval now
carries only APPROVED.

The pipeline never moved the task. One left on CHANGES by a review or a QC fail
stayed there through every re-render, with no way out but a manual kanban drag.
A genuinely new version now moves it to INTERNAL_REVIEW, as actions/versions.ts
and batch-upload already did. A replaced version is excluded: regeneratePreview
re-delivers the same version after a slate fix and is not a new submission.

The pipeline never called recalcShotStatus at all, so shot boards went stale the
moment a render changed a task. finalizePreview and the QC fail path both
recalculate now; the latter already documented the REVISIONS derivation it was
relying on and never triggering.

Shot.status is derived from tasks and approval flags, but six call sites wrote
it directly with the status they expected: internallyApproveShot,
shareWithClient, unshareFromClient, clientApproveShot, unapproveShot and the
client approve route. Rule 1 of the derivation is that any CHANGES task outranks
an approval, so a shot could be pushed past open rework and then snap back to
REVISIONS on the next unrelated recalc, which is close to unreportable as a bug.
They now set the approval inputs and let recalcShotStatus derive.
unshareFromClient additionally hardcoded READY_FOR_CLIENT even for a
client-approved shot. updateShotStatus keeps its direct write as the deliberate
manual override, now documented as transient for the same reason.

markShotForRevisions replaces the duplicated change-request logic. Both copies
marked all non-DONE tasks CHANGES, which matches nothing on the shot this is
most often called for: one out for client review precisely because all its tasks
are finished. The request then derived to INTERNAL_REVIEW and had no visible
effect anywhere. When nothing is picked up it now reopens the task behind the
shot's latest version, which is the deliverable the reviewer was looking at.

A client's shot-level change request also marks the versions and writes Approval
rows now. The dashboard counters, the version badges and the portal's own
filters all read Version.approvalStatus, so a shot-level verdict was invisible
everywhere those look.

clearStaleShotApproval covers the reverse case: uploading a new version onto an
approved shot moved the task to INTERNAL_REVIEW and changed nothing visible,
because the derivation short-circuits on shotApprovalStatus. The shot kept
reading COMPLETE while carrying work nobody had looked at. This is the one
user-visible behaviour change here, so watch the boards on a live show: an
approved shot now drops back to INTERNAL_REVIEW on a new upload. sharedWithClient
is deliberately left alone, since revoking client access stays a separate act.

submitApproval and unapproveVersion are transactional now. The verdict, the
version, the task and the derived shot status are one decision, and a failure
partway through left the three layers disagreeing with no way to tell which one
was right.

KanbanCard compared approvalStatus against "CHANGES_REQUESTED", which is not a
member of the enum, so the changes-requested icon never rendered at all.

Thirteen tests cover carryApproval, markShotForRevisions including the all-DONE
regression, and clearStaleShotApproval. What is not covered is the pipeline
transaction itself, which needs a database: queue a render against a shot in
REVISIONS and confirm the task and shot both move before trusting this on a
show.

Version.reviewStatus is still written nowhere while being published through
ext/shots/lookup and EXT_API_REFERENCE.md as a permanent "PENDING". Left alone
deliberately: removing a field from that contract could break the connector.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-31 18:17:04 +02:00
twotalesanimation 93137cdcd2 fix(connector): anchor built comps on the plate's own EXR timecode
Build Shot produced comps starting at 00:00:00:00 because the panel never
actually read the EXR timecode. getFootageStartFrames ranked a fragile "New
Comp from Selection" probe first: it toggles the Project panel via the Window
menu to get focus, and where that does not land the menu item is greyed out,
executeCommand silently does nothing, and the probe returns null. A shot with
no timecodeStart then fell through the API rank to zero.

The worker already reads EXR headers properly in ExrHeader.cs, and its
validation ranks the plate's own timeCode above the API value, which stores the
editorial in-point and sits a handle-length ahead of the plate by design. Shots
were therefore being built from rank 3 and validated against rank 1. That is a
timecode desync waiting to reach a delivery, not just a cosmetic start frame.

readExrTimecode ports the worker's reader to ExtendScript and becomes rank 1:
one short header read, walking `name\0 type\0 int32 size data` for timeCode and
falling back to timeCodeString where a writer omitted the packed attribute.
decodePackedTimecode mirrors Timecode.FromPacked, decoding the SMPTE 12M BCD a
byte at a time so the arithmetic never touches the sign bit. The menu probe is
kept as rank 2 and now runs only when the plate carries no timecode at all, so
the Project-panel toggle is off the normal path.

setCompStartFrame was the second failure. Assigning displayStartFrame on a
version of AE that does not have the property is ignored silently rather than
throwing, so the early return skipped the displayStartTime fallback entirely.
It now reads the value back, falls through when it did not take, and returns
whether anything stuck; buildShotFromCode logs when nothing does. A start frame
that cannot be set is now visible in the diagnostics report instead of a comp
quietly sitting at zero.

A plate whose timecode is present but zero still falls through to the API rank,
keeping the existing frames > 0 convention so the safety net survives. If a
genuine 00:00:00:00 plate should win outright that is a deliberate follow-up.

The parser is covered against synthetic headers, including the 0x18585712
example documented in ExrHeader.cs, drop-frame, truncated and non-EXR input.
What is not yet exercised in a live After Effects session is mainSource.file
resolving to the sequence's first frame and displayStartFrame taking on a given
AE build, so build one shot and check its start against the plate before
relying on this. Picture-lock automation was reverted for a timecode desync of
the same shape.

PANEL_VERSION goes to 2.6.0 per the documented rule, so Pipeline → Machines
does not show two workstations on one version behaving differently. The
startSource comment in the manifest schema enumerated only the two older
values; the queue-time provenance check keys on /\bAPI\b/ and so already reads
"EXR timecode …" as trustworthy rather than suspect.

The same silent-failure setCompStartFrame still exists in the farm-side
vfxr_build_preview.jsx, which is fed the right value from the manifest but can
drop it the same way. Left for its own change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-29 16:53:49 +02:00
twotalesanimation 6678721fb1 fix(pipeline): create the comp task an export needs when a shot has none
Deploy / deploy (push) Successful in 6m48s
A shot with no COMP task rendered and previewed fine and then showed
nothing in the app. createExport set Export.taskId from the shot's first
COMP task or null, and finalizePreview registered the review Version with
that same null taskId — so the MP4 was uploaded and stored, but the
Version hung off no task and none of the review flows had anywhere to
draw it. From the artist's side the export completed and produced
nothing.

E1 now resolves the shot's comp task inside the version-allocation
transaction and creates one when there isn't any, titled after the
preview file the export will produce: {shotCode}_cmp_TT_{version}, the
same convention the manual batch upload's create-task path already uses.

renderOutputBase() is exported and buildPreviewManifest takes its `base`
from it, so the task title and the MOV/MP4 name come from one function
rather than two copies of the same template. The title therefore already
carries the version, which makes finalizePreview's rename-to-the-
delivered-version a no-op on that first export rather than an immediate
rename of a task created moments earlier.

The lookup and the create sit inside the transaction so the P2002
version-collision retry rolls a losing attempt's task back with
everything else, instead of leaving a duplicate behind.

recalcShotStatus runs only when a task was actually created: a shot with
no tasks derives WAITING and now has one. Approval-driven statuses still
take precedence, so an already-approved shot stays COMPLETE.

Both the queue-time ExportEvent note and the E1 response record what
happened, so a task appearing under a shot on its own is traceable to the
export that made it.

Exports already in flight with a null taskId keep their orphaned
versions; backfilling those is a separate migration.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-28 14:09:01 +02:00
twotalesanimation bac525ddd0 feat(shot-status): shot version beside the name, and a scaled-in-edit flag
Deploy / deploy (push) Successful in 7m28s
Two small board additions.

The shot version now shows next to the shot code. It is Shot.shotVersion —
the value the AE panel burns into overlays and queueExport renders under,
and the one the shot detail page edits — not a count of uploaded review
Versions, so the board agrees with what the artist has in the panel.

Shot.isScaled records that a shot is scaled in the edit: the plate is not
used at its native size, which changes how the shot is comped and
reviewed. That makes it a standing property of the shot rather than
something buried in the notes, so it is flagged the way isKeyShot is — a
cyan pill next to the shot name, and a Scaled toggle column beside Key.
toggleScaledShot() (actions/shots.ts) mirrors toggleKeyShot, same roles.

KeyShotToggle's switch markup would have been duplicated verbatim for the
second flag, so both now sit on a shared FlagToggle taking a colour tone
and a setter. The key-shot switch behaves exactly as before, optimistic
update and rollback included.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-28 09:57:05 +02:00
twotalesanimation 7f066c1372 feat(pipeline): MOV review delivery packages from selected shots
Deploy / deploy (push) Successful in 7m28s
A formal review is shared as a flat, dated folder of the preview MOVs —
{deliveryRoot}/PRODUCER_REVIEWS/20260828_Producer_review, then _02, _03
for further reviews the same day. It reuses the delivery package's
machinery end to end: DeliveryPackage/DeliveryItem, the DELIVERY_BUILD
job, the same claim path and the same hardlink-or-copy builder, with
DeliveryPackage.kind telling the two apart.

Three things separate a review from a delivery:

A review never advances an Export. Reviews happen throughout a shot's
life, long before QC passes it, and the same version is routinely shown
twice — so nothing is marked PACKAGED, and markDelivered() refuses a
review package outright (the button is hidden too).

Selection is by shot, not by export. Shot Status → Bulk Actions → Build
MOV Review Package; the server resolves each shot to its newest export
that actually has a deliveryMovPath, which is not always its newest
export — a shot whose latest version is still rendering belongs in the
review as the version that can be watched. Shots with no MOV at all are
listed in the confirm dialog with the reason rather than silently
shrinking the folder.

The folder is exactly the MOVs. No CSV, no manifest.json written beside
them; the manifest still returns to the server, so the record of what was
shared is kept without cluttering the share. Names follow the same
client-naming rule as a delivery, so a shot reads identically in a review
folder and in the delivery that follows it.

Verification (DeliveryStage.BuildReviewItem) is proportional as it is for
EXRs, adapted to a single file with no validation-time digest: a hard
link is the source and needs nothing, a copy is checked against its
source by length always and by full hash under "always-hash". A missing
MOV fails the item here — in an EXR delivery the MOV is a viewing copy
beside the real deliverable, but in a review it is the deliverable, and a
review folder quietly one shot short is worse than one that says so.

Worker bumped to 1.6.0 for the new manifest field (DeliveryManifest.Kind).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-28 08:58:21 +02:00
twotalesanimation ed9f9b13c1 feat(client-portal): show shots and task titles in the client's own naming
Deploy / deploy (push) Successful in 6m8s
Shot.clientCode already drove slates, overlay burn-ins and delivered file
names, but the client portal — the one place the client actually reads — was
still showing our internal codes.

Task titles were the larger leak. They follow the house convention
"UNG_106_010_020_cmp_TT_v004", so the internal code sat embedded in the
string the client reads and copies, in three places on the shot list and
again in the player header. Swapping only the heading would have left it on
display directly underneath.

lib/shot-code.ts resolves both: clientShotCode picks the alias when set, and
clientTaskTitle swaps the code out of a title by substring, leaving a
hand-edited title that does not carry the code untouched rather than guessing
at it.

Applied at the API boundary rather than at each render site, so the shot
list, search, playlist labels, alt text, player header and every
copy-to-clipboard button inherit it and nothing downstream has to remember
which code it is holding. The internal code is no longer sent to the browser
on these routes at all.

Slack notifications deliberately keep the internal code: those go to our
artists, who need the code that matches the comp and the SAN path.

The two existing "clientCode || shotCode" expressions in preview.ts and
deliveries.ts now use the same helper so slates, deliveries and the portal
cannot drift apart. Shots with no clientCode are unchanged throughout.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-27 23:16:53 +02:00
twotalesanimation 1fad6a739d fix(worker): drain ffmpeg's pipes so thumbnail generation stops deadlocking
Deploy / deploy (push) Successful in 9m16s
ffmpeg was started with stdout and stderr redirected and neither pipe ever
read. Windows gives an anonymous pipe a ~4 KB buffer, which ffmpeg's banner
and stream summary exceed on their own, so it blocked forever on the write,
never exited, and the two-minute cap fired:

    TaskCanceledException at Process.WaitForExitAsync
    Preview complete for job ... in 221s (mov + mp4)

The exception was swallowed as "non-fatal", so every preview silently
produced no thumbnail while paying 120s for the privilege. Nothing
downstream was wrong — there was simply never a thumbnail to promote.

Both pipes are now drained concurrently before the wait. A timeout kills the
process tree rather than leaking an ffmpeg per job, and attempts report a
three-way outcome so a hung or unstartable ffmpeg is not retried — without
that, the slate fallback would have doubled the wasted time to four minutes.

Failures are no longer silent: an unset or missing ffmpegPath, the seek that
was chosen, and ffmpeg's own exit code, command and stderr are all logged.

finalizePreview likewise records every promotion outcome on the export
timeline, not just success. Silence there was indistinguishable from a broken
worker, a project whose flag never saved, and the feature working as
configured — which is what made this take so long to find.

Adds scripts/diagnose-thumbnails.mjs, which walks the chain (ffmpeg →
Export.thumbnailKey → project flag → Shot.generatedThumbnailUrl → what the UI
resolves) and names the first broken link.

Worker 1.5.1 -> 1.5.2; republish required for the fix to take effect.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-27 22:48:29 +02:00
twotalesanimation 9cd7b0df6e chore: retrigger deploy
Deploy / deploy (push) Successful in 5s
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-27 17:23:42 +02:00
twotalesanimation caaa333f02 feat(pipeline): render-derived shot thumbnails, and bulk shot delete
Deploy / deploy (push) Failing after 19m11s
Two independent features landing together:

Generated shot thumbnails — a shot can now carry a thumbnail promoted
from a render export (Shot.generatedThumbnailUrl/generatedThumbnailFrom)
alongside the existing brief-supplied thumbnailUrl, which always takes
display precedence (lib/shot-thumbnail.ts) so a promoted frame can only
ever fill a gap, never overwrite the brief. Shows with
pipelineConfig.autoShotThumbnail promote automatically on every
finished export (lib/render-pipeline/preview.ts); promoteExportThumbnail/
clearGeneratedThumbnail (actions/shots.ts) are the manual equivalent for
everyone else. Worker-side seek logic for picking the promoted frame is
covered by RenderWorker/VFXReviewWorker.Tests/ThumbnailSeekTests.cs.

Bulk shot delete — the shot-status page's selection bar gets a "Bulk
Actions" dropdown (alongside the existing Change Due Date) with Delete
Shots. bulkDeleteShots() (actions/shots.ts) deletes one at a time rather
than in a single statement: exports_shotId_fkey is ON DELETE RESTRICT
by design, so a shot with renders or deliveries on record is protected
and gets skipped and reported by name rather than aborting the whole
selection or being silently destroyed along with its history.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-27 17:06:55 +02:00
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
111 changed files with 7839 additions and 505 deletions
+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()
+310
View File
@@ -0,0 +1,310 @@
# Delivery Packages — Workflow Guide
How a finished shot becomes a dated folder ready to upload to the client.
There are two kinds of package. An **EXR delivery** is the shippable one and is
what most of this guide describes. A **MOV review** is a flat folder of preview
MOVs shared for a formal review — see
[MOV review packages](#mov-review-packages) at the end.
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.
---
## MOV review packages
For a formal review you share the preview MOVs, not the EXRs. That is its own
kind of package, built the same way and listed on the same page.
### Building one
**Shot Status**, tick the shots, then **Bulk Actions → Build MOV Review
Package**. A dialog shows exactly what would be built before anything happens:
the folder name, the version each shot contributes, and any shots being left
out. Requires **admin, producer or supervisor**.
The version each shot contributes is its **newest export that actually has a
preview MOV** — not necessarily its newest export. A shot whose latest version
is still rendering goes into the review as the version that can be watched.
A shot with no MOV at all is listed as left out, with the reason, rather than
quietly reducing the folder.
### What lands on disk
```
{deliveryRoot}/PRODUCER_REVIEWS/20260828_Producer_review/
├── EP6_VFX_012_v004.mov
├── EP6_VFX_013_v002.mov
└── UNG_106_010_040_cmp_TT_v001.mov
```
Flat — the MOVs sit beside each other so they can be scrubbed through in order.
Names follow the same client-naming rule as a delivery: the production's own
code where it has one, ours where it does not, so a shot reads identically in a
review folder and in the delivery that follows it.
The folder is **exactly the MOVs**: no CSV, no `manifest.json` beside them. The
manifest still goes back to the app, so the record of what was shared is kept
without cluttering the share.
Second review the same day is `20260828_Producer_review_02`, then `_03`. A
number is never reused, even if the package that took it was cancelled.
### What it does not do
**A review never moves a shot along.** Reviews happen throughout a shot's life,
long before QC passes it, and the same version is routinely shown twice — so
building one changes nothing about the exports in it, and there is no
**Mark delivered** on a review package. Shots stay exactly where they are in
the pipeline.
A **missing MOV fails the package** here, unlike in an EXR delivery where a
missing MOV is logged and the build continues. In a review the MOV is the
deliverable, and a review folder quietly one shot short is worse than one that
says so.
### Configuration
Two more keys in the same `deliveryConfig` (§11.6):
```json
{
"reviewNameTemplate": "{yyyymmdd}_Producer_review",
"layout": {
"reviewDir": "{deliveryRoot}/PRODUCER_REVIEWS/{packageName}"
}
}
```
+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
+88 -5
View File
@@ -207,7 +207,7 @@ stateDiagram-v2
| T9 | VALIDATION_FAILED | QUEUED | Retry (full re-render) | User | new attempt; old validation rows kept for history |
| T10 | GENERATING_PREVIEW | PREVIEW_FAILED | ffmpeg/upload failure | Worker | error stored |
| T11 | PREVIEW_FAILED | GENERATING_PREVIEW | Retry preview | User | validation is NOT re-run |
| T12 | GENERATING_PREVIEW | READY_FOR_QC | `finalize` report | Worker | `Version` row created (isLatest, **never client-shared**), thumbnail set, metadata JSON key stored; **no task/shot status change** — QC typically runs on already client-approved shots and must not disturb review state (Section 10) |
| T12 | GENERATING_PREVIEW | READY_FOR_QC | `finalize` report | Worker | `Version` row created (isLatest, **never client-shared**), thumbnail set, metadata JSON key stored; `Shot.generatedThumbnailUrl` set when the project opts in (§9.1a) — never `Shot.thumbnailUrl`; **no task/shot status change** — QC typically runs on already client-approved shots and must not disturb review state (Section 10) |
| T13 | READY_FOR_QC | QC_FAILED | `POST .../qc {FAIL}` | Artist (AE) or user (web) | `QCReview` row; task → CHANGES (drives existing Shot REVISIONS derivation) |
| T14 | READY_FOR_QC | READY_FOR_DELIVERY | `POST .../qc {PASS}` | Artist / user | `QCReview` row |
| T15 | READY_FOR_DELIVERY | PACKAGED | Delivery build completes | Worker | `DeliveryItem` links Export to package |
@@ -268,6 +268,9 @@ model Export {
shot Shot @relation(fields: [shotId], references: [id])
projectId String
taskId String? // comp task the preview Version attaches to
// (E1 creates one named after the preview file
// when the shot has none, so the preview lands
// somewhere the app shows it)
versionId String? // preview Version created at READY_FOR_QC
versionNumber Int // 4
versionString String // "v004"
@@ -448,6 +451,7 @@ model DeliveryPackage {
projectId String
episode String // "101"
name String // "260805_Delivery" (per 18.1-Q6 convention)
kind DeliveryKind @default(EXR_DELIVERY) // EXR_DELIVERY | MOV_REVIEW (§11.6)
packageNumber Int // sequential per project → "Package #15"
status DeliveryStatus @default(DRAFT)
rootPath String? // final path on delivery volume
@@ -464,6 +468,7 @@ model DeliveryPackage {
@@unique([projectId, packageNumber])
@@index([projectId, episode])
@@index([projectId, kind])
}
model DeliveryItem {
@@ -488,6 +493,8 @@ model DeliveryItem {
**Version locking:** the package references `Export` rows, and items denormalise `shotCode`/`versionString` at creation. Later re-renders of a shot never mutate a package — delivery history is immutable by construction.
**`kind`** distinguishes a shippable EXR delivery from a MOV review folder (§11.6). Both use these two models and the same `DELIVERY_BUILD` job; only a review leaves `exrPath` null, and only a delivery advances its exports to PACKAGED/DELIVERED.
### 5.8 Changes to existing models (additive only)
| Model | Addition | Purpose |
@@ -603,7 +610,8 @@ The server validates the manifest with Zod, cross-checks `shotId`/`shotCode`/fra
**`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 element the comp's start time was anchored to (the panel's `primaryFootage`: longest duration, first on tie). A shot's elements routinely carry unrelated camera timecodes, so "the plate" must be named explicitly rather than guessed by the worker.
- `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.
@@ -1032,11 +1040,21 @@ Runs on the worker immediately after a successful render (Export = VALIDATING).
| `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_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` rational + drop-frame flag on render vs timing plate vs manifest `fps` | any disagreement |
| `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.
@@ -1075,6 +1093,7 @@ The offset term matters — a shot may render a sub-range of a long plate (obser
- 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).
---
@@ -1088,18 +1107,36 @@ Runs on the worker after validation passes (Export = GENERATING_PREVIEW).
### 9.1 Stages
1. **Build + render preview comp (AE, headless).** The worker launches `AfterFX.com -noui -r vfxr_build_preview.jsx`, passing a job-context JSON file (manifest + slate/overlay fields fetched from E3). The script is the connector's existing preview-comp code, packaged with the worker: it imports the *validated* EXR sequence, builds the preview comp from the studio template (head slate populated from API data, overlays/burn-ins throughout), applies the colour chain (linear → log → show LUT from `colorPipeline` config), queues it with the project's MOV output-module template, and renders the **delivery-grade preview MOV** to the SAN beside the EXRs (`Export.deliveryMovPath`). This is the "MOV LT Preview" that ships inside delivery packages (Section 11).
2. **Web transcode (ffmpeg).** The delivery MOV is transcoded to a web-playable H.264 (1920-wide, CRF 18) and a thumbnail JPEG (frame at 25% duration, 960-wide), uploaded via E20 presign.
2. **Web transcode (ffmpeg).** The delivery MOV is transcoded to a web-playable H.264 (1920-wide, CRF 18) and a thumbnail JPEG (960-wide), uploaded via E20 presign. The thumbnail is taken at **25% of *picture* duration**, seeking past the head slate: the build script reports the SHOT layer's in-point as `pictureStartSeconds`, and the worker seeks to `pictureStart + 25%`. Builds that report no picture start fall back to scanning the whole file. (Until 2026-08-27 this used ffmpeg's `thumbnail` filter, which only considers the first 100 frames — on a slated preview, the slate card. Every thumbnail produced before then is a picture of the slate.)
3. **Metadata JSON.** Worker-composed (manifest + validation summary + render stats + checksums + tool/template versions), uploaded via E20.
| Artifact | Produced by | Destination |
|---|---|---|
| Delivery MOV (slate + burn-ins, graded via show LUT, delivery codec from AE output template) | AE headless render | SAN → `Export.deliveryMovPath`; copied/linked into delivery packages |
| Web preview MOV (H.264) | ffmpeg transcode of the delivery MOV | object storage `videos/` → `Version.fileUrl` |
| Thumbnail | ffmpeg | `image/` → `Version.thumbnailUrl` + `Export.thumbnailKey` |
| Thumbnail | ffmpeg | `image/` → `Version.thumbnailUrl` + `Export.thumbnailKey`; also `Shot.generatedThumbnailUrl` when the project opts in (§9.3) |
| Metadata JSON | worker | `renders/` → `Export.metadataKey` |
Because the web preview is a transcode of the AE-generated MOV, review media and delivery media are guaranteed to show identical slates, burn-ins, and colour — one source of truth.
### 9.1a Render frames as shot thumbnails
Shots carry two stills, in two columns, and the distinction is the whole design:
| Column | Written by | Meaning |
|---|---|---|
| `Shot.thumbnailUrl` | humans only — single upload, batch upload, ext API | The reference frame that came with the brief. Editorial data. |
| `Shot.generatedThumbnailUrl` | the pipeline, and the manual promote action | A frame lifted from a finished export. |
Display resolution is `thumbnailUrl ?? generatedThumbnailUrl` (`lib/shot-thumbnail.ts`), applied at every shot surface: shot grid, kanban, schedule, shot status, storyboard (screen and PDF), shoot log, slate tab, client portal, and the ext APIs the Nuke/AE panel reads. **The reference always wins**, so the pipeline can only fill a gap and can never overwrite the brief — clearing the generated one always falls back.
Promotion happens two ways:
* **Automatically**, for projects with `pipelineConfig.autoShotThumbnail` set (Project Settings → *Use render frames as shot thumbnails*). Off by default and deliberately per-show: productions that ship a still with every shot already have a reference frame and the renders should not compete with it. It exists for shows that arrive with no stills at all, where the alternative is an empty grid. `finalizePreview` writes the column and notes it on the export timeline.
* **By hand**, via `promoteExportThumbnail` / `clearGeneratedThumbnail` (Shot Settings → Thumbnail → *From renders*), which work regardless of the project flag — one shot on an otherwise hands-off show. With no explicit export, the newest export of that shot that has a thumbnail is used.
Note this is the one place a render-derived artifact reaches the client portal. It is a still, not a `Version`, so §10.0 is intact — no technical render re-enters the review flow and no approval state moves — but a client viewing a shot with no supplied still now sees a frame from the render rather than a placeholder.
### 9.2 Colour configuration
`Project.deliveryConfig.colorPipeline` (per 18.1-Q4/Q12) — **required and unique per project**; enabling the pipeline on a project without it is a validation error, and values must never be carried over from another show:
@@ -1120,6 +1157,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
@@ -1198,6 +1255,27 @@ Tokens: `{showId} {episode} {yymmdd} {yyyymmdd} {packageName} {packageDir} {shot
The Delivery Packages page (Section 13) lists every package permanently: `#15 · 101/260805_Delivery · Episode 101 · 18 shots · built 2026-08-05 · delivered 2026-08-05 by Chris`, expandable to items → Export → full render/validation/QC history. Packages are never deleted; a mistaken package is CANCELLED (DRAFT/QUEUED/FAILED only) or superseded by building a new one.
### 11.6 MOV review packages (`DeliveryPackage.kind = MOV_REVIEW`)
A formal review is shared as a flat, dated folder of the preview MOVs — the same package/job/verification machinery as §11.1–11.5, a different shape on disk:
```
{deliveryRoot}/PRODUCER_REVIEWS/20260828_Producer_review/
├── EP6_VFX_012_v004.mov ← client naming where the production supplies it
├── EP6_VFX_013_v002.mov
└── UNG_106_010_040_cmp_TT_v001.mov ← ours where it does not
```
The second review that day is `_02`, the third `_03`; the first carries no suffix. Numbering counts every package built under that base — cancelled and failed ones included — so a number is never reused for a different folder. Config: `reviewNameTemplate` (default `{yyyymmdd}_Producer_review`) and `layout.reviewDir` (default `{deliveryRoot}/PRODUCER_REVIEWS/{packageName}`).
Three rules separate a review from a delivery:
- **It never advances an Export.** Reviews happen throughout a shot's life, long before QC passes it, and the same version is routinely shown twice. Nothing is marked PACKAGED or DELIVERED when the folder is built, and `Mark delivered` is refused on a review package.
- **Selection is by shot, not by export.** The user picks shots on Shot Status → *Bulk Actions → Build MOV Review Package*; the server resolves each to its **newest export that actually has a `deliveryMovPath`** — not necessarily its newest export, since a shot whose latest version is still rendering should go into the review as the version that can be watched. Shots with no MOV at all are listed in the confirm dialog and left out rather than silently dropped.
- **The folder is exactly the MOVs.** No CSV, no `manifest.json` written beside them. The manifest still returns to the server, so the record of what was shared is kept without cluttering the share.
Verification is proportional as in §11.3, adapted to a single file with no validation-time digest: a hard link is the source and needs nothing; a copy is checked against its source by length always, and by full hash under `"verifyMode": "always-hash"`. A missing MOV **fails the item** here — in an EXR delivery the MOV is a viewing copy beside the real deliverable, but in a review it *is* the deliverable, and a review folder quietly one shot short is worse than one that says so.
---
## 12. AE Panel Changes
@@ -1214,6 +1292,11 @@ The panel keeps all existing capabilities (episode/shot discovery, overlays, pic
| Latest Export + QC status | new E2 `exports/latest` — e.g. `v004 — READY_FOR_QC`, `v004 — RENDERING 42% (ETA 1:36 on RENDER-01)`, `v003 — QC FAILED: "grain mismatch"` |
While an export is active the panel polls E2 every 15 s to live-update the header.
The poll stops when the export leaves an active status, and also when the panel is
closed or reloaded — `app.scheduleTask` outlives the panel instance that armed it,
so the task id is kept in ExtendScript global scope where the next instance can
still cancel it. The export is unaffected either way: it runs on the farm, and the
header picks its status back up on the next Refresh.
### 12.2 Buttons and their API calls
+36
View File
@@ -89,6 +89,41 @@ 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
@@ -156,6 +191,7 @@ 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:/" }
@@ -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;
}
}
@@ -123,17 +123,80 @@ public class DeliveryStageTests : IDisposable
}
[Fact]
public async Task ChecksumMismatchFailsTheItem()
public async Task ChecksumMismatchFailsACopiedItem()
{
WriteFrames(3);
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" },
Manifest(checksum: "deadbeefdeadbeef"), "machine1", CancellationToken.None, CancellationToken.None);
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()
{
@@ -163,15 +226,116 @@ public class DeliveryStageTests : IDisposable
public async Task ChecksumMatchesTheValidationTimeDigestForIdenticalContent()
{
WriteFrames(3);
var first = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, Manifest(), "machine1",
CancellationToken.None, CancellationToken.None);
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.
// 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), "machine1", CancellationToken.None, CancellationToken.None);
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")));
}
}
@@ -100,7 +100,13 @@ public class ExrHeaderTests
[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));
@@ -0,0 +1,193 @@
using Microsoft.Extensions.Logging.Abstractions;
using VFXReviewWorker;
using Xunit;
namespace VFXReviewWorker.Tests;
/// <summary>
/// MOV review packages (RenderPipeline2 §11.6). A review folder is opened
/// directly by a producer, so the things pinned here are the ones they would
/// notice: it is flat, it carries the client's own naming, and it contains the
/// MOVs and nothing else.
/// </summary>
public class MovReviewStageTests : IDisposable
{
private readonly string _root = Path.Combine(Path.GetTempPath(), $"vfxr_review_{Guid.NewGuid():N}");
private readonly string _renderDir;
private readonly string _reviewDir;
public MovReviewStageTests()
{
_renderDir = Path.Combine(_root, "renders", "SHOT_001", "v004");
_reviewDir = Path.Combine(_root, "DELIVERY", "PRODUCER_REVIEWS", "20260828_Producer_review");
Directory.CreateDirectory(_renderDir);
}
public void Dispose()
{
try { Directory.Delete(_root, recursive: true); } catch { }
}
private string WriteMov(string shotCode, string version, string contents = "mov bytes")
{
var path = Path.Combine(_renderDir, $"{shotCode}_cmp_TT_{version}.mov");
File.WriteAllText(path, contents);
return path;
}
private DeliveryManifest Manifest(params DeliveryManifestItem[] items) => new()
{
Kind = "MOV_REVIEW",
PackageId = "pkg1",
PackageName = "20260828_Producer_review",
PackageNumber = 7,
Episode = "101",
PackageDir = _reviewDir,
// A review writes no report; the server keeps the record instead.
ReportFile = "",
Items = items.ToList(),
};
private DeliveryManifestItem Item(
string shotCode, string version, string? movPath, string? deliveredBase = null) => new()
{
ItemId = $"item_{shotCode}",
ExportId = $"exp_{shotCode}",
ShotCode = shotCode,
VersionString = version,
SourceDir = "",
OutputPattern = "",
FrameStart = 1001,
FrameEnd = 1050,
DeliveryMovPath = movPath,
// Flat: every item's folder is the package folder itself.
ShotDir = _reviewDir,
DeliveredBaseName = deliveredBase ?? $"{shotCode}_cmp_TT_{version}",
};
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 BuildsAFlatFolderOfMovsUnderTheClientFacingName()
{
var mov = WriteMov("SHOT_001", "v004");
var manifest = Manifest(Item("SHOT_001", "v004", mov, deliveredBase: "EP6_VFX_012_v004"));
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(1, item.FileCount);
// No shot subfolder: the MOVs sit beside each other to be scrubbed through.
Assert.Null(item.ExrPath);
Assert.Equal(Path.Combine(_reviewDir, "EP6_VFX_012_v004.mov"), item.MovPath);
Assert.Single(Directory.GetDirectories(_reviewDir).Concat(Directory.GetFiles(_reviewDir)));
}
[Fact]
public async Task LeavesNoReportOrManifestBesideTheMovs()
{
var manifest = Manifest(Item("SHOT_001", "v004", WriteMov("SHOT_001", "v004")));
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.True(result.Ok);
Assert.Null(result.ReportPath);
// What a producer opens is exactly the MOVs — no manifest.json, no CSV.
Assert.False(File.Exists(Path.Combine(_reviewDir, "manifest.json")));
Assert.All(Directory.GetFiles(_reviewDir), f => Assert.EndsWith(".mov", f));
}
[Fact]
public async Task HardLinksSoASeventyShotReviewCostsNoDisk()
{
var mov = WriteMov("SHOT_001", "v004");
var manifest = Manifest(Item("SHOT_001", "v004", mov));
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.Equal("hardlink", result.Items[0].LinkMode);
File.WriteAllText(mov, "rewritten");
Assert.Equal("rewritten", File.ReadAllText(result.Items[0].MovPath!));
}
[Fact]
public async Task AlwaysCopyModeProducesAnIndependentFile()
{
var mov = WriteMov("SHOT_001", "v004");
var manifest = Manifest(Item("SHOT_001", "v004", mov));
manifest.CopyMode = "always-copy";
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.True(result.Ok);
Assert.Equal("copy", result.Items[0].LinkMode);
File.WriteAllText(mov, "rewritten");
Assert.NotEqual("rewritten", File.ReadAllText(result.Items[0].MovPath!));
}
[Fact]
public async Task AMissingMovFailsTheReviewRatherThanShippingItShort()
{
// In an EXR delivery a missing MOV is a missing viewing copy and the
// package continues. In a review the MOV *is* the deliverable.
var manifest = Manifest(Item("SHOT_001", "v004", Path.Combine(_renderDir, "never_rendered.mov")));
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("Preview MOV not found", result.Items[0].ErrorMessage!);
}
[Fact]
public async Task AnItemWithNoRecordedMovFails()
{
var manifest = Manifest(Item("SHOT_001", "v004", null));
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.False(result.Ok);
Assert.Contains("No preview MOV", result.Items[0].ErrorMessage!);
}
[Fact]
public async Task HashesEveryFileWhenTheConfigDemandsIt()
{
var manifest = Manifest(Item("SHOT_001", "v004", WriteMov("SHOT_001", "v004")));
manifest.VerifyMode = "always-hash";
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.True(result.Ok);
// A MOV has no validation-time digest of its own, so the one recorded
// here is the one this build computed.
Assert.False(string.IsNullOrWhiteSpace(result.Items[0].Checksum));
}
[Fact]
public async Task OneBadShotFailsThePackageAndTheRestStillReport()
{
var manifest = Manifest(
Item("SHOT_001", "v004", WriteMov("SHOT_001", "v004")),
Item("SHOT_002", "v002", Path.Combine(_renderDir, "absent.mov")));
var result = await NewStage().RunAsync(new ClaimedJob { Id = "job1" }, manifest, "machine1",
CancellationToken.None, CancellationToken.None);
Assert.False(result.Ok);
Assert.Equal("VERIFIED", result.Items[0].Status);
Assert.Equal("FAILED", result.Items[1].Status);
}
}
@@ -0,0 +1,54 @@
using VFXReviewWorker;
using Xunit;
namespace VFXReviewWorker.Tests;
/// <summary>
/// The preview MP4 opens on the Netflix slate. ffmpeg's <c>thumbnail</c> filter
/// only considers the first 100 frames, so every thumbnail the pipeline has ever
/// produced was a picture of the slate card rather than of the shot — invisible
/// while thumbnails were only decoration in the QC queue, and unacceptable now
/// they can become a shot's thumbnail.
///
/// The fix is to seek past the slate, so the seek arithmetic is worth pinning.
/// </summary>
public class ThumbnailSeekTests
{
private static PreviewBuildResult Build(double? pictureStart, int? frameCount) =>
new() { PictureStartSeconds = pictureStart, FrameCount = frameCount };
[Fact]
public void SeeksAQuarterIntoPictureNotIntoTheFile()
{
// 5s slate, then 96 frames (4s) of picture at 24fps → 5 + 1 = 6s.
var seek = PreviewStage.ThumbnailSeekSeconds(Build(5.0, 96), 24);
Assert.NotNull(seek);
Assert.Equal(6.0, seek!.Value, 3);
}
[Fact]
public void HandlesATemplateWithNoSlateAtAll()
{
var seek = PreviewStage.ThumbnailSeekSeconds(Build(0.0, 240), 24);
Assert.Equal(2.5, seek!.Value, 3);
}
[Fact]
public void FallsBackWhenTheBuildDidNotReportWherePictureStarts()
{
// Older worker, or a template with no SHOT layer: null means "keep the
// old whole-file behaviour" rather than guessing an offset.
Assert.Null(PreviewStage.ThumbnailSeekSeconds(Build(null, 96), 24));
Assert.Null(PreviewStage.ThumbnailSeekSeconds(null, 24));
}
[Theory]
[InlineData(-1.0, 96, 24)] // negative slate length
[InlineData(5.0, 0, 24)] // no picture frames
[InlineData(5.0, -5, 24)] // nonsense frame count
[InlineData(5.0, 96, 0)] // no fps to divide by
public void RefusesNumbersThatDoNotDescribeARealClip(double start, int frames, double fps)
{
Assert.Null(PreviewStage.ThumbnailSeekSeconds(Build(start, frames), fps));
}
}
@@ -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);
}
}
+20 -3
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))!;
@@ -115,11 +128,15 @@ public sealed class ApiClient
};
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;
@@ -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 { }
}
}
+209 -21
View File
@@ -11,6 +11,10 @@ namespace VFXReviewWorker;
/// 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.
///
/// A MOV_REVIEW package (§11.6) runs the same path for a different shape: one
/// flat folder, one preview MOV per shot, and nothing written into it but the
/// MOVs themselves — it is shared with a producer, not filed as a delivery.
///
/// 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
@@ -37,9 +41,11 @@ public sealed class DeliveryStage
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);
var isReview = string.Equals(manifest.Kind, "MOV_REVIEW", StringComparison.OrdinalIgnoreCase);
_log.LogInformation("Building delivery package {Name} ({Count} shots) at {Dir}",
manifest.PackageName, manifest.Items.Count, packageDir);
_log.LogInformation("Building {What} {Name} ({Count} shots) at {Dir}",
isReview ? "MOV review" : "delivery package", manifest.PackageName, manifest.Items.Count, packageDir);
Directory.CreateDirectory(packageDir);
for (var i = 0; i < manifest.Items.Count; i++)
@@ -50,7 +56,9 @@ public sealed class DeliveryStage
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, manifestFiles);
var result = isReview
? BuildReviewItem(item, mapper, alwaysCopy, alwaysHash, manifestFiles)
: BuildItem(item, mapper, alwaysCopy, alwaysHash, manifestFiles);
results.Add(result);
if (result.Status == "FAILED")
{
@@ -62,22 +70,29 @@ public sealed class DeliveryStage
// 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.
//
// A review folder gets neither: it is opened by a producer who wants the
// MOVs and nothing else. The manifest still travels back to the server,
// so the record of what was shared is kept without cluttering the share.
string? reportPath = null;
try
if (!isReview)
{
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);
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, List<object> manifestFiles)
DeliveryManifestItem item, PathMapper mapper, bool alwaysCopy, bool alwaysHash, List<object> manifestFiles)
{
var sourceDir = mapper.Map(item.SourceDir);
var shotDir = mapper.Map(item.ShotDir);
@@ -108,11 +123,18 @@ public sealed class DeliveryStage
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, Path.GetFileName(src));
var dest = Path.Combine(shotDir, destNames[src]);
if (Place(src, dest, alwaysCopy, out var copied) is string placeError)
{
return DeliveryItemResult.Failed(item, placeError);
@@ -121,15 +143,51 @@ public sealed class DeliveryStage
totalBytes += new FileInfo(dest).Length;
}
// Verification reads the delivered bytes back, which works the same
// whether the entry is a link or a copy — `fsutil hardlink list` is
// not available over SMB, so link identity cannot be queried.
var digest = SequenceChecksum(sources.Select(s => Path.Combine(shotDir, Path.GetFileName(s))));
if (item.Checksum is { Length: > 0 } && !string.Equals(digest, item.Checksum, StringComparison.OrdinalIgnoreCase))
// 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)
{
return DeliveryItemResult.Failed(item,
$"Checksum mismatch after packaging: expected {item.Checksum}, got {digest}");
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))
@@ -137,7 +195,10 @@ public sealed class DeliveryStage
var movSrc = mapper.Map(item.DeliveryMovPath!);
if (File.Exists(movSrc))
{
movDest = Path.Combine(shotDir, Path.GetFileName(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);
@@ -155,7 +216,7 @@ public sealed class DeliveryStage
foreach (var src in sources)
{
var name = Path.GetFileName(src);
var name = destNames[src];
manifestFiles.Add(new
{
shotCode = item.ShotCode,
@@ -187,6 +248,108 @@ public sealed class DeliveryStage
}
}
/// <summary>
/// One shot of a MOV review package: place its preview MOV straight into
/// the (flat) review folder under the client-facing name.
///
/// A missing MOV is fatal here, unlike in an EXR delivery where the MOV is
/// a viewing copy beside the real deliverable — in a review it *is* the
/// deliverable, and a review folder quietly one shot short is worse than
/// one that says so.
/// </summary>
private DeliveryItemResult BuildReviewItem(
DeliveryManifestItem item, PathMapper mapper, bool alwaysCopy, bool alwaysHash, List<object> manifestFiles)
{
try
{
if (string.IsNullOrWhiteSpace(item.DeliveryMovPath))
{
return DeliveryItemResult.Failed(item, "No preview MOV is recorded for this version");
}
var movSrc = mapper.Map(item.DeliveryMovPath!);
if (!File.Exists(movSrc))
{
return DeliveryItemResult.Failed(item, $"Preview MOV not found: {movSrc}");
}
// ShotDir is the package folder itself for a review — the MOVs sit
// beside each other so a producer can scrub through them in order.
var reviewDir = mapper.Map(item.ShotDir);
Directory.CreateDirectory(reviewDir);
var name = string.IsNullOrWhiteSpace(item.DeliveredBaseName)
? Path.GetFileName(movSrc)
: item.DeliveredBaseName + Path.GetExtension(movSrc);
var dest = Path.Combine(reviewDir, name);
if (Place(movSrc, dest, alwaysCopy, out var copied) is string error)
{
return DeliveryItemResult.Failed(item, error);
}
var sourceLength = new FileInfo(movSrc).Length;
var destLength = new FileInfo(dest).Length;
// There is no validation-time digest for a MOV to check against, so
// a copy is proved against the source it came from: length always
// (it catches the truncation a full disk causes, for free), and the
// full hash when the config asks for it. A hard link is the source.
string? digest = null;
if (copied)
{
if (destLength != sourceLength)
{
return DeliveryItemResult.Failed(item,
$"Copied MOV is {destLength} bytes but the source is {sourceLength} — the copy is incomplete");
}
if (alwaysHash)
{
digest = XxHash64.HashFile(dest);
var sourceDigest = XxHash64.HashFile(movSrc);
if (!string.Equals(digest, sourceDigest, StringComparison.OrdinalIgnoreCase))
{
return DeliveryItemResult.Failed(item,
$"Copied MOV does not match its source: expected {sourceDigest}, got {digest}");
}
}
}
else if (alwaysHash)
{
digest = XxHash64.HashFile(dest);
}
manifestFiles.Add(new
{
shotCode = item.ShotCode,
relativePath = name,
bytes = destLength,
exportId = item.ExportId,
});
return new DeliveryItemResult
{
ItemId = item.ItemId,
ShotCode = item.ShotCode,
VersionString = item.VersionString,
Status = "VERIFIED",
// No EXR sequence is involved, so there is no shot folder to record.
ExrPath = null,
MovPath = dest,
FileCount = 1,
TotalBytes = destLength,
Checksum = digest,
LinkMode = copied ? "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
@@ -215,6 +378,31 @@ public sealed class DeliveryStage
}
}
/// <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);
+69
View File
@@ -49,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>
@@ -65,12 +68,44 @@ public sealed class ClaimedJob
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";
/// <summary>
/// "EXR_DELIVERY" builds the per-shot folders of EXRs + MOVs; "MOV_REVIEW"
/// builds a flat folder of preview MOVs for a formal review (§11.6). One
/// job type and one claim path either way — only what lands on disk differs.
/// </summary>
public string Kind { get; set; } = "EXR_DELIVERY";
public string PackageId { get; set; } = "";
public string PackageName { get; set; } = "";
public int PackageNumber { get; set; }
@@ -79,6 +114,8 @@ public sealed class DeliveryManifest
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();
@@ -98,6 +135,22 @@ public sealed class DeliveryManifestItem
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>
/// True on a MOV_REVIEW item: there is no EXR sequence, so SourceDir,
/// OutputPattern, FileCount and Checksum are empty and DeliveryMovPath is
/// the whole deliverable.
/// </summary>
public bool IsMovOnly => string.IsNullOrWhiteSpace(SourceDir);
}
/// <summary>PREVIEW_ONLY manifest (server-built, RenderPipeline2 §9).</summary>
@@ -134,6 +187,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; }
@@ -151,6 +206,12 @@ public sealed class PreviewBuildResult
public int? FrameCount { get; set; }
public int? Width { get; set; }
public int? Height { get; set; }
/// <summary>
/// Seconds of slate ahead of picture in the preview comp (the SHOT layer's
/// in-point). Null on builds predating this field, or when the template has
/// no SHOT layer — the thumbnail then falls back to scanning from frame 0.
/// </summary>
public double? PictureStartSeconds { get; set; }
}
/// <summary>The Render Manifest (§6.2) — the fields the render and validation stages need; the rest is preserved raw.</summary>
@@ -163,8 +224,16 @@ public sealed class RenderManifest
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; }
+77 -1
View File
@@ -16,11 +16,12 @@ public sealed class JobExecutor
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,
ValidationStage validation, DeliveryStage delivery, ReportSpooler spooler, ILogger<JobExecutor> log)
ValidationStage validation, DeliveryStage delivery, BlenderRunner blender, ReportSpooler spooler, ILogger<JobExecutor> log)
{
_options = options;
_api = api;
@@ -28,6 +29,7 @@ public sealed class JobExecutor
_preview = preview;
_validation = validation;
_delivery = delivery;
_blender = blender;
_spooler = spooler;
_log = log;
}
@@ -46,6 +48,12 @@ public sealed class JobExecutor
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);
@@ -169,6 +177,74 @@ 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.
@@ -38,6 +38,11 @@ public static class Preflight
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");
+168 -11
View File
@@ -179,7 +179,7 @@ public sealed class PreviewStage
null, null, null, build.TempAep, build, sw.Elapsed.TotalSeconds);
}
var thumbnail = await TryMakeThumbnailAsync(job.Id, mp4Local, shutdown);
var thumbnail = await TryMakeThumbnailAsync(job.Id, mp4Local, build, manifest.Fps, shutdown);
sw.Stop();
_log.LogInformation("Preview complete for job {JobId} in {Sec:F0}s (mov + mp4{Thumb})",
@@ -231,14 +231,96 @@ public sealed class PreviewStage
return process.ExitCode;
}
/// <summary>Optional 960-wide poster frame at 25% duration (§9.1). Never fatal.</summary>
private async Task<string?> TryMakeThumbnailAsync(string jobId, string mp4Path, CancellationToken ct)
/// <summary>
/// Optional 960-wide poster frame at 25% of <em>picture</em> duration
/// (§9.1). Never fatal.
/// </summary>
/// <remarks>
/// The preview MP4 opens on the Netflix slate, so the frame has to be taken
/// relative to picture rather than to the file. This previously used
/// ffmpeg's <c>thumbnail</c> filter, which considers only the first 100
/// frames — on a slated preview that is the slate card, which is what every
/// thumbnail in the system was until now. Seeking to
/// <c>pictureStart + 25%</c> matches what §9.1 always documented and is what
/// makes these frames usable as shot thumbnails.
///
/// A build that reports no picture start (older worker, or a template with
/// no SHOT layer) keeps the old whole-file behaviour rather than guessing.
/// </remarks>
private async Task<string?> TryMakeThumbnailAsync(
string jobId, string mp4Path, PreviewBuildResult? build, double fps, CancellationToken ct)
{
if (string.IsNullOrWhiteSpace(_options.FfmpegPath) || !File.Exists(_options.FfmpegPath))
if (string.IsNullOrWhiteSpace(_options.FfmpegPath))
{
_log.LogWarning(
"No thumbnail for job {JobId}: ffmpegPath is not set in config.json. " +
"Thumbnails are skipped, and shots cannot take a frame from this render.",
jobId);
return null;
}
if (!File.Exists(_options.FfmpegPath))
{
_log.LogWarning(
"No thumbnail for job {JobId}: ffmpegPath points at {Path}, which does not exist.",
jobId, _options.FfmpegPath);
return null;
}
var outPath = Path.Combine(WorkerOptions.ScratchDir, $"job_{jobId}_thumb.jpg");
var seek = ThumbnailSeekSeconds(build, fps);
if (seek is { } t)
{
_log.LogInformation(
"Thumbnail for job {JobId}: seeking to {Seek:F2}s (slate {Start:F2}s + 25% of {Frames} frames @ {Fps}fps)",
jobId, t, build!.PictureStartSeconds, build.FrameCount, fps);
var attempt = await RunFfmpegThumbnailAsync(jobId, mp4Path, outPath, t, ct);
if (attempt == ThumbAttempt.Wrote) return outPath;
// A hung or unstartable ffmpeg will hang the same way a second
// time, and each attempt costs the full two-minute cap.
if (attempt == ThumbAttempt.Broken) return null;
// The seek is derived from what the AE build reported; if those
// numbers disagree with the rendered file, ffmpeg lands past the
// end and writes nothing. Falling back to the whole-file scan means
// a wrong seek costs picture content, never the thumbnail itself.
_log.LogWarning(
"Thumbnail seek to {Seek:F2}s produced nothing for job {JobId} — retrying across the whole file. " +
"The frame will likely be the slate.", t, jobId);
}
else
{
_log.LogInformation(
"Thumbnail for job {JobId}: build reported no picture start, scanning the whole file " +
"(the frame will likely be the slate).", jobId);
}
if (await RunFfmpegThumbnailAsync(jobId, mp4Path, outPath, null, ct) == ThumbAttempt.Wrote) return outPath;
_log.LogWarning("No thumbnail produced for job {JobId} — see the ffmpeg output above.", jobId);
return null;
}
/// <summary>How one ffmpeg attempt ended.</summary>
private enum ThumbAttempt
{
/// <summary>A thumbnail was written.</summary>
Wrote,
/// <summary>ffmpeg ran and wrote nothing — a different attempt may work.</summary>
NoOutput,
/// <summary>ffmpeg hung or could not start — retrying costs minutes and fixes nothing.</summary>
Broken,
}
/// <summary>
/// One ffmpeg invocation. <paramref name="seekSeconds"/> null means the old
/// whole-file <c>thumbnail</c> filter. Logs ffmpeg's own diagnosis when no
/// file is produced.
/// </summary>
private async Task<ThumbAttempt> RunFfmpegThumbnailAsync(
string jobId, string mp4Path, string outPath, double? seekSeconds, CancellationToken ct)
{
TryDelete(outPath);
var psi = new ProcessStartInfo
@@ -249,27 +331,102 @@ public sealed class PreviewStage
UseShellExecute = false,
CreateNoWindow = true,
};
foreach (var a in new[] { "-y", "-i", mp4Path, "-vf", "thumbnail,scale=960:-1", "-frames:v", "1", outPath })
var args = new List<string> { "-y" };
if (seekSeconds is { } t)
{
psi.ArgumentList.Add(a);
// Before -i: ffmpeg seeks by keyframe, which is fast and accurate
// enough for a poster frame.
args.Add("-ss");
args.Add(t.ToString("0.###", System.Globalization.CultureInfo.InvariantCulture));
args.Add("-i");
args.Add(mp4Path);
args.Add("-vf");
args.Add("scale=960:-1");
}
else
{
args.Add("-i");
args.Add(mp4Path);
args.Add("-vf");
args.Add("thumbnail,scale=960:-1");
}
args.Add("-frames:v");
args.Add("1");
args.Add(outPath);
foreach (var a in args) psi.ArgumentList.Add(a);
try
{
using var process = Process.Start(psi);
if (process is null) return null;
if (process is null)
{
_log.LogWarning("Could not start ffmpeg at {Path} for job {JobId}", _options.FfmpegPath, jobId);
return ThumbAttempt.Broken;
}
// Drain BOTH pipes while the process runs. Windows gives an
// anonymous pipe a ~4 KB buffer; ffmpeg's banner and stream summary
// exceed that on their own, so a redirected-but-unread pipe fills,
// ffmpeg blocks forever on the write, and the wait below times out
// with the process still alive. That is a deadlock, not a slow
// encode, and it is why this step failed with nothing but a
// cancellation to show for it.
var stderrTask = process.StandardError.ReadToEndAsync();
var stdoutTask = process.StandardOutput.ReadToEndAsync();
using var timeout = CancellationTokenSource.CreateLinkedTokenSource(ct);
timeout.CancelAfter(TimeSpan.FromMinutes(2));
await process.WaitForExitAsync(timeout.Token);
return File.Exists(outPath) ? outPath : null;
try
{
await process.WaitForExitAsync(timeout.Token);
}
catch (OperationCanceledException) when (!ct.IsCancellationRequested)
{
// Our own 2-minute cap, not a shutdown: leaving ffmpeg running
// would hold the scratch file open and leak a process per job.
_log.LogWarning(
"ffmpeg timed out after 2 minutes for job {JobId} — killing it. Command: {Args}",
jobId, string.Join(" ", args));
try { process.Kill(entireProcessTree: true); } catch { }
return ThumbAttempt.Broken;
}
var stderr = await stderrTask;
await stdoutTask;
if (File.Exists(outPath) && new FileInfo(outPath).Length > 0) return ThumbAttempt.Wrote;
_log.LogWarning(
"ffmpeg wrote no thumbnail for job {JobId} (exit {Exit}). Command: {Args} -- ffmpeg said: {Stderr}",
jobId, process.ExitCode, string.Join(" ", args), Tail(stderr, 1200));
return ThumbAttempt.NoOutput;
}
catch (Exception ex)
{
_log.LogWarning(ex, "Thumbnail generation failed (non-fatal)");
return null;
_log.LogWarning(ex, "Thumbnail generation failed for job {JobId} (non-fatal)", jobId);
return ThumbAttempt.Broken;
}
}
/// <summary>Last <paramref name="max"/> characters — ffmpeg puts the error at the end.</summary>
private static string Tail(string? text, int max) =>
string.IsNullOrEmpty(text) ? "(no output)"
: text.Length <= max ? text
: text[^max..];
/// <summary>
/// Timestamp for the poster frame: a quarter of the way into picture,
/// skipping the slate. Null when the build did not report where picture
/// starts, or when the numbers do not describe a real clip.
/// </summary>
internal static double? ThumbnailSeekSeconds(PreviewBuildResult? build, double fps)
{
if (build?.PictureStartSeconds is not { } start || start < 0) return null;
if (build.FrameCount is not { } frames || frames <= 0) return null;
if (fps <= 0) return null;
return start + (frames / fps) * 0.25;
}
private static PreviewStageResult Fail(string message, bool retryable, Stopwatch sw, PreviewBuildResult? build = null)
{
sw.Stop();
+1
View File
@@ -41,6 +41,7 @@ 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>();
@@ -15,7 +15,7 @@
every change that gets published. publish.ps1 appends the git SHA via
SourceRevisionId, giving "1.1.0+feb1c7b".
-->
<Version>1.1.0</Version>
<Version>1.6.0</Version>
</PropertyGroup>
<ItemGroup>
+89 -20
View File
@@ -102,15 +102,28 @@ public sealed class ValidationStage
if (files.Count == 0) return files;
// missing_frames / duplicate_frames / first_frame / last_frame
// 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 = manifest.FrameStart; f <= manifest.FrameEnd; f++)
for (var f = runStart; f <= runEnd; f++)
{
if (!seen.Contains(f)) missing.Add(f);
}
@@ -118,7 +131,8 @@ public sealed class ValidationStage
checks.Add(missing.Count == 0
? ValidationCheck.Pass("missing_frames", "none", "none")
: ValidationCheck.Fail("missing_frames", "none", $"{missing.Count} missing",
"Missing frames: " + Summarise(missing), new { missing = missing.Take(500) }));
$"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")
@@ -126,16 +140,27 @@ public sealed class ValidationStage
"Duplicate frame numbers (differing padding?): " + Summarise(duplicates),
new { duplicates = duplicates.Take(100) }));
checks.Add(frameNumbers[0] == manifest.FrameStart
? ValidationCheck.Pass("first_frame", manifest.FrameStart.ToString(), frameNumbers[0].ToString())
: ValidationCheck.Fail("first_frame", manifest.FrameStart.ToString(), frameNumbers[0].ToString(),
$"Sequence starts at {frameNumbers[0]}, expected {manifest.FrameStart}"));
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 last = frameNumbers[^1];
checks.Add(last == manifest.FrameEnd
? ValidationCheck.Pass("last_frame", manifest.FrameEnd.ToString(), last.ToString())
: ValidationCheck.Fail("last_frame", manifest.FrameEnd.ToString(), last.ToString(),
$"Sequence ends at {last}, expected {manifest.FrameEnd}"));
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>();
@@ -315,7 +340,7 @@ public sealed class ValidationStage
}
// timecode_plate_match — reference precedence, rank 1 → 3.
var reference = ResolveTimecodeReference(m, config);
var reference = ResolveTimecodeReference(m, config, renderFirstFrame);
if (reference is null)
{
checks.Add(ValidationCheck.Warn("timecode_plate_match", "plate timecode", renderTc.ToString(),
@@ -325,6 +350,31 @@ public sealed class ValidationStage
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);
@@ -371,7 +421,7 @@ public sealed class ValidationStage
/// 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)
private TimecodeReference? ResolveTimecodeReference(RenderManifest m, ServerConfig config, int renderFirstFrame)
{
var mapper = new PathMapper(_options.PathMappings);
var handleFrames = m.Source?.HandleFrames ?? config.ValidationHandleFrames;
@@ -384,8 +434,14 @@ public sealed class ValidationStage
var header = File.Exists(local) ? ExrHeader.TryRead(local) : null;
if (header?.Timecode is not null)
{
var frame = SequencePattern.FrameFromName(Path.GetFileName(local)) ?? timing.FrameStart ?? m.FrameStart;
return new TimecodeReference("manifest", local, header.Timecode.Value, frame, handleFrames);
// 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);
}
@@ -395,12 +451,19 @@ public sealed class ValidationStage
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, m.FrameStart, handleFrames);
return new TimecodeReference("api", null, plateStart, renderFirstFrame, handleFrames);
}
return null;
@@ -470,7 +533,7 @@ public sealed class ValidationStage
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);
return new TimecodeReference("derived", firstFile, header.Timecode.Value, frame, 0, header.FramesPerSecond);
}
private static void AddCandidate(List<(string Dir, int Count)> candidates, string dir)
@@ -517,7 +580,8 @@ public sealed class ValidationStage
}
public sealed record TimecodeReference(
string Kind, string? PlatePath, Timecode PlateTimecode, int PlateFirstFrame, int HandleFrames);
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)
@@ -557,7 +621,12 @@ public sealed class SequencePattern
public string Extension { get; private init; } = ".exr";
public int Padding { get; private init; }
private static readonly Regex FrameInName = new(@"\.(\d{2,9})\.[A-Za-z0-9]+$", RegexOptions.Compiled);
// 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)
{
@@ -20,6 +20,12 @@ 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();
/// <summary>
@@ -64,9 +64,11 @@ public sealed class WorkerService : BackgroundService
}
// 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", "DELIVERY_BUILD" }
: new[] { "AE_RENDER", "PREVIEW_ONLY", "DELIVERY_BUILD" };
? 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)
+30 -1
View File
@@ -30,7 +30,11 @@
queued: [],
frameCount: null,
width: null,
height: null
height: null,
// Seconds of slate ahead of picture in the preview comp — the SHOT
// layer's in-point. The worker needs it to grab a thumbnail from
// picture rather than from the slate card.
pictureStartSeconds: null
};
var resultPath = null;
@@ -266,6 +270,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;
@@ -437,6 +462,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");
}
@@ -471,6 +497,7 @@
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
@@ -489,6 +516,8 @@
var shotLayer = previewComp.layer("SHOT");
var targetOutPoint = shotLayer.inPoint + shotComp.duration;
// Everything before this is slate; the thumbnail has to start after it.
result.pictureStartSeconds = shotLayer.inPoint;
if (targetOutPoint > previewComp.duration) {
previewComp.duration = targetOutPoint;
}
+745 -84
View File
File diff suppressed because it is too large Load Diff
+132 -9
View File
@@ -17,6 +17,43 @@ Settings are stored per-machine via the **⚙ Settings** button in the panel (pe
| **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.
---
@@ -66,6 +103,21 @@ Source EXR plates are read from **`<Footage Root>/{SHOW_ID}/`**. Configure `foot
└── {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.
@@ -149,16 +201,60 @@ Constructs a full shot composite in the open AE project from the episode and sho
**Process:**
1. Calls the shot lookup API to retrieve metadata (description, notes, episode, scene, etc.).
2. If a comp with the shot code already exists, updates its overlay instead of rebuilding.
3. Scans `FOOTAGE_ROOT/{episodeCode}/` for subfolders matching `{shotCode}_*` and imports each as an EXR image sequence at 24 fps.
3. Scans `FOOTAGE_ROOT/{episodeCode}/` for subfolders matching `{shotCode}_*` and imports each as an EXR image sequence, conformed to the shot's frame rate.
4. Creates a `{shotCode}_FOOTAGE` precomp containing all imported sequences, each with an OCIO Color Space Transform effect added (disabled by default).
5. Creates the main `{shotCode}` comp and places the footage precomp inside it.
6. If a `_SHOW LUT` comp exists in the project, adds it as a collapsed layer on top.
7. Calls **Add Overlay** logic to attach the `UNG_VFX_OVERLAY` comp.
8. Organises items into `__SHOTS/{episodeCode}`, `_FOOTAGE_4K`, and `_PRECOMPS` project folders.
6. Anchors both comps on the plate's start timecode — see [Start timecode](#start-timecode).
7. If a `_SHOW LUT` comp exists in the project, adds it as a collapsed layer on top.
8. Calls **Add Overlay** logic to attach the `UNG_VFX_OVERLAY` comp.
9. 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).
#### Start timecode
Neither comp starts at `00:00:00:00`. Both are anchored on the plate's own start
timecode, taken from the first source that has one:
| Rank | Source | Notes |
|---|---|---|
| 1 | The first EXR's header | The `timeCode` attribute, or `timeCodeString` where the packed one is absent. Read straight off disk — no pixel decode, and no dependency on what AE chose to expose. |
| 2 | AE's footage metadata | What "New Comp from Selection" would have inherited. |
| 3 | API `timecodeStart` less `handleFrames` | The convention **Set Start Timecode** uses. Last resort: the API stores the *editorial* in-point, which is a handle-length ahead of the plate by design. |
This is the same ranking the render worker's validation uses (RenderPipeline2
§8.1a), so a comp is anchored on exactly the value its EXRs are later checked
against — a shot built from rank 3 and validated against rank 1 is how a
timecode desync gets into a delivery.
The status line and the diagnostics log both name the rank that was used, e.g.
`start frame 864108 from EXR timecode 10:00:04:12`. A plate carrying no timecode
in any rank leaves the comp at `00:00:00:00` and says so.
---
## 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
@@ -298,17 +394,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/
@@ -318,8 +434,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**.
+82 -72
View File
@@ -5,7 +5,7 @@ import { db } from "@/lib/db";
import { revalidatePath } from "next/cache";
import { z } from "zod";
import { ApprovalStatus } from "@prisma/client";
import { recalcShotStatus } from "@/lib/shot-status";
import { recalcShotStatus, clearStaleShotApproval } from "@/lib/shot-status";
import { notifyApprovalChange } from "@/lib/notifications";
import { slackNotifyApproval } from "@/lib/slack";
import { versionLabel } from "@/lib/utils";
@@ -29,57 +29,62 @@ export async function submitApproval(data: z.infer<typeof approvalSchema>) {
throw new Error("Insufficient permissions to review versions");
}
// Create the approval record
const approval = await db.approval.create({
data: {
versionId: parsed.versionId,
userId: session.user.id,
status: parsed.status,
notes: parsed.notes,
},
});
// The verdict, the version, the task and the derived shot status are one
// decision and are written as one: a failure partway through used to leave the
// three layers disagreeing, with no way to tell which one was right.
const { approval, version } = await db.$transaction(async (tx) => {
const approval = await tx.approval.create({
data: {
versionId: parsed.versionId,
userId: session.user.id,
status: parsed.status,
notes: parsed.notes,
},
});
// Update version approval status
await db.version.update({
where: { id: parsed.versionId },
data: { approvalStatus: parsed.status },
});
await tx.version.update({
where: { id: parsed.versionId },
data: { approvalStatus: parsed.status },
});
// Load version + task + shot + project for downstream effects
const version = await db.version.findUnique({
where: { id: parsed.versionId },
include: {
task: {
include: {
shot: true,
project: true,
// Load version + task + shot + project for downstream effects
const version = await tx.version.findUnique({
where: { id: parsed.versionId },
include: {
task: {
include: {
shot: true,
project: true,
},
},
},
},
});
if (!version) throw new Error("Version not found");
// Update task status based on approval result
if (version.task && parsed.status !== "PENDING_REVIEW") {
if (parsed.status === "APPROVED") {
await tx.task.update({
where: { id: version.task.id },
data: { status: "DONE" },
});
} else if (parsed.status === "REJECTED" || parsed.status === "NEEDS_CHANGES") {
await tx.task.update({
where: { id: version.task.id },
data: { status: "CHANGES" },
});
}
// Recalculate shot status from updated task states
if (version.task.shot) {
await recalcShotStatus(version.task.shot.id, tx);
}
}
return { approval, version };
});
if (!version) throw new Error("Version not found");
// Update task status based on approval result
if (version.task && parsed.status !== "PENDING_REVIEW") {
if (parsed.status === "APPROVED") {
await db.task.update({
where: { id: version.task.id },
data: { status: "DONE" },
});
} else if (parsed.status === "REJECTED" || parsed.status === "NEEDS_CHANGES") {
await db.task.update({
where: { id: version.task.id },
data: { status: "CHANGES" },
});
}
// Recalculate shot status from updated task states
if (version.task.shot) {
await recalcShotStatus(version.task.shot.id).catch(() => {});
}
}
// Notifications
const reviewer = await db.user.findUnique({ where: { id: session.user.id } });
const reviewerName = reviewer?.name ?? "Reviewer";
@@ -166,34 +171,39 @@ export async function unapproveVersion(versionId: string) {
throw new Error("Only approved versions can be unapproved");
}
// Create an audit record for the unapproval
await db.approval.create({
data: {
versionId,
userId: session.user.id,
status: "PENDING_REVIEW",
notes: "Approval undone",
},
});
// Reset version approval status
await db.version.update({
where: { id: versionId },
data: { approvalStatus: "PENDING_REVIEW" },
});
// Reset task back to INTERNAL_REVIEW if it was moved to DONE
if (version.task && version.task.status === "DONE") {
await db.task.update({
where: { id: version.task.id },
data: { status: "INTERNAL_REVIEW" },
// One decision, one write — same reasoning as submitApproval.
await db.$transaction(async (tx) => {
// Create an audit record for the unapproval
await tx.approval.create({
data: {
versionId,
userId: session.user.id,
status: "PENDING_REVIEW",
notes: "Approval undone",
},
});
}
// Recalculate shot status
if (version.task?.shot) {
await recalcShotStatus(version.task.shot.id).catch(() => {});
}
// Reset version approval status
await tx.version.update({
where: { id: versionId },
data: { approvalStatus: "PENDING_REVIEW" },
});
// Reset task back to INTERNAL_REVIEW if it was moved to DONE
if (version.task && version.task.status === "DONE") {
await tx.task.update({
where: { id: version.task.id },
data: { status: "INTERNAL_REVIEW" },
});
}
// Undoing a version approval also invalidates any shot-level sign-off that
// rested on it, otherwise the shot keeps reading COMPLETE / READY_FOR_CLIENT.
if (version.task?.shot) {
await clearStaleShotApproval(tx, version.task.shot.id);
await recalcShotStatus(version.task.shot.id, tx);
}
});
revalidatePath(`/review/${versionId}`);
if (version.task) {
+43
View File
@@ -0,0 +1,43 @@
"use server";
import { revalidatePath } from "next/cache";
import { requirePipelineAdmin } from "@/lib/render-pipeline/session-auth";
import { PipelineError } from "@/lib/render-pipeline/errors";
import {
createMovReviewPackage,
previewMovReviewPackage,
} from "@/lib/render-pipeline/reviews";
/**
* Server actions behind "Build MOV Review Package" on the shot-status page
* (RenderPipeline2 §11.6). The heavy lifting lives in lib/render-pipeline;
* these only carry the session and turn service errors into messages a toast
* can show.
*/
function message(err: unknown): string {
if (err instanceof PipelineError) return err.message;
return err instanceof Error ? err.message : "Unknown error";
}
/** What the confirm dialog shows: the folder, the resolved versions, the gaps. */
export async function previewMovReview(shotIds: string[]) {
try {
await requirePipelineAdmin();
const preview = await previewMovReviewPackage(shotIds);
return { ok: true as const, ...preview };
} catch (err) {
return { ok: false as const, error: message(err) };
}
}
export async function buildMovReview(shotIds: string[]) {
try {
const user = await requirePipelineAdmin();
const result = await createMovReviewPackage({ shotIds }, user.id);
revalidatePath("/pipeline/deliveries");
return { ok: true as const, ...result };
} catch (err) {
return { ok: false as const, error: message(err) };
}
}
+17 -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,19 @@ 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 "".
// Booleans are kept as-is: `false` is a meaningful stored value, and the
// blank-string test would otherwise discard every non-string setting.
...(rest.pipelineConfig !== undefined && {
pipelineConfig: rest.pipelineConfig
? (Object.fromEntries(
Object.entries(rest.pipelineConfig).filter(([, v]) =>
typeof v === "boolean" ? true : typeof v === "string" && !!v.trim()
)
) as Prisma.InputJsonValue)
: Prisma.DbNull,
}),
},
});
+223 -47
View File
@@ -4,8 +4,8 @@ import { auth } from "@/auth";
import { db } from "@/lib/db";
import { revalidatePath } from "next/cache";
import { z } from "zod";
import { ShotStatus, ShotPriority, ShotApprovalStatus } from "@prisma/client";
import { recalcShotStatus } from "@/lib/shot-status";
import { ShotStatus, ShotPriority, ShotApprovalStatus, Prisma } from "@prisma/client";
import { recalcShotStatus, markShotForRevisions } from "@/lib/shot-status";
const createShotSchema = z.object({
scene: z.string().min(1).max(50).regex(/^[A-Z0-9_]+$/i, "Alphanumeric and underscore only"),
@@ -341,6 +341,15 @@ export async function importShotsFromCsv(
return { success: true, created, errors };
}
/**
* Manual override of the shot's status.
*
* Deliberately the one place that writes Shot.status without deriving it — but
* note the override is transient: Shot.status is a derived field, so the next
* recalc (any task move, approval, upload or render) recomputes it from the
* tasks and approval flags and discards whatever was set here. Change the
* underlying task states if the new status needs to stick.
*/
export async function updateShotStatus(
shotId: string,
status: ShotStatus
@@ -498,6 +507,7 @@ export async function updateShotSlate(
slateDescription?: string | null;
slateVfxScope?: string | null;
slateSubmissionNote?: string | null;
clientCode?: string | null;
}
) {
const session = await auth();
@@ -516,6 +526,7 @@ export async function updateShotSlate(
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,
},
});
@@ -548,6 +559,34 @@ export async function toggleKeyShot(shotId: string, isKeyShot: boolean) {
return { success: true };
}
/**
* Scaled in the edit: the plate is not used at its native size, which changes
* how the shot is comped and reviewed. Same shape as toggleKeyShot — a standing
* property of the shot, flipped from the shot-status board.
*/
export async function toggleScaledShot(shotId: string, isScaled: boolean) {
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: { isScaled },
});
revalidatePath(`/projects/${shot.projectId}`);
revalidatePath(`/shot-status`);
return { success: true };
}
export async function deleteShot(shotId: string) {
const session = await auth();
if (!session?.user) throw new Error("Unauthorized");
@@ -613,6 +652,59 @@ export async function bulkUpdateDueDates(
return { success: true, updated: shots.length };
}
// ── Bulk Delete Shots ─────────────────────────────────────────────────────────
export async function bulkDeleteShots(shotIds: string[]) {
const session = await auth();
if (!session?.user) throw new Error("Unauthorized");
if (!["ADMIN", "PRODUCER", "SUPERVISOR"].includes(session.user.role)) {
throw new Error("Insufficient permissions");
}
if (!shotIds.length) return { success: true, deleted: 0, failed: [] as { shotId: string; shotCode: string; reason: string }[] };
const shots = await db.shot.findMany({
where: { id: { in: shotIds } },
select: { id: true, shotCode: true, projectId: true },
});
const projectIds = [...new Set(shots.map((s) => s.projectId))];
const failed: { shotId: string; shotCode: string; reason: string }[] = [];
let deleted = 0;
// One at a time, not deleteMany: a shot with renders or deliveries is
// protected at the database level (exports_shotId_fkey is ON DELETE
// RESTRICT, deliberately — delivery history must never be destroyable by
// deleting the shot underneath it). A single bulk statement would abort
// entirely on the first shot it hits; deleting individually means every
// shot that *can* go still does, and the ones that can't are reported by
// name instead of failing the whole selection.
for (const shot of shots) {
try {
await db.shot.delete({ where: { id: shot.id } });
deleted += 1;
} catch (e) {
failed.push({
shotId: shot.id,
shotCode: shot.shotCode,
reason:
e instanceof Prisma.PrismaClientKnownRequestError && e.code === "P2003"
? "has renders or deliveries — delete those first"
: e instanceof Error
? e.message
: "unknown error",
});
}
}
for (const pid of projectIds) {
revalidatePath(`/projects/${pid}`);
}
revalidatePath(`/shot-status`);
return { success: true, deleted, failed };
}
export async function renameFootagePlate(plateId: string, label: string) {
const session = await auth();
if (!session?.user) throw new Error("Unauthorized");
@@ -654,13 +746,19 @@ export async function internallyApproveShot(shotId: string) {
});
if (!shot) throw new Error("Shot not found");
await db.shot.update({
where: { id: shotId },
data: {
shotApprovalStatus: "INTERNALLY_APPROVED",
sharedWithClient: false,
status: "READY_FOR_CLIENT",
},
// Set the approval inputs and let the derivation pick the status. Writing
// READY_FOR_CLIENT directly skipped the rule that an outstanding CHANGES task
// outranks any approval, so a shot could be pushed past open rework and then
// snap back to REVISIONS on the next unrelated recalc.
await db.$transaction(async (tx) => {
await tx.shot.update({
where: { id: shotId },
data: {
shotApprovalStatus: "INTERNALLY_APPROVED",
sharedWithClient: false,
},
});
await recalcShotStatus(shotId, tx);
});
revalidatePath(`/projects/${shot.projectId}`);
@@ -703,7 +801,7 @@ export async function shareWithClient(shotId: string) {
// Mark shot as shared
await tx.shot.update({
where: { id: shotId },
data: { sharedWithClient: true, status: "CLIENT_REVIEW" },
data: { sharedWithClient: true },
});
// For each task, make the latest version client-visible
@@ -723,6 +821,8 @@ export async function shareWithClient(shotId: string) {
});
}
}
await recalcShotStatus(shotId, tx);
});
revalidatePath(`/projects/${shot.projectId}`);
@@ -755,7 +855,7 @@ export async function unshareFromClient(shotId: string) {
await db.$transaction(async (tx) => {
await tx.shot.update({
where: { id: shotId },
data: { sharedWithClient: false, status: "READY_FOR_CLIENT" },
data: { sharedWithClient: false },
});
// Hide all client-visible versions on this shot's tasks
@@ -766,6 +866,8 @@ export async function unshareFromClient(shotId: string) {
data: { isClientVisible: false },
});
}
await recalcShotStatus(shotId, tx);
});
revalidatePath(`/projects/${shot.projectId}`);
@@ -794,9 +896,12 @@ export async function clientApproveShot(shotId: string) {
if (!shot) throw new Error("Shot not found");
if (!shot.sharedWithClient) throw new Error("Shot is not shared with client");
await db.shot.update({
where: { id: shotId },
data: { shotApprovalStatus: "CLIENT_APPROVED", status: "COMPLETE" },
await db.$transaction(async (tx) => {
await tx.shot.update({
where: { id: shotId },
data: { shotApprovalStatus: "CLIENT_APPROVED" },
});
await recalcShotStatus(shotId, tx);
});
revalidatePath(`/projects/${shot.projectId}`);
@@ -826,14 +931,15 @@ export async function unapproveShot(shotId: string) {
throw new Error("Shot is not client-approved");
}
const newStatus = shot.sharedWithClient ? "CLIENT_REVIEW" : "READY_FOR_CLIENT";
await db.shot.update({
where: { id: shotId },
data: {
shotApprovalStatus: "INTERNALLY_APPROVED",
status: newStatus,
},
// The derivation already encodes "CLIENT_REVIEW if still shared, else
// READY_FOR_CLIENT" for an INTERNALLY_APPROVED shot, and additionally honours
// any open CHANGES task.
await db.$transaction(async (tx) => {
await tx.shot.update({
where: { id: shotId },
data: { shotApprovalStatus: "INTERNALLY_APPROVED" },
});
await recalcShotStatus(shotId, tx);
});
revalidatePath(`/projects/${shot.projectId}`);
@@ -1134,9 +1240,12 @@ export async function assignShotGroups(
}
/**
* Internal: handle client requesting changes on a shot.
* Resets shotApprovalStatus = PENDING, sharedWithClient = false.
* Recalculates shot status (will become REVISIONS if tasks set to CHANGES).
* Session-authenticated wrapper for requesting changes on a shot — a supervisor
* or producer relaying a client note from inside the app.
*
* The client portal cannot use this: it runs on a review token, not a session,
* so it calls markShotForRevisions directly from its route. Both go through that
* one helper so the two entry points cannot drift apart again.
*/
export async function clientRequestShotChanges(shotId: string, taskId?: string) {
const session = await auth();
@@ -1151,28 +1260,7 @@ export async function clientRequestShotChanges(shotId: string, taskId?: string)
});
if (!shot) throw new Error("Shot not found");
await db.$transaction(async (tx) => {
// Reset shot approval
await tx.shot.update({
where: { id: shotId },
data: { shotApprovalStatus: "PENDING", sharedWithClient: false },
});
// If a specific task is called out, mark it CHANGES; otherwise mark all non-DONE tasks
if (taskId) {
await tx.task.update({
where: { id: taskId },
data: { status: "CHANGES" },
});
} else {
await tx.task.updateMany({
where: { shotId, status: { not: "DONE" } },
data: { status: "CHANGES" },
});
}
await recalcShotStatus(shotId, tx);
});
await db.$transaction((tx) => markShotForRevisions(tx, shotId, taskId));
revalidatePath(`/projects/${shot.projectId}`);
revalidatePath(`/projects/${shot.projectId}/shots/${shotId}`);
@@ -1211,3 +1299,91 @@ export async function updateShotVersion(shotId: string, version: string) {
revalidatePath(`/projects/${shot.projectId}/shots/${shotId}`);
return { success: true, shotVersion: version };
}
// ── Generated (render-derived) shot thumbnails ───────────────────────────────
//
// A shot can carry two stills: `thumbnailUrl`, the reference frame that came
// with the brief, and `generatedThumbnailUrl`, a frame promoted from a render
// export. The reference always wins on display (lib/shot-thumbnail.ts), so
// these actions can only ever fill a gap — a promotion never overwrites the
// brief, and clearing one always falls back to it.
//
// Shows with `pipelineConfig.autoShotThumbnail` promote on every finished
// export automatically (lib/render-pipeline/preview.ts). These actions are the
// manual equivalent, and work regardless of that flag: a supervisor can pull a
// frame onto one shot on a project that is otherwise hands-off.
/**
* Promote a render export's thumbnail onto its shot.
*
* With no `exportId`, uses the newest export of that shot which actually has a
* thumbnail — "use the latest render frame".
*/
export async function promoteExportThumbnail(shotId: string, exportId?: string) {
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: { id: true, projectId: true },
});
if (!shot) throw new Error("Shot not found");
const exportRow = await db.export.findFirst({
where: {
shotId,
thumbnailKey: { not: null },
...(exportId ? { id: exportId } : {}),
},
orderBy: { versionNumber: "desc" },
select: { id: true, thumbnailKey: true, versionString: true },
});
if (!exportRow?.thumbnailKey) {
throw new Error(
exportId
? "That export has no thumbnail — its preview may have been skipped, or the worker had no ffmpeg configured"
: "No render of this shot has produced a thumbnail yet"
);
}
const generatedThumbnailUrl = `/api/files/${exportRow.thumbnailKey}`;
await db.shot.update({
where: { id: shotId },
data: { generatedThumbnailUrl, generatedThumbnailFrom: exportRow.versionString },
});
revalidatePath(`/projects/${shot.projectId}`);
revalidatePath(`/projects/${shot.projectId}/shots/${shotId}`);
return {
success: true,
generatedThumbnailUrl,
generatedThumbnailFrom: exportRow.versionString,
};
}
/** Drop the render-derived still. The reference frame, if any, comes back. */
export async function clearGeneratedThumbnail(shotId: string) {
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: { id: true, projectId: true },
});
if (!shot) throw new Error("Shot not found");
await db.shot.update({
where: { id: shotId },
data: { generatedThumbnailUrl: null, generatedThumbnailFrom: null },
});
revalidatePath(`/projects/${shot.projectId}`);
revalidatePath(`/projects/${shot.projectId}/shots/${shotId}`);
return { success: true };
}
+10 -3
View File
@@ -4,7 +4,7 @@ import { auth } from "@/auth";
import { db } from "@/lib/db";
import { revalidatePath } from "next/cache";
import { z } from "zod";
import { recalcShotStatus } from "@/lib/shot-status";
import { recalcShotStatus, clearStaleShotApproval } from "@/lib/shot-status";
import { notifyNewVersionUploaded } from "@/lib/notifications";
import { slackNotifyVersionUploaded } from "@/lib/slack";
@@ -50,9 +50,16 @@ export async function createVersion(data: z.infer<typeof createVersionSchema>) {
data: { status: "INTERNAL_REVIEW" },
});
// Recalculate shot status
// Recalculate shot status — clearing any stale sign-off first, so a new
// version does not land under a shot still reading COMPLETE.
if (task.shot) {
await recalcShotStatus(task.shot.id).catch(() => {});
const shotId = task.shot.id;
await db
.$transaction(async (tx) => {
await clearStaleShotApproval(tx, shotId);
await recalcShotStatus(shotId, tx);
})
.catch(() => {});
}
// Get the next version number for this task
@@ -112,6 +112,12 @@ 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" />
@@ -274,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>
);
}
@@ -29,6 +29,7 @@ interface PackageRow {
id: string;
packageNumber: number;
name: string;
kind: "EXR_DELIVERY" | "MOV_REVIEW";
episode: string;
status: string;
rootPath: string | null;
@@ -242,6 +243,11 @@ export function DeliveriesClient({ canBuild }: { canBuild: boolean }) {
<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>
{p.kind === "MOV_REVIEW" && (
<span className="rounded-full border border-violet-500/30 bg-violet-500/10 px-2 py-0.5 text-xs text-violet-300">
MOV review
</span>
)}
<span
className={cn(
"rounded-full border px-2 py-0.5 text-xs",
@@ -257,7 +263,7 @@ export function DeliveriesClient({ canBuild }: { canBuild: boolean }) {
<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" && (
{canBuild && p.status === "READY" && p.kind === "EXR_DELIVERY" && (
<Button
size="sm"
variant="outline"
@@ -309,7 +315,9 @@ export function DeliveriesClient({ canBuild }: { canBuild: boolean }) {
</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>}
{p.kind === "EXR_DELIVERY" && 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>
@@ -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";
@@ -105,6 +106,10 @@ const CHECK_STYLES: Record<string, string> = {
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],
@@ -125,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 (
@@ -178,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
@@ -186,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>
@@ -227,6 +320,13 @@ export function ExportDetailClient({ exportId }: { exportId: string }) {
<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);
@@ -58,6 +58,14 @@ 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;
autoShotThumbnail?: boolean | null;
} | null;
};
clients: Client[];
teamMembers: TeamMember[];
@@ -41,7 +41,7 @@ export default async function KanbanPage({
where: { projectId: id },
orderBy: [{ status: "asc" }, { sortOrder: "asc" }],
include: {
shot: { select: { id: true, shotCode: true, thumbnailUrl: true } },
shot: { select: { id: true, shotCode: true, thumbnailUrl: true, generatedThumbnailUrl: true } },
asset: { select: { id: true, assetCode: true, name: true } },
assignedArtist: {
select: { id: true, name: true, email: true, image: true },
+9 -1
View File
@@ -60,7 +60,7 @@ async function getProject(id: string) {
tasks: {
orderBy: [{ status: "asc" }, { sortOrder: "asc" }],
include: {
shot: { select: { id: true, shotCode: true, thumbnailUrl: true } },
shot: { select: { id: true, shotCode: true, thumbnailUrl: true, generatedThumbnailUrl: true } },
asset: { select: { id: true, assetCode: true, name: true } },
assignedArtist: { select: { id: true, name: true, email: true, image: true } },
_count: { select: { versions: true } },
@@ -201,6 +201,14 @@ 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;
autoShotThumbnail?: boolean | null;
} | null,
}}
clients={clients}
teamMembers={teamMembers}
@@ -76,6 +76,7 @@ const PRIORITY_CONFIG: Record<string, { label: string; dot: string }> = {
};
import { useToast } from "@/components/ui/use-toast";
import { shotThumbnail } from "@/lib/shot-thumbnail";
export default function ShotDetailPage() {
const params = useParams<{ id: string; shotId: string }>();
@@ -251,11 +252,11 @@ export default function ShotDetailPage() {
<ArrowLeft className="h-4 w-4" />
</Link>
</Button>
{shot.thumbnailUrl && (
{shotThumbnail(shot) && (
<div className="relative flex-shrink-0 w-72 aspect-[2.39] rounded-lg overflow-hidden border border-border">
<Image
src={shot.thumbnailUrl}
src={shotThumbnail(shot)!}
alt={shot.shotCode}
fill
className="object-cover"
@@ -53,7 +53,12 @@ export interface ScheduleTask {
email: string;
image: string | null;
} | null;
shot: { id: string; shotCode: string; thumbnailUrl: string | null } | null;
shot: {
id: string;
shotCode: string;
thumbnailUrl: string | null;
generatedThumbnailUrl: string | null;
} | null;
asset: { id: string; assetCode: string; name: string } | null;
project: { id: string; name: string; code: string };
}
+2 -2
View File
@@ -31,7 +31,7 @@ export default async function SchedulePage({
...(artist ? { assignedArtistId: artist } : {}),
},
include: {
shot: { select: { id: true, shotCode: true, thumbnailUrl: true } },
shot: { select: { id: true, shotCode: true, thumbnailUrl: true, generatedThumbnailUrl: true } },
asset: { select: { id: true, assetCode: true, name: true } },
project: { select: { id: true, name: true, code: true } },
assignedArtist: {
@@ -49,7 +49,7 @@ export default async function SchedulePage({
...(artist ? { assignedArtistId: artist } : {}),
},
include: {
shot: { select: { id: true, shotCode: true, thumbnailUrl: true } },
shot: { select: { id: true, shotCode: true, thumbnailUrl: true, generatedThumbnailUrl: true } },
asset: { select: { id: true, assetCode: true, name: true } },
project: { select: { id: true, name: true, code: true } },
assignedArtist: {
+362 -20
View File
@@ -18,11 +18,19 @@ import {
DialogTitle,
DialogFooter,
} from "@/components/ui/dialog";
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuSeparator,
DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { Textarea } from "@/components/ui/textarea";
import { cn } from "@/lib/utils";
import { updateShotNotes, bulkUpdateDueDates, toggleKeyShot } from "@/actions/shots";
import { updateShotNotes, bulkUpdateDueDates, bulkDeleteShots, toggleKeyShot, toggleScaledShot } from "@/actions/shots";
import { previewMovReview, buildMovReview } from "@/actions/deliveries";
import { useToast } from "@/components/ui/use-toast";
import {
Film,
@@ -38,8 +46,13 @@ import {
ShieldCheck,
Eye,
Star,
Trash2,
ChevronsUpDown,
Clapperboard,
Scaling,
} from "lucide-react";
import { format } from "date-fns";
import { shotThumbnail } from "@/lib/shot-thumbnail";
type ShotRow = {
id: string;
@@ -51,9 +64,12 @@ type ShotRow = {
priority: string;
dueDate: Date | string | null;
thumbnailUrl: string | null;
generatedThumbnailUrl: string | null;
notes: string | null;
description: string | null;
isKeyShot: boolean;
isScaled: boolean;
shotVersion: string | null;
artist: { id: string; name: string | null; image: string | null; email: string } | null;
shotGroup: { id: string; name: string } | null;
};
@@ -209,6 +225,203 @@ function BulkDueDateDialog({
);
}
function BulkDeleteDialog({
open,
onClose,
onConfirm,
count,
}: {
open: boolean;
onClose: () => void;
onConfirm: () => Promise<void>;
count: number;
}) {
const [isPending, startTransition] = useTransition();
const handleConfirm = () => {
startTransition(async () => {
await onConfirm();
});
};
return (
<Dialog open={open} onOpenChange={(o) => { if (!o && !isPending) onClose(); }}>
<DialogContent className="sm:max-w-sm">
<DialogHeader>
<DialogTitle className="text-red-400">Delete {count} shot{count !== 1 ? "s" : ""}?</DialogTitle>
</DialogHeader>
<p className="text-sm text-zinc-300">
This will permanently delete <span className="font-semibold text-white">{count}</span>{" "}
shot{count !== 1 ? "s" : ""}, including all tasks, versions, footage, and annotations.
This cannot be undone.
</p>
<p className="text-xs text-zinc-500">
A shot with renders or deliveries already on record is protected and will be skipped
rather than deleted — you'll see which ones and why.
</p>
<DialogFooter className="mt-2">
<Button variant="ghost" onClick={onClose} disabled={isPending}>
Cancel
</Button>
<Button variant="destructive" onClick={handleConfirm} disabled={isPending}>
{isPending && <Loader2 className="h-3.5 w-3.5 mr-1.5 animate-spin" />}
{isPending ? "Deleting…" : `Yes, delete ${count} shot${count !== 1 ? "s" : ""}`}
</Button>
</DialogFooter>
</DialogContent>
</Dialog>
);
}
// ── MovReviewDialog ───────────────────────────────────────────────────────────
type ReviewPreview = Awaited<ReturnType<typeof previewMovReview>>;
/**
* Confirm what a MOV review package would contain before building it
* (RenderPipeline2 §11.6).
*
* The version each shot resolves to is the newest one that actually has a
* preview MOV, which is not always the newest one full stop — so the dialog
* names the version per shot rather than making anyone guess, and lists the
* shots with no MOV at all instead of quietly building a smaller folder.
*/
function MovReviewDialog({
open,
onClose,
onBuilt,
shotIds,
}: {
open: boolean;
onClose: () => void;
onBuilt: () => void;
shotIds: string[];
}) {
const { toast } = useToast();
const [preview, setPreview] = useState<ReviewPreview | null>(null);
const [loading, setLoading] = useState(false);
const [isPending, startTransition] = useTransition();
useEffect(() => {
if (!open) {
setPreview(null);
return;
}
let cancelled = false;
setLoading(true);
previewMovReview(shotIds)
.then((result) => {
if (!cancelled) setPreview(result);
})
.finally(() => {
if (!cancelled) setLoading(false);
});
return () => {
cancelled = true;
};
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [open]);
const ready = preview?.ok ? preview.candidates : [];
const skipped = preview?.ok ? preview.skipped : [];
const handleBuild = () => {
startTransition(async () => {
const result = await buildMovReview(shotIds);
if (!result.ok) {
toast({ title: "Could not build review package", description: result.error, variant: "destructive" });
return;
}
toast({
title: `${result.package.name} queued`,
description: `${result.package.itemCount} MOV${result.package.itemCount !== 1 ? "s" : ""} → ${result.package.rootPath}`,
});
onBuilt();
});
};
return (
<Dialog open={open} onOpenChange={(o) => { if (!o && !isPending) onClose(); }}>
<DialogContent className="sm:max-w-lg">
<DialogHeader>
<DialogTitle>Build MOV review package</DialogTitle>
</DialogHeader>
{loading && (
<p className="text-sm text-zinc-400 flex items-center gap-2">
<Loader2 className="h-3.5 w-3.5 animate-spin" />
Working out what each shot would contribute…
</p>
)}
{!loading && preview && !preview.ok && (
<p className="text-sm text-red-400">{preview.error}</p>
)}
{!loading && preview?.ok && (
<div className="space-y-4">
<div className="rounded-md border border-zinc-800 bg-zinc-900/60 px-3 py-2">
<div className="text-xs text-zinc-500">Folder</div>
<div className="text-sm text-white font-medium break-all">{preview.packageName}</div>
<div className="text-xs text-zinc-500 break-all">{preview.packageDir}</div>
</div>
{ready.length > 0 && (
<div className="space-y-1.5">
<div className="text-xs font-medium text-zinc-400">
{ready.length} MOV{ready.length !== 1 ? "s" : ""}
</div>
<div className="max-h-52 overflow-y-auto rounded-md border border-zinc-800 divide-y divide-zinc-800/60">
{ready.map((c) => (
<div key={c.shotId} className="flex items-center gap-2 px-3 py-1.5 text-xs">
<span className="text-zinc-200">{c.shotCode}</span>
<span className="text-zinc-500">{c.versionString}</span>
<span className="ml-auto text-zinc-600 truncate">{c.deliveredName}</span>
</div>
))}
</div>
</div>
)}
{skipped.length > 0 && (
<div className="space-y-1.5">
<div className="text-xs font-medium text-amber-400">
{skipped.length} shot{skipped.length !== 1 ? "s" : ""} left out
</div>
<div className="max-h-32 overflow-y-auto rounded-md border border-amber-500/20 bg-amber-500/5 divide-y divide-amber-500/10">
{skipped.map((sk) => (
<div key={sk.shotId} className="flex items-center gap-2 px-3 py-1.5 text-xs">
<span className="text-zinc-300">{sk.shotCode}</span>
<span className="text-amber-400/80">{sk.reason}</span>
</div>
))}
</div>
</div>
)}
<p className="text-xs text-zinc-500">
A render machine builds the folder. Nothing about these shots changes — a review is
not a delivery, so the versions stay exactly where they are in the pipeline.
</p>
</div>
)}
<DialogFooter className="mt-2">
<Button variant="ghost" onClick={onClose} disabled={isPending}>
Cancel
</Button>
<Button onClick={handleBuild} disabled={isPending || loading || ready.length === 0}>
{isPending && <Loader2 className="h-3.5 w-3.5 mr-1.5 animate-spin" />}
{isPending ? "Queueing…" : `Build with ${ready.length} MOV${ready.length !== 1 ? "s" : ""}`}
</Button>
</DialogFooter>
</DialogContent>
</Dialog>
);
}
// ── NotesCell ─────────────────────────────────────────────────────────────────
function NotesCell({
@@ -264,10 +477,30 @@ function NotesCell({
);
}
// ── KeyShotToggle ─────────────────────────────────────────────────────────────
// ── Shot flag toggles ─────────────────────────────────────────────────────────
function KeyShotToggle({ shot }: { shot: ShotRow }) {
const [optimistic, setOptimistic] = useState(shot.isKeyShot);
/**
* A standing yes/no property of a shot, flipped straight from the board.
* Optimistic: the switch moves immediately and rolls back if the save fails,
* because a producer ticking twenty shots should not wait on a round trip each
* time.
*/
function FlagToggle({
value,
onSet,
onLabel,
offLabel,
failureTitle,
tone,
}: {
value: boolean;
onSet: (next: boolean) => Promise<unknown>;
onLabel: string;
offLabel: string;
failureTitle: string;
tone: { on: string; ring: string };
}) {
const [optimistic, setOptimistic] = useState(value);
const [isPending, startTransition] = useTransition();
const { toast } = useToast();
@@ -276,10 +509,10 @@ function KeyShotToggle({ shot }: { shot: ShotRow }) {
setOptimistic(next);
startTransition(async () => {
try {
await toggleKeyShot(shot.id, next);
await onSet(next);
} catch {
setOptimistic(!next);
toast({ title: "Failed to update key shot", variant: "destructive" });
toast({ title: failureTitle, variant: "destructive" });
}
});
};
@@ -289,12 +522,13 @@ function KeyShotToggle({ shot }: { shot: ShotRow }) {
type="button"
role="switch"
aria-checked={optimistic}
aria-label={optimistic ? "Remove key shot" : "Mark as key shot"}
aria-label={optimistic ? offLabel : onLabel}
disabled={isPending}
onClick={handle}
className={cn(
"relative inline-flex h-5 w-9 shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-amber-400 disabled:opacity-50",
optimistic ? "bg-amber-500" : "bg-zinc-600 hover:bg-zinc-500"
"relative inline-flex h-5 w-9 shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors focus:outline-none focus-visible:ring-2 disabled:opacity-50",
tone.ring,
optimistic ? tone.on : "bg-zinc-600 hover:bg-zinc-500"
)}
>
<span
@@ -307,6 +541,32 @@ function KeyShotToggle({ shot }: { shot: ShotRow }) {
);
}
function KeyShotToggle({ shot }: { shot: ShotRow }) {
return (
<FlagToggle
value={shot.isKeyShot}
onSet={(next) => toggleKeyShot(shot.id, next)}
onLabel="Mark as key shot"
offLabel="Remove key shot"
failureTitle="Failed to update key shot"
tone={{ on: "bg-amber-500", ring: "focus-visible:ring-amber-400" }}
/>
);
}
function ScaledShotToggle({ shot }: { shot: ShotRow }) {
return (
<FlagToggle
value={shot.isScaled}
onSet={(next) => toggleScaledShot(shot.id, next)}
onLabel="Mark as scaled in the edit"
offLabel="Remove scaled flag"
failureTitle="Failed to update scaled flag"
tone={{ on: "bg-cyan-500", ring: "focus-visible:ring-cyan-400" }}
/>
);
}
function ShotTable({
shots,
canManage,
@@ -349,6 +609,12 @@ function ShotTable({
Key
</span>
</th>
<th className="py-2 px-3 text-xs font-medium text-zinc-500 w-20 text-center">
<span className="flex items-center gap-1 justify-center">
<Scaling className="h-3 w-3" />
Scaled
</span>
</th>
</tr>
</thead>
<tbody className="divide-y divide-zinc-800/60">
@@ -382,9 +648,9 @@ function ShotTable({
{/* Thumbnail */}
<td className="py-2 px-3">
<div className="w-24 aspect-[2.39/1] rounded overflow-hidden bg-zinc-800 flex items-center justify-center shrink-0">
{shot.thumbnailUrl ? (
{shotThumbnail(shot) ? (
<Image
src={shot.thumbnailUrl}
src={shotThumbnail(shot)!}
alt={shot.shotCode}
width={96}
height={40}
@@ -409,6 +675,15 @@ function ShotTable({
>
{shot.shotCode}
</Link>
{shot.shotVersion && (
<span className="font-mono text-xs text-zinc-400 shrink-0">{shot.shotVersion}</span>
)}
{shot.isScaled && (
<span className="flex items-center gap-1 rounded-full border border-cyan-500/30 bg-cyan-500/10 px-1.5 py-0.5 text-[10px] font-medium text-cyan-300 shrink-0">
<Scaling className="h-2.5 w-2.5" />
Scaled
</span>
)}
</div>
{shot.description && (
<p className="text-xs text-zinc-500 mt-0.5 truncate max-w-[200px]">
@@ -451,6 +726,11 @@ function ShotTable({
<td className="py-2 px-3 text-center">
<KeyShotToggle shot={shot} />
</td>
{/* Scaled-in-edit toggle */}
<td className="py-2 px-3 text-center">
<ScaledShotToggle shot={shot} />
</td>
</tr>
);
})}
@@ -513,6 +793,8 @@ export function ShotStatusClient({
}
}, [selectedProjectId]);
const [dueDateDialogOpen, setDueDateDialogOpen] = useState(false);
const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
const [movReviewDialogOpen, setMovReviewDialogOpen] = useState(false);
const toggleEpisode = (ep: string) =>
setExpandedEpisodes((prev) => {
@@ -586,6 +868,26 @@ export function ShotStatusClient({
}
};
const handleBulkDelete = async () => {
try {
const result = await bulkDeleteShots([...selectedIds]);
if (result.failed.length > 0) {
toast({
title: `Deleted ${result.deleted} shot${result.deleted !== 1 ? "s" : ""}, ${result.failed.length} skipped`,
description: result.failed.map((f) => `${f.shotCode}: ${f.reason}`).join("; "),
variant: "destructive",
});
} else {
toast({ title: `Deleted ${result.deleted} shot${result.deleted !== 1 ? "s" : ""}` });
}
setDeleteDialogOpen(false);
clearSelection();
router.refresh();
} catch (e) {
toast({ title: "Failed to delete shots", description: e instanceof Error ? e.message : undefined, variant: "destructive" });
}
};
// Group by episode for episodic projects
const isEpisodic = selectedProject?.projectType === "EPISODIC";
const episodeGroups: [string, ShotRow[]][] = isEpisodic
@@ -722,15 +1024,36 @@ export function ShotStatusClient({
<span className="text-sm font-medium text-blue-300">
{selectionCount} shot{selectionCount !== 1 ? "s" : ""} selected
</span>
<Button
size="sm"
variant="outline"
className="h-7 gap-1.5 border-blue-500/40 text-blue-300 hover:bg-blue-500/20 hover:text-blue-200"
onClick={() => setDueDateDialogOpen(true)}
>
<CalendarDays className="h-3.5 w-3.5" />
Change Due Date
</Button>
<DropdownMenu>
<DropdownMenuTrigger asChild>
<Button
size="sm"
variant="outline"
className="h-7 gap-1.5 border-blue-500/40 text-blue-300 hover:bg-blue-500/20 hover:text-blue-200"
>
Bulk Actions
<ChevronsUpDown className="h-3.5 w-3.5" />
</Button>
</DropdownMenuTrigger>
<DropdownMenuContent align="start">
<DropdownMenuItem onClick={() => setDueDateDialogOpen(true)}>
<CalendarDays className="h-3.5 w-3.5 mr-2" />
Change Due Date
</DropdownMenuItem>
<DropdownMenuItem onClick={() => setMovReviewDialogOpen(true)}>
<Clapperboard className="h-3.5 w-3.5 mr-2" />
Build MOV Review Package
</DropdownMenuItem>
<DropdownMenuSeparator />
<DropdownMenuItem
onClick={() => setDeleteDialogOpen(true)}
className="text-red-400 focus:text-red-300"
>
<Trash2 className="h-3.5 w-3.5 mr-2" />
Delete Shots
</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenu>
<button
onClick={clearSelection}
className="text-zinc-500 hover:text-zinc-300 transition-colors"
@@ -925,6 +1248,25 @@ export function ShotStatusClient({
onApply={handleBulkDueDate}
count={selectionCount}
/>
{/* Bulk delete dialog */}
<BulkDeleteDialog
open={deleteDialogOpen}
onClose={() => setDeleteDialogOpen(false)}
onConfirm={handleBulkDelete}
count={selectionCount}
/>
{/* MOV review package (§11.6) */}
<MovReviewDialog
open={movReviewDialogOpen}
onClose={() => setMovReviewDialogOpen(false)}
onBuilt={() => {
setMovReviewDialogOpen(false);
clearSelection();
}}
shotIds={[...selectedIds]}
/>
</div>
);
}
+5
View File
@@ -37,9 +37,14 @@ async function getShotsForProject(projectId: string) {
priority: true,
dueDate: true,
thumbnailUrl: true,
generatedThumbnailUrl: true,
notes: true,
description: true,
isKeyShot: true,
isScaled: true,
// The shot-level version the panel burns into overlays and queueExport
// renders under — not the count of review Versions uploaded.
shotVersion: true,
artist: { select: { id: true, name: true, image: true, email: true } },
shotGroup: { select: { id: true, name: true } },
},
+9 -3
View File
@@ -2,7 +2,7 @@ import { NextRequest, NextResponse } from "next/server";
import { auth } from "@/auth";
import { db } from "@/lib/db";
import { uploadToHetzner, deleteFromHetzner } from "@/lib/storage";
import { recalcShotStatus } from "@/lib/shot-status";
import { recalcShotStatus, clearStaleShotApproval } from "@/lib/shot-status";
export const maxDuration = 300; // 5 min — large .mov high-res files
@@ -194,8 +194,14 @@ export async function POST(
data: { status: "INTERNAL_REVIEW" },
});
// Recalculate the parent shot's status
await recalcShotStatus(shotId).catch(() => {});
// Recalculate the parent shot's status, clearing any stale sign-off first so
// the new version does not land under a shot still reading COMPLETE.
await db
.$transaction(async (tx) => {
await clearStaleShotApproval(tx, shotId);
await recalcShotStatus(shotId, tx);
})
.catch(() => {});
return NextResponse.json({
success: true,
+43 -27
View File
@@ -1,21 +1,8 @@
import { NextRequest, NextResponse } from "next/server";
import { db } from "@/lib/db";
import { ApprovalStatus } from "@prisma/client";
import { recalcShotStatus } from "@/lib/shot-status";
import { validateReviewToken } from "@/lib/review-auth";
async function getOrCreateClientUser(email: string, label?: string | null) {
const existing = await db.user.findUnique({ where: { email } });
if (existing) return existing;
return db.user.create({
data: {
email,
name: label ?? email.split("@")[0],
role: "CLIENT",
isActive: true,
},
});
}
import { recalcShotStatus, markShotForRevisions } from "@/lib/shot-status";
import { validateReviewToken, getOrCreateReviewUser } from "@/lib/review-auth";
export async function POST(
req: NextRequest,
@@ -48,9 +35,12 @@ export async function POST(
}
if (action === "APPROVE") {
await db.shot.update({
where: { id: shotId },
data: { shotApprovalStatus: "CLIENT_APPROVED", status: "COMPLETE" },
await db.$transaction(async (tx) => {
await tx.shot.update({
where: { id: shotId },
data: { shotApprovalStatus: "CLIENT_APPROVED" },
});
await recalcShotStatus(shotId, tx);
});
} else if (action === "NEEDS_CHANGES") {
// Increment shotVersion: v001 → v002, v009 → v010, etc.
@@ -59,17 +49,41 @@ export async function POST(
const nextNum = verMatch ? parseInt(verMatch[1], 10) + 1 : 2;
const nextVersion = "v" + String(nextNum).padStart(3, "0");
const user = await getOrCreateReviewUser(session, token);
await db.$transaction(async (tx) => {
await tx.shot.update({
where: { id: shotId },
data: { shotApprovalStatus: "PENDING", sharedWithClient: false, shotVersion: nextVersion },
data: { shotVersion: nextVersion },
});
// Mark all non-DONE tasks as CHANGES
await tx.task.updateMany({
where: { shotId, status: { not: "DONE" } },
data: { status: "CHANGES" },
// Clears the approval, unshares, marks the tasks needing rework and
// recalculates — including the case where every task was already DONE,
// which used to match nothing and leave the request with no effect.
await markShotForRevisions(tx, shotId);
// The shot-level verdict has to land on the versions too: the dashboard
// counters, the version badges and the client portal's own filters all
// read Version.approvalStatus, so a shot-level change request was
// invisible everywhere those look.
const shown = await tx.version.findMany({
where: { task: { shotId }, isClientVisible: true, isLatest: true },
select: { id: true },
});
await recalcShotStatus(shotId, tx);
for (const v of shown) {
await tx.approval.create({
data: {
versionId: v.id,
userId: user.id,
status: "NEEDS_CHANGES",
notes: notes ?? "Changes requested on the shot",
},
});
await tx.version.update({
where: { id: v.id },
data: { approvalStatus: "NEEDS_CHANGES" },
});
}
});
} else {
return NextResponse.json({ error: "Invalid action" }, { status: 400 });
@@ -99,8 +113,7 @@ export async function POST(
return NextResponse.json({ error: "Version not found" }, { status: 404 });
}
const email = session.email ?? `client+${token.slice(0, 8)}@review.external`;
const user = await getOrCreateClientUser(email, session.label);
const user = await getOrCreateReviewUser(session, token);
// Record approval
await db.approval.create({
@@ -126,9 +139,12 @@ export async function POST(
select: { sharedWithClient: true, shotApprovalStatus: true },
});
if (shot?.sharedWithClient && shot.shotApprovalStatus !== "CLIENT_APPROVED") {
// status is left to the recalc below — writing COMPLETE here was
// overwritten by it anyway, and disagreed with it whenever another
// task on the shot was still on CHANGES.
await db.shot.update({
where: { id: version.task.shot.id },
data: { shotApprovalStatus: "CLIENT_APPROVED", status: "COMPLETE" },
data: { shotApprovalStatus: "CLIENT_APPROVED" },
});
}
}
@@ -0,0 +1,127 @@
import { NextRequest, NextResponse } from "next/server";
import { db } from "@/lib/db";
import { validateReviewToken, findReviewUser, ownsComment } from "@/lib/review-auth";
/**
* Edit and delete for notes left through a client review link.
*
* A reviewer may only touch their own notes: the studio's comments and those of
* any other review session are read-only here, whatever the link holder sends.
* Ownership is the review session's guest User (lib/review-auth.ts) — the link
* is the credential, so everyone holding it shares that identity.
*/
/** Matches the internal addComment/editComment limits (actions/comments.ts). */
const MAX_LENGTH = 5000;
/** The annotation companion comments written by the drawing tools. */
const ANNOTATION_PREFIX = "✏️ Annotation at frame";
type Ctx = { params: Promise<{ token: string; commentId: string }> };
/**
* Resolves the request to a comment the caller is allowed to change, or the
* response explaining why not.
*
* "Not yours" is deliberately answered with 404 rather than 403: a link holder
* has no business learning which comment ids exist outside their own notes.
*/
async function authorizeCommentEdit(req: NextRequest, ctx: Ctx) {
const { token, commentId } = await ctx.params;
const result = await validateReviewToken(token, req);
if (result.type === "requiresPassword") {
return { error: NextResponse.json({ requiresPassword: true }, { status: 401 }) };
}
if (result.type === "invalid") {
return {
error: NextResponse.json({ error: "Invalid or expired review link" }, { status: 403 }),
};
}
const session = result.session;
const notFound = NextResponse.json({ error: "Comment not found" }, { status: 404 });
const comment = await db.comment.findUnique({
where: { id: commentId },
select: {
id: true,
authorId: true,
versionId: true,
frameNumber: true,
text: true,
version: {
select: {
shot: { select: { projectId: true } },
task: { select: { projectId: true } },
},
},
},
});
if (!comment) return { error: notFound };
// Same project scoping the rest of the portal applies.
const projectId = comment.version.shot?.projectId ?? comment.version.task?.projectId;
if (projectId !== session.projectId) return { error: notFound };
const user = await findReviewUser(session, token);
if (!ownsComment(comment, user?.id)) return { error: notFound };
return { comment };
}
/** PATCH — change the text of one's own note. */
export async function PATCH(req: NextRequest, ctx: Ctx) {
const authorized = await authorizeCommentEdit(req, ctx);
if (authorized.error) return authorized.error;
const { comment } = authorized;
const body = await req.json().catch(() => null);
const text = typeof body?.text === "string" ? body.text.trim() : "";
if (!text) {
return NextResponse.json({ error: "Note text is required" }, { status: 400 });
}
if (text.length > MAX_LENGTH) {
return NextResponse.json(
{ error: `Note must be ${MAX_LENGTH} characters or fewer` },
{ status: 400 }
);
}
// Only the text is editable. The frame a note is pinned to is what the studio
// works from, so moving it would silently repoint feedback someone may have
// already actioned; a note about a different frame is a new note.
const updated = await db.comment.update({
where: { id: comment.id },
data: { text },
include: {
author: { select: { id: true, name: true, image: true, email: true } },
replies: {
orderBy: { createdAt: "asc" },
include: { author: { select: { id: true, name: true, image: true, email: true } } },
},
},
});
return NextResponse.json({ comment: { ...updated, canEdit: true } });
}
/** DELETE — remove one's own note. */
export async function DELETE(req: NextRequest, ctx: Ctx) {
const authorized = await authorizeCommentEdit(req, ctx);
if (authorized.error) return authorized.error;
const { comment } = authorized;
await db.comment.delete({ where: { id: comment.id } });
// A drawing leaves a companion comment; deleting the note without the strokes
// would leave marks on the frame that nothing explains. Mirrors deleteComment
// in actions/comments.ts.
if (comment.text.startsWith(ANNOTATION_PREFIX)) {
await db.annotation.deleteMany({
where: { versionId: comment.versionId, frameNumber: comment.frameNumber },
});
}
return NextResponse.json({ success: true });
}
+4 -18
View File
@@ -1,21 +1,7 @@
import { NextRequest, NextResponse } from "next/server";
import { db } from "@/lib/db";
import { slackNotifyNewFeedback } from "@/lib/slack";
import { validateReviewToken } from "@/lib/review-auth";
/** Find or create a guest user for the client reviewer based on the session email */
async function getOrCreateClientUser(email: string, label?: string | null) {
const existing = await db.user.findUnique({ where: { email } });
if (existing) return existing;
return db.user.create({
data: {
email,
name: label ?? email.split("@")[0],
role: "CLIENT",
isActive: true,
},
});
}
import { validateReviewToken, getOrCreateReviewUser } from "@/lib/review-auth";
export async function POST(
req: NextRequest,
@@ -52,8 +38,7 @@ export async function POST(
}
// Resolve commenter identity
const email = session.email ?? `client+${token.slice(0, 8)}@review.external`;
const user = await getOrCreateClientUser(email, session.label);
const user = await getOrCreateReviewUser(session, token);
const comment = await db.comment.create({
data: {
@@ -85,5 +70,6 @@ export async function POST(
});
}
return NextResponse.json({ comment }, { status: 201 });
// canEdit mirrors the GET shape — a note you just wrote is always your own.
return NextResponse.json({ comment: { ...comment, canEdit: true } }, { status: 201 });
}
+20 -3
View File
@@ -1,6 +1,8 @@
import { NextRequest, NextResponse } from "next/server";
import { db } from "@/lib/db";
import { validateReviewToken } from "@/lib/review-auth";
import { shotThumbnail } from "@/lib/shot-thumbnail";
import { clientShotCode, clientTaskTitle } from "@/lib/shot-code";
/** GET /api/client/[token]/project — returns project + shots with tasks that have client-visible versions */
export async function GET(
@@ -43,12 +45,14 @@ export async function GET(
select: {
id: true,
shotCode: true,
clientCode: true,
episode: true,
sequence: true,
description: true,
status: true,
shotApprovalStatus: true,
thumbnailUrl: true,
generatedThumbnailUrl: true,
tasks: {
where: {
versions: { some: { isClientVisible: true } },
@@ -68,7 +72,6 @@ export async function GET(
fps: true,
duration: true,
thumbnailUrl: true,
notes: true,
createdAt: true,
},
},
@@ -100,7 +103,6 @@ export async function GET(
fps: true,
duration: true,
thumbnailUrl: true,
notes: true,
createdAt: true,
},
},
@@ -115,7 +117,22 @@ export async function GET(
return NextResponse.json({
project,
shots,
// Shots the client sees resolve the same way as internally: the reference
// still first, a render-derived one only where the show supplied none.
// Everything the client reads is in their own naming: the alias replaces
// our shot code, and the same swap runs over task titles, which carry the
// code by convention ("UNG_106_010_020_cmp_TT_v004"). The internal code is
// not sent at all — there is nothing here for it to be useful for, and
// leaking it invites the client to quote it back at us.
shots: shots.map(({ generatedThumbnailUrl, clientCode, ...shot }) => ({
...shot,
shotCode: clientShotCode({ ...shot, clientCode }),
thumbnailUrl: shotThumbnail({ ...shot, generatedThumbnailUrl }),
tasks: shot.tasks.map((task) => ({
...task,
title: clientTaskTitle(task.title, { ...shot, clientCode }),
})),
})),
assetTasks,
sessionLabel: session.label,
});
@@ -1,6 +1,7 @@
import { NextRequest, NextResponse } from "next/server";
import { db } from "@/lib/db";
import { validateReviewToken } from "@/lib/review-auth";
import { validateReviewToken, findReviewUser, ownsComment } from "@/lib/review-auth";
import { clientShotCode, clientTaskTitle } from "@/lib/shot-code";
/** GET /api/client/[token]/versions/[versionId] — returns version + comments for client portal */
export async function GET(
@@ -40,7 +41,7 @@ export async function GET(
task: {
include: {
project: { select: { id: true, name: true, code: true } },
shot: { select: { id: true, shotCode: true, highResKey: true, highResFilename: true } },
shot: { select: { id: true, shotCode: true, clientCode: true, highResKey: true, highResFilename: true } },
asset: { select: { assetCode: true, name: true } },
},
},
@@ -64,7 +65,7 @@ export async function GET(
return NextResponse.json({ error: "Version not found" }, { status: 404 });
}
const comments = await db.comment.findMany({
const commentRows = await db.comment.findMany({
where: { versionId },
orderBy: { frameNumber: "asc" },
include: {
@@ -78,9 +79,22 @@ export async function GET(
},
});
// Which notes this reviewer may edit or delete. Read-only: opening a review
// link should not create the guest User, so a session that has never posted
// simply owns nothing. The edit/delete route re-checks this — the flag drives
// the UI, it does not grant anything.
const reviewUser = await findReviewUser(session, token);
const comments = commentRows.map((c) => ({
...c,
canEdit: ownsComment(c, reviewUser?.id),
}));
// Resolve the shot that has the high-res file (comes from version.shot OR version.task.shot)
const highResShot = version.shot ?? (version.task as any)?.shot ?? null;
// The shot the title and breadcrumb are drawn from — either relation.
const namingShot = version.shot ?? ((version.task as any)?.shot ?? null);
const serializedVersion = {
...version,
fileSize: version.fileSize?.toString() ?? null,
@@ -92,17 +106,24 @@ export async function GET(
shot: version.shot
? {
...version.shot,
shotCode: clientShotCode(version.shot),
clientCode: undefined,
hasHighRes: !!version.shot.highResKey,
highResFilename: version.shot.highResFilename ?? null,
highResKey: undefined,
}
: null,
// Task titles carry the shot code by convention, so the player header gets
// the same swap as the shot list (lib/shot-code.ts).
task: version.task
? {
...version.task,
title: namingShot ? clientTaskTitle(version.task.title, namingShot) : version.task.title,
shot: (version.task as any)?.shot
? {
...((version.task as any).shot),
shotCode: clientShotCode((version.task as any).shot),
clientCode: undefined,
highResKey: undefined, // strip storage key
}
: null,
+3 -1
View File
@@ -1,5 +1,5 @@
import { NextRequest, NextResponse } from "next/server";
import { DeliveryStatus } from "@prisma/client";
import { DeliveryKind, DeliveryStatus } from "@prisma/client";
import { toErrorResponse } from "@/lib/render-pipeline/errors";
import { requirePipelineUser, requirePipelineAdmin } from "@/lib/render-pipeline/session-auth";
import {
@@ -15,10 +15,12 @@ export async function GET(req: NextRequest) {
await requirePipelineUser();
const { searchParams } = new URL(req.url);
const status = searchParams.get("status");
const kind = searchParams.get("kind");
const result = await listDeliveryPackages({
projectId: searchParams.get("projectId") ?? undefined,
episode: searchParams.get("episode") ?? undefined,
status: status ? (status as DeliveryStatus) : undefined,
kind: kind ? (kind as DeliveryKind) : undefined,
});
return NextResponse.json(result);
} catch (err) {
+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) {
@@ -1,5 +1,6 @@
import { NextRequest, NextResponse } from "next/server";
import { db } from "@/lib/db";
import { shotThumbnail } from "@/lib/shot-thumbnail";
// ── Auth ─────────────────────────────────────────────────────────────────────
@@ -91,6 +92,7 @@ export async function GET(
seqTimecodeStart: true,
seqTimecodeEnd: true,
thumbnailUrl: true,
generatedThumbnailUrl: true,
artist: {
select: { id: true, name: true, email: true },
},
@@ -111,6 +113,9 @@ export async function GET(
return NextResponse.json({
project,
pagination: { page, limit, total, pages: Math.ceil(total / limit) },
shots,
shots: shots.map(({ generatedThumbnailUrl, ...shot }) => ({
...shot,
thumbnailUrl: shotThumbnail({ ...shot, generatedThumbnailUrl }),
})),
});
}
+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 });
}
+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 });
}
}
+6 -1
View File
@@ -1,5 +1,6 @@
import { NextRequest, NextResponse } from "next/server";
import { db } from "@/lib/db";
import { shotThumbnail } from "@/lib/shot-thumbnail";
// ── Auth ─────────────────────────────────────────────────────────────────────
@@ -67,6 +68,7 @@ export async function GET(req: NextRequest) {
seqTimecodeEnd: true,
shotVersion: true,
thumbnailUrl: true,
generatedThumbnailUrl: true,
createdAt: true,
updatedAt: true,
project: {
@@ -104,5 +106,8 @@ export async function GET(req: NextRequest) {
return NextResponse.json({ error: "Shot not found" }, { status: 404 });
}
return NextResponse.json({ shot });
const { generatedThumbnailUrl, ...rest } = shot;
return NextResponse.json({
shot: { ...rest, thumbnailUrl: shotThumbnail(shot) },
});
}
+3 -1
View File
@@ -1,6 +1,7 @@
import { NextRequest, NextResponse } from "next/server";
import { auth } from "@/auth";
import { db } from "@/lib/db";
import { shotThumbnail } from "@/lib/shot-thumbnail";
export async function GET(req: NextRequest) {
const session = await auth();
@@ -33,6 +34,7 @@ export async function GET(req: NextRequest) {
shotApprovalStatus: true,
sharedWithClient: true,
thumbnailUrl: true,
generatedThumbnailUrl: true,
tasks: {
select: {
id: true,
@@ -75,7 +77,7 @@ export async function GET(req: NextRequest) {
status: shot.status,
shotApprovalStatus: shot.shotApprovalStatus,
sharedWithClient: shot.sharedWithClient,
thumbnailUrl: shot.thumbnailUrl,
thumbnailUrl: shotThumbnail(shot),
latestVersion: {
id: latest.id,
versionNumber: latest.versionNumber,
+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 });
}
}
+7 -1
View File
@@ -1,6 +1,7 @@
import { NextRequest, NextResponse } from "next/server";
import { auth } from "@/auth";
import { db } from "@/lib/db";
import { shotThumbnail } from "@/lib/shot-thumbnail";
function requireRole(role: string) {
return ["ADMIN", "PRODUCER", "SUPERVISOR"].includes(role);
@@ -27,6 +28,7 @@ export async function GET(
scene: true,
episode: true,
thumbnailUrl: true,
generatedThumbnailUrl: true,
references: {
orderBy: { sortOrder: "asc" },
select: {
@@ -41,5 +43,9 @@ export async function GET(
});
if (!shot) return NextResponse.json({ error: "Not found" }, { status: 404 });
return NextResponse.json({ shot });
const { generatedThumbnailUrl, ...rest } = shot;
return NextResponse.json({
shot: { ...rest, thumbnailUrl: shotThumbnail(shot) },
});
}
+7 -1
View File
@@ -1,6 +1,7 @@
import { NextRequest, NextResponse } from "next/server";
import { auth } from "@/auth";
import { db } from "@/lib/db";
import { shotThumbnail } from "@/lib/shot-thumbnail";
// ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -409,13 +410,18 @@ export async function GET(req: NextRequest) {
where: { projectId },
select: {
id: true, shotCode: true, scene: true, episode: true, shotNumber: true,
description: true, notes: true, status: true, thumbnailUrl: true,
description: true, notes: true, status: true,
thumbnailUrl: true, generatedThumbnailUrl: true,
frameStart: true, frameEnd: true, fps: true, isKeyShot: true, shotVersion: true,
shotGroup: { select: { id: true, name: true } },
},
orderBy: [{ episode: "asc" }, { scene: "asc" }, { shotNumber: "asc" }],
});
// Collapse the two columns before anything reads them, so the "only shots
// with thumbnails" filter and the page renderer agree on what counts as one.
shots = shots.map((s) => ({ ...s, thumbnailUrl: shotThumbnail(s) }));
if (onlyThumbs) shots = shots.filter((s) => !!s.thumbnailUrl);
if (epFilter.length) shots = shots.filter((s) => epFilter.includes(s.episode ?? ""));
if (grpFilter.length) shots = shots.filter((s) => grpFilter.includes(s.shotGroup?.id ?? ""));
+10 -1
View File
@@ -1,6 +1,7 @@
import { NextRequest, NextResponse } from "next/server";
import { auth } from "@/auth";
import { db } from "@/lib/db";
import { shotThumbnail } from "@/lib/shot-thumbnail";
// GET /api/storyboard/shots?projectId=xxx
export async function GET(req: NextRequest) {
@@ -26,6 +27,7 @@ export async function GET(req: NextRequest) {
notes: true,
status: true,
thumbnailUrl: true,
generatedThumbnailUrl: true,
frameStart: true,
frameEnd: true,
fps: true,
@@ -40,5 +42,12 @@ export async function GET(req: NextRequest) {
],
});
return NextResponse.json({ shots });
// The reference still wins; a render-derived one fills the gap where a show
// shipped no stills at all (lib/shot-thumbnail.ts).
return NextResponse.json({
shots: shots.map(({ generatedThumbnailUrl, ...shot }) => ({
...shot,
thumbnailUrl: shotThumbnail({ ...shot, generatedThumbnailUrl }),
})),
});
}
-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">
+179 -1
View File
@@ -31,6 +31,8 @@ import {
Copy,
Check,
Download,
Pencil,
Trash2,
} from "lucide-react";
import { useReviewStore } from "@/hooks/use-review-player";
import { ReviewPasswordGate } from "@/components/clients/ReviewPasswordGate";
@@ -42,6 +44,8 @@ interface Comment {
text: string;
isResolved: boolean;
createdAt: string;
/** This reviewer wrote it, so they can change or remove it. Set by the API. */
canEdit?: boolean;
author: { id: string; name: string | null; image: string | null; email: string };
replies: { id: string; text: string; createdAt: string; author: { name: string | null } }[];
}
@@ -104,6 +108,13 @@ export default function ClientReviewPage({
const [commentFrame, setCommentFrame] = useState<number | null>(null);
const [submittingComment, setSubmittingComment] = useState(false);
// Editing / deleting one's own notes
const [editingCommentId, setEditingCommentId] = useState<string | null>(null);
const [editingText, setEditingText] = useState("");
const [savingEdit, setSavingEdit] = useState(false);
const [deletingComment, setDeletingComment] = useState<Comment | null>(null);
const [deleting, setDeleting] = useState(false);
// Approval dialog
const [approvalDialog, setApprovalDialog] = useState<{
open: boolean;
@@ -209,6 +220,58 @@ export default function ClientReviewPage({
}
};
const beginEditComment = (comment: Comment) => {
setEditingCommentId(comment.id);
setEditingText(comment.text);
};
const cancelEditComment = () => {
setEditingCommentId(null);
setEditingText("");
};
const handleSaveEditedComment = async () => {
const trimmed = editingText.trim();
if (!editingCommentId || !trimmed || !version) return;
setSavingEdit(true);
try {
const res = await fetch(`/api/client/${token}/comment/${editingCommentId}`, {
method: "PATCH",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ text: trimmed }),
});
if (!res.ok) throw new Error("Failed to save note");
cancelEditComment();
await refreshComments(token, version.id);
toast({ title: "Note updated" });
} catch {
toast({ title: "Failed to update note", variant: "destructive" });
} finally {
setSavingEdit(false);
}
};
const handleDeleteComment = async () => {
if (!deletingComment || !version) return;
setDeleting(true);
try {
const res = await fetch(`/api/client/${token}/comment/${deletingComment.id}`, {
method: "DELETE",
});
if (!res.ok) throw new Error("Failed to delete note");
setDeletingComment(null);
// Deleting a drawing note also removes its strokes server-side, and those
// live in the canvas's own state — a full reload remounts the player so
// the frame does not keep showing marks that no longer exist.
loadVersion(token, version.id);
toast({ title: "Note deleted" });
} catch {
toast({ title: "Failed to delete note", variant: "destructive" });
} finally {
setDeleting(false);
}
};
const handleDownloadHighRes = async () => {
const shotId = version?.highResShotId ?? version?.shot?.id;
if (!shotId || !token) return;
@@ -510,8 +573,51 @@ export default function ClientReviewPage({
<div className="space-y-3">
{comments.map((comment) => (
<div key={comment.id} className="space-y-2">
{editingCommentId === comment.id ? (
// Editing replaces the note in place, so it stays in the
// list at its own frame rather than jumping to a dialog.
<div className="rounded-lg bg-zinc-800/70 p-3 space-y-2">
<div className="flex items-center gap-2">
<span className="text-xs text-zinc-400">Editing note</span>
<span className="ml-auto font-mono text-xs text-amber-400/80">
{frameToTimecode(comment.frameNumber, version.fps)}
</span>
</div>
<Textarea
value={editingText}
onChange={(e) => setEditingText(e.target.value)}
rows={3}
maxLength={5000}
autoFocus
className="bg-zinc-900 border-zinc-700 text-sm resize-none"
onKeyDown={(e) => {
if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) handleSaveEditedComment();
if (e.key === "Escape") cancelEditComment();
}}
/>
<div className="flex gap-2">
<Button
size="sm"
className="h-7 text-xs"
disabled={!editingText.trim() || savingEdit}
onClick={handleSaveEditedComment}
>
{savingEdit ? "Saving…" : "Save"}
</Button>
<Button
size="sm"
variant="ghost"
className="h-7 text-xs"
onClick={cancelEditComment}
disabled={savingEdit}
>
Cancel
</Button>
</div>
</div>
) : (
<div
className="rounded-lg bg-zinc-800/70 p-3 space-y-2 cursor-pointer hover:bg-zinc-700/70 transition-colors"
className="group rounded-lg bg-zinc-800/70 p-3 space-y-2 cursor-pointer hover:bg-zinc-700/70 transition-colors"
onClick={() => playerRef.current?.seekToFrame(comment.frameNumber)}
title={`Jump to frame ${comment.frameNumber}`}
>
@@ -529,7 +635,36 @@ export default function ClientReviewPage({
</span>
</div>
<p className="text-sm text-zinc-200 leading-relaxed">{comment.text}</p>
{comment.canEdit && (
// Own notes only. The buttons stop propagation so they
// do not also seek the player to the note's frame.
<div className="flex items-center gap-1 pt-1 opacity-0 group-hover:opacity-100 focus-within:opacity-100 transition-opacity">
<button
type="button"
className="flex items-center gap-1 rounded px-1.5 py-0.5 text-xs text-zinc-400 hover:text-white hover:bg-zinc-700"
onClick={(e) => {
e.stopPropagation();
beginEditComment(comment);
}}
>
<Pencil className="h-3 w-3" />
Edit
</button>
<button
type="button"
className="flex items-center gap-1 rounded px-1.5 py-0.5 text-xs text-zinc-400 hover:text-red-400 hover:bg-zinc-700"
onClick={(e) => {
e.stopPropagation();
setDeletingComment(comment);
}}
>
<Trash2 className="h-3 w-3" />
Delete
</button>
</div>
)}
</div>
)}
{comment.replies.map((reply) => (
<div key={reply.id} className="ml-4 rounded-lg bg-zinc-800/40 border border-zinc-700/50 p-2.5">
<span className="text-xs text-zinc-400 font-medium">
@@ -658,6 +793,49 @@ export default function ClientReviewPage({
</DialogFooter>
</DialogContent>
</Dialog>
{/* Delete confirmation — a note may already have been actioned by the
studio, so removing it is worth one deliberate step. */}
<Dialog
open={!!deletingComment}
onOpenChange={(open) => { if (!open) setDeletingComment(null); }}
>
<DialogContent className="sm:max-w-md">
<DialogHeader>
<DialogTitle>Delete this note?</DialogTitle>
</DialogHeader>
{deletingComment && (
<div className="space-y-2">
<p className="text-xs text-zinc-500 font-mono">
Frame {deletingComment.frameNumber} ·{" "}
{version ? frameToTimecode(deletingComment.frameNumber, version.fps) : ""}
</p>
<p className="rounded bg-zinc-800/70 p-3 text-sm text-zinc-200">
{deletingComment.text}
</p>
<p className="text-xs text-zinc-500">
This removes it for everyone, including the studio. It cannot be undone.
</p>
</div>
)}
<DialogFooter>
<Button
variant="ghost"
onClick={() => setDeletingComment(null)}
disabled={deleting}
>
Cancel
</Button>
<Button
variant="destructive"
onClick={handleDeleteComment}
disabled={deleting}
>
{deleting ? "Deleting…" : "Delete note"}
</Button>
</DialogFooter>
</DialogContent>
</Dialog>
</div>
);
}
+119 -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,13 @@ 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(),
autoShotThumbnail: z.boolean().optional(),
});
type SettingsFormValues = z.infer<typeof settingsSchema>;
@@ -67,6 +74,14 @@ 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;
autoShotThumbnail?: boolean | null;
} | null;
};
clients: Client[];
teamMembers: TeamMember[];
@@ -109,9 +124,20 @@ 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 ?? "",
autoShotThumbnail: project.pipelineConfig?.autoShotThumbnail ?? false,
},
});
// 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 +156,14 @@ 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,
autoShotThumbnail: data.autoShotThumbnail ?? false,
},
});
toast({ title: "Project settings saved" });
router.refresh();
@@ -338,6 +372,90 @@ 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 className="pt-4 mt-4 border-t border-border/60">
<label className="flex items-start gap-2.5 cursor-pointer group">
<input
id="autoShotThumbnail"
type="checkbox"
className="accent-amber-500 h-3.5 w-3.5 mt-0.5"
{...register("autoShotThumbnail")}
/>
<span className="space-y-1">
<span className="block text-sm group-hover:text-foreground transition-colors">
Use render frames as shot thumbnails
</span>
<span className="block text-xs text-muted-foreground">
Every finished export sets its shot&apos;s thumbnail from the render.
A thumbnail supplied with the brief always takes priority and is
never overwritten &mdash; turn this on for shows that arrive with no
stills at all, where the alternative is an empty grid.
</span>
</span>
</label>
</div>
</div>
</section>
{/* Save */}
<div className="flex justify-end pt-2">
<Button type="submit" disabled={isSubmitting || !isDirty} className="min-w-[120px]">
+2 -1
View File
@@ -23,6 +23,7 @@ import {
ActiveDragData,
} from "@/app/(dashboard)/schedule/SchedulePageClient";
import { TASK_TYPE_LABELS } from "@/components/tasks/TaskCard";
import { shotThumbnail } from "@/lib/shot-thumbnail";
const STATUS_STYLES: Record<
TaskStatus,
@@ -134,7 +135,7 @@ export function ScheduleTaskBlock({
const statusStyle = STATUS_STYLES[task.status];
const contextCode = task.shot?.shotCode ?? task.asset?.assetCode;
const contextName = task.shot?.shotCode ?? task.asset?.name ?? task.title;
const thumbnail = task.shot?.thumbnailUrl ?? null;
const thumbnail = shotThumbnail(task.shot);
const isOverdue =
task.dueDate &&
+3 -2
View File
@@ -33,6 +33,7 @@ import {
import type { ShotWithDetails } from "@/types";
import { duplicateShot } from "@/actions/shots";
import { useToast } from "@/components/ui/use-toast";
import { shotThumbnail } from "@/lib/shot-thumbnail";
interface ShotCardProps {
shot: ShotWithDetails;
@@ -128,9 +129,9 @@ export function ShotCard({ shot, projectId, compact = false, canManage = false }
{/* Thumbnail with cinema scope aspect ratio (2.39:1) */}
<div className="mb-3 -mx-6 -mt-6 overflow-hidden rounded-t-lg">
<div className="relative w-full aspect-[2.39]">
{shot.thumbnailUrl || latestVersion?.thumbnailUrl || latestVersion?.posterUrl ? (
{shotThumbnail(shot) || latestVersion?.thumbnailUrl || latestVersion?.posterUrl ? (
<Image
src={shot.thumbnailUrl || latestVersion?.thumbnailUrl || latestVersion?.posterUrl || ""}
src={shotThumbnail(shot) || latestVersion?.thumbnailUrl || latestVersion?.posterUrl || ""}
alt={shot.shotCode}
fill
className="object-cover"
+74 -20
View File
@@ -1,8 +1,13 @@
"use client";
import Link from "next/link";
import { useState } from "react";
import { useRouter } from "next/navigation";
import Image from "next/image";
import { useQuery } from "@tanstack/react-query";
import { Layers, ExternalLink } from "lucide-react";
import { Layers, ExternalLink, ImageIcon, Loader2 } from "lucide-react";
import { promoteExportThumbnail } from "@/actions/shots";
import { useToast } from "@/components/ui/use-toast";
import { cn } from "@/lib/utils";
import {
EXPORT_STATUS_STYLES,
@@ -16,6 +21,7 @@ interface ExportRow {
statusChangedAt: string;
createdAt: string;
outputDir: string;
thumbnailUrl: string | null;
job: {
attempt: number;
progress: number;
@@ -29,6 +35,29 @@ interface ExportRow {
* pipeline history for this shot, linking into the Export detail page.
*/
export function ShotExportsTab({ shotId }: { shotId: string }) {
const router = useRouter();
const { toast } = useToast();
const [promotingId, setPromotingId] = useState<string | null>(null);
// Take this export's frame as the shot's thumbnail. Fills in only where the
// shot has no reference frame of its own (§9.1a) — it never overwrites one.
const promote = async (exportId: string, versionString: string) => {
setPromotingId(exportId);
try {
await promoteExportThumbnail(shotId, exportId);
toast({ title: `Shot thumbnail taken from ${versionString}` });
router.refresh();
} catch (err) {
toast({
title: "Could not use that frame",
description: (err as Error).message,
variant: "destructive",
});
} finally {
setPromotingId(null);
}
};
const { data, isLoading } = useQuery({
queryKey: ["shot-exports", shotId],
queryFn: async () => {
@@ -56,29 +85,54 @@ export function ShotExportsTab({ shotId }: { shotId: string }) {
return (
<div className="space-y-2">
{exports.map((e) => (
<Link
<div
key={e.id}
href={`/pipeline/exports/${e.id}`}
className="flex items-center gap-4 rounded-lg border border-border bg-card p-4 hover:border-zinc-600 transition-colors"
>
<span className="font-mono text-sm text-white w-14">{e.versionString}</span>
<span
className={cn(
"rounded-full border px-2 py-0.5 text-xs whitespace-nowrap",
EXPORT_STATUS_STYLES[e.status] ?? "bg-zinc-500/15 text-zinc-300 border-zinc-500/30"
<Link href={`/pipeline/exports/${e.id}`} className="flex flex-1 min-w-0 items-center gap-4">
{e.thumbnailUrl ? (
<span className="relative h-8 w-[76px] shrink-0 overflow-hidden rounded border border-border">
<Image src={e.thumbnailUrl} alt="" fill className="object-cover" sizes="76px" />
</span>
) : (
<span className="h-8 w-[76px] shrink-0 rounded border border-border bg-zinc-900" />
)}
>
{statusLabel(e.status)}
</span>
<span className="flex-1 min-w-0 truncate text-xs text-muted-foreground">
{e.job?.machineName ? `${e.job.machineName} · attempt ${e.job.attempt} · ` : ""}
{e.outputDir}
</span>
<span className="text-xs text-muted-foreground whitespace-nowrap">
{new Date(e.createdAt).toLocaleDateString()}
</span>
<ExternalLink className="h-3.5 w-3.5 text-muted-foreground shrink-0" />
</Link>
<span className="font-mono text-sm text-white w-14">{e.versionString}</span>
<span
className={cn(
"rounded-full border px-2 py-0.5 text-xs whitespace-nowrap",
EXPORT_STATUS_STYLES[e.status] ?? "bg-zinc-500/15 text-zinc-300 border-zinc-500/30"
)}
>
{statusLabel(e.status)}
</span>
<span className="flex-1 min-w-0 truncate text-xs text-muted-foreground">
{e.job?.machineName ? `${e.job.machineName} · attempt ${e.job.attempt} · ` : ""}
{e.outputDir}
</span>
<span className="text-xs text-muted-foreground whitespace-nowrap">
{new Date(e.createdAt).toLocaleDateString()}
</span>
<ExternalLink className="h-3.5 w-3.5 text-muted-foreground shrink-0" />
</Link>
{e.thumbnailUrl && (
<button
type="button"
onClick={() => promote(e.id, e.versionString)}
disabled={promotingId !== null}
title="Use this frame as the shot thumbnail (never replaces one supplied with the brief)"
className="shrink-0 flex items-center gap-1.5 rounded-md border border-border px-2 py-1 text-xs text-muted-foreground hover:text-foreground hover:border-zinc-600 disabled:opacity-50 transition-colors"
>
{promotingId === e.id ? (
<Loader2 className="h-3.5 w-3.5 animate-spin" />
) : (
<ImageIcon className="h-3.5 w-3.5" />
)}
Use frame
</button>
)}
</div>
))}
</div>
);
+102 -2
View File
@@ -18,9 +18,14 @@ import {
SelectTrigger,
SelectValue,
} from "@/components/ui/select";
import { updateShot, deleteShot } from "@/actions/shots";
import {
updateShot,
deleteShot,
promoteExportThumbnail,
clearGeneratedThumbnail,
} from "@/actions/shots";
import { useToast } from "@/components/ui/use-toast";
import { Upload, X, Film, ImageIcon, Trash2, BookImage, Loader2 } from "lucide-react";
import { Upload, X, Film, ImageIcon, Trash2, BookImage, Loader2, Sparkles } from "lucide-react";
// ─── Shot References ──────────────────────────────────────────────────────────
@@ -191,6 +196,8 @@ interface ShotSettingsTabProps {
dueDate: Date | string | null;
artistId: string | null;
thumbnailUrl: string | null;
generatedThumbnailUrl?: string | null;
generatedThumbnailFrom?: string | null;
projectId: string;
};
artists: Artist[];
@@ -208,6 +215,48 @@ export function ShotSettingsTab({ shot, artists, onSaved }: ShotSettingsTabProps
const [clearThumbnail, setClearThumbnail] = useState(false);
const fileInputRef = useRef<HTMLInputElement>(null);
// Render-derived still, managed separately from the reference frame above.
const [generatedUrl, setGeneratedUrl] = useState(shot.generatedThumbnailUrl ?? null);
const [generatedFrom, setGeneratedFrom] = useState(shot.generatedThumbnailFrom ?? null);
const [isPromoting, setIsPromoting] = useState(false);
const handlePromote = async () => {
setIsPromoting(true);
try {
const res = await promoteExportThumbnail(shot.id);
setGeneratedUrl(res.generatedThumbnailUrl);
setGeneratedFrom(res.generatedThumbnailFrom);
toast({ title: `Thumbnail taken from ${res.generatedThumbnailFrom}` });
router.refresh();
} catch (err) {
toast({
title: "Could not use a render frame",
description: (err as Error).message,
variant: "destructive",
});
} finally {
setIsPromoting(false);
}
};
const handleClearGenerated = async () => {
setIsPromoting(true);
try {
await clearGeneratedThumbnail(shot.id);
setGeneratedUrl(null);
setGeneratedFrom(null);
router.refresh();
} catch (err) {
toast({
title: "Could not clear the render frame",
description: (err as Error).message,
variant: "destructive",
});
} finally {
setIsPromoting(false);
}
};
const formatDate = (d: Date | string | null) => {
if (!d) return "";
return new Date(d).toISOString().split("T")[0];
@@ -452,6 +501,57 @@ export function ShotSettingsTab({ shot, artists, onSaved }: ShotSettingsTabProps
className="hidden"
onChange={handleThumbnailChange}
/>
{/* ── From renders ───────────────────────────────────────────────────
A second, separate still taken from a finished export. It never
replaces the one above — it only shows where there is none — so a
show that ships reference frames keeps them, and a show that ships
none stops rendering empty grids. */}
<div className="pt-4 mt-2 border-t border-border/60 space-y-3">
<div className="flex items-center gap-2 text-xs font-medium text-zinc-400">
<Sparkles className="h-3.5 w-3.5 text-amber-500/70" />
From renders
</div>
{generatedUrl ? (
<div className="flex items-start gap-3">
<div className="relative w-40 aspect-[2.39] rounded-md overflow-hidden border border-border shrink-0">
<Image src={generatedUrl} alt={shot.shotCode} fill className="object-cover" />
</div>
<div className="space-y-2 min-w-0">
<p className="text-xs text-muted-foreground">
{generatedFrom ? <>Taken from <span className="font-mono">{generatedFrom}</span>.</> : "Taken from a render."}{" "}
{thumbnailPreview && !clearThumbnail
? "Not shown anywhere while this shot has a thumbnail of its own."
: "Shown wherever this shot appears, until a thumbnail is uploaded above."}
</p>
<div className="flex gap-2">
<Button type="button" variant="outline" size="sm" onClick={handlePromote} disabled={isPromoting}>
{isPromoting ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : "Refresh from latest"}
</Button>
<Button type="button" variant="ghost" size="sm" onClick={handleClearGenerated} disabled={isPromoting}>
Remove
</Button>
</div>
</div>
</div>
) : (
<div className="space-y-2">
<p className="text-xs text-muted-foreground">
Take a frame from this shot&apos;s most recent finished export. Never
replaces the thumbnail above &mdash; it only fills in where there
isn&apos;t one.
</p>
<Button type="button" variant="outline" size="sm" onClick={handlePromote} disabled={isPromoting}>
{isPromoting ? (
<><Loader2 className="h-3.5 w-3.5 animate-spin mr-1.5" /> Fetching&hellip;</>
) : (
"Use latest render frame"
)}
</Button>
</div>
)}
</div>
</div>
{/* References */}
+20 -3
View File
@@ -9,6 +9,7 @@ import { Textarea } from "@/components/ui/textarea";
import { useToast } from "@/components/ui/use-toast";
import { updateShotSlate } from "@/actions/shots";
import type { ShotWithDetails } from "@/types";
import { shotThumbnail } from "@/lib/shot-thumbnail";
interface Props {
shot: ShotWithDetails;
@@ -48,10 +49,16 @@ export function ShotSlateTab({ shot, projectName, onSaved }: Props) {
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")}`;
const versionName = `${shot.shotCode}_cmp_TT_${shot.shotVersion ?? "v001"}`;
// 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)
@@ -65,6 +72,7 @@ export function ShotSlateTab({ shot, projectName, onSaved }: Props) {
slateDescription: slateDescription.trim() || null,
slateVfxScope: slateVfxScope.trim() || null,
slateSubmissionNote: slateSubmissionNote.trim() || null,
clientCode: clientCode.trim() || null,
});
toast({ title: "Slate saved" });
onSaved();
@@ -105,6 +113,15 @@ export function ShotSlateTab({ shot, projectName, onSaved }: Props) {
</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}
@@ -148,9 +165,9 @@ export function ShotSlateTab({ shot, projectName, onSaved }: Props) {
<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 ? (
{shotThumbnail(shot) ? (
<Image
src={shot.thumbnailUrl}
src={shotThumbnail(shot)!}
alt={shot.shotCode}
width={224}
height={126}
+5 -1
View File
@@ -42,7 +42,11 @@ interface KanbanTask {
status: TaskStatus;
priority: string;
dueDate: Date | null;
shot?: { shotCode: string; thumbnailUrl?: string | null } | null;
shot?: {
shotCode: string;
thumbnailUrl?: string | null;
generatedThumbnailUrl?: string | null;
} | null;
asset?: { assetCode: string; name: string } | null;
assignedArtist?: {
id: string;
+11 -4
View File
@@ -19,6 +19,7 @@ import {
import { TaskStatus, TaskType } from "@prisma/client";
import { TASK_STATUS_CONFIG, TASK_TYPE_LABELS } from "./TaskCard";
import { formatDistanceToNow } from "date-fns";
import { shotThumbnail } from "@/lib/shot-thumbnail";
const PRIORITY_DOT: Record<string, string> = {
LOW: "bg-zinc-500",
@@ -34,7 +35,11 @@ interface KanbanTask {
status: TaskStatus;
priority: string;
dueDate: Date | null;
shot?: { shotCode: string; thumbnailUrl?: string | null } | null;
shot?: {
shotCode: string;
thumbnailUrl?: string | null;
generatedThumbnailUrl?: string | null;
} | null;
asset?: { assetCode: string; name: string } | null;
assignedArtist?: { id: string; name: string | null; email: string; image: string | null } | null;
_count?: { versions: number };
@@ -71,11 +76,12 @@ export function KanbanCard({ task, isDragOverlay = false }: KanbanCardProps) {
const contextCode = task.shot?.shotCode ?? task.asset?.assetCode;
// Resolve thumbnail: prefer latest version thumbnail, then shot thumbnail
// Resolve thumbnail: prefer latest version thumbnail, then the shot's own
// (reference frame first, render-derived one only as a fallback).
const thumbnail =
latestVersion?.thumbnailUrl ??
latestVersion?.posterUrl ??
task.shot?.thumbnailUrl ??
shotThumbnail(task.shot) ??
null;
return (
@@ -137,7 +143,8 @@ export function KanbanCard({ task, isDragOverlay = false }: KanbanCardProps) {
</span>
{latestVersion.approvalStatus === "APPROVED" ? (
<CheckCircle2 className="h-3.5 w-3.5 text-emerald-500" />
) : latestVersion.approvalStatus === "CHANGES_REQUESTED" ? (
) : latestVersion.approvalStatus === "NEEDS_CHANGES" ||
latestVersion.approvalStatus === "REJECTED" ? (
<XCircle className="h-3.5 w-3.5 text-red-500" />
) : (
<Clock className="h-3.5 w-3.5 text-zinc-600" />
+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 } };
}
+8
View File
@@ -11,6 +11,14 @@ export const PIPELINE_CONFIG_DEFAULTS = {
"render.maxAttempts": 3,
"render.stallTimeoutSeconds": 600,
"render.urgentPriorityThreshold": 20,
/**
* 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.
+77 -9
View File
@@ -1,9 +1,10 @@
import { DeliveryStatus, Prisma } from "@prisma/client";
import { DeliveryKind, 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";
import { clientShotCode } from "@/lib/shot-code";
/**
* Delivery builder (RenderPipeline2 §11). The web app decides *what* goes in a
@@ -19,26 +20,43 @@ import { getConfigNumber, getConfigValue } from "./config";
export interface DeliveryConfig {
packageNameTemplate: string;
layout: { packageDir: string; shotDir: string; reportFile: string };
/**
* MOV review packages (§11.6). A formal review is shared as a flat, dated
* folder of preview MOVs, so it gets its own name template and its own
* directory under the delivery root — never mixed in with the episode
* folders that hold shippable EXR packages.
*/
reviewNameTemplate: string;
layout: { packageDir: string; shotDir: string; reportFile: string; reviewDir: 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",
reviewNameTemplate: "{yyyymmdd}_Producer_review",
layout: {
packageDir: "{deliveryRoot}/{episode}/{packageName}",
shotDir: "{packageDir}/{shotCode}",
reportFile: "{packageDir}/{packageName}_report.csv",
reviewDir: "{deliveryRoot}/PRODUCER_REVIEWS/{packageName}",
},
deliveryRoot: "//SAN/DELIVERY",
includeMovs: true,
checksumAlgo: "xxh64",
reportFormats: ["csv", "json"],
copyMode: "auto",
verifyMode: "auto",
};
/**
@@ -216,7 +234,7 @@ export async function createDeliveryPackage(input: CreateDeliveryInput, userId:
...(input.exportIds?.length ? { id: { in: input.exportIds } } : {}),
...(input.episode ? { shot: { episode: input.episode } } : {}),
},
include: { shot: { select: { id: true, shotCode: true, episode: true } } },
include: { shot: { select: { id: true, shotCode: true, clientCode: true, episode: true } } },
orderBy: { shotId: "asc" },
});
@@ -285,6 +303,7 @@ export async function createDeliveryPackage(input: CreateDeliveryInput, userId:
exportId: e.id,
shotId: e.shotId,
shotCode: e.shot.shotCode,
clientCode: e.shot.clientCode,
versionString: e.versionString,
})),
});
@@ -333,10 +352,25 @@ export interface DeliveryManifestItem {
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";
/**
* EXR_DELIVERY builds the per-shot folders of EXRs + MOVs; MOV_REVIEW builds
* a flat folder of preview MOVs only. One job type, one claim path, one
* verification story — the worker branches on this.
*/
kind: DeliveryKind;
packageId: string;
packageName: string;
packageNumber: number;
@@ -345,6 +379,7 @@ export interface DeliveryManifest {
reportFile: string;
includeMovs: boolean;
copyMode: string;
verifyMode: string;
checksumAlgo: string;
reportFormats: string[];
items: DeliveryManifestItem[];
@@ -357,7 +392,17 @@ export async function buildDeliveryJobManifest(
const pkg = await tx.deliveryPackage.findUniqueOrThrow({
where: { id: packageId },
include: {
items: { include: { export: true } },
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 } },
},
});
@@ -372,6 +417,7 @@ export async function buildDeliveryJobManifest(
return {
stage: "DELIVERY",
kind: pkg.kind,
packageId: pkg.id,
packageName: pkg.name,
packageNumber: pkg.packageNumber,
@@ -380,6 +426,7 @@ export async function buildDeliveryJobManifest(
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) => ({
@@ -394,11 +441,17 @@ export async function buildDeliveryJobManifest(
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.shotCode,
shotCode: clientShotCode(item),
versionString: item.versionString,
}),
deliveredBaseName: item.clientCode
? `${item.clientCode}_${item.versionString}`
: `${item.shotCode}_cmp_TT_${item.versionString}`,
})),
};
}
@@ -414,8 +467,8 @@ export const deliveryReportSchema = z.object({
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(),
totalBytes: z.number().nonnegative().optional(),
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(),
@@ -485,7 +538,9 @@ export async function reportDeliveryBuild(jobId: string, body: DeliveryReport) {
const failed = body.items.filter((i) => i.status === "FAILED");
const success = body.ok && failed.length === 0 && verified.length === pkg.items.length;
if (success) {
// A review is not a delivery: the same version is shown in as many reviews
// as it takes, so building one must never advance the Export state machine.
if (success && pkg.kind === "EXR_DELIVERY") {
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") {
@@ -524,12 +579,18 @@ export async function reportDeliveryBuild(jobId: string, body: DeliveryReport) {
// ── E17 / E19 / cancel ───────────────────────────────────────────────────────
export async function listDeliveryPackages(filter: { projectId?: string; episode?: string; status?: DeliveryStatus }) {
export async function listDeliveryPackages(filter: {
projectId?: string;
episode?: string;
status?: DeliveryStatus;
kind?: DeliveryKind;
}) {
const packages = await db.deliveryPackage.findMany({
where: {
...(filter.projectId ? { projectId: filter.projectId } : {}),
...(filter.episode ? { episode: filter.episode } : {}),
...(filter.status ? { status: filter.status } : {}),
...(filter.kind ? { kind: filter.kind } : {}),
},
orderBy: { createdAt: "desc" },
include: {
@@ -543,6 +604,7 @@ export async function listDeliveryPackages(filter: { projectId?: string; episode
id: p.id,
packageNumber: p.packageNumber,
name: p.name,
kind: p.kind,
episode: p.episode,
status: p.status,
rootPath: p.rootPath,
@@ -570,6 +632,12 @@ export async function markDelivered(packageId: string, userId: string) {
if (pkg.status !== "READY") {
throw new PipelineError(409, `Package is ${pkg.status} — only a READY package can be marked delivered`);
}
if (pkg.kind !== "EXR_DELIVERY") {
throw new PipelineError(
409,
"A MOV review package is shared for review, not delivered — it has no delivered state"
);
}
for (const item of pkg.items) {
const exportRow = await tx.export.findUnique({ where: { id: item.exportId }, select: { id: true, status: true } });
+19
View File
@@ -0,0 +1,19 @@
import { describe, it, expect } from "vitest";
import { renderOutputBase } from "./exports";
import { nextTaskTitle } from "./preview";
describe("renderOutputBase", () => {
it("follows the panel's house convention", () => {
expect(renderOutputBase("UNG_102_019_010", "v001")).toBe("UNG_102_019_010_cmp_TT_v001");
});
// createExport names the comp task it creates after this basename, and
// buildPreviewManifest names the MOV/MP4 off the same call — so a shot queued
// with no task ends up with a task titled exactly like its preview file. The
// title already carries the version, which makes finalizePreview's rename of
// the task to the delivered version a no-op on that first export.
it("gives a freshly created comp task a title finalizePreview leaves alone", () => {
const title = renderOutputBase("UNG_102_019_010", "v003");
expect(nextTaskTitle(title, "v003")).toBe(title);
});
});
+62 -5
View File
@@ -4,6 +4,7 @@ import { PipelineError } from "./errors";
import { describePlateProvenance, renderManifestSchema, type RenderManifest } from "./manifest";
import { applyTransition, type TransitionActor } from "./transitions";
import { getConfigNumber, getConfigValue } from "./config";
import { recalcShotStatus } from "@/lib/shot-status";
/** Statuses in which a shot has a live export in flight (§6.4 E1 409 rule). */
const ACTIVE_STATUSES: ExportStatus[] = [
@@ -48,7 +49,7 @@ function nextExrOutputBase(current: string | null, shotCode: string, versionStri
* shot-code based and deliberately excludes the source clip name that
* `Shot.exrOutput` carries from the EDL import.
*/
function renderOutputBase(shotCode: string, versionString: string): string {
export function renderOutputBase(shotCode: string, versionString: string): string {
return `${shotCode}_cmp_TT_${versionString}`;
}
@@ -63,6 +64,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;
}
/**
@@ -82,7 +90,6 @@ export async function createExport(input: CreateExportInput) {
where: { id: manifest.shotId },
include: {
project: { select: { id: true, code: true, showId: true, projectType: true } },
tasks: { where: { type: "COMP" }, orderBy: { sortOrder: "asc" }, take: 1, select: { id: true } },
},
});
if (!shot) throw new PipelineError(404, `Shot not found: ${manifest.shotId}`);
@@ -150,6 +157,43 @@ export async function createExport(input: CreateExportInput) {
const versionString = freshShot.shotVersion ?? formatVersionString(versionNumber);
const exrBase = nextExrOutputBase(freshShot.exrOutput, shot.shotCode, versionString);
// Every Version the pipeline registers hangs off a Task, so a shot with
// no comp task renders fine and then has its preview land nowhere the
// app shows it — the export completes and the artist sees nothing.
// Give the export the task it needs, named after the preview file it
// will produce (the same name the manual batch upload picks, and the
// one finalizePreview's rename keeps in step from here on).
//
// The lookup is repeated inside the transaction because `shot` was read
// before it opened, and because the P2002 retry above re-runs this
// block: a rolled-back attempt takes its task with it.
const existingTask = await tx.task.findFirst({
where: { shotId: shot.id, type: "COMP" },
orderBy: { sortOrder: "asc" },
select: { id: true },
});
let taskId = existingTask?.id ?? null;
let taskCreated = false;
if (!taskId) {
const lastTask = await tx.task.findFirst({
where: { shotId: shot.id },
orderBy: { sortOrder: "desc" },
select: { sortOrder: true },
});
const task = await tx.task.create({
data: {
title: renderOutputBase(shot.shotCode, versionString),
type: "COMP",
shotId: shot.id,
projectId: shot.project.id,
createdById: submittedBy?.id ?? null,
sortOrder: (lastTask?.sortOrder ?? -1) + 1,
},
});
taskId = task.id;
taskCreated = true;
}
// {root}/{showId}/[{episode} for episodic]/{shotCode}/{version}
const showSegment = shot.project.showId || shot.project.code;
const episodeSegment =
@@ -180,7 +224,7 @@ export async function createExport(input: CreateExportInput) {
data: {
shotId: shot.id,
projectId: shot.project.id,
taskId: shot.tasks[0]?.id ?? null,
taskId,
versionNumber,
versionString,
status: "QUEUED",
@@ -197,6 +241,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,
},
@@ -238,11 +283,19 @@ export async function createExport(input: CreateExportInput) {
actorType: "USER",
actorId: submittedBy?.id ?? null,
note:
`Queue Export ${versionString}${input.force ? " (force)" : ""} — ` +
`${provenance.ok ? "" : "WARNING: "}${provenance.note}`,
`Queue Export ${versionString}${input.force ? " (force)" : ""}` +
`${input.skipPreview ? " (skip preview)" : ""} — ` +
`${provenance.ok ? "" : "WARNING: "}${provenance.note}` +
(taskCreated
? ` — shot had no comp task, created "${renderOutputBase(shot.shotCode, versionString)}" for the review version`
: ""),
},
});
if (taskCreated) {
await recalcShotStatus(shot.id, tx);
}
return {
export: {
id: created.id,
@@ -256,6 +309,7 @@ export async function createExport(input: CreateExportInput) {
submissionNote,
},
renderJob: { id: renderJob.id, attempt: renderJob.attempt, priority: renderJob.priority },
task: { id: taskId, created: taskCreated },
shot: { id: shot.id, shotVersion: versionString, exrOutput: exrBase },
superseded: toSupersede.map((s) => s.id),
};
@@ -497,6 +551,9 @@ export async function listExports(filter: ListExportsFilter) {
statusChangedAt: e.statusChangedAt,
createdAt: e.createdAt,
outputDir: e.outputDir,
// Lets the shot's Exports tab offer this export's frame as the shot
// thumbnail (§9.1a) without a second round trip per row.
thumbnailUrl: e.thumbnailKey ? `/api/files/${e.thumbnailKey}` : null,
job: e.renderJobs[0]
? {
id: e.renderJobs[0].id,
+43 -8
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;
@@ -91,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,
},
@@ -189,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 };
}
@@ -313,7 +345,7 @@ export async function completeRender(
// 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 };
@@ -324,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";
+13 -3
View File
@@ -37,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(),
@@ -66,9 +74,11 @@ export const renderManifestSchema = z
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.
* Verbatim from the panel's start-frame resolution, in the order it
* ranks them: "EXR timecode …" (the plate's own header, best),
* "footage metadata" (AE's read of it, 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(),
@@ -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);
});
});
+26 -1
View File
@@ -1,5 +1,5 @@
import { describe, it, expect } from "vitest";
import { nextTaskTitle } from "./preview";
import { nextTaskTitle, carryApproval } from "./preview";
describe("nextTaskTitle", () => {
it("swaps an existing version suffix", () => {
@@ -30,3 +30,28 @@ describe("nextTaskTitle", () => {
expect(nextTaskTitle("SHOT_cmp_TT_V12", "v013")).toBe("SHOT_cmp_TT_v013");
});
});
describe("carryApproval", () => {
it("carries an approval forward, so a re-export does not reopen a signed-off shot", () => {
expect(carryApproval("APPROVED")).toBe("APPROVED");
});
// The regression: a render queued to address a note used to arrive already
// wearing that note, so nothing registered that the work had been redone.
it("resets NEEDS_CHANGES — this render is the fix for it", () => {
expect(carryApproval("NEEDS_CHANGES")).toBe("PENDING_REVIEW");
});
it("resets REJECTED for the same reason", () => {
expect(carryApproval("REJECTED")).toBe("PENDING_REVIEW");
});
it("leaves an unreviewed version pending", () => {
expect(carryApproval("PENDING_REVIEW")).toBe("PENDING_REVIEW");
});
it("defaults to pending when there is no previous version", () => {
expect(carryApproval(null)).toBe("PENDING_REVIEW");
expect(carryApproval(undefined)).toBe("PENDING_REVIEW");
});
});
+265 -37
View File
@@ -1,8 +1,12 @@
import { ExportStatus, Prisma } from "@prisma/client";
import { ApprovalStatus, 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, autoShotThumbnailEnabled } from "./project-templates";
import { clientShotCode } from "@/lib/shot-code";
import { recalcShotStatus, clearStaleShotApproval } from "@/lib/shot-status";
import { renderOutputBase } from "./exports";
/** Slate date format used by the panel's getDateString (YYYY/MM/DD). */
function slateDate(d = new Date()): string {
@@ -37,6 +41,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;
@@ -70,17 +76,31 @@ export async function buildPreviewManifest(exportRow: ExportForPreview): Promise
where: { id: exportRow.shotId },
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();
const base = `${shot.shotCode}_cmp_TT_${exportRow.versionString}`;
// 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);
// Shared with createExport, which names the shot's comp task after this
// basename when it has to create one: the task and the file it holds must
// not drift apart.
const base = renderOutputBase(shot.shotCode, 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",
@@ -92,25 +112,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(),
// 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: clientShotCode(shot),
// 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,
@@ -119,26 +141,143 @@ 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,
},
});
}
/**
* What approval a pipeline-created Version inherits from the one it supersedes.
*
* Only APPROVED carries. A re-export re-renders EXRs for delivery from a shot
* that has usually already been signed off, and defaulting to PENDING_REVIEW
* would make an approved shot silently reappear as awaiting review.
*
* The rejecting verdicts are the opposite case: NEEDS_CHANGES and REJECTED
* describe the version someone asked to be fixed, and the render coming through
* here is the fix. Carrying them forward left every re-render wearing the note
* that prompted it, so nothing in the app registered that the work was redone.
*/
export function carryApproval(previous: ApprovalStatus | null | undefined): ApprovalStatus {
return previous === "APPROVED" ? "APPROVED" : "PENDING_REVIEW";
}
/**
* `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
@@ -208,6 +347,8 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
let versionId: string | null = null;
let versionReplaced = false;
let versionCreated = false;
let inheritedApproval: string | null = null;
if (artifacts.previewMovKey) {
const mediaFields = {
fileUrl: `/api/files/${artifacts.previewMovKey}`,
@@ -239,6 +380,15 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
// 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 previousLatest = exportRow.taskId
? await tx.version.findFirst({
where: { taskId: exportRow.taskId },
orderBy: { versionNumber: "desc" },
select: { approvalStatus: true, versionNumber: true },
})
: null;
const carriedApproval = carryApproval(previousLatest?.approvalStatus);
const taskMax = exportRow.taskId
? await tx.version.aggregate({
where: { taskId: exportRow.taskId },
@@ -254,12 +404,18 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
shotId: exportRow.shotId,
taskId: exportRow.taskId,
artistId: exportRow.submittedById,
notes: `Pipeline render ${exportRow.versionString} (internal only)`,
// `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: carriedApproval,
isLatest: true,
isClientVisible: false, // never shared to the client portal (§10.0)
},
});
versionId = version.id;
versionCreated = true;
inheritedApproval = carriedApproval;
}
if (exportRow.taskId) {
@@ -270,6 +426,44 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
}
}
// Promote the render frame onto the shot, for shows that opted in.
//
// Only `generatedThumbnailUrl` is written — `thumbnailUrl` holds the
// reference frame that came with the brief and the pipeline never touches
// it. Shows that supply stills therefore look exactly as they did; shows
// that supply none get their empty grids filled from the renders instead.
//
// Every outcome is recorded on the export timeline, including the ones that
// did nothing: silence here is indistinguishable from a broken worker, a
// project whose flag never saved, and a feature working as configured.
let thumbnailNote: string;
if (!artifacts.thumbnailKey) {
thumbnailNote =
" — no thumbnail in this render, so the shot's was left alone " +
"(the worker reported no thumbnail: check ffmpegPath in its config.json)";
} else {
const shot = await tx.shot.findUnique({
where: { id: exportRow.shotId },
select: { project: { select: { pipelineConfig: true } } },
});
if (!shot) {
thumbnailNote = " — shot not found, thumbnail not applied";
} else if (!autoShotThumbnailEnabled(shot.project)) {
thumbnailNote =
" — shot thumbnail left alone (this project has \"Use render frames as " +
"shot thumbnails\" turned off)";
} else {
await tx.shot.update({
where: { id: exportRow.shotId },
data: {
generatedThumbnailUrl: `/api/files/${artifacts.thumbnailKey}`,
generatedThumbnailFrom: exportRow.versionString,
},
});
thumbnailNote = " — shot thumbnail updated from this render";
}
}
// 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
@@ -293,6 +487,40 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
}
}
// A genuinely new version is new work awaiting review, so the task moves the
// same way a manual upload moves it (actions/versions.ts, batch-upload) —
// otherwise a task left on CHANGES by a review or a QC fail stays there
// through every re-render, and the shot stays on REVISIONS with no way out
// but a manual kanban drag.
//
// A *replaced* version is deliberately excluded: regeneratePreview
// re-delivers the same version after a slate fix, and that is not a new
// submission. Nor is an already-approved carry-over, which would drag a
// signed-off shot back into review.
let taskStatusMoved = false;
let approvalCleared = false;
if (versionCreated && exportRow.taskId && inheritedApproval !== "APPROVED") {
const task = await tx.task.findUnique({
where: { id: exportRow.taskId },
select: { status: true },
});
if (task && task.status !== "INTERNAL_REVIEW") {
await tx.task.update({
where: { id: exportRow.taskId },
data: { status: "INTERNAL_REVIEW" },
});
taskStatusMoved = true;
}
approvalCleared = await clearStaleShotApproval(tx, exportRow.shotId);
}
// Shot.status is derived from task states (lib/shot-status.ts); nothing in
// the pipeline recalculated it, so shot boards went stale the moment a
// render changed a task.
if (taskStatusMoved || approvalCleared) {
await recalcShotStatus(exportRow.shotId, tx);
}
const updated = await applyTransition(
tx,
exportRow,
@@ -305,9 +533,11 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
(versionId
? versionReplaced
? " — review version media replaced"
: " — review version created"
: ` — review version created (${inheritedApproval ?? "PENDING_REVIEW"})`
: " — no preview media reported") +
(taskRenamed ? ` — task renamed to ${taskTitle}` : ""),
(taskRenamed ? ` — task renamed to ${taskTitle}` : "") +
(taskStatusMoved ? " — task moved to INTERNAL_REVIEW" : "") +
thumbnailNote,
},
{
...(versionId ? { versionId } : {}),
@@ -342,18 +572,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,
maxAttempts,
priority: last?.priority ?? 50,
manifest: manifest as unknown as Prisma.InputJsonValue,
},
});
const job = await createPreviewJob(
tx,
exportRow,
manifest,
maxAttempts,
await renderPriorityFor(tx, exportId),
(last?.attempt ?? 0) + 1
);
const updated = await applyTransition(tx, exportRow, "GENERATING_PREVIEW", {
type: "USER",
@@ -422,18 +651,17 @@ export async function regeneratePreview(exportId: string, input: RegeneratePrevi
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,
maxAttempts,
priority: last?.priority ?? 50,
manifest: manifest as unknown as Prisma.InputJsonValue,
},
});
const job = await createPreviewJob(
tx,
refreshed,
manifest,
maxAttempts,
await renderPriorityFor(tx, exportId),
(last?.attempt ?? 0) + 1
);
const updated = await applyTransition(
tx,
@@ -0,0 +1,62 @@
import { describe, it, expect } from "vitest";
import { conventionalNames, autoShotThumbnailEnabled } 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");
});
});
/**
* The flag decides whether finished renders start writing shot thumbnails, so
* anything short of an explicit `true` has to leave shots alone — a malformed
* config in particular, which must not be read as consent.
*/
describe("autoShotThumbnailEnabled", () => {
it("is on only when explicitly enabled", () => {
expect(autoShotThumbnailEnabled({ pipelineConfig: { autoShotThumbnail: true } })).toBe(true);
});
it("defaults to off", () => {
expect(autoShotThumbnailEnabled({ pipelineConfig: {} })).toBe(false);
expect(autoShotThumbnailEnabled({ pipelineConfig: null })).toBe(false);
expect(autoShotThumbnailEnabled({})).toBe(false);
expect(autoShotThumbnailEnabled({ pipelineConfig: { autoShotThumbnail: false } })).toBe(false);
});
it("stays off when the config is malformed", () => {
expect(autoShotThumbnailEnabled({ pipelineConfig: { autoShotThumbnail: "yes" } })).toBe(false);
expect(autoShotThumbnailEnabled({ pipelineConfig: "not an object" })).toBe(false);
});
it("does not disturb the other settings it shares a column with", () => {
const cfg = { pipelineConfig: { templateAep: "X:/show.aep", autoShotThumbnail: true } };
expect(autoShotThumbnailEnabled(cfg)).toBe(true);
});
});
+119
View File
@@ -0,0 +1,119 @@
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(),
/**
* Promote each finished export's thumbnail onto its shot
* (`Shot.generatedThumbnailUrl`). Off by default and deliberately per-show:
* productions that ship a still with every shot already have a reference
* frame, and the renders should not compete with it. Turn it on for shows
* that arrive with no stills at all, where an empty grid is the alternative.
*
* Never touches `Shot.thumbnailUrl` — see lib/shot-thumbnail.ts.
*/
autoShotThumbnail: z.boolean().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",
};
}
/**
* Whether finished exports promote their thumbnail onto the shot. Defaults to
* false, including when `pipelineConfig` is malformed — a broken config must
* not start rewriting shot thumbnails.
*/
export function autoShotThumbnailEnabled(project: { pipelineConfig?: unknown }): boolean {
const parsed = pipelineConfigSchema.safeParse(project.pipelineConfig ?? {});
return parsed.success ? parsed.data.autoShotThumbnail === true : false;
}
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,
};
}
+4
View File
@@ -3,6 +3,7 @@ import { z } from "zod";
import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { applyTransition } from "./transitions";
import { recalcShotStatus } from "@/lib/shot-status";
/**
* QC workflow (RenderPipeline2 §10) — technical/final-delivery QC on shots the
@@ -104,6 +105,9 @@ export async function submitQCReview(exportId: string, input: QCSubmitInput, act
if (task && task.status !== "CHANGES") {
await tx.task.update({ where: { id: task.id }, data: { status: "CHANGES" } });
taskUpdated = { id: task.id, status: "CHANGES" };
// Shot.status is derived from its tasks and does not recompute on its
// own, so without this the shot never actually reached REVISIONS.
await recalcShotStatus(exportRow.shotId, tx);
}
}
+79
View File
@@ -0,0 +1,79 @@
import { describe, it, expect } from "vitest";
import { nextReviewName, reviewMovName } from "./reviews";
/**
* Review folders are named by date, and several reviews a day are normal —
* a morning pass and an afternoon one land in the same studio's inbox, so the
* numbering has to be unambiguous about which came first.
*/
describe("nextReviewName", () => {
const BASE = "20260828_Producer_review";
it("leaves the first review of the day unnumbered", () => {
expect(nextReviewName(BASE, [])).toBe(BASE);
});
it("numbers from _02 once the plain name is taken", () => {
expect(nextReviewName(BASE, [BASE])).toBe(`${BASE}_02`);
expect(nextReviewName(BASE, [BASE, `${BASE}_02`])).toBe(`${BASE}_03`);
});
it("counts from the highest number, not the count", () => {
// A cancelled _02 still holds its number: reusing it would give two
// different folders the same name in the delivery history.
expect(nextReviewName(BASE, [BASE, `${BASE}_02`, `${BASE}_04`])).toBe(`${BASE}_05`);
});
it("picks up numbering even when the plain name was never used", () => {
expect(nextReviewName(BASE, [`${BASE}_02`])).toBe(`${BASE}_03`);
});
it("ignores names that merely start with the base", () => {
// A hand-named "…_review_final" is somebody's own folder, not part of
// this sequence, and must not push the number along.
expect(nextReviewName(BASE, [`${BASE}_final`, `${BASE}_02x`])).toBe(BASE);
});
it("does not confuse another day's reviews", () => {
expect(nextReviewName(BASE, ["20260827_Producer_review_03"])).toBe(BASE);
});
it("treats the base as a literal, not a pattern", () => {
const dotted = "2026.08.28_review";
expect(nextReviewName(dotted, ["2026x08x28_review"])).toBe(dotted);
});
});
describe("reviewMovName", () => {
const SOURCE = "//SAN/renders/UNG_106_010_020/v004/UNG_106_010_020_cmp_TT_v004.mov";
it("uses the client's own naming when the production supplies it", () => {
expect(reviewMovName({ shotCode: "UNG_106_010_020", clientCode: "EP6_VFX_012" }, "v004", SOURCE)).toBe(
"EP6_VFX_012_v004.mov"
);
});
it("falls back to the studio convention", () => {
expect(reviewMovName({ shotCode: "UNG_106_010_020", clientCode: null }, "v004", SOURCE)).toBe(
"UNG_106_010_020_cmp_TT_v004.mov"
);
});
it("ignores a whitespace-only client code", () => {
expect(reviewMovName({ shotCode: "UNG_106_010_020", clientCode: " " }, "v004", SOURCE)).toBe(
"UNG_106_010_020_cmp_TT_v004.mov"
);
});
it("keeps whatever extension the source actually has", () => {
expect(
reviewMovName({ shotCode: "UNG_106_010_020", clientCode: null }, "v004", "//SAN/a/b_v004.mxf")
).toBe("UNG_106_010_020_cmp_TT_v004.mxf");
});
it("does not mistake a dot in a folder name for an extension", () => {
expect(
reviewMovName({ shotCode: "UNG_106_010_020", clientCode: null }, "v004", "//SAN/v1.2/rendered_mov")
).toBe("UNG_106_010_020_cmp_TT_v004.mov");
});
});
+424
View File
@@ -0,0 +1,424 @@
import { Prisma } from "@prisma/client";
import { z } from "zod";
import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { getConfigNumber } from "./config";
import {
applyTokens,
dateTokens,
resolveDeliveryConfig,
type DeliveryConfig,
type DeliveryManifest,
type TokenValues,
} from "./deliveries";
/**
* MOV review packages (RenderPipeline2 §11.6).
*
* A formal review is shared as a flat, dated folder of the preview MOVs —
* `20260828_Producer_review`, `_02` for the second one that day. It is built by
* the same worker, through the same queue and the same claim path, as an EXR
* delivery; only the shape of what lands on disk differs.
*
* The one rule that separates it from a delivery: **a review never advances an
* Export**. Reviews happen throughout a shot's life, long before QC passes it,
* and the same version is routinely shown twice. So there is no eligibility
* gate beyond "this version has a MOV", and nothing is marked PACKAGED or
* DELIVERED when the folder is built.
*/
// ── Which version of each shot gets reviewed ─────────────────────────────────
export interface ReviewCandidate {
shotId: string;
shotCode: string;
clientCode: string | null;
episode: string;
exportId: string;
versionString: string;
versionNumber: number;
status: string;
deliveryMovPath: string;
/** What the MOV is named in the review folder. */
deliveredName: string;
frameStart: number;
frameEnd: number;
}
export interface ReviewSkip {
shotId: string;
shotCode: string;
reason: string;
}
/**
* `{clientCode}_{versionString}` when the production supplies its own naming,
* else the studio's `{shotCode}_cmp_TT_{versionString}` — the same rule the EXR
* delivery names its files by, so a shot reads identically in a review folder
* and in the delivery that follows it.
*/
export function reviewMovName(
shot: { shotCode: string; clientCode: string | null },
versionString: string,
sourcePath: string
): string {
const base = shot.clientCode?.trim()
? `${shot.clientCode.trim()}_${versionString}`
: `${shot.shotCode}_cmp_TT_${versionString}`;
const dot = sourcePath.lastIndexOf(".");
const slash = Math.max(sourcePath.lastIndexOf("/"), sourcePath.lastIndexOf("\\"));
const ext = dot > slash ? sourcePath.slice(dot) : ".mov";
return `${base}${ext}`;
}
/**
* The newest export of each shot that actually has a delivery MOV on the SAN.
*
* Newest-with-a-MOV rather than newest outright: a shot whose latest version is
* still rendering should go into the review as the version that can be watched,
* not be dropped from it. Shots with no MOV at all come back in `skipped` so
* the caller can say which ones and why rather than silently shipping fewer.
*/
export async function resolveReviewCandidates(shotIds: string[]) {
if (shotIds.length === 0) {
throw new PipelineError(422, "No shots selected");
}
const shots = await db.shot.findMany({
where: { id: { in: shotIds } },
select: {
id: true,
shotCode: true,
clientCode: true,
episode: true,
projectId: true,
project: { select: { id: true, name: true, code: true, showId: true, deliveryConfig: true } },
},
});
if (shots.length === 0) throw new PipelineError(404, "No such shots");
const projectIds = [...new Set(shots.map((s) => s.projectId))];
if (projectIds.length > 1) {
// Delivery roots and naming templates are per project; one folder cannot
// honour two of them.
throw new PipelineError(422, "Selected shots span more than one project — review one project at a time");
}
const exports = await db.export.findMany({
where: {
shotId: { in: shots.map((s) => s.id) },
deliveryMovPath: { not: null },
status: { notIn: ["CANCELLED"] },
},
orderBy: [{ shotId: "asc" }, { versionNumber: "desc" }],
select: {
id: true,
shotId: true,
versionString: true,
versionNumber: true,
status: true,
deliveryMovPath: true,
frameStart: true,
frameEnd: true,
},
});
const newestPerShot = new Map<string, (typeof exports)[number]>();
for (const e of exports) {
if (!newestPerShot.has(e.shotId)) newestPerShot.set(e.shotId, e);
}
const candidates: ReviewCandidate[] = [];
const skipped: ReviewSkip[] = [];
for (const shot of shots) {
const chosen = newestPerShot.get(shot.id);
if (!chosen?.deliveryMovPath) {
skipped.push({
shotId: shot.id,
shotCode: shot.shotCode,
reason: "no preview MOV rendered yet",
});
continue;
}
candidates.push({
shotId: shot.id,
shotCode: shot.shotCode,
clientCode: shot.clientCode,
episode: shot.episode ?? "",
exportId: chosen.id,
versionString: chosen.versionString,
versionNumber: chosen.versionNumber,
status: chosen.status,
deliveryMovPath: chosen.deliveryMovPath,
deliveredName: reviewMovName(shot, chosen.versionString, chosen.deliveryMovPath),
frameStart: chosen.frameStart,
frameEnd: chosen.frameEnd,
});
}
candidates.sort((a, b) => a.shotCode.localeCompare(b.shotCode));
skipped.sort((a, b) => a.shotCode.localeCompare(b.shotCode));
return { project: shots[0].project, candidates, skipped };
}
// ── Folder naming ────────────────────────────────────────────────────────────
function escapeRegExp(value: string): string {
return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}
/**
* `20260828_Producer_review`, then `_02`, `_03` for further reviews the same
* day. Numbering counts every package built under that base — cancelled and
* failed ones included — so a number is never reused for a different folder.
*/
export function nextReviewName(base: string, existingNames: string[]): string {
const pattern = new RegExp(`^${escapeRegExp(base)}(?:_(\\d+))?$`);
let highest = 0;
for (const name of existingNames) {
const match = pattern.exec(name);
if (!match) continue;
highest = Math.max(highest, match[1] ? Number.parseInt(match[1], 10) : 1);
}
return highest === 0 ? base : `${base}_${String(highest + 1).padStart(2, "0")}`;
}
async function reviewNameFor(
tx: Prisma.TransactionClient | typeof db,
projectId: string,
base: string
): Promise<string> {
const existing = await tx.deliveryPackage.findMany({
where: { projectId, kind: "MOV_REVIEW", name: { startsWith: base } },
select: { name: true },
});
return nextReviewName(base, existing.map((p) => p.name));
}
function reviewTokens(
config: DeliveryConfig,
project: { code: string; showId: string | null },
episode: string,
buildDate: Date,
packageNumber: number
): TokenValues {
return {
showId: project.showId || project.code,
episode,
...dateTokens(buildDate),
packageName: "",
packageDir: "",
deliveryRoot: config.deliveryRoot,
shotCode: "",
versionString: "",
packageNumber: String(packageNumber),
};
}
/**
* The episode a review folder belongs to: the one every selected shot shares,
* or "" when the review spans several. It is a label on the record only —
* unlike an EXR package, the folder path never includes it.
*/
function commonEpisode(candidates: ReviewCandidate[]): string {
const episodes = new Set(candidates.map((c) => c.episode));
return episodes.size === 1 ? [...episodes][0] : "";
}
// ── Preview: what would this build ───────────────────────────────────────────
/**
* What the dialog shows before anyone commits: the folder that would be
* created, the version each shot resolves to, and the shots that have no MOV.
* The name is what it would be *right now* — another review built in between
* takes the number and this one moves up.
*/
export async function previewMovReviewPackage(shotIds: string[]) {
const { project, candidates, skipped } = await resolveReviewCandidates(shotIds);
const config = await resolveDeliveryConfig(project.deliveryConfig);
const buildDate = new Date();
const tokens = reviewTokens(config, project, commonEpisode(candidates), buildDate, 0);
const base = applyTokens(config.reviewNameTemplate, tokens);
tokens.packageName = await reviewNameFor(db, project.id, base);
tokens.packageDir = applyTokens(config.layout.reviewDir, tokens);
return {
projectId: project.id,
projectName: project.name,
packageName: tokens.packageName,
packageDir: tokens.packageDir,
candidates,
skipped,
};
}
// ── Create ───────────────────────────────────────────────────────────────────
export const createMovReviewSchema = z.object({
shotIds: z.array(z.string().min(1)).min(1).max(500),
options: z
.object({
/** Override the dated name entirely, e.g. for a re-share under an agreed folder name. */
name: z.string().max(120).optional(),
copyMode: z.enum(["auto", "always-copy"]).optional(),
})
.optional(),
});
export type CreateMovReviewInput = z.infer<typeof createMovReviewSchema>;
/**
* Build a MOV review package from selected shots. Shots without a MOV are
* skipped and reported rather than failing the build — a producer asking for a
* review of 15 shots wants the 13 that exist, plus a clear list of the 2 that
* do not.
*/
export async function createMovReviewPackage(input: CreateMovReviewInput, userId: string) {
const { project, candidates, skipped } = await resolveReviewCandidates(input.shotIds);
if (candidates.length === 0) {
throw new PipelineError(422, "None of the selected shots has a preview MOV yet — nothing to review");
}
const config = await resolveDeliveryConfig(project.deliveryConfig);
if (input.options?.copyMode) config.copyMode = input.options.copyMode;
const buildDate = new Date();
const maxAttempts = await getConfigNumber("render.maxAttempts");
const episode = commonEpisode(candidates);
return db.$transaction(async (tx) => {
const lastNumber = await tx.deliveryPackage.aggregate({
where: { projectId: project.id },
_max: { packageNumber: true },
});
const packageNumber = (lastNumber._max.packageNumber ?? 0) + 1;
const tokens = reviewTokens(config, project, episode, buildDate, packageNumber);
const base = applyTokens(config.reviewNameTemplate, tokens);
tokens.packageName = input.options?.name ?? (await reviewNameFor(tx, project.id, base));
tokens.packageDir = applyTokens(config.layout.reviewDir, tokens);
const pkg = await tx.deliveryPackage.create({
data: {
projectId: project.id,
kind: "MOV_REVIEW",
episode,
name: tokens.packageName,
packageNumber,
status: "QUEUED",
rootPath: tokens.packageDir,
configSnapshot: { ...config, tokens } as unknown as Prisma.InputJsonValue,
createdById: userId,
},
});
// Same version lock as a delivery: shotCode, clientCode and versionString
// are copied in, so a later rename or re-render cannot rewrite what this
// review was.
await tx.deliveryItem.createMany({
data: candidates.map((c) => ({
packageId: pkg.id,
exportId: c.exportId,
shotId: c.shotId,
shotCode: c.shotCode,
clientCode: c.clientCode,
versionString: c.versionString,
})),
});
const manifest = await buildMovReviewJobManifest(tx, pkg.id);
const job = await tx.renderJob.create({
data: {
type: "DELIVERY_BUILD",
deliveryId: pkg.id,
attempt: 1,
maxAttempts,
// Same reasoning as a delivery build: someone is waiting on the folder
// and no After Effects is involved, so it jumps the render queue.
priority: 10,
manifest: manifest as unknown as Prisma.InputJsonValue,
},
});
return {
package: {
id: pkg.id,
kind: pkg.kind,
name: pkg.name,
packageNumber,
episode,
status: pkg.status,
rootPath: pkg.rootPath,
itemCount: candidates.length,
},
skipped,
renderJob: { id: job.id },
};
});
}
// ── The MOV_REVIEW manifest ──────────────────────────────────────────────────
/**
* The DELIVERY_BUILD manifest for a review: the same envelope the EXR builder
* gets, with `kind: "MOV_REVIEW"` and one MOV per item. Every item's `shotDir`
* is the package folder itself — a review is flat, so the MOVs sit beside each
* other where a producer can scrub through them in order.
*/
export async function buildMovReviewJobManifest(
tx: Prisma.TransactionClient,
packageId: string
): Promise<DeliveryManifest> {
const pkg = await tx.deliveryPackage.findUniqueOrThrow({
where: { id: packageId },
include: {
items: { include: { export: true } },
project: { select: { code: true, showId: true } },
},
});
const snapshot = pkg.configSnapshot as unknown as DeliveryConfig & { tokens: TokenValues };
const packageDir = pkg.rootPath ?? snapshot.tokens.packageDir;
return {
stage: "DELIVERY",
kind: "MOV_REVIEW",
packageId: pkg.id,
packageName: pkg.name,
packageNumber: pkg.packageNumber,
episode: pkg.episode,
packageDir,
// A review folder is exactly the MOVs — no CSV, no manifest.json dropped
// in beside them. The manifest still comes back to the server, so the
// record of what was shared is kept without cluttering what is shared.
reportFile: "",
includeMovs: true,
copyMode: snapshot.copyMode ?? "auto",
verifyMode: snapshot.verifyMode ?? "auto",
checksumAlgo: snapshot.checksumAlgo,
reportFormats: [],
items: pkg.items.map((item) => ({
itemId: item.id,
exportId: item.exportId,
shotCode: item.shotCode,
versionString: item.versionString,
// No EXR sequence is involved, so the fields that describe one are empty
// rather than misleadingly populated.
sourceDir: "",
outputPattern: "",
frameStart: item.export.frameStart,
frameEnd: item.export.frameEnd,
fileCount: null,
checksum: null,
deliveryMovPath: item.export.deliveryMovPath,
shotDir: packageDir,
deliveredBaseName: item.clientCode
? `${item.clientCode}_${item.versionString}`
: `${item.shotCode}_cmp_TT_${item.versionString}`,
validatedAt: null,
})),
};
}
+4 -1
View File
@@ -23,7 +23,10 @@ export const EXPORT_TRANSITIONS: Record<ExportStatus, ExportStatus[]> = {
// 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"],
VALIDATION_FAILED: ["QUEUED", "SUPERSEDED"],
// 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"],
// GENERATING_PREVIEW: a slate/burn-in mistake is caught *after* a successful
+121 -5
View File
@@ -3,8 +3,8 @@ import { z } from "zod";
import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { applyTransition } from "./transitions";
import { getConfigBoolean, getConfigValue, getPreviewConfig } from "./config";
import { buildPreviewManifest, createPreviewJob } from "./preview";
import { getConfigBoolean, getConfigNumber, getConfigValue, getPreviewConfig } from "./config";
import { buildPreviewManifest, createPreviewJob, inheritPreviewMedia, renderPriorityFor } from "./preview";
/**
* Validation engine results (RenderPipeline2 §8). The worker runs the checks —
@@ -172,13 +172,16 @@ export async function reportValidation(jobId: string, body: ValidationReport) {
// Passed: hand off to the preview stage, the same handoff completeRender
// used to make directly before validation existed.
if (!previewEnabled) {
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}); preview stage disabled` },
stats
{ type: "WORKER", id: body.machineId, note: `Validation passed (${summary}); ${inherited.note}` },
{ ...stats, ...inherited.data }
);
return {
export: { id: updated.id, status: updated.status },
@@ -214,6 +217,119 @@ 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;
+66
View File
@@ -0,0 +1,66 @@
import { describe, it, expect, vi } from "vitest";
// Mock Prisma so the pure helpers can be tested without a database.
vi.mock("@/lib/db", () => ({ db: {} }));
import { reviewClientEmail, ownsComment } from "./review-auth";
import type { ReviewSession } from "@prisma/client";
const session = (email: string | null): ReviewSession =>
({ email, label: null } as ReviewSession);
describe("reviewClientEmail", () => {
it("uses the session's own email when it has one", () => {
expect(reviewClientEmail(session("dailies@client.com"), "tok123456789")).toBe(
"dailies@client.com"
);
});
it("falls back to a token-derived address when it has none", () => {
expect(reviewClientEmail(session(null), "tok123456789")).toBe(
"client+tok12345@review.external"
);
});
// Identity has to be stable across requests, or a reviewer would stop owning
// the notes they wrote a minute ago.
it("is stable for the same token", () => {
const a = reviewClientEmail(session(null), "tok123456789");
const b = reviewClientEmail(session(null), "tok123456789");
expect(a).toBe(b);
});
it("separates two different review links", () => {
expect(reviewClientEmail(session(null), "aaaaaaaaaaaa")).not.toBe(
reviewClientEmail(session(null), "bbbbbbbbbbbb")
);
});
});
describe("ownsComment", () => {
it("lets a reviewer edit their own note", () => {
expect(ownsComment({ authorId: "u1" }, "u1")).toBe(true);
});
it("refuses another author's note", () => {
expect(ownsComment({ authorId: "u2" }, "u1")).toBe(false);
});
// The studio's notes reach the portal in the same list; they must stay
// read-only there.
it("refuses a note written by an internal user", () => {
expect(ownsComment({ authorId: "supervisor-id" }, "client-id")).toBe(false);
});
it("refuses when the reviewer has never posted, so has no identity yet", () => {
expect(ownsComment({ authorId: "u1" }, undefined)).toBe(false);
expect(ownsComment({ authorId: "u1" }, null)).toBe(false);
});
// An authorless comment (its User row was deleted — Comment.authorId is
// SetNull) belongs to nobody and must not become claimable.
it("refuses an authorless note rather than letting it be claimed", () => {
expect(ownsComment({ authorId: null }, "u1")).toBe(false);
expect(ownsComment({ authorId: null }, null)).toBe(false);
});
});
+59
View File
@@ -32,3 +32,62 @@ export async function validateReviewToken(
return { type: "ok", session };
}
/**
* The email a review session writes its activity under.
*
* A session with no email on it still needs a stable identity so its comments
* group under one author and stay attributable to that link — hence the
* token-derived fallback. Note what this means for ownership: everyone holding
* the same review link *is* the same author. That is the intended scope, since
* the link is the credential.
*/
export function reviewClientEmail(session: ReviewSession, token: string): string {
return session.email ?? `client+${token.slice(0, 8)}@review.external`;
}
/** The guest User a review session posts as, creating it on first activity. */
export async function getOrCreateReviewUser(session: ReviewSession, token: string) {
const email = reviewClientEmail(session, token);
const existing = await db.user.findUnique({ where: { email } });
if (existing) return existing;
return db.user.create({
data: {
email,
name: session.label ?? email.split("@")[0],
role: "CLIENT",
isActive: true,
},
});
}
/**
* The guest User a review session posts as, or null if it has never posted.
*
* Read-only counterpart to getOrCreateReviewUser, for the paths that only need
* to ask "is this theirs?" — merely opening a review link should not conjure a
* User row.
*/
export async function findReviewUser(session: ReviewSession, token: string) {
return db.user.findUnique({
where: { email: reviewClientEmail(session, token) },
select: { id: true },
});
}
/**
* May this review session change or remove this comment?
*
* Only its own. The studio's notes and those of every other review session are
* read-only through a client link, and an authorless comment (its User was
* deleted) belongs to nobody and so cannot be claimed.
*
* Shared by the listing route, which uses it to decide whether to offer the
* controls, and the edit/delete route, which enforces it.
*/
export function ownsComment(
comment: { authorId: string | null },
reviewUserId: string | null | undefined
): boolean {
return !!reviewUserId && !!comment.authorId && comment.authorId === reviewUserId;
}
+45
View File
@@ -0,0 +1,45 @@
import { describe, it, expect } from "vitest";
import { clientShotCode, clientTaskTitle } from "./shot-code";
describe("clientShotCode", () => {
it("prefers the client's alias", () => {
expect(clientShotCode({ shotCode: "UNG_106_010_020", clientCode: "EP6_VFX_012" })).toBe("EP6_VFX_012");
});
it("falls back to our code when there is no alias", () => {
expect(clientShotCode({ shotCode: "UNG_106_010_020", clientCode: null })).toBe("UNG_106_010_020");
expect(clientShotCode({ shotCode: "UNG_106_010_020" })).toBe("UNG_106_010_020");
});
it("ignores a whitespace-only alias", () => {
expect(clientShotCode({ shotCode: "UNG_106_010_020", clientCode: " " })).toBe("UNG_106_010_020");
});
});
describe("clientTaskTitle", () => {
const shot = { shotCode: "UNG_106_010_020", clientCode: "EP6_VFX_012" };
it("swaps the internal code out of a house-convention title", () => {
expect(clientTaskTitle("UNG_106_010_020_cmp_TT_v004", shot)).toBe("EP6_VFX_012_cmp_TT_v004");
});
it("leaves the title alone when there is no alias", () => {
const t = "UNG_106_010_020_cmp_TT_v004";
expect(clientTaskTitle(t, { shotCode: "UNG_106_010_020", clientCode: null })).toBe(t);
});
it("leaves a title that does not carry the code untouched", () => {
// Hand-edited titles are not guessed at — better an unhelpful title than a
// mangled one.
expect(clientTaskTitle("Roto pass", shot)).toBe("Roto pass");
});
it("swaps every occurrence", () => {
expect(clientTaskTitle("UNG_106_010_020 / UNG_106_010_020_cmp", shot)).toBe("EP6_VFX_012 / EP6_VFX_012_cmp");
});
it("is a no-op when the alias equals the code", () => {
const same = { shotCode: "UNG_106_010_020", clientCode: "UNG_106_010_020" };
expect(clientTaskTitle("UNG_106_010_020_cmp", same)).toBe("UNG_106_010_020_cmp");
});
});
+41
View File
@@ -0,0 +1,41 @@
/**
* What a client is shown for a shot.
*
* `Shot.clientCode` is the naming alias some productions supply — their own
* code for the same shot. It already drives slates, overlay burn-ins and
* delivered file names (RenderPipeline2 §11.2); internal paths, comp names and
* every DB lookup stay on `shotCode`.
*
* The client portal is the other place the client's own naming belongs, and
* that includes task titles: they follow the house convention
* `UNG_102_019_010_cmp_TT_v004`, so the internal code is embedded in the
* string the client reads and copies.
*
* Apply these at the API boundary rather than at each render site, so nothing
* downstream has to remember which code it is holding.
*/
export interface ShotCodeFields {
shotCode: string;
clientCode?: string | null;
}
/** The shot's code as the client knows it; their alias if set, ours otherwise. */
export function clientShotCode(shot: ShotCodeFields): string {
return shot.clientCode?.trim() || shot.shotCode;
}
/**
* A task title with the internal shot code swapped for the client's alias.
*
* Titles are built from the shot code by convention, so this is a substring
* swap rather than a rename — a title that does not contain the code (a
* hand-edited one, say) is returned untouched rather than guessed at.
*/
export function clientTaskTitle(title: string, shot: ShotCodeFields): string {
const alias = shot.clientCode?.trim();
if (!alias || !title || alias === shot.shotCode) return title;
// split/join rather than a regex: shot codes are user-supplied and would
// otherwise need escaping.
return title.split(shot.shotCode).join(alias);
}
+190 -2
View File
@@ -3,8 +3,13 @@ import { describe, it, expect, vi } from "vitest";
// Mock Prisma db so the pure deriveShotStatus function can be tested in isolation
vi.mock("@/lib/db", () => ({ db: {} }));
import { deriveShotStatus } from "./shot-status";
import type { TaskStatus } from "@prisma/client";
import {
deriveShotStatus,
clearStaleShotApproval,
markShotForRevisions,
recalcShotStatus,
} from "./shot-status";
import type { TaskStatus, ShotApprovalStatus } from "@prisma/client";
// Helper to build task arrays quickly
const tasks = (...statuses: TaskStatus[]) => statuses.map((status) => ({ status }));
@@ -142,3 +147,186 @@ describe("deriveShotStatus", () => {
});
});
});
// ─────────────────────────────────────────────────────────────────────────────
// Fake Prisma client — enough of the surface for the two write helpers. Each
// call mutates the in-memory shot so the assertions read final state, not spies.
// ─────────────────────────────────────────────────────────────────────────────
type FakeTask = { id: string; status: TaskStatus };
type FakeVersion = { id: string; taskId: string; isLatest: boolean; createdAt: Date };
// The helpers take a Prisma client; the fake implements just the calls they make.
type TxArg = Parameters<typeof recalcShotStatus>[1];
const asTx = (c: { shotState: unknown }): NonNullable<TxArg> =>
c as unknown as NonNullable<TxArg>;
function fakeClient(shot: {
id: string;
shotApprovalStatus: ShotApprovalStatus;
sharedWithClient: boolean;
status?: string;
tasks: FakeTask[];
versions?: FakeVersion[];
}) {
const versions = shot.versions ?? [];
return {
shot: {
findUnique: async () => shot,
update: async ({ data }: { data: Record<string, unknown> }) => {
Object.assign(shot, data);
return shot;
},
},
task: {
findMany: async ({ where }: { where: { status?: { not: TaskStatus } } }) =>
where.status?.not
? shot.tasks.filter((t) => t.status !== where.status!.not)
: shot.tasks,
update: async ({ where, data }: { where: { id: string }; data: { status: TaskStatus } }) => {
const t = shot.tasks.find((x) => x.id === where.id);
if (t) t.status = data.status;
return t;
},
updateMany: async ({
where,
data,
}: {
where: { status?: { not: TaskStatus } };
data: { status: TaskStatus };
}) => {
for (const t of shot.tasks) {
if (!where.status?.not || t.status !== where.status.not) t.status = data.status;
}
return { count: shot.tasks.length };
},
},
version: {
findFirst: async () =>
[...versions].sort(
(a, b) =>
Number(b.isLatest) - Number(a.isLatest) ||
b.createdAt.getTime() - a.createdAt.getTime()
)[0] ?? null,
},
shotState: shot,
};
}
describe("clearStaleShotApproval", () => {
it("clears an internal sign-off so new work is visible", async () => {
const c = fakeClient({
id: "s1",
shotApprovalStatus: "INTERNALLY_APPROVED",
sharedWithClient: false,
tasks: [{ id: "t1", status: "INTERNAL_REVIEW" }],
});
expect(await clearStaleShotApproval(asTx(c), "s1")).toBe(true);
expect(c.shotState.shotApprovalStatus).toBe("PENDING");
});
it("clears a client sign-off, so an upload cannot hide under COMPLETE", async () => {
const c = fakeClient({
id: "s1",
shotApprovalStatus: "CLIENT_APPROVED",
sharedWithClient: true,
tasks: [{ id: "t1", status: "INTERNAL_REVIEW" }],
});
expect(await clearStaleShotApproval(asTx(c), "s1")).toBe(true);
expect(c.shotState.shotApprovalStatus).toBe("PENDING");
});
it("is a no-op when there is no sign-off to clear", async () => {
const c = fakeClient({
id: "s1",
shotApprovalStatus: "PENDING",
sharedWithClient: false,
tasks: [{ id: "t1", status: "IN_PROGRESS" }],
});
expect(await clearStaleShotApproval(asTx(c), "s1")).toBe(false);
});
it("leaves sharedWithClient alone — revoking access is a separate act", async () => {
const c = fakeClient({
id: "s1",
shotApprovalStatus: "CLIENT_APPROVED",
sharedWithClient: true,
tasks: [{ id: "t1", status: "DONE" }],
});
await clearStaleShotApproval(asTx(c), "s1");
expect(c.shotState.sharedWithClient).toBe(true);
});
});
describe("markShotForRevisions", () => {
it("marks the open tasks and lands the shot on REVISIONS", async () => {
const c = fakeClient({
id: "s1",
shotApprovalStatus: "CLIENT_APPROVED",
sharedWithClient: true,
tasks: [
{ id: "t1", status: "DONE" },
{ id: "t2", status: "IN_PROGRESS" },
],
});
const changed = await markShotForRevisions(asTx(c), "s1");
expect(changed).toEqual(["t2"]);
expect(c.shotState.tasks.find((t) => t.id === "t1")!.status).toBe("DONE");
expect(c.shotState.tasks.find((t) => t.id === "t2")!.status).toBe("CHANGES");
expect(c.shotState.shotApprovalStatus).toBe("PENDING");
expect(c.shotState.sharedWithClient).toBe(false);
expect(c.shotState.status).toBe("REVISIONS");
});
// The regression this helper exists for: a shot out for client review has all
// its tasks DONE, so the old "non-DONE" filter matched nothing and the change
// request silently derived to INTERNAL_REVIEW instead of REVISIONS.
it("reopens the task behind the latest version when every task is DONE", async () => {
const c = fakeClient({
id: "s1",
shotApprovalStatus: "CLIENT_APPROVED",
sharedWithClient: true,
tasks: [
{ id: "t1", status: "DONE" },
{ id: "t2", status: "DONE" },
],
versions: [
{ id: "v1", taskId: "t1", isLatest: false, createdAt: new Date("2026-01-01") },
{ id: "v2", taskId: "t2", isLatest: true, createdAt: new Date("2026-02-01") },
],
});
const changed = await markShotForRevisions(asTx(c), "s1");
expect(changed).toEqual(["t2"]);
expect(c.shotState.tasks.find((t) => t.id === "t2")!.status).toBe("CHANGES");
expect(c.shotState.status).toBe("REVISIONS");
});
it("marks only the called-out task when one is named", async () => {
const c = fakeClient({
id: "s1",
shotApprovalStatus: "INTERNALLY_APPROVED",
sharedWithClient: false,
tasks: [
{ id: "t1", status: "TODO" },
{ id: "t2", status: "DONE" },
],
});
const changed = await markShotForRevisions(asTx(c), "s1", "t2");
expect(changed).toEqual(["t2"]);
expect(c.shotState.tasks.find((t) => t.id === "t1")!.status).toBe("TODO");
expect(c.shotState.tasks.find((t) => t.id === "t2")!.status).toBe("CHANGES");
});
it("still clears the approval when a shot has no tasks to mark", async () => {
const c = fakeClient({
id: "s1",
shotApprovalStatus: "CLIENT_APPROVED",
sharedWithClient: true,
tasks: [],
});
const changed = await markShotForRevisions(asTx(c), "s1");
expect(changed).toEqual([]);
expect(c.shotState.shotApprovalStatus).toBe("PENDING");
expect(c.shotState.status).toBe("WAITING");
});
});
+97
View File
@@ -77,3 +77,100 @@ export async function recalcShotStatus(
data: { status: newStatus },
});
}
/**
* New review material arrived on a shot, so any standing sign-off is stale.
*
* deriveShotStatus short-circuits on shotApprovalStatus: a CLIENT_APPROVED shot
* reads COMPLETE and an INTERNALLY_APPROVED one reads READY_FOR_CLIENT no matter
* what its tasks say. Without this, uploading a new version onto an approved
* shot moved the task to INTERNAL_REVIEW and changed nothing visible — the shot
* still read as signed off while carrying work nobody had looked at.
*
* sharedWithClient is left alone; clearing the approval is enough to pull the
* shot back to INTERNAL_REVIEW, and revoking client access is a separate,
* deliberate act (unshareFromClient).
*
* @returns true if a stale approval was actually cleared.
*/
export async function clearStaleShotApproval(
client: TxClient,
shotId: string
): Promise<boolean> {
const shot = await client.shot.findUnique({
where: { id: shotId },
select: { shotApprovalStatus: true },
});
if (!shot || shot.shotApprovalStatus === "PENDING") return false;
await client.shot.update({
where: { id: shotId },
data: { shotApprovalStatus: "PENDING" },
});
return true;
}
/**
* Put a shot into revisions: clear its approval, unshare it, and mark the tasks
* that need rework so the derivation lands on REVISIONS.
*
* The task selection is the subtle part. Marking every non-DONE task as CHANGES
* matches nothing at all on the shot this is most often called for — one that is
* out for client review precisely *because* all of its tasks are finished. That
* left the shot deriving to INTERNAL_REVIEW and the change request with no
* visible effect anywhere. So when nothing was picked up, the task behind the
* shot's latest version is marked instead: that is the deliverable the reviewer
* was actually looking at.
*
* @param taskId Mark only this task (a reviewer calling out one specific task).
* @returns ids of the tasks moved to CHANGES.
*/
export async function markShotForRevisions(
client: TxClient,
shotId: string,
taskId?: string
): Promise<string[]> {
await client.shot.update({
where: { id: shotId },
data: { shotApprovalStatus: "PENDING", sharedWithClient: false },
});
let changed: string[];
if (taskId) {
await client.task.update({ where: { id: taskId }, data: { status: "CHANGES" } });
changed = [taskId];
} else {
const open = await client.task.findMany({
where: { shotId, status: { not: "DONE" } },
select: { id: true },
});
if (open.length > 0) {
await client.task.updateMany({
where: { shotId, status: { not: "DONE" } },
data: { status: "CHANGES" },
});
changed = open.map((t) => t.id);
} else {
// Every task is DONE — reopen the one that produced what was reviewed.
const latest = await client.version.findFirst({
where: { task: { shotId } },
orderBy: [{ isLatest: "desc" }, { createdAt: "desc" }],
select: { taskId: true },
});
if (latest?.taskId) {
await client.task.update({
where: { id: latest.taskId },
data: { status: "CHANGES" },
});
changed = [latest.taskId];
} else {
changed = [];
}
}
}
await recalcShotStatus(shotId, client);
return changed;
}
+40
View File
@@ -0,0 +1,40 @@
import { describe, it, expect } from "vitest";
import { shotThumbnail, isGeneratedThumbnail } from "./shot-thumbnail";
/**
* The whole point of the second column is that promotion can never destroy the
* reference frame that came with the brief. These cases are that guarantee.
*/
describe("shotThumbnail", () => {
it("prefers the reference frame over a render-derived one", () => {
expect(
shotThumbnail({ thumbnailUrl: "/api/files/image/ref.jpg", generatedThumbnailUrl: "/api/files/image/gen.jpg" })
).toBe("/api/files/image/ref.jpg");
});
it("falls back to the render frame when the show supplied no still", () => {
expect(shotThumbnail({ thumbnailUrl: null, generatedThumbnailUrl: "/api/files/image/gen.jpg" })).toBe(
"/api/files/image/gen.jpg"
);
});
it("returns null when the shot has neither", () => {
expect(shotThumbnail({ thumbnailUrl: null, generatedThumbnailUrl: null })).toBeNull();
expect(shotThumbnail(null)).toBeNull();
expect(shotThumbnail({})).toBeNull();
});
it("treats an empty string as no thumbnail", () => {
// updateShot accepts "" from a cleared form field, which must not win over
// a generated frame or render as a broken <img src="">.
expect(shotThumbnail({ thumbnailUrl: "", generatedThumbnailUrl: "/api/files/image/gen.jpg" })).toBe(
"/api/files/image/gen.jpg"
);
});
it("reports whether what is displayed came from a render", () => {
expect(isGeneratedThumbnail({ thumbnailUrl: null, generatedThumbnailUrl: "/g.jpg" })).toBe(true);
expect(isGeneratedThumbnail({ thumbnailUrl: "/r.jpg", generatedThumbnailUrl: "/g.jpg" })).toBe(false);
expect(isGeneratedThumbnail({ thumbnailUrl: null, generatedThumbnailUrl: null })).toBe(false);
});
});
+41
View File
@@ -0,0 +1,41 @@
/**
* Shot thumbnail resolution.
*
* A shot can carry two stills:
*
* • `thumbnailUrl` — the reference frame supplied with the brief
* (client still, batch upload, ext API). Editorial
* data: only ever written by a human.
* • `generatedThumbnailUrl` — a frame promoted from a render export, either
* automatically (projects with
* `pipelineConfig.autoShotThumbnail`) or by hand.
*
* The reference always wins. Shows that arrive with stills look exactly as they
* do today; shows that arrive without any get their empty grids filled from the
* renders instead. Because the two live in different columns, a promotion can
* never destroy the reference — clearing the generated one always falls back to
* the brief.
*/
export interface ShotThumbnailFields {
thumbnailUrl?: string | null;
generatedThumbnailUrl?: string | null;
}
/** The still to display for a shot, or null when it has neither. */
export function shotThumbnail(shot: ShotThumbnailFields | null | undefined): string | null {
return shot?.thumbnailUrl || shot?.generatedThumbnailUrl || null;
}
/** True when the displayed still came from a render rather than the brief. */
export function isGeneratedThumbnail(shot: ShotThumbnailFields | null | undefined): boolean {
return !shot?.thumbnailUrl && !!shot?.generatedThumbnailUrl;
}
/**
* Prisma `select` fragment for the two columns. Spread it wherever a query
* already selects `thumbnailUrl` so the fallback has something to fall back to.
*/
export const shotThumbnailSelect = {
thumbnailUrl: true,
generatedThumbnailUrl: true,
} as const;

Some files were not shown because too many files have changed in this diff Show More