Skip to content

Commit 86b5c1d

Browse files
feat: add Studio current-frame capture (heygen-com#565)
## Problem Closes heygen-com#555. Studio users could inspect the preview, but there was no first-class way to capture the current rendered frame as an image. ## What this fixes - Adds a `Capture` action to the Studio header toolbar so it does not cover the video preview. - Downloads the current composition frame as a PNG using the current player time. - Extends the existing thumbnail route and Studio/CLI thumbnail generators with an explicit PNG format path while preserving JPEG thumbnails for existing previews. - Adds URL/filename utility coverage plus thumbnail route coverage for PNG requests. ## Root cause Studio already had frame thumbnail generation, but the API path was JPEG-oriented and the editor UI only used it for previews. There was no current-frame capture affordance wired to the player state. ## Verification ### Local - `bun run --filter @hyperframes/core test src/studio-api/routes/thumbnail.test.ts` - `bun run --filter @hyperframes/studio test src/utils/frameCapture.test.ts src/player/components/PlayerControls.test.ts` - `bun run --filter @hyperframes/studio typecheck` - `bun run --filter @hyperframes/core typecheck` - `bun run --filter @hyperframes/cli typecheck` - `bunx oxlint packages/cli/src/server/studioServer.ts packages/core/src/studio-api/routes/thumbnail.test.ts packages/core/src/studio-api/routes/thumbnail.ts packages/core/src/studio-api/types.ts packages/studio/src/App.tsx packages/studio/src/icons/SystemIcons.tsx packages/studio/vite.config.ts packages/studio/src/utils/frameCapture.ts packages/studio/src/utils/frameCapture.test.ts` - `bunx oxfmt --check packages/cli/src/server/studioServer.ts packages/core/src/studio-api/routes/thumbnail.test.ts packages/core/src/studio-api/routes/thumbnail.ts packages/core/src/studio-api/types.ts packages/studio/src/App.tsx packages/studio/src/icons/SystemIcons.tsx packages/studio/vite.config.ts packages/studio/src/utils/frameCapture.ts packages/studio/src/utils/frameCapture.test.ts` - `git diff --check` ### Browser <img width="1027" height="910" alt="image" src="https://github.com/user-attachments/assets/71973af4-0279-4074-9 <img width="1026" height="902" alt="Screenshot 2026-04-29 at 16 17 22" src="https://github.com/user-attachments/assets/a32e1c19-b793-40b9-82f8-de8bbb11f123" /> 060-130839a2d419" />
1 parent aa34132 commit 86b5c1d

13 files changed

Lines changed: 321 additions & 117 deletions

File tree

‎packages/cli/src/server/studioServer.ts‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -278,11 +278,18 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
278278
};
279279
}, opts.selector);
280280
}
281-
const screenshot = (await page.screenshot({
282-
type: "jpeg",
283-
quality: 80,
284-
...(clip ? { clip } : {}),
285-
})) as Buffer;
281+
const screenshot = (await page.screenshot(
282+
opts.format === "png"
283+
? {
284+
type: "png",
285+
...(clip ? { clip } : {}),
286+
}
287+
: {
288+
type: "jpeg",
289+
quality: 80,
290+
...(clip ? { clip } : {}),
291+
},
292+
)) as Buffer;
286293
return screenshot;
287294
} catch {
288295
return null;

‎packages/core/src/studio-api/routes/thumbnail.test.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,27 @@ describe("registerThumbnailRoutes", () => {
5151
compPath: "index.html",
5252
seekTime: 1.2,
5353
selector: "#title-card",
54+
format: "jpeg",
55+
}),
56+
);
57+
});
58+
59+
it("forwards png capture requests and returns a png content type", async () => {
60+
const adapter = createAdapter();
61+
const app = new Hono();
62+
registerThumbnailRoutes(app, adapter);
63+
64+
const response = await app.request(
65+
"http://localhost/projects/demo/thumbnail/compositions%2Fintro.html?t=2&format=png",
66+
);
67+
68+
expect(response.status).toBe(200);
69+
expect(response.headers.get("Content-Type")).toBe("image/png");
70+
expect(adapter.generateThumbnail).toHaveBeenCalledWith(
71+
expect.objectContaining({
72+
compPath: "compositions/intro.html",
73+
seekTime: 2,
74+
format: "png",
5475
}),
5576
);
5677
});

