Skip to content

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.md
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.js
const 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.ts
index 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 key
if (!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);
}
};