mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
feat(cli): add 1440p resolution presets to --resolution (#7418)
* feat(cli): add 1440p resolution presets to --resolution Adds landscape-1440p (2560x1440), portrait-1440p (1440x2560) and square-1440p (1440x1440) next to the existing 4K, 720p and 480p tiers, with the aliases 1440p, 2k and qhd plus 1440p-portrait and 1440p-square. 1440p joins the aspect-agnostic aliases, like 720p and 480p. Every validator derives from CANVAS_DIMENSIONS, so no logic changes: a 4K composition renders down to 1440p through the existing smaller-preset path, and a 1280x720 composition supersamples to 1440p at an exact 2x. A 1920x1080 composition is still refused by the non-integer-scale check (4/3); fractional scale factors are not part of this change. Refs #6309 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> * fix(cli): clarify 1440p aliases and repair skill validation --------- Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com> Co-authored-by: James <james.russo@heygen.com>
This commit is contained in:
co-authored by
Claude Sonnet 5.5
James
parent
91ad7fb6ee
commit
5e8abd7574
@@ -178,7 +178,7 @@ npx hyperframes init my-video --tailwind
|
||||
| Flag | Description |
|
||||
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `--example, -e` | Example to scaffold. Default is the centered blank. See [Examples](/examples) for the full list. |
|
||||
| `--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. |
|
||||
| `--resolution` | Canvas preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k` (3840×2160), `portrait-4k` (2160×3840), `square` (1080×1080), `square-4k` (2160×2160), `landscape-1440p` (2560×1440), `portrait-1440p` (1440×2560), `square-1440p` (1440×1440). Aliases: `1080p`, `4k`, `uhd`, `1440p`, `qhd`, `1080p-square`, `square-1080p`, `4k-square`, `1440p-portrait`, `1440p-square`. Default: keep template dimensions. |
|
||||
| `--video, -v` | Path to a video file (MP4, WebM, MOV) |
|
||||
| `--audio, -a` | Path to an audio file (MP3, WAV, M4A) |
|
||||
| `--tailwind` | Add Tailwind CSS browser-runtime support to the scaffolded HTML |
|
||||
@@ -1822,7 +1822,7 @@ The flags that come up most:
|
||||
| `--format` | `mp4` | `mp4`, `webm`, `mov`, `gif`, `png-sequence`, or `hls`. WebM and MOV carry transparency; `png-sequence` writes RGBA frames to a directory; `hls` writes a VOD playlist directory. |
|
||||
| `--fps, -f` | root `data-fps`, otherwise 30 | 1–240, or an ffmpeg rational like `30000/1001` for 29.97 |
|
||||
| `--quality, -q` | `looks` | `draft`, `looks` (CRF 16, default), `delivery` (= `high`), `standard`, or `high`. MOV always uses the fixed alpha-preserving ProRes 4444 profile. |
|
||||
| `--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). |
|
||||
| `--resolution` | the composition's size | Render to a preset via Chrome's `deviceScaleFactor`, including `landscape-1440p`, `portrait-1440p`, `square-1440p` (aliases `1440p`, `qhd`). Aspect ratio must match; upscaling requires an integer multiple. 720p→1440p and 4K→1440p work; 1080p→1440p is refused. Not with `--hdr`. See [4K rendering](/guides/4k-rendering). |
|
||||
| `--docker` | off | Render inside Docker for [deterministic output](/concepts/determinism) |
|
||||
| `--variables` | — | JSON object merged over the composition's `data-composition-variables` defaults |
|
||||
| `--variables-file` | — | Read those overrides from a JSON file instead |
|
||||
|
||||
@@ -625,6 +625,25 @@ describe("applyResolutionPreset", () => {
|
||||
});
|
||||
});
|
||||
|
||||
it("rewrites every dimension fingerprint for landscape-1440p", () => {
|
||||
withFixture((dir) => {
|
||||
const file = join(dir, "index.html");
|
||||
writeFileSync(file, sampleHtml, "utf-8");
|
||||
|
||||
applyResolutionPreset(dir, "landscape-1440p");
|
||||
const out = readFileSync(file, "utf-8");
|
||||
|
||||
expect(out).toContain('data-resolution="landscape-1440p"');
|
||||
expect(out).toContain('data-width="2560"');
|
||||
expect(out).toContain('data-height="1440"');
|
||||
expect(out).toContain("width: 2560px");
|
||||
expect(out).toContain("height: 1440px");
|
||||
expect(out).toContain('content="width=2560, height=1440"');
|
||||
expect(out).not.toContain("1920");
|
||||
expect(out).not.toContain("1080");
|
||||
});
|
||||
});
|
||||
|
||||
it("swaps to portrait dimensions for portrait-4k", () => {
|
||||
withFixture((dir) => {
|
||||
const file = join(dir, "index.html");
|
||||
|
||||
@@ -842,7 +842,7 @@ export default defineCommand({
|
||||
resolution: {
|
||||
type: "string",
|
||||
description:
|
||||
"Canvas resolution preset: landscape (1920x1080), portrait (1080x1920), landscape-4k (3840x2160), portrait-4k (2160x3840), square (1080x1080), square-4k (2160x2160). Aliases: 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-square. Default: a --video clip's own shape as it plays, 1080 on the short side (4:3 -> 1440x1080), else the template's dimensions (typically 1920x1080).",
|
||||
"Canvas resolution preset: landscape (1920x1080), portrait (1080x1920), landscape-4k (3840x2160), portrait-4k (2160x3840), square (1080x1080), square-4k (2160x2160), landscape-1440p (2560x1440), portrait-1440p (1440x2560), square-1440p (1440x1440). Aliases: 1080p, 4k, uhd, 1440p, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square. Default: a --video clip's own shape as it plays, 1080 on the short side (4:3 -> 1440x1080), else the template's dimensions (typically 1920x1080).",
|
||||
},
|
||||
skill: {
|
||||
type: "string",
|
||||
@@ -894,8 +894,9 @@ export default defineCommand({
|
||||
console.error(
|
||||
c.error(
|
||||
`Invalid --resolution: "${args.resolution}". ` +
|
||||
`Use one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k ` +
|
||||
`(or aliases 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-square).`,
|
||||
`Use one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k, ` +
|
||||
`landscape-1440p, portrait-1440p, square-1440p ` +
|
||||
`(or aliases 1080p, 4k, uhd, 1440p, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square).`,
|
||||
),
|
||||
);
|
||||
failUsage();
|
||||
|
||||
@@ -2089,6 +2089,21 @@ describe("checkRenderResolutionPreflight", () => {
|
||||
).toBeUndefined();
|
||||
});
|
||||
|
||||
it("clears a landscape-1440p preset on a portrait 720p composition (an exact 2×)", async () => {
|
||||
expect(
|
||||
await checkRenderResolutionPreflight(comp(720, 1280), "landscape-1440p", agnostic),
|
||||
).toBeUndefined();
|
||||
});
|
||||
|
||||
it("refuses `--resolution 1440p` on a 1920×1080 composition: 4/3 is not an integer scale", async () => {
|
||||
const result = await checkRenderResolutionPreflight(
|
||||
landscapeHtml,
|
||||
"landscape-1440p",
|
||||
agnostic,
|
||||
);
|
||||
expect(result?.kind).toBe("non-integer-scale");
|
||||
});
|
||||
|
||||
it("clears a landscape preset on a square composition", async () => {
|
||||
// aspect > 1 → landscape, aspect = 1 → square. Both self-heal.
|
||||
expect(
|
||||
|
||||
@@ -384,7 +384,7 @@ export default defineCommand({
|
||||
resolution: {
|
||||
type: "string",
|
||||
description:
|
||||
"Output resolution preset: landscape (1920x1080), portrait (1080x1920), landscape-4k (3840x2160), portrait-4k (2160x3840), square (1080x1080), square-4k (2160x2160). Aliases: 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-square. The composition is unchanged — Chrome renders at higher DPR (deviceScaleFactor) so the captured screenshot lands at the requested dimensions. Aspect ratio must match the composition; the scale must be an integer multiple. Not yet supported with --hdr.",
|
||||
"Output resolution preset: landscape (1920x1080), portrait (1080x1920), landscape-4k (3840x2160), portrait-4k (2160x3840), square (1080x1080), square-4k (2160x2160), landscape-1440p (2560x1440), portrait-1440p (1440x2560), square-1440p (1440x1440). Aliases: 1080p, 4k, uhd, 1440p, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square. The composition is unchanged — Chrome renders at higher DPR (deviceScaleFactor) so the captured screenshot lands at the requested dimensions. Aspect ratio must match the composition; upscaling requires an integer multiple. Not yet supported with --hdr.",
|
||||
},
|
||||
"page-side-compositing": {
|
||||
type: "boolean",
|
||||
|
||||
@@ -386,8 +386,9 @@ export function createRenderPlan(args: RenderCommandArgs, now = new Date()): Ren
|
||||
if (!outputResolution) {
|
||||
errorBox(
|
||||
"Invalid resolution",
|
||||
`Got "${args.resolution}". Must be one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k ` +
|
||||
`(or aliases 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-square).`,
|
||||
`Got "${args.resolution}". Must be one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k, ` +
|
||||
`landscape-1440p, portrait-1440p, square-1440p ` +
|
||||
`(or aliases 1080p, 4k, uhd, 1440p, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square).`,
|
||||
);
|
||||
failUsage();
|
||||
}
|
||||
|
||||
@@ -12,6 +12,9 @@ describe("@hyperframes/core public API exports", () => {
|
||||
expect(core.CANVAS_DIMENSIONS["portrait-4k"]).toEqual({ width: 2160, height: 3840 });
|
||||
expect(core.CANVAS_DIMENSIONS.square).toEqual({ width: 1080, height: 1080 });
|
||||
expect(core.CANVAS_DIMENSIONS["square-4k"]).toEqual({ width: 2160, height: 2160 });
|
||||
expect(core.CANVAS_DIMENSIONS["landscape-1440p"]).toEqual({ width: 2560, height: 1440 });
|
||||
expect(core.CANVAS_DIMENSIONS["portrait-1440p"]).toEqual({ width: 1440, height: 2560 });
|
||||
expect(core.CANVAS_DIMENSIONS["square-1440p"]).toEqual({ width: 1440, height: 1440 });
|
||||
});
|
||||
|
||||
it("exports VALID_CANVAS_RESOLUTIONS derived from CANVAS_DIMENSIONS", () => {
|
||||
@@ -22,6 +25,9 @@ describe("@hyperframes/core public API exports", () => {
|
||||
"portrait-4k",
|
||||
"square",
|
||||
"square-4k",
|
||||
"landscape-1440p",
|
||||
"portrait-1440p",
|
||||
"square-1440p",
|
||||
"landscape-720p",
|
||||
"portrait-720p",
|
||||
"square-720p",
|
||||
@@ -41,6 +47,12 @@ describe("@hyperframes/core public API exports", () => {
|
||||
expect(core.normalizeResolutionFlag("square-4k")).toBe("square-4k");
|
||||
expect(core.normalizeResolutionFlag("1080p-square")).toBe("square");
|
||||
expect(core.normalizeResolutionFlag("4k-square")).toBe("square-4k");
|
||||
expect(core.normalizeResolutionFlag("1440p")).toBe("landscape-1440p");
|
||||
expect(core.normalizeResolutionFlag("2k")).toBeUndefined();
|
||||
expect(core.normalizeResolutionFlag("QHD")).toBe("landscape-1440p");
|
||||
expect(core.normalizeResolutionFlag("1440p-portrait")).toBe("portrait-1440p");
|
||||
expect(core.normalizeResolutionFlag("1440p-square")).toBe("square-1440p");
|
||||
expect(core.normalizeResolutionFlag("portrait-1440p")).toBe("portrait-1440p");
|
||||
expect(core.normalizeResolutionFlag("8k")).toBeUndefined();
|
||||
expect(core.normalizeResolutionFlag(undefined)).toBeUndefined();
|
||||
});
|
||||
@@ -51,6 +63,9 @@ describe("@hyperframes/core public API exports", () => {
|
||||
expect(core.isAspectAgnosticResolutionAlias("hd")).toBe(true);
|
||||
expect(core.isAspectAgnosticResolutionAlias("4k")).toBe(true);
|
||||
expect(core.isAspectAgnosticResolutionAlias("uhd")).toBe(true);
|
||||
expect(core.isAspectAgnosticResolutionAlias("1440p")).toBe(true);
|
||||
expect(core.isAspectAgnosticResolutionAlias("2k")).toBe(false);
|
||||
expect(core.isAspectAgnosticResolutionAlias("qhd")).toBe(true);
|
||||
// Case-insensitive.
|
||||
expect(core.isAspectAgnosticResolutionAlias("1080P")).toBe(true);
|
||||
expect(core.isAspectAgnosticResolutionAlias("UHD")).toBe(true);
|
||||
@@ -59,6 +74,7 @@ describe("@hyperframes/core public API exports", () => {
|
||||
expect(core.isAspectAgnosticResolutionAlias("portrait-1080p")).toBe(false);
|
||||
expect(core.isAspectAgnosticResolutionAlias("4k-square")).toBe(false);
|
||||
expect(core.isAspectAgnosticResolutionAlias("1080p-square")).toBe(false);
|
||||
expect(core.isAspectAgnosticResolutionAlias("1440p-portrait")).toBe(false);
|
||||
// Canonical presets → false.
|
||||
expect(core.isAspectAgnosticResolutionAlias("landscape")).toBe(false);
|
||||
expect(core.isAspectAgnosticResolutionAlias("portrait")).toBe(false);
|
||||
|
||||
@@ -145,6 +145,46 @@ describe("checkOutputResolutionCompatibility", () => {
|
||||
},
|
||||
);
|
||||
|
||||
it.each([
|
||||
[1280, 720, "landscape-1440p"],
|
||||
[720, 1280, "portrait-1440p"],
|
||||
[720, 720, "square-1440p"],
|
||||
[2560, 1440, "landscape-1440p"],
|
||||
[3840, 2160, "landscape-1440p"],
|
||||
[2160, 3840, "portrait-1440p"],
|
||||
[2160, 2160, "square-1440p"],
|
||||
] as const)(
|
||||
"allows %i×%i to %s (an exact multiple or a smaller preset)",
|
||||
(compositionWidth, compositionHeight, outputResolution) => {
|
||||
expect(
|
||||
checkOutputResolutionCompatibility({
|
||||
compositionWidth,
|
||||
compositionHeight,
|
||||
outputResolution,
|
||||
}),
|
||||
).toEqual({ ok: true });
|
||||
},
|
||||
);
|
||||
|
||||
it("refuses 1920×1080 to landscape-1440p: 4/3 is not an integer scale factor", () => {
|
||||
const result = checkOutputResolutionCompatibility({
|
||||
compositionWidth: 1920,
|
||||
compositionHeight: 1080,
|
||||
outputResolution: "landscape-1440p",
|
||||
});
|
||||
expect(result.kind).toBe("non-integer-scale");
|
||||
});
|
||||
|
||||
it("keeps the 1440p tier when suggesting a swap for the wrong orientation", () => {
|
||||
const result = checkOutputResolutionCompatibility({
|
||||
compositionWidth: 2560,
|
||||
compositionHeight: 1440,
|
||||
outputResolution: "portrait-1440p",
|
||||
});
|
||||
expect(result.kind).toBe("aspect-mismatch");
|
||||
expect(result.suggestedResolution).toBe("landscape-1440p");
|
||||
});
|
||||
|
||||
it("keeps the 480p tier when suggesting a swap for the wrong orientation", () => {
|
||||
const result = checkOutputResolutionCompatibility({
|
||||
compositionWidth: 1920,
|
||||
|
||||
@@ -23,6 +23,9 @@ export const CANVAS_DIMENSIONS = {
|
||||
"portrait-4k": { width: 2160, height: 3840 },
|
||||
square: { width: 1080, height: 1080 },
|
||||
"square-4k": { width: 2160, height: 2160 },
|
||||
"landscape-1440p": { width: 2560, height: 1440 },
|
||||
"portrait-1440p": { width: 1440, height: 2560 },
|
||||
"square-1440p": { width: 1440, height: 1440 },
|
||||
"landscape-720p": { width: 1280, height: 720 },
|
||||
"portrait-720p": { width: 720, height: 1280 },
|
||||
"square-720p": { width: 720, height: 720 },
|
||||
@@ -56,6 +59,10 @@ const RESOLUTION_ALIASES: Record<string, CanvasResolution> = {
|
||||
"1080p-square": "square",
|
||||
"square-1080p": "square",
|
||||
"4k-square": "square-4k",
|
||||
"1440p": "landscape-1440p",
|
||||
qhd: "landscape-1440p",
|
||||
"1440p-portrait": "portrait-1440p",
|
||||
"1440p-square": "square-1440p",
|
||||
"720p": "landscape-720p",
|
||||
"720p-portrait": "portrait-720p",
|
||||
"720p-square": "square-720p",
|
||||
@@ -83,6 +90,8 @@ const ASPECT_AGNOSTIC_RESOLUTION_ALIASES: ReadonlySet<string> = new Set([
|
||||
"hd",
|
||||
"4k",
|
||||
"uhd",
|
||||
"1440p",
|
||||
"qhd",
|
||||
"720p",
|
||||
"480p",
|
||||
]);
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
"files": 78
|
||||
},
|
||||
"hyperframes-cli": {
|
||||
"hash": "adcd30f21c700eba",
|
||||
"hash": "53ea8e568639d20a",
|
||||
"files": 13
|
||||
},
|
||||
"hyperframes-registry": {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# init, capture, skills
|
||||
|
||||
<!-- registry-items: allow=blank,landscape-4k,portrait-4k,square-4k,media-use -->
|
||||
<!-- registry-items: allow=blank,landscape-4k,portrait-4k,square-4k,landscape-1440p,portrait-1440p,square-1440p,media-use -->
|
||||
|
||||
Scaffolding commands. Use these instead of creating files by hand — they set up the right file structure, copy media, and run transcription.
|
||||
|
||||
@@ -22,7 +22,7 @@ Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decisi
|
||||
|
||||
Other useful flags:
|
||||
|
||||
- `--resolution` — preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k`, `portrait-4k`, `square` (1080×1080), `square-4k`. Aliases: `1080p`, `4k`, `uhd`, `1080p-square`, `4k-square`.
|
||||
- `--resolution` — preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k`, `portrait-4k`, `square` (1080×1080), `square-4k`, `landscape-1440p` (2560×1440), `portrait-1440p`, `square-1440p`. Aliases: `1080p`, `4k`, `uhd`, `1440p`, `qhd`, `1080p-square`, `4k-square`.
|
||||
- `--skill=<slug>` — record the owning skill (e.g. `hyperframes`) in `hyperframes.json`, so every later render of this project — re-renders, `npm run render`, `--batch` — is attributed to it on usage telemetry without re-passing the flag. You rarely pass it by hand.
|
||||
- `--skip-skills` — leave AI coding skills alone: `init` does not install the core set. `HYPERFRAMES_SKIP_SKILLS=1` does the same. Always pass it: without it `init` installs any missing core skill, and installing skills is the person's step. When a core skill is missing, tell the person they can install it with `npx hyperframes skills update`.
|
||||
- `--skip-transcribe` — don't auto-transcribe `--audio` / `--video` with Whisper.
|
||||
|
||||
@@ -147,6 +147,8 @@ npx hyperframes render --docker # byte-identical
|
||||
|
||||
**Quality guidance:** `draft` while iterating, `looks` (the default) for the first real encode, `delivery` for final delivery. `standard` and `high` still work.
|
||||
|
||||
The 1440p presets are `landscape-1440p` (2560×1440), `portrait-1440p` (1440×2560), and `square-1440p` (1440×1440). Aliases `1440p` and `qhd` follow the composition’s orientation. A 720p composition can upscale to 1440p at 2×, and a 4K composition can downscale to 1440p. A 1920×1080 composition cannot upscale to 1440p because 4/3 is not an integer scale; author at 1440p or render at 4K and downscale separately.
|
||||
|
||||
**Read the summary's second line.** After the output path and size, `render` prints the capture path, GPU mode, and per-stage timings, e.g. `beginframe capture · software gpu · compile 0.7s · setup 1.1s · capture 8.1s · encode 5.8s`. `capture` is the frame loop and `setup` is calibration plus session init; the capture path reads `a|b` when parallel workers diverged, and `encode (during capture)` means the streaming encoder overlapped the loop, so do not add it to the wall time. Local GPU `auto` (the default) requests BeginFrame. If the line still says `screenshot capture` with `software gpu` on Linux, a hint under it says BeginFrame did not run (needs chrome-headless-shell, no `--resolution` upscale). It only appears when the GPU was auto-probed, never under `--docker` or `--no-browser-gpu`, where software GL is the point. Heavy compositions can stall on software GL. Do not reach for `--debug` just to learn which path ran.
|
||||
|
||||
**Parametrized renders:** the composition declares its variables on the `<html>` root with **`data-composition-variables`** — a JSON **array of declarations** (`{id, type, label, default}` per entry) that defines the schema. Scripts inside read the resolved values via `window.__hyperframes.getVariables()`. The CLI `--variables '{"title":"Q4 Report"}'` is a JSON **object keyed by id** that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. Sub-comp hosts can also override per-instance with `data-variable-values`. See `../../hyperframes/references/format.md` for the full pattern.
|
||||
|
||||
Reference in New Issue
Block a user