‎packages/core/src/studio-api/routes/thumbnail.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
2323
const vpWidth = parseInt(url.searchParams.get("w") || "0") || 0;
2424
const vpHeight = parseInt(url.searchParams.get("h") || "0") || 0;
2525
const selector = url.searchParams.get("selector") || undefined;
26+
const format = url.searchParams.get("format") === "png" ? "png" : "jpeg";
27+
const contentType = format === "png" ? "image/png" : "image/jpeg";
2628

2729
// Determine composition dimensions from HTML
2830
let compW = vpWidth || 1920;
@@ -48,11 +50,11 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
4850
const selectorKey = selector
4951
? `_${selector.replace(/[^a-zA-Z0-9_-]+/g, "_").slice(0, 80)}`
5052
: "";
51-
const cacheKey = `${THUMBNAIL_CACHE_VERSION}_${compPath.replace(/\//g, "_")}_${seekTime.toFixed(2)}${selectorKey}.jpg`;
53+
const cacheKey = `${THUMBNAIL_CACHE_VERSION}_${format}_${compPath.replace(/\//g, "_")}_${seekTime.toFixed(2)}${selectorKey}.${format === "png" ? "png" : "jpg"}`;
5254
const cachePath = join(cacheDir, cacheKey);
5355
if (existsSync(cachePath)) {
5456
return new Response(new Uint8Array(readFileSync(cachePath)), {
55-
headers: { "Content-Type": "image/jpeg", "Cache-Control": "public, max-age=60" },
57+
headers: { "Content-Type": contentType, "Cache-Control": "public, max-age=60" },
5658
});
5759
}
5860

@@ -65,14 +67,15 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
6567
height: compH,
6668
previewUrl,
6769
selector,
70+
format,
6871
});
6972
if (!buffer) {
7073
return c.json({ error: "Thumbnail generation returned null" }, 500);
7174
}
7275
if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true });
7376
writeFileSync(cachePath, buffer);
7477
return new Response(new Uint8Array(buffer), {
75-
headers: { "Content-Type": "image/jpeg", "Cache-Control": "public, max-age=60" },
78+
headers: { "Content-Type": contentType, "Cache-Control": "public, max-age=60" },
7679
});
7780
} catch (err) {
7881
const msg = err instanceof Error ? err.message : String(err);

‎packages/core/src/studio-api/types.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ export interface StudioApiAdapter {
7272
height: number;
7373
previewUrl: string;
7474
selector?: string;
75+
format?: "jpeg" | "png";
7576
}) => Promise<Buffer | null>;
7677

7778
/** Optional: resolve session ID to project (multi-project mode). */

‎packages/studio/src/App.tsx‎

Lines changed: 130 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,19 @@
1-
import { useState, useCallback, useRef, useEffect, useMemo, type ReactNode } from "react";
1+
import {
2+
useState,
3+
useCallback,
4+
useRef,
5+
useEffect,
6+
useMemo,
7+
type MouseEvent,
8+
type ReactNode,
9+
} from "react";
210
import { useMountEffect } from "./hooks/useMountEffect";
311
import { NLELayout } from "./components/nle/NLELayout";
412
import { SourceEditor } from "./components/editor/SourceEditor";
513
import { LeftSidebar } from "./components/sidebar/LeftSidebar";
614
import { RenderQueue } from "./components/renders/RenderQueue";
715
import { useRenderQueue } from "./components/renders/useRenderQueue";
8-
import { CompositionThumbnail, VideoThumbnail, usePlayerStore } from "./player";
16+
import { CompositionThumbnail, VideoThumbnail, liveTime, usePlayerStore } from "./player";
917
import { AudioWaveform } from "./player/components/AudioWaveform";
1018
import type { TimelineElement } from "./player";
1119
import { LintModal } from "./components/LintModal";
@@ -40,6 +48,8 @@ import {
4048
getTimelineToggleTitle,
4149
shouldHandleTimelineToggleHotkey,
4250
} from "./utils/timelineDiscovery";
51+
import { buildFrameCaptureFilename, buildFrameCaptureUrl } from "./utils/frameCapture";
52+
import { Camera } from "./icons/SystemIcons";
4353

