Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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.tsindex 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 "@hyperimport { 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.tsindex 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.tsindex 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;}