Code-first video & image, rendered natively on WebGPU.
fix(renderer): fail fast on missing local media files
okanasl71d48b48360e
diff --git a/.changeset/missing-media-fail-fast.md b/.changeset/missing-media-fail-fast.mdnew file mode 100644index 00000000..ccb4ba65--- /dev/null+++ b/.changeset/missing-media-fail-fast.md@@ -0,0 +1,7 @@+---+"@framefields/webgpu-renderers": patch+"@framefields/compositions": patch+"framefields": patch+---++Fail fast when referenced local media files cannot be opened or decoded during headless rendering, instead of silently resolving with black frames or silent audio.diff --git a/packages/compositions/src/utils/audio-extractor.ts b/packages/compositions/src/utils/audio-extractor.tsindex d2534435..48b7b8d0 100644--- a/packages/compositions/src/utils/audio-extractor.ts+++ b/packages/compositions/src/utils/audio-extractor.ts@@ -281,6 +281,12 @@ export async function decodeAudioSource(return { channels, sampleRate };} catch (err) {+ if (+ err instanceof Error &&+ err.message.includes("Cannot open local media file")+ ) {+ throw err;+ }if (typeof process !== "undefined" && process.versions?.node) {try {const { execSync } = await import("node:child_process");@@ -320,6 +326,12 @@ export async function decodeAudioSource(}}} catch (err) {+ if (+ err instanceof Error &&+ err.message.includes("Cannot open local media file")+ ) {+ throw err;+ }mediaLogger.error({ err },`[AudioExtractor] Failed to decode source ${url}`,diff --git a/packages/framefields/src/render.test.ts b/packages/framefields/src/render.test.tsindex eba6aaa6..64499270 100644--- a/packages/framefields/src/render.test.ts+++ b/packages/framefields/src/render.test.ts@@ -225,6 +225,43 @@ describe("Framefields Rendering Engine", () => {await expect(fs.stat(filePath)).rejects.toThrow();});++ it("fails fast when a local video file does not exist", async () => {+ const comp = new Composition({+ width: 320,+ height: 240,+ fps: 30,+ durationMs: 500,+ });+ comp.add(+ Layer.video("../media/does-not-exist.mp4", {+ width: 320,+ height: 240,+ }),+ );+ await expect(comp.renderVideo()).rejects.toThrow(+ /Cannot open local media file.*does-not-exist\.mp4/,+ );+ });++ it("fails fast when a local audio file does not exist", async () => {+ const comp = new Composition({+ width: 320,+ height: 240,+ fps: 30,+ durationMs: 500,+ });+ comp.add(+ Layer.audio("../media/does-not-exist.wav", {+ volume: 1,+ startFrame: 0,+ durationFrames: 15,+ }),+ );+ await expect(comp.renderVideo()).rejects.toThrow(+ /Cannot open local media file.*does-not-exist\.wav/,+ );+ });});describe("4. Audio DSP & Mixing Pipeline", () => {diff --git a/packages/webgpu-renderers/src/nodes/image.ts b/packages/webgpu-renderers/src/nodes/image.tsindex 2acd9642..6fdd0c32 100644--- a/packages/webgpu-renderers/src/nodes/image.ts+++ b/packages/webgpu-renderers/src/nodes/image.ts@@ -44,7 +44,7 @@ class ImageLoader {} else {// Local filesystem file in headless Node.jsconst filePath = (await toLocalPath(src)) ?? src;- const fs = await import(/* webpackIgnore: true */ "fs/promises");+ const fs = await import(/* webpackIgnore: true */ "node:fs/promises");const fileBuf = await fs.readFile(filePath);arrayBuffer = fileBuf.buffer.slice(fileBuf.byteOffset,@@ -99,12 +99,16 @@ export async function drawImageNode(}let tex = textureCache.acquire(props.src);+ const isHeadless =+ props.isHeadless ??+ (typeof window === "undefined" ||+ Boolean(+ (globalThis as { __IS_HEADLESS_RENDERER__?: boolean })+ .__IS_HEADLESS_RENDERER__,+ ));+if (!tex) {try {- const isHeadless =- props.isHeadless ??- (typeof window === "undefined" ||- (globalThis as any).__IS_HEADLESS_RENDERER__);const data = await imageLoader.load(props.src, isHeadless);// Check the cache again in case another concurrent render task already created and cached the texture!@@ -115,6 +119,9 @@ export async function drawImageNode(textureCache.set(props.src, tex, ctx.device);}} catch (err) {+ if (isHeadless) {+ throw err;+ }console.error("Failed to load image texture:", err);return;}diff --git a/packages/webgpu-renderers/src/nodes/video.ts b/packages/webgpu-renderers/src/nodes/video.tsindex 910379f6..c0280aab 100644--- a/packages/webgpu-renderers/src/nodes/video.ts+++ b/packages/webgpu-renderers/src/nodes/video.ts@@ -127,6 +127,10 @@ export const drawVideoNode = async (const exactKey = props.frameKey;let exactTex = textureCache.acquire(exactKey);+ const isPlaying = props.isPlaying ?? true;+ const shouldWait = isHeadless || props.forceWait || !isPlaying;+ const isFirstFrame = !lastGoodFrameKey.has(nodeId);+if (!exactTex) {// Only start a decode if one isn't already running for this keyif (!pendingDecodes.has(exactKey)) {@@ -140,28 +144,31 @@ export const drawVideoNode = async (0,Number.isFinite(props.timestampSec) ? props.timestampSec : 0,);- const decodePromise = decoder- .getFrame(safeTimestampSec)- .then((frame) => {- if (!frame) return;- // Another render cycle may have already uploaded this- const existing = textureCache.acquire(exactKey);- if (existing) {- textureCache.release(exactKey);- return;- }- const tex = uploadFrameToTexture(ctx, exactKey, frame, isHeadless);- if (tex) {- updateLastGoodFrame(nodeId, exactKey, ctx.device);- }- })- .catch((err) => {+ const innerPromise = (async () => {+ const frame = await decoder.getFrame(safeTimestampSec);+ if (!frame) return;+ // Another render cycle may have already uploaded this+ const existing = textureCache.acquire(exactKey);+ if (existing) {+ textureCache.release(exactKey);+ return;+ }+ const tex = uploadFrameToTexture(ctx, exactKey, frame, isHeadless);+ if (tex) {+ updateLastGoodFrame(nodeId, exactKey, ctx.device);+ }+ })();++ const decodePromise = innerPromise.finally(() => {+ pendingDecodes.delete(exactKey);+ delays.delete(delayHandle);+ });++ decodePromise.catch((err) => {+ if (!shouldWait && !isFirstFrame) {console.error("[VideoNode] decode error:", err);- })- .finally(() => {- pendingDecodes.delete(exactKey);- delays.delete(delayHandle);- });+ }+ });pendingDecodes.set(exactKey, decodePromise);@@ -173,17 +180,11 @@ export const drawVideoNode = async (// keeps rendering smooth at full frame-rate.// In headless mode we ALWAYS await every frame to guarantee 100%// frame-accuracy and prevent parallel decodes clogging WebCodecs.- const isPlaying = props.isPlaying ?? true;- const shouldWait = isHeadless || props.forceWait || !isPlaying;- const isFirstFrame = !lastGoodFrameKey.has(nodeId);if (isFirstFrame || shouldWait) {await decodePromise;exactTex = textureCache.acquire(exactKey);}} else {- const isPlaying = props.isPlaying ?? true;- const shouldWait = isHeadless || props.forceWait || !isPlaying;- const isFirstFrame = !lastGoodFrameKey.has(nodeId);if (isFirstFrame || shouldWait) {await pendingDecodes.get(exactKey);exactTex = textureCache.acquire(exactKey);@@ -226,6 +227,9 @@ export const drawVideoNode = async (textureCache.release(activeKey);}} catch (err) {+ if (isHeadless) {+ throw err;+ }console.error("[VideoNode] drawVideoNode error:", err);}};