Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(engine): invalidate cached media metadata after file changes (#5258)
Abdullah M. Nazif730a3308008e
diff --git a/packages/engine/src/utils/ffprobe.test.ts b/packages/engine/src/utils/ffprobe.test.tsindex 7c35deb10e..6cb00a6685 100644--- a/packages/engine/src/utils/ffprobe.test.ts+++ b/packages/engine/src/utils/ffprobe.test.ts@@ -1,7 +1,7 @@// fallow-ignore-file code-duplicationimport { EventEmitter } from "events";import { spawnSync } from "child_process";-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";+import { mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";import { tmpdir } from "os";import { basename, resolve } from "path";import { afterEach, describe, expect, it, vi } from "vitest";@@ -593,6 +593,258 @@ function createSpawnSpy(outcomes: SpawnOutcome[]): {return { spawn, calls };}+describe("media metadata cache invalidation", () => {+ afterEach(() => {+ vi.resetModules();+ vi.doUnmock("child_process");+ });++ it("refreshes video metadata after an in-place file change", async () => {+ const dir = mkdtempSync(resolve(tmpdir(), "hf-video-metadata-change-"));+ const file = resolve(dir, "video.mp4");+ writeFileSync(file, "original file");+ const { spawn, calls } = createSpawnSpy([+ {+ kind: "exit",+ code: 0,+ stdout: JSON.stringify({+ streams: [+ { codec_type: "video", width: 32, height: 24, avg_frame_rate: "10/1", duration: "1" },+ ],+ format: { duration: "1" },+ }),+ },+ {+ kind: "exit",+ code: 0,+ stdout: JSON.stringify({+ streams: [+ { codec_type: "video", width: 64, height: 48, avg_frame_rate: "24/1", duration: "2" },+ ],+ format: { duration: "2" },+ }),+ },+ ]);+ vi.resetModules();+ vi.doMock("child_process", () => ({ spawn }));+ const { extractMediaMetadata } = await import("./ffprobe.js");+ try {+ expect(await extractMediaMetadata(file)).toMatchObject({ width: 32, durationSeconds: 1 });+ writeFileSync(file, "updated file with different dimensions");+ const refreshed = await extractMediaMetadata(file);+ expect(refreshed).toMatchObject({ width: 64, height: 48, fps: 24, durationSeconds: 2 });+ expect(await extractMediaMetadata(file)).toBe(refreshed);+ expect(calls).toHaveLength(2);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });++ it("refreshes audio metadata after an atomic same-size file replacement", async () => {+ const dir = mkdtempSync(resolve(tmpdir(), "hf-audio-metadata-change-"));+ const file = resolve(dir, "audio.wav");+ const replacement = resolve(dir, "replacement.wav");+ writeFileSync(file, "first");+ const { spawn, calls } = createSpawnSpy([+ {+ kind: "exit",+ code: 0,+ stdout: JSON.stringify({+ streams: [+ { codec_type: "audio", codec_name: "pcm_s16le", sample_rate: "22050", channels: 1 },+ ],+ format: { duration: "1" },+ }),+ },+ {+ kind: "exit",+ code: 0,+ stdout: JSON.stringify({+ streams: [+ { codec_type: "audio", codec_name: "pcm_s16le", sample_rate: "44100", channels: 2 },+ ],+ format: { duration: "2" },+ }),+ },+ ]);+ vi.resetModules();+ vi.doMock("child_process", () => ({ spawn }));+ const { extractAudioMetadata } = await import("./ffprobe.js");+ try {+ expect(await extractAudioMetadata(file)).toMatchObject({+ durationSeconds: 1,+ sampleRate: 22050,+ });+ writeFileSync(replacement, "other");+ renameSync(replacement, file);+ const refreshed = await extractAudioMetadata(file);+ expect(refreshed).toMatchObject({ durationSeconds: 2, sampleRate: 44100, channels: 2 });+ expect(await extractAudioMetadata(file)).toBe(refreshed);+ expect(calls).toHaveLength(2);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });++ it.each([false, true])(+ "refreshes final-frame timestamps in signal scope %s",+ async (useSignal) => {+ const dir = mkdtempSync(resolve(tmpdir(), "hf-final-frame-change-"));+ const file = resolve(dir, "video.mp4");+ writeFileSync(file, "original file");+ const { spawn, calls } = createSpawnSpy([+ { kind: "exit", code: 0, stdout: "1.900000\n" },+ { kind: "exit", code: 0, stdout: "1.950000\n" },+ ]);+ vi.resetModules();+ vi.doMock("child_process", () => ({ spawn }));+ const { extractFinalVideoFrameTimestamp } = await import("./ffprobe.js");+ const metadata = { videoStreamDurationSeconds: 2, videoStreamStartSeconds: 0 };+ const signal = useSignal ? new AbortController().signal : undefined;+ try {+ expect(await extractFinalVideoFrameTimestamp(file, metadata, signal)).toBe(1.9);+ writeFileSync(file, "updated file with a different frame rate");+ expect(await extractFinalVideoFrameTimestamp(file, metadata, signal)).toBe(1.95);+ expect(await extractFinalVideoFrameTimestamp(file, metadata, signal)).toBe(1.95);+ expect(calls).toHaveLength(2);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ },+ );++ it("does not return successful cached metadata after the file disappears", async () => {+ const dir = mkdtempSync(resolve(tmpdir(), "hf-metadata-removed-"));+ const file = resolve(dir, "video.mp4");+ writeFileSync(file, "original file");+ const { spawn, calls } = createSpawnSpy([+ {+ kind: "exit",+ code: 0,+ stdout: JSON.stringify({+ streams: [{ codec_type: "video", width: 32, height: 24 }],+ format: { duration: "1" },+ }),+ },+ { kind: "exit", code: 1, stderr: "input missing" },+ ]);+ vi.resetModules();+ vi.doMock("child_process", () => ({ spawn }));+ const { extractMediaMetadata } = await import("./ffprobe.js");+ try {+ await extractMediaMetadata(file);+ rmSync(file);+ await expect(extractMediaMetadata(file)).rejects.toThrow(/input missing/);+ expect(calls).toHaveLength(2);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });++ it("does not retain completed metadata when file identity is unavailable", async () => {+ const dir = mkdtempSync(resolve(tmpdir(), "hf-metadata-no-identity-"));+ const file = resolve(dir, "missing.wav");+ const { spawn, calls } = createSpawnSpy([+ {+ kind: "exit",+ code: 0,+ stdout: JSON.stringify({+ streams: [{ codec_type: "audio", codec_name: "mp3" }],+ format: { duration: "1" },+ }),+ },+ {+ kind: "exit",+ code: 0,+ stdout: JSON.stringify({+ streams: [{ codec_type: "audio", codec_name: "mp3" }],+ format: { duration: "2" },+ }),+ },+ ]);+ vi.resetModules();+ vi.doMock("child_process", () => ({ spawn }));+ const { extractAudioMetadata } = await import("./ffprobe.js");+ try {+ expect(await extractAudioMetadata(file)).toMatchObject({ durationSeconds: 1 });+ expect(await extractAudioMetadata(file)).toMatchObject({ durationSeconds: 2 });+ expect(calls).toHaveLength(2);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });++ it("keeps the replacement probe cached when an older probe fails", async () => {+ const dir = mkdtempSync(resolve(tmpdir(), "hf-metadata-probe-race-"));+ const file = resolve(dir, "video.mp4");+ writeFileSync(file, "original file");+ const factory = createSpawnSpy([]);+ const processes: FakeProc[] = [];+ vi.resetModules();+ vi.doMock("child_process", () => ({+ spawn: (command: string, args: readonly string[]) => {+ const proc = factory.spawn(command, args);+ processes.push(proc);+ return proc;+ },+ }));+ const { extractMediaMetadata } = await import("./ffprobe.js");+ try {+ const failed = expect(extractMediaMetadata(file)).rejects.toThrow(/code 1/);+ writeFileSync(file, "updated file with different dimensions");+ const replacement = extractMediaMetadata(file);+ processes[0]?.emit("close", 1);+ await failed;+ const shared = extractMediaMetadata(file);+ expect(factory.calls).toHaveLength(2);+ processes[1]?.stdout.emit(+ "data",+ Buffer.from(+ JSON.stringify({+ streams: [{ codec_type: "video", width: 64, height: 48 }],+ format: { duration: "2" },+ }),+ ),+ );+ processes[1]?.emit("close", 0);+ const [first, second] = await Promise.all([replacement, shared]);+ expect(second).toBe(first);+ expect(first).toMatchObject({ width: 64, durationSeconds: 2 });+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });++ it("still shares an unchanged file probe between concurrent callers", async () => {+ const dir = mkdtempSync(resolve(tmpdir(), "hf-metadata-shared-"));+ const file = resolve(dir, "video.mp4");+ writeFileSync(file, "unchanged file");+ const { spawn, calls } = createSpawnSpy([+ {+ kind: "exit",+ code: 0,+ stdout: JSON.stringify({+ streams: [{ codec_type: "video", width: 32, height: 24 }],+ format: { duration: "1" },+ }),+ },+ ]);+ vi.resetModules();+ vi.doMock("child_process", () => ({ spawn }));+ const { extractMediaMetadata } = await import("./ffprobe.js");+ try {+ const [first, second] = await Promise.all([+ extractMediaMetadata(file),+ extractMediaMetadata(file),+ ]);+ expect(second).toBe(first);+ expect(calls).toHaveLength(1);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });+});+describe("ffprobe missing-binary fallback", () => {const originalFfprobePath = process.env.HYPERFRAMES_FFPROBE_PATH;const originalPath = process.env.PATH;diff --git a/packages/engine/src/utils/ffprobe.ts b/packages/engine/src/utils/ffprobe.tsindex 67c39d32dd..b0576258c4 100644--- a/packages/engine/src/utils/ffprobe.ts+++ b/packages/engine/src/utils/ffprobe.ts@@ -142,16 +142,16 @@ function parseProbeJson(stdout: string): FFProbeOutput {}}-const videoMetadataCache = new Map<string, Promise<VideoMetadata>>();-const finalVideoFrameTimestampCache = new Map<string, Promise<number>>();+const videoMetadataCache = new Map<string, MediaProbeCacheEntry<VideoMetadata>>();+const finalVideoFrameTimestampCache = new Map<string, MediaProbeCacheEntry<number>>();const finalVideoFrameTimestampSignalCaches = new WeakMap<AbortSignal,- Map<string, Promise<number>>+ Map<string, MediaProbeCacheEntry<number>>>();-const audioMetadataCache = new Map<string, Promise<AudioMetadata>>();-interface MediaProbeCacheEntry {- identity: string;- promise: Promise<FFProbeOutput>;+const audioMetadataCache = new Map<string, MediaProbeCacheEntry<AudioMetadata>>();+interface MediaProbeCacheEntry<T = FFProbeOutput> {+ identity: string | null;+ promise: Promise<T>;}const mediaProbeOutputCache = new Map<string, MediaProbeCacheEntry>();@@ -329,6 +329,34 @@ function mediaFileIdentity(filePath: string): string | null {}}+function readMetadataCache<T>(+ cache: Map<string, MediaProbeCacheEntry<T>>,+ key: string,+ identity: string | null,+): Promise<T> | undefined {+ const cached = cache.get(key);+ return cached?.identity === identity ? cached.promise : undefined;+}++function writeMetadataCache<T>(+ cache: Map<string, MediaProbeCacheEntry<T>>,+ key: string,+ identity: string | null,+ promise: Promise<T>,+): void {+ const entry = { identity, promise };+ cache.set(key, entry);+ void promise.then(+ () => {+ // Without a file identity, share only the in-flight probe, never its result.+ if (identity === null && cache.get(key) === entry) cache.delete(key);+ },+ () => {+ if (cache.get(key) === entry) cache.delete(key);+ },+ );+}+async function probeMediaOutput(filePath: string, signal?: AbortSignal): Promise<FFProbeOutput> {let cache = mediaProbeOutputCache;if (signal) {@@ -667,7 +695,8 @@ export function parseFrameRate(frameRateStr: string | undefined): number {* can be used uniformly for any visual asset the HDR pipeline encounters.*/export async function extractMediaMetadata(filePath: string): Promise<VideoMetadata> {- const cached = videoMetadataCache.get(filePath);+ const identity = mediaFileIdentity(filePath);+ const cached = readMetadataCache(videoMetadataCache, filePath, identity);if (cached) return cached;const probePromise = (async (): Promise<VideoMetadata> => {@@ -797,12 +826,7 @@ export async function extractMediaMetadata(filePath: string): Promise<VideoMetad};})();- videoMetadataCache.set(filePath, probePromise);- probePromise.catch(() => {- if (videoMetadataCache.get(filePath) === probePromise) {- videoMetadataCache.delete(filePath);- }- });+ writeMetadataCache(videoMetadataCache, filePath, identity, probePromise);return probePromise;}@@ -845,6 +869,7 @@ export async function extractFinalVideoFrameTimestamp(videoStreamDurationSeconds: videoDurationSeconds,cacheKey,} = resolveStreamWindow(filePath, metadata);+ const identity = mediaFileIdentity(filePath);// A caller-owned abort signal cannot safely own a globally shared process// promise: aborting one render would fail unrelated consumers. Calls in the// SAME cancellation scope should still share the expensive interval +@@ -857,7 +882,7 @@ export async function extractFinalVideoFrameTimestamp(probeCache = finalVideoFrameTimestampSignalCaches.get(signal) ?? new Map();finalVideoFrameTimestampSignalCaches.set(signal, probeCache);}- const cached = probeCache.get(cacheKey);+ const cached = readMetadataCache(probeCache, cacheKey, identity);if (cached) return cached;const probePromise = (async () => {@@ -900,12 +925,7 @@ export async function extractFinalVideoFrameTimestamp(return Math.min(Math.max(timestamp - videoStreamStartSeconds, 0), videoDurationSeconds);})();- probeCache.set(cacheKey, probePromise);- probePromise.catch(() => {- if (probeCache.get(cacheKey) === probePromise) {- probeCache.delete(cacheKey);- }- });+ writeMetadataCache(probeCache, cacheKey, identity, probePromise);return probePromise;}@@ -924,7 +944,10 @@ export async function extractAudioMetadata(// A caller-owned abort signal cannot safely share a cached in-flight probe:// cancelling one consumer would also cancel unrelated consumers. Signal-bound// probes therefore bypass the process-promise cache.- const cached = options?.signal ? undefined : audioMetadataCache.get(filePath);+ const identity = mediaFileIdentity(filePath);+ const cached = options?.signal+ ? undefined+ : readMetadataCache(audioMetadataCache, filePath, identity);if (cached) return cached;const probePromise = (async (): Promise<AudioMetadata> => {@@ -1003,12 +1026,7 @@ export async function extractAudioMetadata(})();if (options?.signal) return probePromise;- audioMetadataCache.set(filePath, probePromise);- probePromise.catch(() => {- if (audioMetadataCache.get(filePath) === probePromise) {- audioMetadataCache.delete(filePath);- }- });+ writeMetadataCache(audioMetadataCache, filePath, identity, probePromise);return probePromise;}