Skip to content

Commit b5a5baf

Browse files
committed
fix(cli): clarify 1440p aliases and repair skill validation
1 parent ff568aa commit b5a5baf

9 files changed

Lines changed: 13 additions & 13 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,7 @@ npx hyperframes init my-video --tailwind
178178
| Flag | Description |
179179
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
180180
| `--example, -e` | Example to scaffold. Default is the centered blank. See [Examples](/examples) for the full list. |
181-
| `--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`, `2k`, `qhd`, `1080p-square`, `square-1080p`, `4k-square`, `1440p-portrait`, `1440p-square`. Default: keep template dimensions. |
181+
| `--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. |
182182
| `--video, -v` | Path to a video file (MP4, WebM, MOV) |
183183
| `--audio, -a` | Path to an audio file (MP3, WAV, M4A) |
184184
| `--tailwind` | Add Tailwind CSS browser-runtime support to the scaffolded HTML |
@@ -1822,7 +1822,7 @@ The flags that come up most:
18221822
| `--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. |
18231823
| `--fps, -f` | root `data-fps`, otherwise 30 | 1–240, or an ffmpeg rational like `30000/1001` for 29.97 |
18241824
| `--quality, -q` | `looks` | `draft`, `looks` (CRF 16, default), `delivery` (= `high`), `standard`, or `high`. MOV always uses the fixed alpha-preserving ProRes 4444 profile. |
1825-
| `--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). |
1825+
| `--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). |
18261826
| `--docker` | off | Render inside Docker for [deterministic output](/concepts/determinism) |
18271827
| `--variables` | — | JSON object merged over the composition's `data-composition-variables` defaults |
18281828
| `--variables-file` | — | Read those overrides from a JSON file instead |

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -842,7 +842,7 @@ export default defineCommand({
842842
resolution: {
843843
type: "string",
844844
description:
845-
"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, 2k, 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).",
845+
"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).",
846846
},
847847
skill: {
848848
type: "string",
@@ -896,7 +896,7 @@ export default defineCommand({
896896
`Invalid --resolution: "${args.resolution}". ` +
897897
`Use one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k, ` +
898898
`landscape-1440p, portrait-1440p, square-1440p ` +
899-
`(or aliases 1080p, 4k, uhd, 1440p, 2k, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square).`,
899+
`(or aliases 1080p, 4k, uhd, 1440p, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square).`,
900900
),
901901
);
902902
failUsage();

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -384,7 +384,7 @@ export default defineCommand({
384384
resolution: {
385385
type: "string",
386386
description:
387-
"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, 2k, 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; the scale must be an integer multiple. Not yet supported with --hdr.",
387+
"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.",
388388
},
389389
"page-side-compositing": {
390390
type: "boolean",

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -388,7 +388,7 @@ export function createRenderPlan(args: RenderCommandArgs, now = new Date()): Ren
388388
"Invalid resolution",
389389
`Got "${args.resolution}". Must be one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k, ` +
390390
`landscape-1440p, portrait-1440p, square-1440p ` +
391-
`(or aliases 1080p, 4k, uhd, 1440p, 2k, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square).`,
391+
`(or aliases 1080p, 4k, uhd, 1440p, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square).`,
392392
);
393393
failUsage();
394394
}

‎packages/core/src/index.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ describe("@hyperframes/core public API exports", () => {
4848
expect(core.normalizeResolutionFlag("1080p-square")).toBe("square");
4949
expect(core.normalizeResolutionFlag("4k-square")).toBe("square-4k");
5050
expect(core.normalizeResolutionFlag("1440p")).toBe("landscape-1440p");
51-
expect(core.normalizeResolutionFlag("2k")).toBe("landscape-1440p");
51+
expect(core.normalizeResolutionFlag("2k")).toBeUndefined();
5252
expect(core.normalizeResolutionFlag("QHD")).toBe("landscape-1440p");
5353
expect(core.normalizeResolutionFlag("1440p-portrait")).toBe("portrait-1440p");
5454
expect(core.normalizeResolutionFlag("1440p-square")).toBe("square-1440p");
@@ -64,7 +64,7 @@ describe("@hyperframes/core public API exports", () => {
6464
expect(core.isAspectAgnosticResolutionAlias("4k")).toBe(true);
6565
expect(core.isAspectAgnosticResolutionAlias("uhd")).toBe(true);
6666
expect(core.isAspectAgnosticResolutionAlias("1440p")).toBe(true);
67-
expect(core.isAspectAgnosticResolutionAlias("2k")).toBe(true);
67+
expect(core.isAspectAgnosticResolutionAlias("2k")).toBe(false);
6868
expect(core.isAspectAgnosticResolutionAlias("qhd")).toBe(true);
6969
// Case-insensitive.
7070
expect(core.isAspectAgnosticResolutionAlias("1080P")).toBe(true);

‎packages/parsers/src/types.ts‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,6 @@ const RESOLUTION_ALIASES: Record<string, CanvasResolution> = {
6060
"square-1080p": "square",
6161
"4k-square": "square-4k",
6262
"1440p": "landscape-1440p",
63-
"2k": "landscape-1440p",
6463
qhd: "landscape-1440p",
6564
"1440p-portrait": "portrait-1440p",
6665
"1440p-square": "square-1440p",
@@ -92,7 +91,6 @@ const ASPECT_AGNOSTIC_RESOLUTION_ALIASES: ReadonlySet<string> = new Set([
9291
"4k",
9392
"uhd",
9493
"1440p",
95-
"2k",
9694
"qhd",
9795
"720p",
9896
"480p",

‎skills-manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
"files": 78
1111
},
1212
"hyperframes-cli": {
13-
"hash": "fb05b272b907bc9a",
13+
"hash": "53ea8e568639d20a",
1414
"files": 13
1515
},
1616
"hyperframes-registry": {

‎skills/hyperframes-cli/references/init-and-scaffold.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# init, capture, skills
22

3-
<!-- registry-items: allow=blank,landscape-4k,portrait-4k,square-4k,media-use -->
3+
<!-- registry-items: allow=blank,landscape-4k,portrait-4k,square-4k,landscape-1440p,portrait-1440p,square-1440p,media-use -->
44

55
Scaffolding commands. Use these instead of creating files by hand — they set up the right file structure, copy media, and run transcription.
66

@@ -22,7 +22,7 @@ Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decisi
2222

2323
Other useful flags:
2424

25-
- `--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`, `2k`, `qhd`, `1080p-square`, `4k-square`.
25+
- `--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`.
2626
- `--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.
2727
- `--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`.
2828
- `--skip-transcribe` — don't auto-transcribe `--audio` / `--video` with Whisper.

‎skills/hyperframes-cli/references/preview-render.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,8 @@ npx hyperframes render --docker # byte-identical
147147

148148
**Quality guidance:** `draft` while iterating, `looks` (the default) for the first real encode, `delivery` for final delivery. `standard` and `high` still work.
149149

150+
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.
151+
150152
**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.
151153

152154
**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.

0 commit comments

Comments
 (0)