fix(studio-server): give every freeze still its own immutable name

Two clip ids that sanitise alike (a.b / a_b), ids sharing an 80-character
prefix, or a second freeze of one clip at the same playhead all produced the
same still path, and ffmpeg's -y replaced the first still's pixels. The name
now carries a hash of the raw id and a per-extraction token, the route
refuses a name that already exists, and ffmpeg runs with -n so it can never
overwrite. The freeze media time reads data-playback-start before
data-media-start, as playback does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: vanceingalls

packages/studio-server/src/helpers/freezeFrame.test.ts

@@ -61,9 +61,9 @@ describe("freezeFrameMediaTime", () => {
 });
 
 describe("freezeExtractArgs", () => {
-  it("seeks before the input and writes one frame", () => {
+  it("seeks before the input and writes one frame, never over an existing file", () => {
     expect(freezeExtractArgs("/p/a.mp4", 7.2004, "/p/assets/freeze/a-3200.png")).toEqual([
-      "-y",
+      "-n",
       "-ss",
       "7.2",
       "-i",
@@ -98,6 +98,14 @@ describe("readFreezeSource", () => {
     });
   });
 
+  it("reads the in-point as playback does: data-playback-start before data-media-start", () => {
+    const both = project.replace(
+      'data-media-start="2"',
+      'data-media-start="2" data-playback-start="5"',
+    );
+    expect(readFreezeSource(both, { id: "talk" }, 3.2)?.mediaTime).toBe(7.2);
+  });
+
   it("refuses a playhead outside the clip or a non-video", () => {
     expect(readFreezeSource(project, { id: "talk" }, 0.5)).toBeNull();
     expect(readFreezeSource(project, { id: "later" }, 8.5)).toBeNull();
@@ -156,9 +164,23 @@ describe("applyFreezeFrameToHtml", () => {
 
 describe("freezeStillFileName", () => {
   it("reduces a clip id to one safe filename component", () => {
-    expect(freezeStillFileName("talk", 2.5)).toBe("talk-2500.png");
-    expect(freezeStillFileName("../../etc/x", 1)).toBe("______etc_x-1000.png");
-    expect(freezeStillFileName("a\\b:c", 1)).toBe("a_b_c-1000.png");
-    expect(freezeStillFileName("", 1)).toBe("clip-1000.png");
+    expect(freezeStillFileName("talk", 2.5, "t0")).toMatch(/^talk-[0-9a-f]{10}-2500-t0\.png$/);
+    expect(freezeStillFileName("../../etc/x", 1, "t0")).toMatch(
+      /^______etc_x-[0-9a-f]{10}-1000-t0\.png$/,
+    );
+    expect(freezeStillFileName("a\\b:c", 1, "t0")).toMatch(/^a_b_c-[0-9a-f]{10}-1000-t0\.png$/);
+    expect(freezeStillFileName("", 1, "t0")).toMatch(/^clip-[0-9a-f]{10}-1000-t0\.png$/);
+  });
+
+  it("keeps ids that sanitise or truncate alike apart", () => {
+    expect(freezeStillFileName("a.b", 2.5, "t0")).not.toBe(freezeStillFileName("a_b", 2.5, "t0"));
+    const prefix = "v".repeat(80);
+    expect(freezeStillFileName(`${prefix}1`, 2.5, "t0")).not.toBe(
+      freezeStillFileName(`${prefix}2`, 2.5, "t0"),
+    );
+  });
+
+  it("names every extraction of one clip at one time differently", () => {
+    expect(freezeStillFileName("talk", 2.5)).not.toBe(freezeStillFileName("talk", 2.5));
   });
 });

packages/studio-server/src/helpers/freezeFrame.ts

@@ -1,4 +1,6 @@
+import { createHash, randomBytes } from "node:crypto";
 import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
+import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
 import { resolveRateSpec, sourceTimeAt } from "@hyperframes/core/speed-ramp";
 import {
   findTargetElement,
@@ -38,12 +40,19 @@ export function freezeFrameMediaTime(input: {
 }
 
 export function freezeExtractArgs(src: string, mediaTime: number, output: string): string[] {
-  return ["-y", "-ss", String(round3(mediaTime)), "-i", src, "-frames:v", "1", output];
+  return ["-n", "-ss", String(round3(mediaTime)), "-i", src, "-frames:v", "1", output];
 }
 
-export function freezeStillFileName(clipId: string, playhead: number): string {
-  const stem = clipId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80) || "clip";
-  return `${stem}-${Math.round(playhead * 1000)}.png`;
+export const randomStillToken = (): string => randomBytes(4).toString("hex");
+
+export function freezeStillFileName(
+  clipId: string,
+  playhead: number,
+  token: string = randomStillToken(),
+): string {
+  const stem = clipId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 48) || "clip";
+  const idHash = createHash("sha256").update(clipId).digest("hex").slice(0, 10);
+  return `${stem}-${idHash}-${Math.round(playhead * 1000)}-${token}.png`;
 }
 
 export interface FreezeSource {
@@ -72,7 +81,7 @@ export function readFreezeSource(
     mediaTime: freezeFrameMediaTime({
       clipStart: start,
       playhead,
-      mediaStart: numberAttr(el, "data-media-start") ?? numberAttr(el, "data-playback-start") ?? 0,
+      mediaStart: readMediaOffsetSeconds((name) => el.getAttribute(name)),
       playbackRate: numberAttr(el, "data-playback-rate") ?? 1,
       automation: el.getAttribute("data-automation"),
     }),

packages/studio-server/src/routes/freezeFrame.test.ts

@@ -2,7 +2,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import { Hono } from "hono";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { registerFreezeFrameRoutes, type FrameExtractor } from "./freezeFrame";
 import { fileContentVersion } from "../helpers/fileVersion";
 import type { StudioApiAdapter } from "../types";
@@ -16,7 +16,11 @@ const html = `<div data-composition-id="main" data-start="0" data-duration="6">
 <video id="talk" class="clip" src="media/talk.mp4" data-start="0" data-duration="6" data-track-index="0"></video>
 </div>`;
 
-function setup(extract: FrameExtractor, file = { path: "index.html", html }) {
+function setup(
+  extract: FrameExtractor,
+  file = { path: "index.html", html },
+  stillToken?: () => string,
+) {
   const dir = mkdtempSync(join(tmpdir(), "hf-freeze-"));
   tempDirs.push(dir);
   mkdirSync(dirname(join(dir, file.path)), { recursive: true });
@@ -31,7 +35,7 @@ function setup(extract: FrameExtractor, file = { path: "index.html", html }) {
     startRender: () => ({ id: "j", status: "rendering", progress: 0, outputPath: "/tmp/o.mp4" }),
   };
   const app = new Hono();
-  registerFreezeFrameRoutes(app, adapter, extract);
+  registerFreezeFrameRoutes(app, adapter, extract, stillToken);
   const post = (body: unknown) =>
     app.request("http://localhost/projects/demo/file-mutations/freeze-frame", {
       method: "POST",
@@ -56,17 +60,20 @@ describe("freeze-frame route", () => {
     });
     const body: { before?: string; after?: string; imageSrc?: string } = await res.json();
     expect(res.status).toBe(200);
+    const output = calls[0]?.at(-1) ?? "";
     expect(calls[0]).toEqual([
-      "-y",
+      "-n",
       "-ss",
       "2.5",
       "-i",
       join(dir, "media/talk.mp4"),
       "-frames:v",
       "1",
-      join(dir, "assets/freeze/talk-2500.png"),
+      output,
     ]);
-    expect(body.imageSrc).toBe("assets/freeze/talk-2500.png");
+    expect(dirname(output)).toBe(join(dir, "assets/freeze"));
+    expect(basename(output)).toMatch(/^talk-[0-9a-f]{10}-2500-[0-9a-f]{8}\.png$/);
+    expect(body.imageSrc).toBe(`assets/freeze/${basename(output)}`);
     expect(body.before).toBe(html);
     expect(readFileSync(join(dir, "index.html"), "utf-8")).toBe(body.after);
     expect(body.after).toContain('id="talk-freeze"');
@@ -118,11 +125,102 @@ describe("freeze-frame route", () => {
     });
     const body: { imageSrc?: string; after?: string } = await res.json();
     expect(res.status).toBe(200);
-    const output = calls[0]?.at(-1);
-    expect(output).toBe(join(dir, "assets/freeze/____________outside_frame-2500.png"));
-    expect(dirname(output ?? "")).toBe(join(dir, "assets/freeze"));
-    expect(body.imageSrc).toBe("../assets/freeze/____________outside_frame-2500.png");
-    expect(body.after).toContain('src="../assets/freeze/____________outside_frame-2500.png"');
+    const output = calls[0]?.at(-1) ?? "";
+    expect(basename(output)).toMatch(/^____________outside_frame-[0-9a-f]{10}-2500-/);
+    expect(dirname(output)).toBe(join(dir, "assets/freeze"));
+    expect(body.imageSrc).toBe(`../assets/freeze/${basename(output)}`);
+    expect(body.after).toContain(`src="../assets/freeze/${basename(output)}"`);
     expect(existsSync(join(dir, "..", "outside"))).toBe(false);
   });
+
+  describe("still identity", () => {
+    const twoVideos = (
+      a: string,
+      b: string,
+    ) => `<div data-composition-id="main" data-start="0" data-duration="6">
+<video id="${a}" class="clip" src="media/a.mp4" data-start="0" data-duration="6" data-track-index="0"></video>
+<video id="${b}" class="clip" src="media/b.mp4" data-start="0" data-duration="6" data-track-index="1"></video>
+</div>`;
+
+    function writingExtractor(outputs: string[]): FrameExtractor {
+      return async (args) => {
+        const output = args.at(-1) ?? "";
+        outputs.push(output);
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        try {
+          writeFileSync(output, `frame of ${args[4]} #${outputs.length}`, {
+            flag: args.includes("-y") ? "w" : "wx",
+          });
+          return { ok: true };
+        } catch (error) {
+          return { ok: false, error: String(error) };
+        }
+      };
+    }
+
+    function freeze(post: (body: unknown) => Promise<Response>, dir: string, id: string) {
+      return post({
+        path: "index.html",
+        expectedVersion: fileContentVersion(readFileSync(join(dir, "index.html"), "utf-8")),
+        target: { id },
+        playhead: 2.5,
+      });
+    }
+
+    it("gives two ids that sanitise alike distinct stills and keeps the first one's pixels", async () => {
+      const outputs: string[] = [];
+      const source = twoVideos("a.b", "a_b");
+      const { dir, post } = setup(writingExtractor(outputs), { path: "index.html", html: source });
+      expect((await freeze(post, dir, "a.b")).status).toBe(200);
+      const first = readFileSync(outputs[0] ?? "", "utf-8");
+      expect((await freeze(post, dir, "a_b")).status).toBe(200);
+      expect(outputs[1]).not.toBe(outputs[0]);
+      expect(readFileSync(outputs[0] ?? "", "utf-8")).toBe(first);
+    });
+
+    it("keeps ids sharing an 80-character prefix apart", async () => {
+      const outputs: string[] = [];
+      const prefix = "v".repeat(80);
+      const source = twoVideos(`${prefix}1`, `${prefix}2`);
+      const { dir, post } = setup(writingExtractor(outputs), { path: "index.html", html: source });
+      expect((await freeze(post, dir, `${prefix}1`)).status).toBe(200);
+      expect((await freeze(post, dir, `${prefix}2`)).status).toBe(200);
+      expect(new Set(outputs).size).toBe(2);
+    });
+
+    it("writes a new still when the same clip is frozen again at the same time", async () => {
+      const outputs: string[] = [];
+      const { dir, post } = setup(writingExtractor(outputs));
+      expect((await freeze(post, dir, "talk")).status).toBe(200);
+      const first = readFileSync(outputs[0] ?? "", "utf-8");
+      writeFileSync(join(dir, "index.html"), html);
+      expect((await freeze(post, dir, "talk")).status).toBe(200);
+      expect(outputs[1]).not.toBe(outputs[0]);
+      expect(readFileSync(outputs[0] ?? "", "utf-8")).toBe(first);
+    });
+
+    it("gives concurrent requests distinct stills", async () => {
+      const outputs: string[] = [];
+      const { dir, post } = setup(writingExtractor(outputs));
+      const results = await Promise.all([freeze(post, dir, "talk"), freeze(post, dir, "talk")]);
+      expect(results.map((res) => res.status).sort()).toEqual([200, 409]);
+      expect(new Set(outputs).size).toBe(2);
+      expect(outputs.map((output) => readFileSync(output, "utf-8"))).toEqual([
+        expect.stringContaining("#"),
+        expect.stringContaining("#"),
+      ]);
+    });
+
+    it("refuses, without extracting, when the still's name is already taken", async () => {
+      const outputs: string[] = [];
+      const { dir, post } = setup(writingExtractor(outputs), undefined, () => "fixed");
+      expect((await freeze(post, dir, "talk")).status).toBe(200);
+      const first = readFileSync(outputs[0] ?? "", "utf-8");
+      writeFileSync(join(dir, "index.html"), html);
+      expect((await freeze(post, dir, "talk")).status).toBe(409);
+      expect(outputs).toHaveLength(1);
+      expect(readFileSync(outputs[0] ?? "", "utf-8")).toBe(first);
+      expect(readFileSync(join(dir, "index.html"), "utf-8")).toBe(html);
+    });
+  });
 });

packages/studio-server/src/routes/freezeFrame.ts

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
 import type { Hono } from "hono";
 import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
@@ -16,6 +16,7 @@ import {
   applyFreezeFrameToHtml,
   freezeExtractArgs,
   freezeStillFileName,
+  randomStillToken,
   readFreezeSource,
   type FreezeSource,
 } from "../helpers/freezeFrame.js";
@@ -84,19 +85,21 @@ async function extractStill(
   absPath: string,
   source: FreezeSource,
   playhead: number,
-  extract: FrameExtractor,
+  tools: { extract: FrameExtractor; stillToken: () => string },
 ): Promise<{ imageSrc: string } | Failure> {
   const fileDir = dirname(absPath);
   const mediaPath = pinWithinProject(projectDir, relative(projectDir, join(fileDir, source.src)));
   if (!mediaPath) return { error: `forbidden media path: ${source.src}`, status: 403 };
   const freezeDir = join(projectDir, ...FREEZE_DIR);
-  const fileName = freezeStillFileName(source.id, playhead);
+  const fileName = freezeStillFileName(source.id, playhead, tools.stillToken());
   mkdirWithinProject(projectDir, freezeDir);
   const imagePath = pinWithinProject(projectDir, join(...FREEZE_DIR, fileName));
   if (!imagePath || dirname(imagePath) !== freezeDir) {
     return { error: `forbidden freeze path: ${fileName}`, status: 403 };
   }
-  const extracted = await extract(freezeExtractArgs(mediaPath, source.mediaTime, imagePath));
+  if (existsSync(imagePath))
+    return { error: `freeze still already exists: ${fileName}`, status: 409 };
+  const extracted = await tools.extract(freezeExtractArgs(mediaPath, source.mediaTime, imagePath));
   if (!extracted.ok) {
     return {
       error: `Could not extract the frame: ${extracted.error ?? "ffmpeg failed"}`,
@@ -132,6 +135,7 @@ export function registerFreezeFrameRoutes(
   api: Hono,
   adapter: StudioApiAdapter,
   extract: FrameExtractor = ffmpegExtractor,
+  stillToken: () => string = randomStillToken,
 ): void {
   // A straight line of request guards, each its own early return.
   // fallow-ignore-next-line complexity
@@ -151,7 +155,10 @@ export function registerFreezeFrameRoutes(
 
     const source = readFreezeSource(before, body.target, body.playhead);
     if (!source) return c.json({ error: "Move the playhead inside a video clip to freeze" }, 400);
-    const still = await extractStill(project.dir, absPath, source, body.playhead, extract);
+    const still = await extractStill(project.dir, absPath, source, body.playhead, {
+      extract,
+      stillToken,
+    });
     if ("error" in still) return c.json({ error: still.error }, still.status);
     const { imageSrc } = still;
     const folded = applyFreezeFrameToHtml(before, {