Skip to content

Commit ab8a4da

Browse files
jrusso1020claude
andauthored
feat(studio-server): accept crf, videoBitrate, videoFrameFormat and hdrMode on the render route (#5549)
* feat(studio-server): accept a crf override on the render route The Studio render route only forwarded draft/standard/high, so a Studio or desktop export could not ask for a specific CRF the way `hyperframes render --crf` can. Film-grain finishing passes need CRF 12 to keep the grain. The route now takes an optional integer `crf` (0-51 for mp4, 0-63 for webm), rejects an out-of-range value with 400 instead of dropping it, ignores it for mov, and both Studio adapters pass it to the render job. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * chore(studio-server): keep the crf change free of new comment lines Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * feat(studio-server): accept videoBitrate, videoFrameFormat and hdrMode on the render route Same options `hyperframes render` already takes (--video-bitrate, --video-frame-format, --sdr/--hdr), so Studio callers are not limited to the quality presets. crf and videoBitrate are an either/or, matching the CLI; an invalid value is a 400. Parsing moves to helpers/encoderOptions.ts. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 8147f7b commit ab8a4da

7 files changed

Lines changed: 198 additions & 1 deletion

File tree

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -627,6 +627,10 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
627627
...(manualEditsRenderScript ? { renderBodyScripts: [manualEditsRenderScript] } : {}),
628628
...(opts.composition ? { entryFile: opts.composition } : {}),
629629
...(opts.variables ? { variables: opts.variables } : {}),
630+
...(opts.crf !== undefined ? { crf: opts.crf } : {}),
631+
...(opts.videoBitrate ? { videoBitrate: opts.videoBitrate } : {}),
632+
...(opts.videoFrameFormat ? { videoFrameFormat: opts.videoFrameFormat } : {}),
633+
...(opts.hdrMode ? { hdrMode: opts.hdrMode } : {}),
630634
...(opts.useGpu ? { useGpu: true } : {}),
631635
});
632636
renderJob = job;
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import { describe, expect, it } from "vitest";
2+
import { parseEncoderOptions } from "./encoderOptions";
3+
4+
describe("parseEncoderOptions", () => {
5+
it("returns no overrides for an empty request", () => {
6+
expect(parseEncoderOptions({}, "mp4")).toEqual({ ok: true, options: {} });
7+
});
8+
9+
it("accepts a bitrate for mp4 and webm and ignores rate control for mov", () => {
10+
expect(parseEncoderOptions({ videoBitrate: "10M" }, "mp4")).toEqual({
11+
ok: true,
12+
options: { videoBitrate: "10M" },
13+
});
14+
expect(parseEncoderOptions({ videoBitrate: "2500k" }, "webm").ok).toBe(true);
15+
expect(parseEncoderOptions({ videoBitrate: "10M", crf: 12 }, "mov")).toEqual({
16+
ok: true,
17+
options: {},
18+
});
19+
});
20+
21+
it("rejects crf and videoBitrate together", () => {
22+
expect(parseEncoderOptions({ crf: 12, videoBitrate: "10M" }, "mp4")).toEqual({
23+
ok: false,
24+
error: "use either crf or videoBitrate, not both",
25+
});
26+
});
27+
28+
it.each(["", "10 M", "-5M", "10M; rm", 10])("rejects bitrate %j", (videoBitrate) => {
29+
expect(parseEncoderOptions({ videoBitrate }, "mp4").ok).toBe(false);
30+
});
31+
32+
it("passes frame format and HDR mode through for every format", () => {
33+
expect(parseEncoderOptions({ videoFrameFormat: "png", hdrMode: "force-sdr" }, "mov")).toEqual({
34+
ok: true,
35+
options: { videoFrameFormat: "png", hdrMode: "force-sdr" },
36+
});
37+
});
38+
39+
it("rejects an unknown frame format or HDR mode", () => {
40+
expect(parseEncoderOptions({ videoFrameFormat: "webp" }, "mp4").ok).toBe(false);
41+
expect(parseEncoderOptions({ hdrMode: "on" }, "mp4").ok).toBe(false);
42+
});
43+
});
Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
const CRF_MAX_BY_FORMAT: Record<string, number> = { mp4: 51, webm: 63 };
2+
const VIDEO_BITRATE = /^\d+(\.\d+)?[kKmMgG]?$/;
3+
const VIDEO_FRAME_FORMATS = ["auto", "jpg", "png"] as const;
4+
const HDR_MODES = ["auto", "force-hdr", "force-sdr"] as const;
5+
6+
interface EncoderOptions {
7+
crf?: number;
8+
videoBitrate?: string;
9+
videoFrameFormat?: (typeof VIDEO_FRAME_FORMATS)[number];
10+
hdrMode?: (typeof HDR_MODES)[number];
11+
}
12+
13+
export interface EncoderOptionsBody {
14+
crf?: unknown;
15+
videoBitrate?: unknown;
16+
videoFrameFormat?: unknown;
17+
hdrMode?: unknown;
18+
}
19+
20+
type Parsed = { ok: true; options: EncoderOptions } | { ok: false; error: string };
21+
22+
const isSet = (value: unknown) => value !== undefined && value !== null;
23+
24+
function oneOf<T extends string>(value: unknown, allowed: readonly T[]): value is T {
25+
return typeof value === "string" && (allowed as readonly string[]).includes(value);
26+
}
27+
28+
function parseCrf(crf: unknown, format: string, max: number): Parsed {
29+
if (typeof crf !== "number" || !Number.isInteger(crf) || crf < 0 || crf > max) {
30+
return { ok: false, error: `crf must be an integer from 0 to ${max} for ${format}` };
31+
}
32+
return { ok: true, options: { crf } };
33+
}
34+
35+
function parseVideoBitrate(videoBitrate: unknown): Parsed {
36+
if (typeof videoBitrate !== "string" || !VIDEO_BITRATE.test(videoBitrate)) {
37+
return { ok: false, error: 'videoBitrate must look like "10M", "2500k" or "8000000"' };
38+
}
39+
return { ok: true, options: { videoBitrate } };
40+
}
41+
42+
function parseRateControl(body: EncoderOptionsBody, format: string): Parsed {
43+
const max = CRF_MAX_BY_FORMAT[format];
44+
if (max === undefined) return { ok: true, options: {} };
45+
if (isSet(body.crf) && isSet(body.videoBitrate)) {
46+
return { ok: false, error: "use either crf or videoBitrate, not both" };
47+
}
48+
if (isSet(body.crf)) return parseCrf(body.crf, format, max);
49+
if (isSet(body.videoBitrate)) return parseVideoBitrate(body.videoBitrate);
50+
return { ok: true, options: {} };
51+
}
52+
53+
/** Explicit encoder overrides from a render request. MOV (ProRes) takes no rate control. */
54+
export function parseEncoderOptions(body: EncoderOptionsBody, format: string): Parsed {
55+
const rate = parseRateControl(body, format);
56+
if (!rate.ok) return rate;
57+
const options: EncoderOptions = { ...rate.options };
58+
if (isSet(body.videoFrameFormat)) {
59+
if (!oneOf(body.videoFrameFormat, VIDEO_FRAME_FORMATS)) {
60+
return {
61+
ok: false,
62+
error: `videoFrameFormat must be one of ${VIDEO_FRAME_FORMATS.join(", ")}`,
63+
};
64+
}
65+
options.videoFrameFormat = body.videoFrameFormat;
66+
}
67+
if (isSet(body.hdrMode)) {
68+
if (!oneOf(body.hdrMode, HDR_MODES)) {
69+
return { ok: false, error: `hdrMode must be one of ${HDR_MODES.join(", ")}` };
70+
}
71+
options.hdrMode = body.hdrMode;
72+
}
73+
return { ok: true, options };
74+
}

