Skip to content

Commit f059a6e

Browse files
feat(cli): default BeginFrame, agent blank, and looks quality (#3927)
* feat(cli): render summary names the capture path, gpu mode and stage timings * fix(lint): drop gsap_exit_missing_hard_kill, its hazard does not reproduce on cold workers * fix(cli): render slow-path hint fires only when the gpu was auto-probed * test(cli): isolate agent hint suite from ambient agent env keys The suite runs inside agent sessions. Ambient env keys fill the 16-key hint cap and fail assertions that a plain shell would pass. * docs(music-to-video): drop leftover hard-kill mandate after lint rule removal Frame workers still required a tl.set hard-kill that the dropped lint rule no longer enforces. Align the self-check with montage.md. * refactor(cli): share hint-key pattern and collapse render summary args Export HINT_KEY_PATTERN for the test isolation strip. Read duration and frame count from the perf summary instead of passing them beside it. * test(cli): lock capture-mode preference and 16-key hint isolation Session mode, including drawelement, must print over observability. The hint suite now fails if ambient keys already fill the 16-key cap. * feat(cli): default BeginFrame, agent blank, and looks quality Local auto render opts out of the software-GPU screenshot clamp so BeginFrame can run. init --agent scaffolds a centered Inter blank with no prompts. --quality looks (now the default) is CRF 16; delivery is high. * fix(cli): honor screenshot env and teach agent pitfalls on the happy path Local auto still requests BeginFrame unless PRODUCER_FORCE_SCREENSHOT=true. The agent blank fills its canvas so --resolution can resize it. Skills now name the four pitfalls and tell agents to read the render summary line. * feat(cli): default init to the centered blank Bare init scaffolds the centered Inter stage. --agent is a hidden alias. * fix(cli): pack from-file and use it for video init TTY --video with no --example selects from-file. Pack copies that template. * fix(cli): wire --video onto from-file even with --example blank One resolver picks the scaffold. Spawned init --video asserts a-roll src. * fix(cli): narrow looks CRF on the quality alias Only looks carries crf. Typecheck failed on the union without a guard. * style(cli): shorten render-pipeline summary comment
1 parent 95bea16 commit f059a6e

27 files changed

Lines changed: 537 additions & 439 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -89,19 +89,19 @@ off the check, the install, and the notice.
8989
Scaffold a new composition project from an example.
9090

9191
```bash
92-
# Agents and CI — every input from a flag
93-
npx hyperframes init my-video --example blank --video video.mp4 --non-interactive
92+
# Default: centered Inter blank. Non-TTY skips the wizard.
93+
npx hyperframes init my-video
9494

95-
# With the Tailwind browser runtime
96-
npx hyperframes init my-video --example blank --tailwind
95+
# Start from a video file
96+
npx hyperframes init my-video --video video.mp4 --non-interactive
9797

98-
# Interactive on a TTY
99-
npx hyperframes init my-video
98+
# With the Tailwind browser runtime
99+
npx hyperframes init my-video --tailwind
100100
```
101101

102102
| Flag | Description |
103103
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
104-
| `--example, -e` | Example to scaffold. Required with `--non-interactive`. See [Examples](/examples) for the full list. |
104+
| `--example, -e` | Example to scaffold. Default is the centered blank. See [Examples](/examples) for the full list. |
105105
| `--resolution` | Canvas preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k` (3840×2160), `portrait-4k` (2160×3840), `square` (1080×1080), `square-4k` (2160×2160). Aliases: `1080p`, `4k`, `uhd`, `1080p-square`, `square-1080p`, `4k-square`. Default: keep template dimensions. |
106106
| `--video, -v` | Path to a video file (MP4, WebM, MOV) |
107107
| `--audio, -a` | Path to an audio file (MP3, WAV, M4A) |
@@ -857,7 +857,7 @@ The flags that come up most:
857857
| `--composition, -c` | `index.html` | Render a different composition file. Sub-compositions using `<template>` wrappers must be referenced from `index.html` via `data-composition-src`. |
858858
| `--format` | `mp4` | `mp4`, `webm`, `mov`, `gif`, or `png-sequence`. WebM and MOV carry transparency; `png-sequence` writes RGBA frames to a directory. |
859859
| `--fps, -f` | root `data-fps`, otherwise 30 | 1–240, or an ffmpeg rational like `30000/1001` for 29.97 |
860-
| `--quality, -q` | `standard` | `draft`, `standard`, or `high`. Drives MP4/WebM encoder settings; MOV always uses the fixed alpha-preserving ProRes 4444 profile. |
860+
| `--quality, -q` | `looks` | `draft`, `looks` (CRF 16, default), `delivery` (= `high`), `standard`, or `high`. MOV always uses the fixed alpha-preserving ProRes 4444 profile. |
861861
| `--resolution` | the composition's size | Supersample to a preset via Chrome's `deviceScaleFactor`. Aspect ratio must match and the scale must be a whole multiple. Not with `--hdr`. See [4K rendering](/guides/4k-rendering). |
862862
| `--docker` | off | Render inside Docker for [deterministic output](/concepts/determinism) |
863863
| `--variables` | — | JSON object merged over the composition's `data-composition-variables` defaults |

‎docs/prompting/rules-and-anti-patterns.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ The skills enforce these automatically, but if you hand-edit compositions or deb
2323

2424
## Lint rules to know
2525

26-
The linter added eight more rules that catch subtler seek-order and SVG-drawing mistakes — cases where a render can look right in the live preview and still render wrong on a cold, non-linear render worker. Two further hazards below carry no rule code: they surface in the render, not the linter. Phrase prompts to avoid these up front rather than debugging them after a render.
26+
The linter added more rules that catch subtler seek-order and SVG-drawing mistakes — cases where a render can look right in the live preview and still render wrong on a cold, non-linear render worker — plus one centering footgun that shows in the preview too. Two further hazards below carry no rule code: they surface in the render, not the linter. Phrase prompts to avoid these up front rather than debugging them after a render.
2727

2828
### Cold-seek visibility
2929

@@ -47,6 +47,10 @@ These four all come from the same root cause: a cold render worker seeks non-lin
4747
- **Function-valued tween vars receive `(index, target, targets)` — the first argument is a number, not the element.** Don't ask for a function value that calls an element method on its first parameter, or that reads transform-sensitive layout (its result would depend on the worker's own seek order). Use the second parameter for the element, index arithmetic like `(i) => i * 20`, or a value computed once at build time. (`gsap_function_value_hazard`, PR [#2611](https://github.com/heygen-com/hyperframes/pull/2611))
4848
- **Don't measure DOM geometry inside a timeline callback.** `getBoundingClientRect()`, `getTotalLength()`, and `getComputedStyle()` all depend on whatever DOM state the render happens to be in — and timeline callbacks re-fire on every seek, so a cold worker's own non-linear seek order can hand the callback a different measurement than the live preview did. Ask for geometry to be computed once at build time instead. (`gsap_callback_dom_measurement`, PR [#2611](https://github.com/heygen-com/hyperframes/pull/2611))
4949

50+
### Centering
51+
52+
- **Don't center with CSS `transform: translate(-50%, -50%)` on an element GSAP moves with `x` or `y`.** GSAP writes the whole transform, so the first tween throws the centering away and the element jumps. Center with layout (flex or grid on the parent) or let GSAP own the offset: `tl.fromTo("#title", { xPercent: -50, yPercent: -50, y: 40 }, { xPercent: -50, yPercent: -50, y: 0 })`. (`gsap_css_transform_conflict`)
53+
5054
### SVG draw-on
5155

5256
Two more ways an SVG "line draws itself" effect (animated `strokeDasharray` / `strokeDashoffset`) can render as a static, undrawn line.

‎packages/cli/scripts/build-copy.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ async function main() {
6666
await waitForStudioDist(studioDist);
6767
copyDirContents(studioDist, join(DIST, "studio"));
6868

69-
for (const tmpl of ["blank", "_shared"]) {
69+
for (const tmpl of ["blank", "from-file", "_shared"]) {
7070
copyDir(join(CLI_ROOT, "src", "templates", tmpl), join(DIST, "templates", tmpl));
7171
}
7272

‎packages/cli/src/commands/init.test.ts‎

Lines changed: 64 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
import { describe, expect, it } from "vitest";
22
import { spawnSync } from "node:child_process";
3-
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
3+
import {
4+
copyFileSync,
5+
existsSync,
6+
mkdirSync,
7+
mkdtempSync,
8+
readFileSync,
9+
rmSync,
10+
writeFileSync,
11+
} from "node:fs";
412
import { tmpdir } from "node:os";
513
import { join, resolve } from "node:path";
614
import { fileURLToPath } from "node:url";
@@ -56,14 +64,22 @@ describe("hyperframes init flag rename", () => {
5664
expect(initSource).not.toMatch(/await ensureModel\(modelFlag/g);
5765
});
5866

59-
it("requires an explicit source in non-interactive mode", () => {
67+
it("bare init scaffolds the centered blank without --example", () => {
6068
const dir = mkdtempSync(join(tmpdir(), "hf-init-test-"));
6169
const target = join(dir, "proj");
6270
try {
6371
const res = runInit([target, "--non-interactive"]);
64-
expect(res.status).toBe(1);
65-
expect(res.stderr).toContain("Non-interactive init requires --example, --video, or --audio");
66-
expect(existsSync(target)).toBe(false);
72+
expect(res.status).toBe(0);
73+
const html = readFileSync(join(target, "index.html"), "utf-8");
74+
expect(html).toContain('data-composition-id="main"');
75+
expect(html).toContain("display: flex");
76+
expect(html).toContain("align-items: center");
77+
expect(html).toContain("font-family: Inter");
78+
expect(html).toContain("tl.seek(0)");
79+
expect(html).not.toMatch(/transform:\s*translate\(-50%/);
80+
expect(html).toMatch(/#root\s*\{[^}]*width:\s*100%/);
81+
expect(html).not.toContain("window.__timelines = window.__timelines || {}");
82+
expectScaffoldedScripts(target);
6783
} finally {
6884
rmSync(dir, { recursive: true, force: true });
6985
}
@@ -82,6 +98,21 @@ describe("hyperframes init flag rename", () => {
8298
}
8399
});
84100

101+
it("deprecated --agent still scaffolds the same centered blank", () => {
102+
const dir = mkdtempSync(join(tmpdir(), "hf-init-test-"));
103+
const target = join(dir, "proj");
104+
try {
105+
const res = runInit([target, "--agent"]);
106+
expect(res.status).toBe(0);
107+
const html = readFileSync(join(target, "index.html"), "utf-8");
108+
expect(html).toContain("font-family: Inter");
109+
expect(html).toContain("tl.seek(0)");
110+
expectScaffoldedScripts(target);
111+
} finally {
112+
rmSync(dir, { recursive: true, force: true });
113+
}
114+
});
115+
85116
it("--example blank scaffolds a bundled project with npm scripts", () => {
86117
const dir = mkdtempSync(join(tmpdir(), "hf-init-test-"));
87118
const target = join(dir, "proj");
@@ -169,6 +200,34 @@ describe("hyperframes init flag rename", () => {
169200
expect(injected).not.toContain("setTimeout");
170201
});
171202

203+
it("packs from-file and wires --video into the composition", () => {
204+
const copySource = readFileSync(
205+
new URL("../../scripts/build-copy.mjs", import.meta.url),
206+
"utf-8",
207+
);
208+
expect(copySource).toContain('for (const tmpl of ["blank", "from-file", "_shared"])');
209+
const dir = mkdtempSync(join(tmpdir(), "hf-init-test-"));
210+
const target = join(dir, "proj");
211+
const clip = join(dir, "clip.mp4");
212+
copyFileSync(
213+
resolve(
214+
fileURLToPath(import.meta.url),
215+
"../../../../studio/tests/e2e/fixtures/design-panel-qa/assets/test.mp4",
216+
),
217+
clip,
218+
);
219+
try {
220+
const res = runInit([target, "--non-interactive", "--skip-transcribe", "--video", clip]);
221+
expect(res.status).toBe(0);
222+
const html = readFileSync(join(target, "index.html"), "utf-8");
223+
expect(html).toContain('id="a-roll"');
224+
expect(html).toContain('src="clip.mp4"');
225+
expect(existsSync(join(target, "clip.mp4"))).toBe(true);
226+
} finally {
227+
rmSync(dir, { recursive: true, force: true });
228+
}
229+
});
230+
172231
it("-v works as the short alias for --video", () => {
173232
const dir = mkdtempSync(join(tmpdir(), "hf-init-test-"));
174233
const target = join(dir, "proj");

‎packages/cli/src/commands/init.ts‎

Lines changed: 19 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,11 @@ export const examples: Example[] = [
1515
["Scaffold a portrait video", "hyperframes init my-video --resolution portrait"],
1616
["Start from an existing video file", "hyperframes init my-video --video clip.mp4"],
1717
["Start from an audio file", "hyperframes init my-video --audio track.mp3"],
18-
["Scaffold with Tailwind CSS", "hyperframes init my-video --example blank --tailwind"],
19-
[
20-
"Non-interactive mode (for CI or AI agents)",
21-
"hyperframes init my-video --example blank --non-interactive",
22-
],
18+
["Scaffold with Tailwind CSS", "hyperframes init my-video --tailwind"],
19+
["Non-interactive mode (for CI or AI agents)", "hyperframes init my-video --non-interactive"],
2320
[
2421
"Opt out of the GitHub skills check (CI/tests only)",
25-
"HYPERFRAMES_SKIP_SKILLS=1 hyperframes init my-video --example blank --non-interactive",
22+
"HYPERFRAMES_SKIP_SKILLS=1 hyperframes init my-video --non-interactive",
2623
],
2724
];
2825
import {
@@ -57,6 +54,13 @@ import {
5754
type CanvasResolution,
5855
} from "@hyperframes/core";
5956

57+
function resolveScaffoldTemplateId(exampleFlag: string | undefined, hasMediaFile: boolean): string {
58+
const example = exampleFlag === "agent" ? "blank" : exampleFlag;
59+
if (example && example !== "blank") return example;
60+
if (hasMediaFile) return "from-file";
61+
return "blank";
62+
}
63+
6064
interface VideoMeta {
6165
durationSeconds: number;
6266
width: number;
@@ -722,6 +726,11 @@ export default defineCommand({
722726
type: "boolean",
723727
description: "Disable interactive prompts (for CI/agents)",
724728
},
729+
agent: {
730+
type: "boolean",
731+
hidden: true,
732+
description: "Deprecated alias; default init is the centered blank",
733+
},
725734
"skip-skills": {
726735
type: "boolean",
727736
description:
@@ -783,7 +792,7 @@ export default defineCommand({
783792
const skipSkills = process.env.HYPERFRAMES_SKIP_SKILLS === "1";
784793
const skipSkillsFlagIgnored = args["skip-skills"] === true && !skipSkills;
785794
const tailwind = args.tailwind === true;
786-
const nonInteractive = args["non-interactive"] === true;
795+
const nonInteractive = args["non-interactive"] === true || args.agent === true;
787796
const modelFlag = args.model;
788797
const languageFlag = args.language;
789798
const initialTranscriptionModel = initialModelForLanguage(
@@ -820,17 +829,7 @@ export default defineCommand({
820829
// Non-interactive mode — all inputs from flags, defaults where missing
821830
// -----------------------------------------------------------------------
822831
if (!interactive) {
823-
if (!exampleFlag && !videoFlag && !audioFlag) {
824-
console.error(
825-
c.error(
826-
"Non-interactive init requires --example, --video, or --audio. " +
827-
"For an empty starter project, pass --example blank explicitly.",
828-
),
829-
);
830-
failCommand();
831-
}
832-
833-
const templateId = exampleFlag ?? "blank";
832+
const templateId = resolveScaffoldTemplateId(exampleFlag, Boolean(videoFlag || audioFlag));
834833
const name = args.name ?? "my-video";
835834
const destDir = resolve(name);
836835

@@ -1091,8 +1090,8 @@ export default defineCommand({
10911090
// 3. Pick example — skip prompt if --example was provided
10921091
let templateId: string;
10931092

1094-
if (exampleFlag) {
1095-
templateId = exampleFlag;
1093+
if (exampleFlag || videoFlag || audioFlag) {
1094+
templateId = resolveScaffoldTemplateId(exampleFlag, Boolean(videoFlag || audioFlag));
10961095
} else {
10971096
// Resolve full template list (bundled + remote)
10981097
const allTemplates = await resolveTemplateList();

‎packages/cli/src/commands/render.test.ts‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -429,13 +429,53 @@ describe("renderLocal browser GPU config", () => {
429429
quiet: true,
430430
});
431431

432-
expect(producerState.resolveConfigCalls).toContainEqual({ browserGpuMode: "auto" });
432+
expect(producerState.resolveConfigCalls).toContainEqual({
433+
browserGpuMode: "auto",
434+
forceScreenshot: false,
435+
});
433436
expect(producerState.createdJobs[0]?.producerConfig).toMatchObject({
434437
browserGpuMode: "auto",
435438
resolved: true,
436439
});
437440
});
438441

442+
it("honors PRODUCER_FORCE_SCREENSHOT=true even on local auto GPU", async () => {
443+
const prev = process.env.PRODUCER_FORCE_SCREENSHOT;
444+
process.env.PRODUCER_FORCE_SCREENSHOT = "true";
445+
try {
446+
await renderLocal("/tmp/project", "/tmp/out.mp4", {
447+
fps: { num: 30, den: 1 },
448+
quality: "standard",
449+
format: "mp4",
450+
gpu: false,
451+
browserGpuMode: "auto",
452+
hdrMode: "auto",
453+
quiet: true,
454+
});
455+
expect(producerState.resolveConfigCalls).toContainEqual({ browserGpuMode: "auto" });
456+
expect(producerState.resolveConfigCalls[0]).not.toHaveProperty("forceScreenshot");
457+
} finally {
458+
if (prev === undefined) delete process.env.PRODUCER_FORCE_SCREENSHOT;
459+
else process.env.PRODUCER_FORCE_SCREENSHOT = prev;
460+
}
461+
});
462+
463+
it("keeps the screenshot clamp when --resolution supersamples", async () => {
464+
await renderLocal("/tmp/project", "/tmp/out.mp4", {
465+
fps: { num: 30, den: 1 },
466+
quality: "standard",
467+
format: "mp4",
468+
gpu: false,
469+
browserGpuMode: "auto",
470+
hdrMode: "auto",
471+
quiet: true,
472+
outputResolution: "landscape",
473+
});
474+
475+
expect(producerState.resolveConfigCalls).toContainEqual({ browserGpuMode: "auto" });
476+
expect(producerState.resolveConfigCalls[0]).not.toHaveProperty("forceScreenshot");
477+
});
478+
439479
it("passes an explicit hardware override for default local browser GPU", async () => {
440480
await renderLocal("/tmp/project", "/tmp/out.mp4", {
441481
fps: { num: 30, den: 1 },

0 commit comments

Comments
 (0)