4454
interface EditingFile {
4555
path: string;
@@ -264,6 +274,7 @@ export function StudioApp() {
264274
const [globalDragOver, setGlobalDragOver] = useState(false);
265275
const [appToast, setAppToast] = useState<AppToast | null>(null);
266276
const [timelineVisible, setTimelineVisible] = useState(true);
277+
const [captureFrameTime, setCaptureFrameTime] = useState(0);
267278
const dragCounterRef = useRef(0);
268279
const toastTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
269280
const lastBlockedTimelineToastAtRef = useRef(0);
@@ -298,6 +309,26 @@ export function StudioApp() {
298309
const toggleTimelineVisibility = useCallback(() => {
299310
setTimelineVisible((visible) => !visible);
300311
}, []);
312+
const toggleLeftSidebar = useCallback(() => {
313+
setLeftCollapsed((collapsed) => !collapsed);
314+
}, []);
315+
const refreshCaptureFrameTime = useCallback(() => {
316+
setCaptureFrameTime(usePlayerStore.getState().currentTime);
317+
}, []);
318+
319+
useMountEffect(() => {
320+
setCaptureFrameTime(usePlayerStore.getState().currentTime);
321+
return liveTime.subscribe(setCaptureFrameTime);
322+
});
323+
324+
const captureFrameHref = projectId
325+
? buildFrameCaptureUrl({
326+
projectId,
327+
compositionPath: activeCompPath,
328+
currentTime: captureFrameTime,
329+
})
330+
: "#";
331+
const captureFrameFilename = buildFrameCaptureFilename(activeCompPath, captureFrameTime);
301332
useMountEffect(() => () => {
302333
if (toastTimerRef.current) clearTimeout(toastTimerRef.current);
303334
});
@@ -496,6 +527,28 @@ export function StudioApp() {
496527
>
497528
+
498529
</button>
530+
<button
531+
type="button"
532+
onClick={toggleTimelineVisibility}
533+
className="ml-1 flex h-7 w-7 items-center justify-center rounded-md text-neutral-500 transition-colors hover:bg-neutral-900 hover:text-neutral-200"
534+
title={getTimelineToggleTitle(true)}
535+
aria-label="Hide timeline editor"
536+
>
537+
<svg
538+
width="14"
539+
height="14"
540+
viewBox="0 0 24 24"
541+
fill="none"
542+
stroke="currentColor"
543+
strokeWidth="1.8"
544+
strokeLinecap="round"
545+
strokeLinejoin="round"
546+
aria-hidden="true"
547+
>
548+
<path d="M5 7h14" />
549+
<path d="m8 11 4 4 4-4" />
550+
</svg>
551+
</button>
499552
</div>
500553
</div>
501554
</div>
@@ -787,6 +840,42 @@ export function StudioApp() {
787840
toastTimerRef.current = setTimeout(() => setAppToast(null), 4000);
788841
}, []);
789842

843+
const handleCaptureFrameClick = useCallback(
844+
async (event: MouseEvent<HTMLAnchorElement>) => {
845+
if (!projectId) return;
846+
event.preventDefault();
847+
848+
const currentTime = usePlayerStore.getState().currentTime;
849+
setCaptureFrameTime(currentTime);
850+
const href = buildFrameCaptureUrl({
851+
projectId,
852+
compositionPath: activeCompPath,
853+
currentTime,
854+
});
855+
const filename = buildFrameCaptureFilename(activeCompPath, currentTime);
856+
857+
try {
858+
const response = await fetch(href, { cache: "no-store" });
859+
if (!response.ok) {
860+
throw new Error(`Capture failed (${response.status})`);
861+
}
862+
const blob = await response.blob();
863+
const blobUrl = URL.createObjectURL(blob);
864+
const link = document.createElement("a");
865+
link.href = blobUrl;
866+
link.download = filename;
867+
document.body.appendChild(link);
868+
link.click();
869+
link.remove();
870+
setTimeout(() => URL.revokeObjectURL(blobUrl), 0);
871+
} catch (err) {
872+
const message = err instanceof Error ? err.message : "Capture failed";
873+
showToast(message);
874+
}
875+
},
876+
[activeCompPath, projectId, showToast],
877+
);
878+
790879
const handleTimelineElementDelete = useCallback(
791880
async (element: TimelineElement) => {
792881
const pid = projectIdRef.current;
@@ -1345,55 +1434,19 @@ export function StudioApp() {
13451434
</div>
13461435
{/* Right: toolbar buttons */}
13471436
<div className="flex items-center gap-1.5">
1348-
<button
1349-
onClick={() => setLeftCollapsed((v) => !v)}
1350-
className={`h-7 w-7 flex items-center justify-center rounded-md border transition-colors ${
1351-
!leftCollapsed
1352-
? "text-studio-accent bg-studio-accent/10 border-studio-accent/30"
1353-
: "bg-transparent border-transparent text-neutral-500 hover:text-neutral-300 hover:bg-neutral-800"
1354-
}`}
1355-
title={leftCollapsed ? "Show sidebar" : "Hide sidebar"}
1437+
<a
1438+
href={captureFrameHref}
1439+
download={captureFrameFilename}
1440+
onClick={handleCaptureFrameClick}
1441+
onFocus={refreshCaptureFrameTime}
1442+
onPointerDown={refreshCaptureFrameTime}
1443+
className="h-7 flex items-center gap-1.5 px-2.5 rounded-md text-[11px] font-medium border border-neutral-700 text-neutral-300 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
1444+
title="Capture current frame"
1445+
aria-label="Capture current frame"
13561446
>
1357-
<svg
1358-
width="14"
1359-
height="14"
1360-
viewBox="0 0 24 24"
1361-
fill="none"
1362-
stroke="currentColor"
1363-
strokeWidth="1.5"
1364-
strokeLinecap="round"
1365-
strokeLinejoin="round"
1366-
>
1367-
<rect x="3" y="3" width="18" height="18" rx="2" />
1368-
<path d="M9 3v18" />
1369-
</svg>
1370-
</button>
1371-
<button
1372-
type="button"
1373-
onClick={toggleTimelineVisibility}
1374-
className={`h-7 flex items-center gap-1.5 px-2.5 rounded-md text-[11px] font-medium border transition-colors ${
1375-
timelineVisible
1376-
? "text-studio-accent bg-studio-accent/10 border-studio-accent/30"
1377-
: "text-neutral-300 border-neutral-700 hover:border-neutral-500 hover:bg-neutral-800"
1378-
}`}
1379-
title={getTimelineToggleTitle(timelineVisible)}
1380-
aria-label={timelineVisible ? "Hide timeline editor" : "Show timeline editor"}
1381-
>
1382-
<svg
1383-
width="14"
1384-
height="14"
1385-
viewBox="0 0 24 24"
1386-
fill="none"
1387-
stroke="currentColor"
1388-
strokeWidth="1.5"
1389-
strokeLinecap="round"
1390-
>
1391-
<rect x="3" y="13" width="18" height="8" rx="1" />
1392-
<line x1="3" y1="9" x2="21" y2="9" />
1393-
<line x1="3" y1="5" x2="21" y2="5" />
1394-
</svg>
1395-
<span>Timeline</span>
1396-
</button>
1447+
<Camera size={14} />
1448+
<span>Capture</span>
1449+
</a>
13971450
<button
13981451
onClick={() => setRightCollapsed((v) => !v)}
13991452
className={`h-7 flex items-center gap-1.5 px-2.5 rounded-md text-[11px] font-medium border transition-colors ${
@@ -1422,7 +1475,32 @@ export function StudioApp() {
14221475
{/* Main content: sidebar + preview + right panel */}
14231476
<div className="flex flex-1 min-h-0">
14241477
{/* Left sidebar: Compositions + Assets (resizable, collapsible) */}
1425-
{!leftCollapsed && (
1478+
{leftCollapsed ? (
1479+
<div className="flex w-10 flex-shrink-0 flex-col items-center border-r border-neutral-800/50 bg-neutral-950 pt-1">
1480+
<button
1481+
type="button"
1482+
onClick={toggleLeftSidebar}
1483+
className="flex h-8 w-8 items-center justify-center rounded-md border border-transparent text-neutral-500 transition-colors hover:border-neutral-800 hover:bg-neutral-900 hover:text-neutral-300"
1484+
title="Show sidebar"
1485+
aria-label="Show sidebar"
1486+
>
1487+
<svg
1488+
width="14"
1489+
height="14"
1490+
viewBox="0 0 24 24"
1491+
fill="none"
1492+
stroke="currentColor"
1493+
strokeWidth="1.5"
1494+
strokeLinecap="round"
1495+
strokeLinejoin="round"
1496+
aria-hidden="true"
1497+
>
1498+
<path d="M5 4v16" />
1499+
<path d="m10 7 5 5-5 5" />
1500+
</svg>
1501+
</button>
1502+
</div>
1503+
) : (
14261504
<LeftSidebar
14271505
width={leftWidth}
14281506
projectId={projectId}
@@ -1469,6 +1547,7 @@ export function StudioApp() {
14691547
}
14701548
onLint={handleLint}
14711549
linting={linting}
1550+
onToggleCollapse={toggleLeftSidebar}
14721551
/>
14731552
)}
14741553

0 commit comments

Comments
 (0)