‎packages/studio-server/src/routes/render.test.ts‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -324,6 +324,69 @@ describe("POST /projects/:id/render — fps wire format", () => {
324324
});
325325
});
326326

327+
describe("POST /projects/:id/render — crf", () => {
328+
async function post(body: Record<string, unknown>) {
329+
const spy = vi.fn();
330+
const { app, cleanup } = buildApp(spy);
331+
try {
332+
const res = await app.request("http://localhost/projects/demo/render", {
333+
method: "POST",
334+
headers: { "content-type": "application/json" },
335+
body: JSON.stringify({ fps: 30, quality: "standard", ...body }),
336+
});
337+
return { res, opts: spy.mock.calls[0]?.[0] };
338+
} finally {
339+
cleanup();
340+
}
341+
}
342+
343+
it("forwards a valid crf for mp4 and webm", async () => {
344+
expect((await post({ format: "mp4", crf: 12 })).opts.crf).toBe(12);
345+
expect((await post({ format: "webm", crf: 63 })).opts.crf).toBe(63);
346+
});
347+
348+
it("omits crf when the request does not specify one", async () => {
349+
const { res, opts } = await post({ format: "mp4" });
350+
expect(res.status).toBe(200);
351+
expect(opts).not.toHaveProperty("crf");
352+
});
353+
354+
it("ignores crf for mov, which has no CRF", async () => {
355+
const { res, opts } = await post({ format: "mov", crf: 12 });
356+
expect(res.status).toBe(200);
357+
expect(opts).not.toHaveProperty("crf");
358+
});
359+
360+
it("forwards the other encoder options and refuses crf with a bitrate", async () => {
361+
const { opts } = await post({
362+
format: "mp4",
363+
videoBitrate: "10M",
364+
videoFrameFormat: "png",
365+
hdrMode: "force-sdr",
366+
});
367+
expect(opts).toMatchObject({
368+
videoBitrate: "10M",
369+
videoFrameFormat: "png",
370+
hdrMode: "force-sdr",
371+
});
372+
const both = await post({ format: "mp4", crf: 12, videoBitrate: "10M" });
373+
expect(both.res.status).toBe(400);
374+
expect(both.opts).toBeUndefined();
375+
});
376+
377+
it.each([
378+
["mp4", 52],
379+
["mp4", -1],
380+
["mp4", 12.5],
381+
["mp4", "12"],
382+
["webm", 64],
383+
])("rejects %s crf %j with 400 and does not start a render", async (format, crf) => {
384+
const { res, opts } = await post({ format, crf });
385+
expect(res.status).toBe(400);
386+
expect(opts).toBeUndefined();
387+
});
388+
});
389+
327390
describe("POST /projects/:id/render — composition path safety", () => {
328391
const tmpDirs: string[] = [];
329392

‎packages/studio-server/src/routes/render.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import {
1313
} from "../helpers/safePath.js";
1414
import { projectDirMissing } from "../helpers/projectDirMissing.js";
1515
import { isVariablesPayload, VARIABLES_PAYLOAD_ERROR } from "../helpers/variablesPayload.js";
16+
import { parseEncoderOptions, type EncoderOptionsBody } from "../helpers/encoderOptions.js";
1617

1718
const VALID_RESOLUTIONS = new Set<string>(VALID_CANVAS_RESOLUTIONS);
1819
const RENDER_MIME: Record<string, string> = {
@@ -85,7 +86,7 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
8586
const project = await adapter.resolveProject(c.req.param("id"));
8687
if (!project) return c.json({ error: "not found" }, 404);
8788

88-
const body = (await c.req.json().catch(() => ({}))) as {
89+
const body = (await c.req.json().catch(() => ({}))) as EncoderOptionsBody & {
8990
// Polymorphic per design note in core.types.Fps:
9091
// number → integer fps (e.g. 30)
9192
// string → rational fps (e.g. "30000/1001" for NTSC 29.97)
@@ -146,6 +147,9 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
146147
variables = body.variables;
147148
}
148149

150+
const encoder = parseEncoderOptions(body, format);
151+
if (!encoder.ok) return c.json({ error: encoder.error }, 400);
152+
149153
const now = new Date();
150154
const jobId = `${project.id}_${formatRenderOutputTimestamp(now)}`;
151155
const rendersDir = adapter.rendersDir(project);
@@ -163,6 +167,7 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
163167
outputResolution,
164168
composition,
165169
variables,
170+
...encoder.options,
166171
useGpu: body.gpu === true && format === "mp4",
167172
distinctId:
168173
typeof body.telemetryDistinctId === "string" ? body.telemetryDistinctId : undefined,

‎packages/studio-server/src/types.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,10 @@ export interface StudioApiAdapter {
171171
*/
172172
fps: import("@hyperframes/core").Fps;
173173
quality: string;
174+
crf?: number;
175+
videoBitrate?: string;
176+
videoFrameFormat?: "auto" | "jpg" | "png";
177+
hdrMode?: "auto" | "force-hdr" | "force-sdr";
174178
jobId: string;
175179
/**
176180
* The triggering browser profile has telemetry disabled (localStorage

‎packages/studio/vite.adapter.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -351,6 +351,10 @@ export function createViteAdapter(
351351
outputResolution: opts.outputResolution,
352352
...(opts.composition ? { entryFile: opts.composition } : {}),
353353
...(opts.variables ? { variables: opts.variables } : {}),
354+
...(opts.crf !== undefined ? { crf: opts.crf } : {}),
355+
...(opts.videoBitrate ? { videoBitrate: opts.videoBitrate } : {}),
356+
...(opts.videoFrameFormat ? { videoFrameFormat: opts.videoFrameFormat } : {}),
357+
...(opts.hdrMode ? { hdrMode: opts.hdrMode } : {}),
354358
...(opts.useGpu ? { useGpu: true } : {}),
355359
});
356360
const onProgress = (j: { progress: number; currentStage?: string }) => {

0 commit comments

Comments
 (0)