feat(review): High quality playback switch and per-version ProRes download
Deploy / deploy (push) Successful in 3m23s

Worker 1.7.0 (preview.highQuality, default on) now, after the AE render:
- encodes a High quality MP4 from the delivery MOV (full-res H.264 High,
  CRF 14 capped at 100 Mbps) -> Version.hqFileUrl
- uploads the MOV itself -> Version.highResKey/Filename/Size
Both best-effort (the preview never fails over them), with a lease
keep-alive during the long encode/uploads; the export timeline records
what was attached.

Player: HQ switch when a High quality source exists; keeps frame, play
state, speed and zoom, remembered per browser, falls back to Standard if
the file won't load. ProRes itself stays download-only (browser support).

Downloads: the client portal's High Res button serves the version's
ProRes (client-code filename), falling back to the shot's manual file;
staff get a ProRes button on the review page.

Housekeeping (lib/render-pipeline/high-res.ts): HQ MP4 + ProRes are kept
while a version is latest, client-shared, approved or younger than
preview.highResRetentionDays (14); otherwise deleted from storage. Runs
per task after finalize and hourly from the reaper; deleting a version or
a reslate removes its files. The Standard MP4 is never touched.

Also: ProRes/Handles top-bar buttons go icon-only below lg so they don't
overlap the version selector.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
twotalesanimation
2026-09-22 16:32:18 +02:00
parent bae46c2968
commit 9660cdc21c
27 changed files with 793 additions and 18 deletions
+15 -2
View File
@@ -48,6 +48,18 @@ export const PIPELINE_CONFIG_DEFAULTS = {
// names as a warning, so it is a config fix rather than a code change.
"preview.slateScopeProp": "Scope",
"preview.slateSubmissionProp": "Notes",
/**
* After the AE render, the worker also encodes a high-bitrate full-res MP4
* from the delivery MOV (the player's "High" quality) and uploads the MOV
* itself as the version's High Res download. Off = Standard MP4 only.
*/
"preview.highQuality": "true",
/**
* Housekeeping (lib/render-pipeline/high-res.ts): a version's High quality
* MP4 and ProRes are removed from storage once it is this many days old and
* nothing still needs them — not the latest, not shared, not approved.
*/
"preview.highResRetentionDays": 14,
/**
* When the dashboard starts calling something stuck. An export waiting on QC
* is normal for a day and suspicious after two; an export in a live render
@@ -79,7 +91,7 @@ export async function getConfigBoolean(key: PipelineConfigKey): Promise<boolean>
export async function getPreviewConfig() {
const [
enabled, templateAep, templateComp, overlayComp, lutComp, movTemplate, mp4Template,
slateScopeProp, slateSubmissionProp,
slateScopeProp, slateSubmissionProp, highQuality,
] = await Promise.all([
getConfigBoolean("preview.enabled"),
getConfigValue("preview.templateAep"),
@@ -90,10 +102,11 @@ export async function getPreviewConfig() {
getConfigValue("preview.mp4Template"),
getConfigValue("preview.slateScopeProp"),
getConfigValue("preview.slateSubmissionProp"),
getConfigBoolean("preview.highQuality"),
]);
return {
enabled, templateAep, templateComp, overlayComp, lutComp, movTemplate, mp4Template,
slateScopeProp, slateSubmissionProp,
slateScopeProp, slateSubmissionProp, highQuality,
};
}
+54
View File
@@ -0,0 +1,54 @@
import { describe, expect, it, vi } from "vitest";
vi.mock("@/lib/db", () => ({ db: {} }));
vi.mock("@/lib/storage", () => ({ deleteFromHetzner: vi.fn() }));
import { highResStorageKeys, shouldKeepHighRes } from "./high-res";
const now = new Date("2026-09-22T12:00:00Z");
const daysAgo = (d: number) => new Date(now.getTime() - d * 24 * 3600 * 1000);
const old = { isLatest: false, isClientVisible: false, approvalStatus: "PENDING_REVIEW", createdAt: daysAgo(30) };
describe("shouldKeepHighRes", () => {
it("prunes an old, superseded, unshared, unapproved version", () => {
expect(shouldKeepHighRes(old, now, 14)).toBe(false);
});
it("keeps the latest version however old", () => {
expect(shouldKeepHighRes({ ...old, isLatest: true }, now, 14)).toBe(true);
});
it("keeps anything shared with the client — they may download it", () => {
expect(shouldKeepHighRes({ ...old, isClientVisible: true }, now, 14)).toBe(true);
});
it("keeps the approved version of record", () => {
expect(shouldKeepHighRes({ ...old, approvalStatus: "APPROVED" }, now, 14)).toBe(true);
});
it("keeps recent superseded versions inside the retention window", () => {
expect(shouldKeepHighRes({ ...old, createdAt: daysAgo(13) }, now, 14)).toBe(true);
expect(shouldKeepHighRes({ ...old, createdAt: daysAgo(15) }, now, 14)).toBe(false);
});
it("treats needs-changes and rejected versions as prunable", () => {
expect(shouldKeepHighRes({ ...old, approvalStatus: "NEEDS_CHANGES" }, now, 14)).toBe(false);
expect(shouldKeepHighRes({ ...old, approvalStatus: "REJECTED" }, now, 14)).toBe(false);
});
it("prunes superseded versions straight away with a zero-day window", () => {
expect(shouldKeepHighRes({ ...old, createdAt: daysAgo(0.01) }, now, 0)).toBe(false);
});
});
describe("highResStorageKeys", () => {
it("returns the ProRes key and the HQ MP4's storage key", () => {
expect(
highResStorageKeys({ highResKey: "highres/a.mov", hqFileUrl: "/api/files/videos/b_HQ.mp4" })
).toEqual(["highres/a.mov", "videos/b_HQ.mp4"]);
});
it("is empty when there is nothing to delete", () => {
expect(highResStorageKeys({ highResKey: null, hqFileUrl: null })).toEqual([]);
});
});
+124
View File
@@ -0,0 +1,124 @@
import { db } from "@/lib/db";
import { deleteFromHetzner } from "@/lib/storage";
import { getConfigNumber } from "./config";
/**
* Housekeeping for per-version high-quality media — the High quality review
* MP4 (`hqFileUrl`) and the ProRes delivery MOV (`highResKey`). The worker
* uploads both for every version, and at UHD they are 5–10× the Standard MP4,
* so versions nobody can need any more have them removed. The Standard MP4 is
* never touched: every version stays reviewable.
*/
export interface HighResCandidate {
isLatest: boolean;
isClientVisible: boolean;
approvalStatus: string;
createdAt: Date;
}
/**
* Whether a version still needs its high-quality media. Kept while it is:
* - the latest version of its task — what everyone is looking at;
* - shared with the client — they may download it;
* - approved — the version of record;
* - younger than the retention window — supervisors compare recent takes.
*/
export function shouldKeepHighRes(v: HighResCandidate, now: Date, retentionDays: number): boolean {
if (v.isLatest || v.isClientVisible || v.approvalStatus === "APPROVED") return true;
const ageMs = now.getTime() - v.createdAt.getTime();
return ageMs < Math.max(0, retentionDays) * 24 * 3600 * 1000;
}
/** Object-storage keys behind a version's high-quality media. */
export function highResStorageKeys(v: { hqFileUrl?: string | null; highResKey?: string | null }): string[] {
const keys: string[] = [];
if (v.highResKey) keys.push(v.highResKey);
if (v.hqFileUrl?.startsWith("/api/files/")) keys.push(v.hqFileUrl.slice("/api/files/".length));
return keys;
}
/** Best-effort deletes; a failure only leaves an orphan, never a broken link. */
export async function deleteStorageKeys(keys: string[]): Promise<void> {
for (const key of keys) {
await deleteFromHetzner(key).catch((err) =>
console.error(`[high-res] could not delete ${key} from storage`, err)
);
}
}
const candidateSelect = {
id: true,
isLatest: true,
isClientVisible: true,
approvalStatus: true,
createdAt: true,
hqFileUrl: true,
highResKey: true,
} as const;
type Candidate = HighResCandidate & { id: string; hqFileUrl: string | null; highResKey: string | null };
/**
* Clears the row first, then deletes the files: if the delete fails the file
* is merely orphaned, whereas the other order could leave a download pointing
* at nothing.
*/
async function prune(candidates: Candidate[], now: Date, retentionDays: number): Promise<number> {
let pruned = 0;
for (const v of candidates) {
if (shouldKeepHighRes(v, now, retentionDays)) continue;
const keys = highResStorageKeys(v);
await db.version.update({
where: { id: v.id },
data: {
hqFileUrl: null,
highResKey: null,
highResFilename: null,
highResSize: null,
highResPrunedAt: now,
},
});
await deleteStorageKeys(keys);
pruned++;
}
return pruned;
}
const hasHighRes = { OR: [{ hqFileUrl: { not: null } }, { highResKey: { not: null } }] };
/** Run after a new version lands: its predecessors may now be redundant. */
export async function pruneHighResForTask(taskId: string): Promise<number> {
const retentionDays = await getConfigNumber("preview.highResRetentionDays");
const candidates = await db.version.findMany({
where: { taskId, ...hasHighRes },
select: candidateSelect,
});
return prune(candidates, new Date(), retentionDays);
}
/**
* Studio-wide pass, for versions that age out of the retention window or are
* unshared/unapproved after the fact. Bounded per run; the reaper calls it
* hourly, so a backlog drains over a few runs.
*/
export async function pruneHighResSweep(batch = 200): Promise<number> {
const retentionDays = await getConfigNumber("preview.highResRetentionDays");
const now = new Date();
const cutoff = new Date(now.getTime() - Math.max(0, retentionDays) * 24 * 3600 * 1000);
const candidates = await db.version.findMany({
where: {
...hasHighRes,
isLatest: false,
isClientVisible: false,
approvalStatus: { not: "APPROVED" },
createdAt: { lt: cutoff },
},
select: candidateSelect,
orderBy: { createdAt: "asc" },
take: batch,
});
const pruned = await prune(candidates, now, retentionDays);
if (pruned > 0) console.log(`[high-res] housekeeping removed high-quality media from ${pruned} version(s)`);
return pruned;
}
+59 -2
View File
@@ -5,6 +5,7 @@ import { applyTransition } from "./transitions";
import { getConfigNumber, getPreviewConfig } from "./config";
import { resolveProjectTemplates, autoShotThumbnailEnabled } from "./project-templates";
import { clientShotCode } from "@/lib/shot-code";
import { deleteStorageKeys, highResStorageKeys, pruneHighResForTask } from "./high-res";
import { recalcShotStatus, clearStaleShotApproval } from "@/lib/shot-status";
import { renderOutputBase } from "./exports";
@@ -35,6 +36,8 @@ export interface PreviewManifest {
mp4Output: string;
slateScopeProp: string;
slateSubmissionProp: string;
/** Also encode the High quality MP4 and upload the MOV (worker >= 1.7.0). */
highQuality: boolean;
slate: {
versionName: string;
date: string;
@@ -122,6 +125,7 @@ export async function buildPreviewManifest(exportRow: ExportForPreview): Promise
mp4Output: `${exportRow.outputDir}/${base}.mp4`,
slateScopeProp: cfg.slateScopeProp,
slateSubmissionProp: cfg.slateSubmissionProp,
highQuality: cfg.highQuality,
slate: {
versionName: clientBase,
date: slateDate(),
@@ -295,6 +299,12 @@ export interface FinalizeInput {
thumbnailKey?: string;
metadataKey?: string;
logFileKey?: string;
/** High-bitrate full-res MP4 encoded from the MOV (worker >= 1.7.0). */
hqPreviewKey?: string | null;
/** The delivery MOV itself, uploaded as the version's High Res file. */
highResKey?: string | null;
highResFileName?: string | null;
highResSize?: number | null;
};
renderStats?: { renderSeconds?: number; previewSeconds?: number };
media?: {
@@ -318,6 +328,19 @@ export interface FinalizeInput {
* resurface in the review flow or the client portal.
*/
export async function finalizePreview(jobId: string, machineId: string, body: FinalizeInput) {
const { replacedHighRes, housekeepTaskId, ...outcome } = await finalizePreviewTx(jobId, machineId, body);
// Storage is only touched once the transaction has committed: a rollback
// must never leave a Version pointing at a deleted file.
await deleteStorageKeys(replacedHighRes);
if (housekeepTaskId) {
await pruneHighResForTask(housekeepTaskId).catch((err) =>
console.error("[high-res] housekeeping after finalize failed", err)
);
}
return outcome;
}
async function finalizePreviewTx(jobId: string, machineId: string, body: FinalizeInput) {
return db.$transaction(async (tx) => {
const job = await tx.renderJob.findUnique({
where: { id: jobId },
@@ -336,6 +359,8 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
version: { id: exportRow.versionId },
task: null,
alreadyApplied: true,
replacedHighRes: [] as string[],
housekeepTaskId: null as string | null,
};
}
@@ -354,6 +379,7 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
});
let versionId: string | null = null;
let replacedHighRes: string[] = [];
let versionReplaced = false;
let versionCreated = false;
let inheritedApproval: string | null = null;
@@ -377,6 +403,16 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
typeof media.pictureStartSeconds === "number" && media.pictureStartSeconds >= 0
? Math.round(media.pictureStartSeconds * fps)
: null,
// High quality + ProRes: whatever this build produced. Absent means
// the worker skipped or failed them (never fatal) — Standard only.
hqFileUrl: artifacts.hqPreviewKey ? `/api/files/${artifacts.hqPreviewKey}` : null,
highResKey: artifacts.highResKey ?? null,
highResFilename: artifacts.highResKey ? (artifacts.highResFileName ?? null) : null,
highResSize:
artifacts.highResKey && typeof artifacts.highResSize === "number"
? BigInt(Math.round(artifacts.highResSize))
: null,
highResPrunedAt: null,
};
// Regenerating a preview (T11b) re-delivers the *same* export version, so
@@ -384,10 +420,18 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
// stacking a second row: the version number stays put and any notes or
// annotations reviewers left on it survive the reslate.
const existing = exportRow.versionId
? await tx.version.findUnique({ where: { id: exportRow.versionId }, select: { id: true } })
? await tx.version.findUnique({
where: { id: exportRow.versionId },
select: { id: true, hqFileUrl: true, highResKey: true },
})
: null;
if (existing) {
// The reslate replaces the high-quality files too; the old ones would
// otherwise sit in storage with nothing pointing at them.
replacedHighRes = highResStorageKeys(existing).filter(
(k) => k !== artifacts.highResKey && k !== artifacts.hqPreviewKey
);
await tx.version.update({
where: { id: existing.id },
data: { ...mediaFields, isLatest: true },
@@ -555,7 +599,8 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
: " — no preview media reported") +
(taskRenamed ? ` — task renamed to ${taskTitle}` : "") +
(taskStatusMoved ? " — task moved to INTERNAL_REVIEW" : "") +
thumbnailNote,
thumbnailNote +
(versionId ? highResNote(artifacts) : ""),
},
{
...(versionId ? { versionId } : {}),
@@ -571,10 +616,22 @@ export async function finalizePreview(jobId: string, machineId: string, body: Fi
version: versionId ? { id: versionId, replaced: versionReplaced } : null,
task: exportRow.taskId ? { id: exportRow.taskId, title: taskTitle, renamed: taskRenamed } : null,
alreadyApplied: false,
replacedHighRes,
housekeepTaskId: versionId ? exportRow.taskId : null,
};
});
}
/** Timeline wording for what high-quality media this build attached. */
function highResNote(artifacts: NonNullable<FinalizeInput["artifacts"]>): string {
const hq = !!artifacts.hqPreviewKey;
const mov = !!artifacts.highResKey;
if (hq && mov) return " — High quality MP4 and ProRes attached";
if (hq) return " — High quality MP4 attached (ProRes upload failed or skipped)";
if (mov) return " — ProRes attached (High quality encode failed or skipped)";
return " — no High quality/ProRes (disabled, worker < 1.7.0, or both failed — see the worker log)";
}
/** T11 — retry the preview stage only; validated EXRs are left alone. */
export async function retryPreview(exportId: string, actorId?: string) {
const maxAttempts = await getConfigNumber("render.maxAttempts");
+14 -1
View File
@@ -1,4 +1,5 @@
import { Prisma } from "@prisma/client";
import { pruneHighResSweep } from "./high-res";
import { db } from "@/lib/db";
import { applyTransition } from "./transitions";
import { getConfigNumber } from "./config";
@@ -96,9 +97,21 @@ export async function reaperSweep() {
await db.workerHeartbeat.deleteMany({
where: { createdAt: { lt: new Date(Date.now() - 7 * 24 * 3600 * 1000) } },
});
// High-quality media housekeeping: hourly is plenty, and it can touch
// object storage, so it stays off the once-a-minute lease path.
if (Date.now() - (globalForReaper.lastHighResSweep ?? 0) >= HIGH_RES_SWEEP_MS) {
globalForReaper.lastHighResSweep = Date.now();
await pruneHighResSweep().catch((err) => console.error("[high-res] housekeeping sweep failed", err));
}
}
const globalForReaper = globalThis as unknown as { renderPipelineReaper?: ReturnType<typeof setInterval> };
const HIGH_RES_SWEEP_MS = 60 * 60 * 1000;
const globalForReaper = globalThis as unknown as {
renderPipelineReaper?: ReturnType<typeof setInterval>;
lastHighResSweep?: number;
};
/** Started once from instrumentation.ts (Next.js server startup hook). */
export function startReaper(intervalMs = 60_000) {