Skip to content

Write HTML. Render video. Built for agents.

fix(cli): warn when a cloud render ignores the composition's fps (#5757)

Miguel Ángel18a8191700e6
diff --git a/packages/cli/src/commands/cloudrun.ts b/packages/cli/src/commands/cloudrun.ts
index 395277f5a2..e95ecf7083 100644
--- a/packages/cli/src/commands/cloudrun.ts
+++ b/packages/cli/src/commands/cloudrun.ts
@@ -29,7 +29,7 @@ import {
validateVariablesAgainstProject,
} from "../utils/variables.js";
import { normalizeErrorMessage } from "../utils/errorMessage.js";
-import { readAllowedCompositionFpsFromDir } from "../utils/compositionFps.js";
+import { defaultCloudFps } from "../utils/compositionFps.js";
import { DISTRIBUTED_FPS, type DistributedFps, isDistributedFps } from "@hyperframes/core";
export const examples: Example[] = [
@@ -531,7 +531,7 @@ function resolveCloudRunFps(
projectDir: string,
command: "render" | "render-batch",
): DistributedFps {
- const fps = parseIntFlag(args.fps) ?? readAllowedCompositionFpsFromDir(projectDir) ?? 30;
+ const fps = parseIntFlag(args.fps) ?? defaultCloudFps(projectDir);
if (isDistributedFps(fps)) return fps;
console.error(
`[cloudrun ${command}] --fps must be one of ${DISTRIBUTED_FPS.join(", ")}; got ${fps}.`,
diff --git a/packages/cli/src/commands/lambda.ts b/packages/cli/src/commands/lambda.ts
index 915b977b80..7a78a9fd95 100644
--- a/packages/cli/src/commands/lambda.ts
+++ b/packages/cli/src/commands/lambda.ts
@@ -15,7 +15,7 @@ import { type CanvasResolution, DISTRIBUTED_FPS, isDistributedFps } from "@hyper
import { parseOutputResolutionFlag } from "../utils/parseOutputResolution.js";
import type { Example } from "./_examples.js";
import { c } from "../ui/colors.js";
-import { readAllowedCompositionFpsFromDir } from "../utils/compositionFps.js";
+import { defaultCloudFps } from "../utils/compositionFps.js";
export const examples: Example[] = [
["Deploy the Lambda render stack to AWS", "hyperframes lambda deploy"],
@@ -304,7 +304,7 @@ export default defineCommand({
console.error("[lambda render] --width and --height are required.");
failCommand();
}
- const fpsRaw = parseIntFlag(args.fps) ?? readAllowedCompositionFpsFromDir(projectDir) ?? 30;
+ const fpsRaw = parseIntFlag(args.fps) ?? defaultCloudFps(projectDir);
if (!isDistributedFps(fpsRaw)) {
console.error(
`[lambda render] --fps must be one of ${DISTRIBUTED_FPS.join(", ")}; got ${fpsRaw}.`,
@@ -360,7 +360,7 @@ export default defineCommand({
console.error("[lambda render-batch] --width and --height are required.");
failCommand();
}
- const fpsRaw = parseIntFlag(args.fps) ?? readAllowedCompositionFpsFromDir(projectDir) ?? 30;
+ const fpsRaw = parseIntFlag(args.fps) ?? defaultCloudFps(projectDir);
if (!isDistributedFps(fpsRaw)) {
console.error(
`[lambda render-batch] --fps must be one of ${DISTRIBUTED_FPS.join(", ")}; got ${fpsRaw}.`,
diff --git a/packages/cli/src/utils/compositionFps.test.ts b/packages/cli/src/utils/compositionFps.test.ts
index 0eb75a5d38..7c2a5b37bc 100644
--- a/packages/cli/src/utils/compositionFps.test.ts
+++ b/packages/cli/src/utils/compositionFps.test.ts
@@ -1,8 +1,8 @@
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { readAllowedCompositionFpsFromDir, readCompositionFps } from "./compositionFps.js";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { defaultCloudFps, readCompositionFps } from "./compositionFps.js";
const wrap = (body: string) => `<!DOCTYPE html><html><body>${body}</body></html>`;
@@ -41,10 +41,11 @@ describe("readCompositionFps", () => {
});
});
-describe("readAllowedCompositionFpsFromDir", () => {
+describe("defaultCloudFps", () => {
const projectDirs: string[] = [];
afterEach(() => {
+ vi.restoreAllMocks();
for (const dir of projectDirs.splice(0)) {
rmSync(dir, { recursive: true, force: true });
}
@@ -57,58 +58,38 @@ describe("readAllowedCompositionFpsFromDir", () => {
return dir;
}
- it("uses cloud-allowed data-fps=60 as the default", () => {
- const dir = makeProject(
- '<div data-composition-id="root" data-root="true" data-fps="60">x</div>',
- );
-
- expect(readAllowedCompositionFpsFromDir(dir)).toBe(60);
- });
-
- it("uses cloud-allowed data-fps=24 as the default", () => {
- const dir = makeProject(
- '<div data-composition-id="root" data-root="true" data-fps="24">x</div>',
- );
-
- expect(readAllowedCompositionFpsFromDir(dir)).toBe(24);
- });
-
- it("uses cloud-allowed data-fps=25 instead of falling back to 30", () => {
- const dir = makeProject(
- '<div data-composition-id="root" data-root="true" data-fps="25">x</div>',
- );
-
- expect(readAllowedCompositionFpsFromDir(dir)).toBe(25);
- });
-
- it("returns null for data-fps=48 so cloud callers keep their ?? 30 fallback", () => {
- const dir = makeProject(
- '<div data-composition-id="root" data-root="true" data-fps="48">x</div>',
+ function root(fps: string): string {
+ return makeProject(
+ `<div data-composition-id="root" data-root="true" data-fps="${fps}">x</div>`,
);
+ }
- const declared = readAllowedCompositionFpsFromDir(dir);
- expect(declared).toBeNull();
- expect(declared ?? 30).toBe(30);
+ it.each([24, 25, 30, 60])("uses a supported data-fps=%i without warning", (fps) => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ expect(defaultCloudFps(root(String(fps)))).toBe(fps);
+ expect(warn).not.toHaveBeenCalled();
});
- it("returns null for fractional data-fps because cloud fps must be an integer", () => {
- const dir = makeProject(
- '<div data-composition-id="root" data-root="true" data-fps="30000/1001">x</div>',
- );
-
- expect(readAllowedCompositionFpsFromDir(dir)).toBeNull();
+ it.each(["48", "50", "30000/1001"])("falls back to 30 and warns for data-fps=%s", (fps) => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ expect(defaultCloudFps(root(fps))).toBe(30);
+ expect(warn).toHaveBeenCalledTimes(1);
+ expect(String(warn.mock.calls[0]?.[0])).toContain(`data-fps="${fps}"`);
});
- it("returns null when index.html has no data-fps", () => {
- const dir = makeProject('<div data-composition-id="root" data-root="true">x</div>');
-
- expect(readAllowedCompositionFpsFromDir(dir)).toBeNull();
+ it("uses 30 without warning when index.html has no data-fps", () => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ expect(
+ defaultCloudFps(makeProject('<div data-composition-id="root" data-root="true">x</div>')),
+ ).toBe(30);
+ expect(warn).not.toHaveBeenCalled();
});
- it("returns null when index.html cannot be read", () => {
+ it("uses 30 without warning when index.html cannot be read", () => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
const dir = mkdtempSync(join(tmpdir(), "hyperframes-composition-fps-missing-"));
projectDirs.push(dir);
-
- expect(readAllowedCompositionFpsFromDir(dir)).toBeNull();
+ expect(defaultCloudFps(dir)).toBe(30);
+ expect(warn).not.toHaveBeenCalled();
});
});
diff --git a/packages/cli/src/utils/compositionFps.ts b/packages/cli/src/utils/compositionFps.ts
index 952c004d35..f2af7f8c9c 100644
--- a/packages/cli/src/utils/compositionFps.ts
+++ b/packages/cli/src/utils/compositionFps.ts
@@ -1,7 +1,8 @@
import { readFileSync } from "node:fs";
import { join } from "node:path";
-import { type DistributedFps, isDistributedFps } from "@hyperframes/core";
+import { DISTRIBUTED_FPS, type DistributedFps, isDistributedFps } from "@hyperframes/core";
import { parseHTML } from "linkedom";
+import { c } from "../ui/colors.js";
/**
* Read a composition's declared frame rate from its root element's `data-fps`
@@ -35,21 +36,29 @@ export function readCompositionFps(html: string): string | null {
return raw ? raw : null;
}
+const DEFAULT_CLOUD_FPS: DistributedFps = 30;
+
/**
- * Cloud render backends (Lambda, Cloud Run) accept only `DISTRIBUTED_FPS`;
- * unlike local `render`, they can't take an arbitrary/fractional data-fps.
- * Returns `<projectDir>/index.html`'s declared data-fps when it is a member,
- * otherwise `null` so the caller keeps its own existing default (30).
+ * Cloud render fps when `--fps` is not passed: `<projectDir>/index.html`'s
+ * data-fps if it is in `DISTRIBUTED_FPS`, otherwise 30, with a warning when the
+ * project declared a rate cloud renders cannot use.
*/
-export function readAllowedCompositionFpsFromDir(projectDir: string): DistributedFps | null {
+export function defaultCloudFps(projectDir: string): DistributedFps {
let html: string;
try {
html = readFileSync(join(projectDir, "index.html"), "utf8");
} catch {
- return null;
+ return DEFAULT_CLOUD_FPS;
}
const raw = readCompositionFps(html);
- if (raw == null) return null;
+ if (raw == null) return DEFAULT_CLOUD_FPS;
const n = Number(raw);
- return isDistributedFps(n) ? n : null;
+ if (isDistributedFps(n)) return n;
+ console.warn(
+ c.warn(
+ `The composition declares data-fps="${raw}", which cloud renders do not support ` +
+ `(${DISTRIBUTED_FPS.join(", ")}). Rendering at ${DEFAULT_CLOUD_FPS} fps; pass --fps to choose.`,
+ ),
+ );
+ return DEFAULT_CLOUD_FPS;
}