Skip to content

Write HTML. Render video. Built for agents.

feat(studio): export can encode on the GPU, like render --gpu (#5397)

Miguel Ángel91f9c9eb0461
diff --git a/packages/cli/src/server/studioRenderTelemetry.test.ts b/packages/cli/src/server/studioRenderTelemetry.test.ts
index f5845015ae..8e0762dd6a 100644
--- a/packages/cli/src/server/studioRenderTelemetry.test.ts
+++ b/packages/cli/src/server/studioRenderTelemetry.test.ts
@@ -352,3 +352,15 @@ describe("studioRenderTelemetry", () => {
});
});
});
+
+describe("studio render telemetry: GPU encoding", () => {
+ it("reports whether the render asked for GPU encoding, on success and on failure", () => {
+ trackRenderComplete.mockClear();
+ trackRenderError.mockClear();
+ emitStudioRenderComplete({ ...opts, useGpu: true }, 1000, undefined);
+ emitStudioRenderError({ ...opts, useGpu: true }, 1000, "capture", new Error("x"), undefined);
+ emitStudioRenderComplete(opts, 1000, undefined);
+ expect(trackRenderComplete.mock.calls.map(([props]) => props.gpu)).toEqual([true, false]);
+ expect(trackRenderError.mock.calls[0]?.[0]).toMatchObject({ gpu: true });
+ });
+});
diff --git a/packages/cli/src/server/studioRenderTelemetry.ts b/packages/cli/src/server/studioRenderTelemetry.ts
index be4121b3c4..b722d33d96 100644
--- a/packages/cli/src/server/studioRenderTelemetry.ts
+++ b/packages/cli/src/server/studioRenderTelemetry.ts
@@ -24,6 +24,7 @@ export interface StudioRenderOpts {
format?: "mp4" | "webm" | "mov";
/** Named canvas preset the Studio request asked for; undefined renders at the composition's native dimensions. */
outputResolution?: CanvasResolution;
+ useGpu?: boolean;
// gif_fps_capped/hdr_mode/video_frame_format are deliberately absent: Studio
// has no gif/png-sequence option and createRenderJob never receives an
// hdrMode or videoFrameFormat from the Studio request type, so there is no
@@ -127,6 +128,7 @@ export function emitStudioRenderError(
fps: fpsToNumber(opts.fps),
quality: opts.quality,
docker: false,
+ gpu: opts.useGpu === true,
source: "studio",
failedStage,
errorMessage: err instanceof Error ? err.message : String(err),
@@ -150,7 +152,7 @@ export function emitStudioRenderComplete(
fps: fpsToNumber(opts.fps),
quality: opts.quality,
docker: false,
- gpu: false,
+ gpu: opts.useGpu === true,
source: "studio",
outputFormat: opts.format,
outputResolutionPreset: opts.outputResolution,
diff --git a/packages/cli/src/server/studioServer.renderBrowser.test.ts b/packages/cli/src/server/studioServer.renderBrowser.test.ts
index 726720d7ed..b5b2539d14 100644
--- a/packages/cli/src/server/studioServer.renderBrowser.test.ts
+++ b/packages/cli/src/server/studioServer.renderBrowser.test.ts
@@ -43,7 +43,7 @@ afterEach(() => {
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
});
-function startStudioRender() {
+function startStudioRender(extra: Record<string, unknown> = {}) {
const dir = mkdtempSync(join(tmpdir(), "hf-studio-render-browser-"));
dirs.push(dir);
server = createStudioServer({ projectDir: dir });
@@ -54,6 +54,7 @@ function startStudioRender() {
fps: { num: 30, den: 1 },
quality: "draft",
jobId: "job",
+ ...extra,
} as never);
}
@@ -86,3 +87,19 @@ describe("Studio render browser resolution", () => {
expect(process.env.PRODUCER_HEADLESS_SHELL_PATH).toBe("/opt/chrome");
});
});
+
+describe("Studio render GPU encoding", () => {
+ it("creates the job with useGpu when the request asks for GPU encoding", async () => {
+ mocks.resolveRenderBrowser.mockResolvedValue({
+ executablePath: "/opt/chrome",
+ source: "cache",
+ });
+
+ startStudioRender({ useGpu: true });
+ await vi.waitFor(() => expect(mocks.createRenderJob).toHaveBeenCalledTimes(1), {
+ timeout: 10_000,
+ });
+
+ expect(mocks.createRenderJob).toHaveBeenCalledWith(expect.objectContaining({ useGpu: true }));
+ });
+});
diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts
index c03d2990b3..deb259767c 100644
--- a/packages/cli/src/server/studioServer.ts
+++ b/packages/cli/src/server/studioServer.ts
@@ -627,6 +627,7 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
...(manualEditsRenderScript ? { renderBodyScripts: [manualEditsRenderScript] } : {}),
...(opts.composition ? { entryFile: opts.composition } : {}),
...(opts.variables ? { variables: opts.variables } : {}),
+ ...(opts.useGpu ? { useGpu: true } : {}),
});
renderJob = job;
const onProgress = (j: { progress: number; currentStage?: string }) => {
diff --git a/packages/studio-server/src/routes/render.test.ts b/packages/studio-server/src/routes/render.test.ts
index 303af44701..893b1f83a2 100644
--- a/packages/studio-server/src/routes/render.test.ts
+++ b/packages/studio-server/src/routes/render.test.ts
@@ -826,6 +826,41 @@ describe("POST /projects/:id/render — variables forwarding", () => {
});
});
+describe("POST /projects/:id/render — GPU encoding", () => {
+ it("passes gpu: true on an MP4 export to the adapter as useGpu, and anything else as off", async () => {
+ const spy = vi.fn();
+ const { app, cleanup } = buildApp(spy);
+ try {
+ const requests = [
+ { format: "mp4", gpu: true },
+ { format: "mp4" },
+ { format: "mp4", gpu: "true" },
+ { format: "mp4", gpu: 1 },
+ { format: "webm", gpu: true },
+ { format: "mov", gpu: true },
+ ];
+ for (const body of requests) {
+ const res = await app.request("http://localhost/projects/demo/render", {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify(body),
+ });
+ expect(res.status).toBe(200);
+ }
+ expect(spy.mock.calls.map(([opts]) => opts.useGpu)).toEqual([
+ true,
+ false,
+ false,
+ false,
+ false,
+ false,
+ ]);
+ } finally {
+ cleanup();
+ }
+ });
+});
+
describe("audioLoweredDb — the limiter's attenuation reaches the host", () => {
async function completedJobProgress(audioLoweredDb: number | undefined): Promise<string> {
const spy = vi.fn();
diff --git a/packages/studio-server/src/routes/render.ts b/packages/studio-server/src/routes/render.ts
index 16e595e541..3823eecd09 100644
--- a/packages/studio-server/src/routes/render.ts
+++ b/packages/studio-server/src/routes/render.ts
@@ -106,6 +106,7 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
// Composition-variable overrides ({variableId: value}), injected as
// window.__hfVariables — same channel as `hyperframes render --variables`.
variables?: Record<string, unknown>;
+ gpu?: boolean;
};
const VALID_FORMATS = new Set(["mp4", "webm", "mov"]);
const FORMAT_EXT: Record<string, string> = { mp4: ".mp4", webm: ".webm", mov: ".mov" };
@@ -162,6 +163,7 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
outputResolution,
composition,
variables,
+ useGpu: body.gpu === true && format === "mp4",
distinctId:
typeof body.telemetryDistinctId === "string" ? body.telemetryDistinctId : undefined,
telemetryOptOut: body.telemetryOptOut === true,
diff --git a/packages/studio-server/src/types.ts b/packages/studio-server/src/types.ts
index 8e55b2885d..8aa2e602db 100644
--- a/packages/studio-server/src/types.ts
+++ b/packages/studio-server/src/types.ts
@@ -192,6 +192,7 @@ export interface StudioApiAdapter {
* the same channel `hyperframes render --variables` uses.
*/
variables?: Record<string, unknown>;
+ useGpu?: boolean;
/**
* Telemetry id of the browser user who triggered the render. Lets the
* adapter attribute the server-emitted render_complete/render_error to
diff --git a/packages/studio/src/components/StudioLeftPanels.tsx b/packages/studio/src/components/StudioLeftPanels.tsx
index b81ef43f1d..1015278c59 100644
--- a/packages/studio/src/components/StudioLeftPanels.tsx
+++ b/packages/studio/src/components/StudioLeftPanels.tsx
@@ -75,8 +75,8 @@ export const StudioLeftPanels = memo(function StudioLeftPanels({
return;
}
await waitForPendingDomEditSaves();
- const { format, quality, fps } = getPersistedRenderSettings();
- await renderQueue.startRender({ composition: comp, format, quality, fps });
+ const { format, quality, fps, gpu } = getPersistedRenderSettings();
+ await renderQueue.startRender({ composition: comp, format, quality, fps, gpu });
},
[renderQueue, waitForPendingDomEditSaves],
);
diff --git a/packages/studio/src/components/renders/GpuEncodingToggle.tsx b/packages/studio/src/components/renders/GpuEncodingToggle.tsx
new file mode 100644
index 0000000000..eb06bf971d
--- /dev/null
+++ b/packages/studio/src/components/renders/GpuEncodingToggle.tsx
@@ -0,0 +1,28 @@
+export function GpuEncodingToggle({
+ format,
+ checked,
+ disabled,
+ onToggle,
+}: {
+ format: "mp4" | "webm" | "mov";
+ checked: boolean;
+ disabled: boolean;
+ onToggle: () => void;
+}) {
+ // GPU encoders exist for H.264/H.265 only, so only MP4 can use one.
+ if (format !== "mp4") return null;
+ return (
+ <label
+ className={`flex items-center gap-2 text-step-10 text-text-4 ${disabled ? "opacity-40 cursor-not-allowed" : "cursor-pointer"}`}
+ >
+ <input
+ type="checkbox"
+ checked={checked}
+ disabled={disabled}
+ onChange={onToggle}
+ className="accent-studio-accent"
+ />
+ <span>Use GPU encoding</span>
+ </label>
+ );
+}
diff --git a/packages/studio/src/components/renders/RenderQueue.test.tsx b/packages/studio/src/components/renders/RenderQueue.test.tsx
index 7346628b68..cc655f386d 100644
--- a/packages/studio/src/components/renders/RenderQueue.test.tsx
+++ b/packages/studio/src/components/renders/RenderQueue.test.tsx
@@ -142,7 +142,7 @@ describe("RenderQueue controls", () => {
exportButtonIn(host).dispatchEvent(new MouseEvent("click", { bubbles: true }));
});
- expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "landscape-4k", 30);
+ expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "landscape-4k", 30, false);
});
it("refuses a resolution the composition cannot reach, and says why", async () => {
@@ -172,7 +172,23 @@ describe("RenderQueue controls", () => {
exportButtonIn(host).dispatchEvent(new MouseEvent("click", { bubbles: true }));
});
- expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "auto", 30);
+ expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "auto", 30, false);
+ });
+
+ it("exports with GPU encoding once the box is ticked, and remembers it", () => {
+ const onStartRender: Mock<StartRenderHandler> = vi.fn();
+ const host = mountRenderQueue(onStartRender);
+ const gpu = [...host.querySelectorAll("label")].find((label) =>
+ label.textContent?.includes("Use GPU encoding"),
+ );
+
+ act(() => gpu?.querySelector("input")?.click());
+ act(() => {
+ exportButtonIn(host).dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+
+ expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "auto", 30, true);
+ expect(getPersistedRenderSettings().gpu).toBe(true);
});
it("persists a changed format as the literal union value", async () => {
@@ -185,7 +201,9 @@ describe("RenderQueue controls", () => {
format: "mov",
quality: "standard",
fps: 30,
+ gpu: false,
});
+ expect(host.textContent).not.toContain("Use GPU encoding");
});
});
diff --git a/packages/studio/src/components/renders/RenderQueue.tsx b/packages/studio/src/components/renders/RenderQueue.tsx
index 7cbb9586ef..98c3f80746 100644
--- a/packages/studio/src/components/renders/RenderQueue.tsx
+++ b/packages/studio/src/components/renders/RenderQueue.tsx
@@ -11,6 +11,7 @@ import { Tooltip } from "../ui/Tooltip";
import { resolveFloatingPanelPosition, type FloatingPosition } from "../editor/floatingPanel";
import type { RenderJob, ResolutionPreset } from "./useRenderQueue";
import { getPersistedRenderSettings, persistRenderSettings } from "./renderSettings";
+import { GpuEncodingToggle } from "./GpuEncodingToggle";
import { trackStudioEvent } from "../../utils/studioTelemetry";
export interface CompositionDimensions {
@@ -23,6 +24,7 @@ export type StartRenderHandler = (
quality: "draft" | "standard" | "high",
resolution: ResolutionPreset | "auto",
fps: 24 | 30 | 60,
+ gpu?: boolean,
) => void | Promise<void>;
export interface RenderQueueProps {
@@ -303,6 +305,7 @@ function FormatExportButton({
const [quality, setQuality] = useState<"draft" | "standard" | "high">(persisted.quality);
const [resolution, setResolution] = useState<RenderScale>("auto");
const [fps, setFps] = useState<24 | 30 | 60>(persisted.fps);
+ const [gpu, setGpu] = useState(persisted.gpu);
// Only a definite "not installed" blocks Export. A null status means the
// probe gave no answer, and refusing to export on no answer would break
@@ -385,6 +388,15 @@ function FormatExportButton({
</div>
)}
</div>
+ <GpuEncodingToggle
+ format={format}
+ checked={gpu}
+ disabled={isRendering}
+ onToggle={() => {
+ setGpu(!gpu);
+ persistRenderSettings(format, quality, fps, !gpu);
+ }}
+ />
<Button
variant="primary"
size="md"
@@ -398,7 +410,7 @@ function FormatExportButton({
if (isRendering || missingFfmpeg) return;
const outputResolution = resolveResolution(resolution, compositionDimensions);
trackStudioEvent("render_start", { format, quality, resolution: outputResolution, fps });
- void onStartRender(format, quality, outputResolution, fps);
+ void onStartRender(format, quality, outputResolution, fps, gpu);
}}
// Width only. A type size or a weight here would win the merge against
// the size recipe and leave this Export a step away from the header's
diff --git a/packages/studio/src/components/renders/RenderQueuePanel.tsx b/packages/studio/src/components/renders/RenderQueuePanel.tsx
index 8551de734b..90cfe83cd0 100644
--- a/packages/studio/src/components/renders/RenderQueuePanel.tsx
+++ b/packages/studio/src/components/renders/RenderQueuePanel.tsx
@@ -29,7 +29,7 @@ export const RenderQueuePanel = memo(function RenderQueuePanel() {
ffmpeg={renderQueue.ffmpeg}
ffmpegChecking={renderQueue.ffmpegChecking}
onRecheckFfmpeg={renderQueue.recheckFfmpeg}
- onStartRender={async (format, quality, resolution, fps) => {
+ onStartRender={async (format, quality, resolution, fps, gpu) => {
await waitForPendingDomEditSaves();
// No `composition`: startRender targets the active one by default.
await renderQueue.startRender({
@@ -37,6 +37,7 @@ export const RenderQueuePanel = memo(function RenderQueuePanel() {
quality,
format,
resolution,
+ gpu,
// Render what the user is previewing: active variable overrides
// from the Variables panel ride along (undefined = defaults).
variables: usePreviewVariablesStore.getState().values ?? undefined,
diff --git a/packages/studio/src/components/renders/renderSettings.ts b/packages/studio/src/components/renders/renderSettings.ts
index f727bc3307..3fdd0272e4 100644
--- a/packages/studio/src/components/renders/renderSettings.ts
+++ b/packages/studio/src/components/renders/renderSettings.ts
@@ -4,6 +4,7 @@ export interface PersistedRenderSettings {
format: "mp4" | "webm" | "mov";
quality: "draft" | "standard" | "high";
fps: 24 | 30 | 60;
+ gpu: boolean;
}
export function getPersistedRenderSettings(): PersistedRenderSettings {
@@ -17,21 +18,23 @@ export function getPersistedRenderSettings(): PersistedRenderSettings {
? parsed.quality
: "standard",
fps: [24, 30, 60].includes(parsed.fps) ? parsed.fps : 30,
+ gpu: parsed.gpu === true,
};
}
} catch {
/* ignore */
}
- return { format: "mp4", quality: "standard", fps: 30 };
+ return { format: "mp4", quality: "standard", fps: 30, gpu: false };
}
export function persistRenderSettings(
format: PersistedRenderSettings["format"],
quality: PersistedRenderSettings["quality"],
fps: PersistedRenderSettings["fps"],
+ gpu: boolean = getPersistedRenderSettings().gpu,
): void {
try {
- localStorage.setItem(RENDER_SETTINGS_KEY, JSON.stringify({ format, quality, fps }));
+ localStorage.setItem(RENDER_SETTINGS_KEY, JSON.stringify({ format, quality, fps, gpu }));
} catch {
/* ignore */
}
diff --git a/packages/studio/src/components/renders/useRenderQueue.ts b/packages/studio/src/components/renders/useRenderQueue.ts
index 62a035ea66..1352b76c38 100644
--- a/packages/studio/src/components/renders/useRenderQueue.ts
+++ b/packages/studio/src/components/renders/useRenderQueue.ts
@@ -32,6 +32,7 @@ export interface StartRenderOptions {
format?: "mp4" | "webm" | "mov";
/** `"auto"` (default) renders at the composition's authored dimensions. */
resolution?: ResolutionPreset | "auto";
+ gpu?: boolean;
/**
* Render a specific composition file. Omit it to render the composition the
* user currently has open — only the sidebar's per-composition Render button
@@ -234,6 +235,7 @@ export function useRenderQueue(
resolution?: string;
composition?: string;
variables?: Record<string, unknown>;
+ gpu?: boolean;
telemetryDistinctId?: string;
telemetryOptOut?: boolean;
} = {
@@ -258,6 +260,7 @@ export function useRenderQueue(
}
if (resolution && resolution !== "auto") body.resolution = resolution;
if (composition) body.composition = composition;
+ if (opts.gpu) body.gpu = true;
if (opts.variables && Object.keys(opts.variables).length > 0) {
body.variables = opts.variables;
}
diff --git a/packages/studio/src/components/renders/useRenderQueueComposition.test.tsx b/packages/studio/src/components/renders/useRenderQueueComposition.test.tsx
index be69800941..b338845348 100644
--- a/packages/studio/src/components/renders/useRenderQueueComposition.test.tsx
+++ b/packages/studio/src/components/renders/useRenderQueueComposition.test.tsx
@@ -53,3 +53,15 @@ describe("render target composition", () => {
expect(body["composition"]).toBeUndefined();
});
});
+
+describe("GPU encoding", () => {
+ it("asks the server for GPU encoding when the export asks for it", async () => {
+ const body = await renderBody(null, { format: "mp4", gpu: true });
+ expect(body["gpu"]).toBe(true);
+ });
+
+ it("leaves GPU encoding off by default", async () => {
+ const body = await renderBody(null, { format: "mp4" });
+ expect(body["gpu"]).toBeUndefined();
+ });
+});
diff --git a/packages/studio/vite.adapter.ts b/packages/studio/vite.adapter.ts
index 3d445262df..b37eb7221f 100644
--- a/packages/studio/vite.adapter.ts
+++ b/packages/studio/vite.adapter.ts
@@ -351,6 +351,7 @@ export function createViteAdapter(
outputResolution: opts.outputResolution,
...(opts.composition ? { entryFile: opts.composition } : {}),
...(opts.variables ? { variables: opts.variables } : {}),
+ ...(opts.useGpu ? { useGpu: true } : {}),
});
const onProgress = (j: { progress: number; currentStage?: string }) => {
state.progress = j.progress;