Skip to content

Code-first video & image, rendered natively on WebGPU.

feat(renderer): abort, progress and per-job cache reset (phase 4)

okanasl588f0b143910
diff --git a/apps/renderer-service/PLAN.md b/apps/renderer-service/PLAN.md
index 549a334a..2852ccae 100644
--- a/apps/renderer-service/PLAN.md
+++ b/apps/renderer-service/PLAN.md
@@ -497,21 +497,23 @@ The service no longer uses `S3StorageService` from `@framefields/server-utils`,
Each phase is its own PR-sized step with tests.
-0. **Unbreak and remove the inline path.**
+0. **Unbreak and remove the inline path.** ✅ Done.
- Drop the DI container (`di-setup.ts`, inversify, `ServerMediaService`, `R2StorageService`). Storage returns in phase 6 as the service's own output sink.
- Delete the `virtualMedia` path: `job-processor.ts`, `render-upload.ts`, `cli.ts --job <json>`, the `/run` and `/status` routes, `configureAssetUrls`/`BASE_URL`, and the old `render.test.ts` cases. Keep `/health`, `/ping`, readiness and graceful shutdown.
- Fix the `gatewai-renderer` paths in the entrypoint and the Python shim.
- Get `pnpm --filter @framefields/renderer-service typecheck test` green.
-1. **Config + job schema v2 + error model.**
+1. **Config + job schema v2 + error model.** ✅ Done.
- `src/config/` (frozen config, secrets scrubbed from `process.env`), `src/jobs/schema.ts`, `src/errors.ts` (`RenderError` with `code`/`phase`/`retryable`), and the redactor.
- API-key auth on HTTP, the job store with TTL eviction, and the single-slot queue.
-2. **GitWorkspace.**
+2. **GitWorkspace.** ✅ Done, except that the LFS download is untested locally because git-lfs isn't installed.
- Mirror cache, ref resolution, workspace leasing, auth helpers and host profiles (6.5), LFS pull with pre- and postflight, eviction.
- Integration tests use local bare repos and a file-based LFS remote (`lfs.standalonetransferagent`), so no network is needed.
-3. **Installer.** Package manager detection, frozen install with framefields filtered out, skipping the install when nothing else is needed, the stamp check, shared stores, and the engine range check.
-4. **Engine hooks (in `@framefields/renderer` and `framefields`).**
- - `signal: AbortSignal` and `onProgress` on `renderVideo`/`renderFrame`/`renderFrameGrid`, checked between frames.
- - A per-job cache reset (fonts, textures, compiled timelines) that keeps the device and pipelines.
+3. **Installer.** ✅ Done: package manager detection (via `packageManager` or the lockfile, run through corepack), frozen install, skipping the install when nothing else is needed, the stamp check, shared stores, the engine range check, and install error classification. `install.prepare` steps are deferred until the repo defaults file (`framefields.render.json`) is implemented.
+4. **Engine hooks (in `@framefields/renderer` and `framefields`).** ✅ Done:
+ - `signal: AbortSignal` and `onProgress` on `renderVideo`, checked between frames and before the audio mix. Single-frame renders don't need either.
+ - `resetRenderCaches()` (`@framefields/renderer`) clears media inputs and decoders, textures, LUTs and fonts. The worker calls it plus `FontManager.clear()` before each job. The GPU device and pipelines stay warm.
+ - A GPU test (`src/engine.gpu.test.ts`, run with `FF_GPU_TESTS=1`) confirmed that without the reset, a changed file at the same workspace path is served stale.
+ - Not yet verified: re-opening a *video* file at the same path after the reset. A comment in `renderImage` says a mediabunny `Input` can only be created once per URL. Phase 5 needs a GPU test that renders a video layer in two jobs back to back.
5. **InProcessRenderer.**
- The engine alias resolve hook, `tsImport` loading, export-shape normalisation, the job sandbox (8.2), the watchdog, the crash journal, and recycling.
6. **Outputs.** The s3, presigned, local and inline sinks, verification (ffprobe), multi-output keys, and idempotency.
diff --git a/apps/renderer-service/src/engine.gpu.test.ts b/apps/renderer-service/src/engine.gpu.test.ts
new file mode 100644
index 00000000..cdd7c6ba
--- /dev/null
+++ b/apps/renderer-service/src/engine.gpu.test.ts
@@ -0,0 +1,127 @@
+/**
+ * Engine hooks the in-process worker relies on (PLAN.md §8): progress and
+ * abort in renderVideo, and the per-job cache reset. Needs a GPU, so it only
+ * runs with FF_GPU_TESTS=1.
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { deflateSync } from "node:zlib";
+import { resetRenderCaches } from "@framefields/renderer";
+import { ApplyLUT, Composition, FontManager, Media } from "framefields";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+const gpu = describe.skipIf(process.env.FF_GPU_TESTS !== "1");
+
+let dir = "";
+
+/** A solid-colour RGB PNG, without pulling in an image library. */
+function solidPng(size: number, rgb: [number, number, number]): Buffer {
+ const crcTable = Array.from({ length: 256 }, (_, n) => {
+ let c = n;
+ for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+ return c >>> 0;
+ });
+ const crc = (buf: Buffer) => {
+ let c = 0xffffffff;
+ for (const b of buf) c = crcTable[(c ^ b) & 0xff] ^ (c >>> 8);
+ return (c ^ 0xffffffff) >>> 0;
+ };
+ const chunk = (type: string, data: Buffer) => {
+ const len = Buffer.alloc(4);
+ len.writeUInt32BE(data.length);
+ const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+ const sum = Buffer.alloc(4);
+ sum.writeUInt32BE(crc(body));
+ return Buffer.concat([len, body, sum]);
+ };
+ const ihdr = Buffer.alloc(13);
+ ihdr.writeUInt32BE(size, 0);
+ ihdr.writeUInt32BE(size, 4);
+ ihdr.set([8, 2, 0, 0, 0], 8);
+ const row = Buffer.concat([
+ Buffer.from([0]),
+ Buffer.from(Array(size).fill(rgb).flat()),
+ ]);
+ return Buffer.concat([
+ Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+ chunk("IHDR", ihdr),
+ chunk("IDAT", deflateSync(Buffer.concat(Array(size).fill(row)))),
+ chunk("IEND", Buffer.alloc(0)),
+ ]);
+}
+
+const cube = (rgb: string) =>
+ ["LUT_3D_SIZE 2", ...Array(8).fill(rgb)].join("\n");
+
+beforeAll(async () => {
+ dir = await fs.mkdtemp(path.join(os.tmpdir(), "ff-engine-"));
+ await fs.writeFile(path.join(dir, "grey.png"), solidPng(64, [128, 128, 128]));
+});
+afterAll(async () => {
+ await fs.rm(dir, { recursive: true, force: true });
+});
+
+gpu("engine hooks", () => {
+ const film = () =>
+ new Composition({
+ width: 64,
+ height: 64,
+ fps: 24,
+ durationFrames: 48,
+ backgroundColor: "#204060",
+ });
+
+ it("reports progress for every frame, then the audio mix", async () => {
+ const seen: string[] = [];
+ const result = await film().renderVideo({
+ onProgress: (p) => seen.push(`${p.phase}:${p.frame}/${p.totalFrames}`),
+ });
+ await result.cleanup();
+ expect(seen.filter((s) => s.startsWith("render:"))).toHaveLength(48);
+ expect(seen.at(-2)).toBe("render:48/48");
+ expect(seen.at(-1)).toBe("audio:48/48");
+ }, 120_000);
+
+ it("aborts between frames with the signal's reason", async () => {
+ const controller = new AbortController();
+ const reason = new Error("job cancelled");
+ let frames = 0;
+ const render = film().renderVideo({
+ signal: controller.signal,
+ onProgress: (p) => {
+ frames = p.frame;
+ if (p.frame === 5) controller.abort(reason);
+ },
+ });
+ await expect(render).rejects.toBe(reason);
+ expect(frames).toBe(5);
+
+ // The worker keeps going after an abort.
+ const next = await film().renderVideo({});
+ await next.cleanup();
+ }, 120_000);
+
+ it("serves a changed file at the same path only after resetRenderCaches()", async () => {
+ const lut = path.join(dir, "look.cube");
+ const grey = path.join(dir, "grey.png");
+ const frame = () =>
+ Media.image(grey, { width: 64, height: 64 })
+ .apply(new ApplyLUT({ lutUrl: lut, intensity: 1 }))
+ .renderFrame({ frame: 0 });
+
+ await fs.writeFile(lut, cube("0 1 0"));
+ const green = await frame();
+
+ // Same path, new bytes: what the next job's checkout looks like.
+ await fs.writeFile(lut, cube("1 0 0"));
+ const stale = await frame();
+
+ resetRenderCaches();
+ FontManager.clear();
+ const red = await frame();
+
+ expect(Buffer.compare(stale, green)).toBe(0);
+ expect(Buffer.compare(red, green)).not.toBe(0);
+ }, 120_000);
+});
diff --git a/packages/framefields/src/index.ts b/packages/framefields/src/index.ts
index afe053d9..ea117cc4 100644
--- a/packages/framefields/src/index.ts
+++ b/packages/framefields/src/index.ts
@@ -243,6 +243,7 @@ import {
import {
type FrameGridOptions,
HeadlessMediaRenderer,
+ type RenderProgress,
renderFrameGrid,
type VideoQaOptions,
type VideoQaReport,
@@ -1000,6 +1001,13 @@ export interface RenderVideoOptions {
* pass thresholds (e.g. `{ targetLufs: -14 }`) to tighten them.
*/
qa?: boolean | VideoQaOptions;
+ /**
+ * Stops the render between frames. The promise rejects with
+ * `signal.reason` and no file is left behind.
+ */
+ signal?: AbortSignal;
+ /** Called as frames finish (`phase: "render"`), then once for the audio mix. */
+ onProgress?: (progress: RenderProgress) => void;
}
export interface RenderVideoResult {
@@ -2914,6 +2922,7 @@ export {
HeadlessWebGPURenderer,
type QaIssue,
type QaSegment,
+ type RenderProgress,
renderFrameGrid,
renderSemaphore,
resolveSamplePoints,
diff --git a/packages/framefields/src/renderer/index.ts b/packages/framefields/src/renderer/index.ts
index 0d5312b3..d811bbad 100644
--- a/packages/framefields/src/renderer/index.ts
+++ b/packages/framefields/src/renderer/index.ts
@@ -5,6 +5,7 @@ export {
HeadlessWebGPURenderer,
type QaIssue,
type QaSegment,
+ type RenderProgress,
renderSemaphore,
type VideoQaOptions,
type VideoQaReport,
diff --git a/packages/renderer/src/headless-webgpu-renderer.ts b/packages/renderer/src/headless-webgpu-renderer.ts
index 245a4161..d8ea1785 100644
--- a/packages/renderer/src/headless-webgpu-renderer.ts
+++ b/packages/renderer/src/headless-webgpu-renderer.ts
@@ -1035,6 +1035,13 @@ export class HeadlessWebGPURenderer {
* and return the findings as `qa`. `true` uses default thresholds.
*/
qa?: boolean | VideoQaOptions;
+ /**
+ * Aborts the render between frames; the promise rejects with
+ * `signal.reason` and the partial output is deleted.
+ */
+ signal?: AbortSignal;
+ /** Called after each frame is queued for encoding, then once for audio. */
+ onProgress?: (progress: RenderProgress) => void;
},
): Promise<{
filePath: string;
@@ -1265,6 +1272,7 @@ export class HeadlessWebGPURenderer {
// Render and encode frames using pipelined double-buffered DMA staging ring
for (let i = 0; i < totalFrames; i++) {
+ options?.signal?.throwIfAborted();
if (i % 10 === 0) {
rendererLogger.info(
{ renderId, frame: i, totalFrames },
@@ -1321,6 +1329,11 @@ export class HeadlessWebGPURenderer {
);
await pipeline.enqueueFrame(i, targetTexture, encoder);
+ options?.onProgress?.({
+ phase: "render",
+ frame: i + 1,
+ totalFrames,
+ });
} else {
throw new Error("Invalid render context state");
}
@@ -1347,6 +1360,12 @@ export class HeadlessWebGPURenderer {
}
// ── Audio ──────────────────────────────────────────────────────────────
+ options?.signal?.throwIfAborted();
+ options?.onProgress?.({
+ phase: "audio",
+ frame: totalFrames,
+ totalFrames,
+ });
const { channels, sampleRate } = await mixAudioTracks(
virtualMedia,
fps,
@@ -1391,6 +1410,7 @@ export class HeadlessWebGPURenderer {
}
}
+ options?.signal?.throwIfAborted();
await output.finalize();
outputFinalized = true;
@@ -1474,5 +1494,14 @@ export class HeadlessWebGPURenderer {
}
}
+/** Progress reported by `renderVideo({ onProgress })`. */
+export interface RenderProgress {
+ /** "render" while frames are drawn and encoded, "audio" while mixing. */
+ phase: "render" | "audio";
+ /** Frames finished so far (1-based). */
+ frame: number;
+ totalFrames: number;
+}
+
export const HeadlessMediaRenderer = HeadlessWebGPURenderer;
export type HeadlessMediaRenderer = HeadlessWebGPURenderer;
diff --git a/packages/renderer/src/index.ts b/packages/renderer/src/index.ts
index a8defd36..a8418280 100644
--- a/packages/renderer/src/index.ts
+++ b/packages/renderer/src/index.ts
@@ -2,6 +2,7 @@ export * from "./asset-preloader.js";
export * from "./dma-staging-ring.js";
export * from "./dynamic-node-discovery.js";
export * from "./headless-webgpu-renderer.js";
+export * from "./job-reset.js";
export * from "./logger.js";
export * from "./node-manifest.js";
export * from "./video-qa.js";
diff --git a/packages/renderer/src/job-reset.ts b/packages/renderer/src/job-reset.ts
new file mode 100644
index 00000000..4e9706d1
--- /dev/null
+++ b/packages/renderer/src/job-reset.ts
@@ -0,0 +1,23 @@
+import {
+ clearAllVideoCache,
+ inputStore,
+ lutStore,
+ mediaDecoderCache,
+ SlugFontCache,
+ textureCache,
+} from "@framefields/webgpu-renderers";
+
+/**
+ * Drops every cache keyed by a file path or URL: media inputs and decoders,
+ * textures, LUTs and fonts. A long-lived worker calls this between jobs,
+ * because the next checkout may hold different bytes at the same path. The
+ * GPU device and compiled pipelines stay warm.
+ */
+export function resetRenderCaches(): void {
+ clearAllVideoCache();
+ mediaDecoderCache.destroy();
+ textureCache.destroy();
+ inputStore.clear();
+ lutStore.destroy();
+ SlugFontCache.destroy();
+}
diff --git a/packages/webgpu-renderers/src/input-store.ts b/packages/webgpu-renderers/src/input-store.ts
index 25b0fc02..aa8a23d3 100644
--- a/packages/webgpu-renderers/src/input-store.ts
+++ b/packages/webgpu-renderers/src/input-store.ts
@@ -95,6 +95,25 @@ class InputStore {
return shared.promise;
}
+ /**
+ * Drops every cached input, including ones a failed render never released.
+ * Used between jobs, when the same path may now hold a different file.
+ */
+ clear(): void {
+ const entries = [...this.store.values()];
+ this.store.clear();
+ for (const shared of entries) {
+ shared.promise.then(
+ (input) => {
+ try {
+ input.dispose();
+ } catch (_) {}
+ },
+ () => {},
+ );
+ }
+ }
+
release(url: string): void {
if (!url) return;
const resolvedUrl = resolveInputUrl(url, isNodeRuntime());