From d32d372dc90f7a55260a03bd2819c19dbdbfe565 Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Fri, 9 Oct 2026 16:37:15 +0800 Subject: [PATCH 01/18] fix(skills): check local render dependencies before design --- packages/cli/src/browser/ffmpeg.test.ts | 9 +++++++-- packages/cli/src/browser/ffmpeg.ts | 3 +++ packages/cli/src/browser/preflight.test.ts | 20 ++++++++++++++++++- skills-manifest.json | 6 +++--- skills/hyperframes-cli/SKILL.md | 8 ++------ .../references/doctor-browser.md | 10 +++++++++- skills/hyperframes/SKILL.md | 4 ++++ skills/motion-graphics/SKILL.md | 4 +++- 8 files changed, 50 insertions(+), 14 deletions(-) diff --git a/packages/cli/src/browser/ffmpeg.test.ts b/packages/cli/src/browser/ffmpeg.test.ts index b409b8527e8..57c419da02c 100644 --- a/packages/cli/src/browser/ffmpeg.test.ts +++ b/packages/cli/src/browser/ffmpeg.test.ts @@ -112,12 +112,17 @@ describe("getFFmpegInstallCommand / getFFmpegInstallHint", () => { setPlatform(realPlatform); }); - it("gives macOS a pasteable command and uses it verbatim as the hint", async () => { + it("gives macOS a pasteable command and a setup route without Homebrew", async () => { setPlatform("darwin"); const { getFFmpegInstallCommand, getFFmpegInstallHint } = await import("./ffmpeg.js"); expect(getFFmpegInstallCommand()).toBe("brew install ffmpeg"); - expect(getFFmpegInstallHint()).toBe("brew install ffmpeg"); + const hint = getFFmpegInstallHint(); + expect(hint).toContain("brew install ffmpeg"); + expect(hint).toContain("https://ffmpeg.org/download.html"); + expect(hint).toContain("HYPERFRAMES_FFMPEG_PATH"); + expect(hint).toContain("HYPERFRAMES_FFPROBE_PATH"); + expect(hint).toContain(".hyperframes/bin/"); }); it("gives Windows a winget command and keeps the manual route in the hint", async () => { diff --git a/packages/cli/src/browser/ffmpeg.ts b/packages/cli/src/browser/ffmpeg.ts index 3ed7594684c..deda1434fa2 100644 --- a/packages/cli/src/browser/ffmpeg.ts +++ b/packages/cli/src/browser/ffmpeg.ts @@ -104,6 +104,9 @@ export function getFFmpegInstallHint(): string { if (command && process.platform === "win32") { return `${command}, or download the 64-bit build from ${FFMPEG_DOWNLOAD_URL}#build-windows and add its bin/ directory to PATH.`; } + if (command && process.platform === "darwin") { + return `${command}, or download FFmpeg and FFprobe from ${FFMPEG_DOWNLOAD_URL}, then set HYPERFRAMES_FFMPEG_PATH and HYPERFRAMES_FFPROBE_PATH to the executable paths or place both binaries in .hyperframes/bin/ in your project.`; + } if (command) return command; if (process.platform === "linux") return ffmpegInstallCommand("unknown"); return FFMPEG_DOWNLOAD_URL; diff --git a/packages/cli/src/browser/preflight.test.ts b/packages/cli/src/browser/preflight.test.ts index 13ef3a2b32e..54dce083b20 100644 --- a/packages/cli/src/browser/preflight.test.ts +++ b/packages/cli/src/browser/preflight.test.ts @@ -174,7 +174,6 @@ describe("runEnvironmentChecks", () => { }); it.each([ - { platform: "darwin" as const, expectedHint: "brew install ffmpeg" }, { platform: "sunos" as const, expectedHint: "https://ffmpeg.org/download.html" }, { platform: "win32" as const, @@ -194,6 +193,25 @@ describe("runEnvironmentChecks", () => { expect(ffmpeg?.title).toBe("FFmpeg cannot start"); expect(ffmpeg?.hint).toBe(expectedHint); }); + + it("offers configured binaries on macOS when FFmpeg cannot launch", async () => { + Object.defineProperty(process, "platform", { value: "darwin", configurable: true }); + runProcess.mockImplementation((binaryPath: string) => { + if (binaryPath !== process.env.HYPERFRAMES_FFMPEG_PATH) + return Promise.resolve({ stdout: "ffprobe version 7.1.1\n", stderr: "" }); + throw Object.assign(new Error("cannot execute binary file"), { status: 126 }); + }); + + const result = await runEnvironmentChecks(); + const ffmpeg = result.outcomes.find((outcome) => outcome.name === "FFmpeg"); + + expect(ffmpeg).toMatchObject({ ok: false, title: "FFmpeg cannot start" }); + expect(ffmpeg?.hint).toContain("brew install ffmpeg"); + expect(ffmpeg?.hint).toContain("HYPERFRAMES_FFMPEG_PATH"); + expect(ffmpeg?.hint).toContain("HYPERFRAMES_FFPROBE_PATH"); + expect(ffmpeg?.hint).toContain(".hyperframes/bin/"); + expect(result.ffmpegPath).toBeUndefined(); + }); }); it("validates an explicit browser path without needing browser discovery", async () => { diff --git a/skills-manifest.json b/skills-manifest.json index 49ddfb2a1e9..de023241b49 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -18,7 +18,7 @@ "files": 5 }, "hyperframes": { - "hash": "589ae40d15628917", + "hash": "a1bdcf644fd7e37b", "files": 29 }, "hyperframes-animation": { @@ -30,7 +30,7 @@ "files": 7 }, "hyperframes-cli": { - "hash": "c053e99be2d209b1", + "hash": "c08b5ad085db691e", "files": 11 }, "hyperframes-core": { @@ -58,7 +58,7 @@ "files": 109 }, "motion-graphics": { - "hash": "6db77031ad839f6a", + "hash": "987e638de9385815", "files": 23 }, "music-to-video": { diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.md index fd74ca4f753..b308f607c9b 100644 --- a/skills/hyperframes-cli/SKILL.md +++ b/skills/hyperframes-cli/SKILL.md @@ -17,7 +17,7 @@ Run commands as `npx hyperframes ...` unless project instructions provide a wrap ## Development loop -1. **Scaffold:** `npx hyperframes init ` (centered blank). Or capture a site. Pass `--example=` only to start from a named example. +1. **Scaffold and check dependencies:** `npx hyperframes init ` (centered blank). Or capture a site. Pass `--example=` only to start from a named example. For a local video, run `npx hyperframes doctor --json` from the initialized or resumed project before step 2; follow [the dependency check](references/doctor-browser.md#check-local-video-dependencies-before-design) for the FFmpeg and FFprobe results. 2. **Find the move:** if the request names an asset, sound, image, voice or fast visual edit, resolve it through `/media-use` before proposing a plan. Otherwise, before authoring motion by hand, search for a primitive that already does it: `npx hyperframes catalog --query "reveal a headline one line at a time"`. Ask for the effect you want rather than the mechanism you have in mind. Install with `npx hyperframes add ` (see `/hyperframes-registry`). Author by hand only once nothing fits. 3. **Author:** write the composition using `/hyperframes-core`. To know what is on a project's timeline (tracks, clips, starts, ends, what plays), run `npx hyperframes timeline --json` instead of reading `index.html` and every sub-composition file: nested rows carry absolute main-timeline `absStart`/`absEnd` and their owning `file`, not just their local, per-sub-composition time. Prefer `--json` over the text form; it costs fewer tokens for the same or better correctness. See `references/upgrade-info-misc.md` for one-liners that answer common questions without reading the whole output. 4. **Get fast feedback while editing:** run `npx hyperframes lint` after the first HTML pass and after structural changes. @@ -93,11 +93,7 @@ Treat tiny unstyled content, canvas-sized icons, missing hero elements, or timel - **Offer the offline tier; never enable it silently.** A one-time ~33 MB download (a quantized ONNX build of `bge-small-en-v1.5` plus its tokenizer, pinned to a fixed revision) and the catalog vectors from the registry, both cached under `~/.hyperframes/`, neither added to the project or any package. Once cached it ranks by meaning with nothing sent. Say the size out loud and let the person decide, then pass `--on-device` (with `-y` to skip the prompt) once they agree. The interactive offer only fires on a TTY. Under `--json` there is no prompt, but a search that found nothing puts the same ask in `warnings`, so read that array and put the decision to the user yourself. When the person asks what the download is, why this model, or what leaves the machine, point them to https://hyperframes.heygen.com/developers/catalog-search. - Prefer `--json` for agent and CI calls. Server-mode `render`, `preview`, and `play` do not provide ordinary JSON output; `preview --selection --json` and `preview --context --json` are query-mode exceptions. -- `doctor --json` always exits zero. Gate on its payload: - - ```bash - npx hyperframes doctor --json | jq -e '.ok' >/dev/null - ``` +- `doctor --json` always exits zero. Inspect the checks required by the current operation. For local video workflows, use [the FFmpeg and FFprobe dependency check](references/doctor-browser.md#check-local-video-dependencies-before-design); the top-level `ok` also includes optional tools. - Non-TTY mode is automatic and scaffolds the centered blank. Pass `--example` only to start from a named example. Use `--non-interactive` to force flag-only mode on a TTY. - Use one `HYPERFRAMES_RUN_ID` for all commands in the same verification loop. diff --git a/skills/hyperframes-cli/references/doctor-browser.md b/skills/hyperframes-cli/references/doctor-browser.md index 7b01899eea7..c51b7f59dad 100644 --- a/skills/hyperframes-cli/references/doctor-browser.md +++ b/skills/hyperframes-cli/references/doctor-browser.md @@ -6,7 +6,7 @@ Environment diagnosis and bundled-Chrome management. Run these first when a rend ```bash npx hyperframes doctor -npx hyperframes doctor --json # CI / agent output (always exit 0; gate on payload `ok`) +npx hyperframes doctor --json # CI / agent output (always exit 0; inspect checks in payload) ``` Runs independent checks and reports each as ok/warn/fail: @@ -26,6 +26,14 @@ Run `doctor` first when: - `preview` opens but the composition fails to load. - A fresh machine has never run HyperFrames. +### Check local video dependencies before design + +For a workflow that will render a video locally, run `npx hyperframes doctor --json` from the project directory immediately after setup or resume, before planning, sourcing, or design. Fresh setup writes its brief first. Keep this result for the current run; repeat after changing the binary configuration or environment. + +Require both **FFmpeg** and **FFprobe** entries with `ok: true`, and inspect their reported paths. Use [the two-tool jq gate](#configure-ffmpeg-without-a-package-manager) when `jq` is available, or inspect the JSON directly. `doctor --json` exits 0 even when dependencies are missing, and its top-level `ok` includes optional tools. + +When either binary is missing or cannot run, surface the affected check and use [the supported setup paths](#configure-ffmpeg-without-a-package-manager) before design starts. Verify the two checks again after setup. If installation is unavailable or needs authorization, report the dependency and agree on how to continue before starting design; retain the user's choice of local or cloud rendering. Check Chrome separately before browser validation and rendering. Deck-only and source-port tasks follow their own prerequisites. + Common issues: - **Missing FFmpeg** — install via `brew install ffmpeg` (macOS) or your package manager, or [configure existing binaries](#configure-ffmpeg-without-a-package-manager). diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index ca16962a5b5..463bf254ed8 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -45,6 +45,10 @@ When you edit an existing project, bracket your edits with project history (`/hy If a fresh request does not identify the subject or input, ask what the video is about before routing. Check preferences and recipes before asking anything (`references/intent-interview.md`, step 1). A `figma.com` input or a named recipe changes intake, not routing — the interview's "Adapt orthogonal inputs" section handles both. +### Check local video dependencies early + +For creation or edits that will produce a locally rendered video, run `npx hyperframes doctor --json` from the project directory after initialization or resume, before design work. Fresh setup still writes `BRIEF.md` as its first action after `init`; run the dependency check next. Read [the CLI's dependency check](../hyperframes-cli/references/doctor-browser.md#check-local-video-dependencies-before-design) and inspect **FFmpeg** and **FFprobe** individually; optional-tool failures in the report's top-level `ok` do not block local encoding. Apply this on entry to the selected workflow, including a resumed `BRIEF.md`, and retain the result for the run. Project operations follow their existing command contracts; deck-only, source-port, and explicit cloud-render work use their own prerequisites. + ### Keep the project's CLI current A scaffolded project pins `hyperframes@` in its `package.json` scripts so renders stay reproducible; the pin never advances on its own, and a pinned run of an older CLI prints no warning about it. When resuming a project whose scripts carry a pin, probe once before the first render-affecting command: diff --git a/skills/motion-graphics/SKILL.md b/skills/motion-graphics/SKILL.md index 3405c600093..087d9a81bc5 100644 --- a/skills/motion-graphics/SKILL.md +++ b/skills/motion-graphics/SKILL.md @@ -66,7 +66,7 @@ Build order: one at a time, coverage-first (rough is fine). `kinetic-type` porte ## Prerequisites -macOS Apple Silicon or Linux x64. System tools: `brew install node ffmpeg`. `npx hyperframes doctor` once. macOS GPU render: `export PRODUCER_BROWSER_GPU_MODE=hardware`. +macOS Apple Silicon or Linux x64. Node.js 22 or newer, FFmpeg, and FFprobe. Follow [the supported binary setup](../hyperframes-cli/references/doctor-browser.md#configure-ffmpeg-without-a-package-manager), including existing binaries on machines without Homebrew. macOS GPU render: `export PRODUCER_BROWSER_GPU_MODE=hardware`. Optional keys (local fallbacks if unset) — only needed by categories that source/generate assets via media-use: @@ -93,6 +93,8 @@ npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=mo **Constraints:** never `hyperframes init` in the workspace root; never nest another `hyperframes/` inside `PROJECT_DIR`; every Bash command (master + subagents) is a `(cd "$PROJECT_DIR" && ...)` subshell — never bare `cd`. +After setup (including the fresh `BRIEF.md`) or project resume, run `(cd "$PROJECT_DIR" && npx hyperframes doctor --json)` before Step 1. Follow [the dependency check](../hyperframes-cli/references/doctor-browser.md#check-local-video-dependencies-before-design) for FFmpeg and FFprobe; keep a passing result already obtained in this run. + ### Step 1 — Plan (subagent: Director Part 1) Dispatch one subagent. prompt = full `agents/director.md` + `## Dispatch context` (`SKILL_DIR` / `PROJECT_DIR` / the user's request / `Schema: /references/shot-plan-ir.md`). It must: From b6d961c9453f5ab9af58888255cae957b3453b7d Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Sat, 10 Oct 2026 11:05:02 +0800 Subject: [PATCH 02/18] chore(skills): prepare manifest for main integration --- skills-manifest.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/skills-manifest.json b/skills-manifest.json index de023241b49..2e9f574955d 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -18,11 +18,11 @@ "files": 5 }, "hyperframes": { - "hash": "a1bdcf644fd7e37b", + "hash": "589ae40d15628917", "files": 29 }, "hyperframes-animation": { - "hash": "3bd80388da91c689", + "hash": "9370b856259f4586", "files": 122 }, "hyperframes-audio": { @@ -30,7 +30,7 @@ "files": 7 }, "hyperframes-cli": { - "hash": "c08b5ad085db691e", + "hash": "5076477812cf2c37", "files": 11 }, "hyperframes-core": { @@ -58,7 +58,7 @@ "files": 109 }, "motion-graphics": { - "hash": "987e638de9385815", + "hash": "6db77031ad839f6a", "files": 23 }, "music-to-video": { From b40d58e9b41dc69c8ffaeb35979e5952f2084361 Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Sat, 10 Oct 2026 11:05:07 +0800 Subject: [PATCH 03/18] fix(skills): regenerate local-render dependency manifest --- skills-manifest.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills-manifest.json b/skills-manifest.json index 2e9f574955d..bdc5967e463 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -18,7 +18,7 @@ "files": 5 }, "hyperframes": { - "hash": "589ae40d15628917", + "hash": "a1bdcf644fd7e37b", "files": 29 }, "hyperframes-animation": { @@ -30,7 +30,7 @@ "files": 7 }, "hyperframes-cli": { - "hash": "5076477812cf2c37", + "hash": "42db537322a9fced", "files": 11 }, "hyperframes-core": { @@ -58,7 +58,7 @@ "files": 109 }, "motion-graphics": { - "hash": "6db77031ad839f6a", + "hash": "987e638de9385815", "files": 23 }, "music-to-video": { From a287ac66d5908f9bb76c3978e880739a10305ab1 Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Wed, 14 Oct 2026 04:11:40 +0800 Subject: [PATCH 04/18] chore: prepare conflict resolution against current main --- skills-manifest.json | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/skills-manifest.json b/skills-manifest.json index bdc5967e463..960e5a88ac8 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -2,35 +2,35 @@ "source": "heygen-com/hyperframes", "skills": { "embedded-captions": { - "hash": "643579aed5919847", - "files": 144 + "hash": "1dc7ec2fd4a6e3fc", + "files": 145 }, "faceless-explainer": { - "hash": "1f10a69e0f879698", - "files": 28 + "hash": "bb2225ebaf7f9622", + "files": 29 }, "figma": { "hash": "f8cf9f2c78ea8374", "files": 2 }, "general-video": { - "hash": "7194a47a82647a88", - "files": 5 + "hash": "17dfbb1d34efb012", + "files": 6 }, "hyperframes": { - "hash": "a1bdcf644fd7e37b", - "files": 29 + "hash": "9787b91e4c16bf7f", + "files": 31 }, "hyperframes-animation": { - "hash": "9370b856259f4586", + "hash": "a5d09375a50f71c8", "files": 122 }, "hyperframes-audio": { - "hash": "e96de47ed2e6097a", - "files": 7 + "hash": "780c9d4d8d23ab40", + "files": 8 }, "hyperframes-cli": { - "hash": "42db537322a9fced", + "hash": "56a46bc15c308d98", "files": 11 }, "hyperframes-core": { @@ -54,11 +54,11 @@ "files": 1 }, "media-use": { - "hash": "c8800249da2d1ce6", - "files": 109 + "hash": "c4c3c723aa04bb7d", + "files": 112 }, "motion-graphics": { - "hash": "987e638de9385815", + "hash": "7e4af0881390ac2e", "files": 23 }, "music-to-video": { @@ -66,12 +66,12 @@ "files": 169 }, "pr-to-video": { - "hash": "88f4c68788eaba9e", - "files": 34 + "hash": "d377b802ef54bc46", + "files": 35 }, "product-launch-video": { - "hash": "76149a9f3514626e", - "files": 36 + "hash": "965b9b93bf19b173", + "files": 37 }, "remotion-to-hyperframes": { "hash": "d02be65b7f3f4a63", @@ -82,7 +82,7 @@ "files": 2 }, "talking-head-recut": { - "hash": "9aac076ceddd2499", + "hash": "4b2cf6d7b6e336b4", "files": 28 } } From d9fc67b5c23b75da3988ab866369df285aed53a0 Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Wed, 14 Oct 2026 04:11:46 +0800 Subject: [PATCH 05/18] chore(skills): regenerate render prerequisite manifest --- skills-manifest.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills-manifest.json b/skills-manifest.json index 960e5a88ac8..29ead6f0b17 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -18,7 +18,7 @@ "files": 6 }, "hyperframes": { - "hash": "9787b91e4c16bf7f", + "hash": "afc26fa793f3ac25", "files": 31 }, "hyperframes-animation": { @@ -30,7 +30,7 @@ "files": 8 }, "hyperframes-cli": { - "hash": "56a46bc15c308d98", + "hash": "92e2e0540a54e33e", "files": 11 }, "hyperframes-core": { @@ -58,7 +58,7 @@ "files": 112 }, "motion-graphics": { - "hash": "7e4af0881390ac2e", + "hash": "c5dc2da9562455c7", "files": 23 }, "music-to-video": { From a3eba078c4f41e1fb42e1c714d460eb28a8d1844 Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Thu, 15 Oct 2026 21:44:28 +0800 Subject: [PATCH 06/18] chore: prepare conflict resolution against current main --- skills-manifest.json | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/skills-manifest.json b/skills-manifest.json index 29ead6f0b17..3c12e2af1f0 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -6,7 +6,7 @@ "files": 145 }, "faceless-explainer": { - "hash": "bb2225ebaf7f9622", + "hash": "395653774d035d3a", "files": 29 }, "figma": { @@ -14,15 +14,15 @@ "files": 2 }, "general-video": { - "hash": "17dfbb1d34efb012", + "hash": "f288a7bc7eb1a1cf", "files": 6 }, "hyperframes": { - "hash": "afc26fa793f3ac25", + "hash": "6c3f074a2d44e4cd", "files": 31 }, "hyperframes-animation": { - "hash": "a5d09375a50f71c8", + "hash": "1c91404cdf888540", "files": 122 }, "hyperframes-audio": { @@ -30,7 +30,7 @@ "files": 8 }, "hyperframes-cli": { - "hash": "92e2e0540a54e33e", + "hash": "f08c429fb0f8b82c", "files": 11 }, "hyperframes-core": { @@ -38,7 +38,7 @@ "files": 11 }, "hyperframes-creative": { - "hash": "8d0601ce26adc560", + "hash": "043c4bc84b16a96f", "files": 79 }, "hyperframes-keyframes": { @@ -50,7 +50,7 @@ "files": 12 }, "hyperframes-studio": { - "hash": "f5e0b44d68152c12", + "hash": "9c347bc86335c354", "files": 1 }, "media-use": { @@ -58,19 +58,19 @@ "files": 112 }, "motion-graphics": { - "hash": "c5dc2da9562455c7", + "hash": "7e4af0881390ac2e", "files": 23 }, "music-to-video": { - "hash": "b775f27b16efb1f2", + "hash": "ac33d950e9a2e1e9", "files": 169 }, "pr-to-video": { - "hash": "d377b802ef54bc46", + "hash": "5e69368e66a27179", "files": 35 }, "product-launch-video": { - "hash": "965b9b93bf19b173", + "hash": "14d03406b4fc6904", "files": 37 }, "remotion-to-hyperframes": { From 85080ee4763c7c027e0289c2aa49320da31794e6 Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Thu, 15 Oct 2026 21:44:37 +0800 Subject: [PATCH 07/18] fix(skills): retain early render checks with current main --- skills-manifest.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills-manifest.json b/skills-manifest.json index 3c12e2af1f0..20c11669ea0 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -18,7 +18,7 @@ "files": 6 }, "hyperframes": { - "hash": "6c3f074a2d44e4cd", + "hash": "bd03374cda75addb", "files": 31 }, "hyperframes-animation": { @@ -30,7 +30,7 @@ "files": 8 }, "hyperframes-cli": { - "hash": "f08c429fb0f8b82c", + "hash": "a9eaeba4ba25f337", "files": 11 }, "hyperframes-core": { @@ -58,7 +58,7 @@ "files": 112 }, "motion-graphics": { - "hash": "7e4af0881390ac2e", + "hash": "c5dc2da9562455c7", "files": 23 }, "music-to-video": { From 5f1f5d780900da8a2788621da9da922ceb9d3d81 Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Sun, 18 Oct 2026 11:34:43 +0800 Subject: [PATCH 08/18] chore: prepare conflict resolution against current main --- skills-manifest.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/skills-manifest.json b/skills-manifest.json index 20c11669ea0..ec3874ae536 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -18,7 +18,7 @@ "files": 6 }, "hyperframes": { - "hash": "bd03374cda75addb", + "hash": "44700184328c21b5", "files": 31 }, "hyperframes-animation": { @@ -30,11 +30,11 @@ "files": 8 }, "hyperframes-cli": { - "hash": "a9eaeba4ba25f337", + "hash": "3c8d1fac9e0a02fe", "files": 11 }, "hyperframes-core": { - "hash": "010a65915fc7b45e", + "hash": "66fc3e623a910923", "files": 11 }, "hyperframes-creative": { @@ -58,7 +58,7 @@ "files": 112 }, "motion-graphics": { - "hash": "c5dc2da9562455c7", + "hash": "7e4af0881390ac2e", "files": 23 }, "music-to-video": { From 89788caa2c87a7c7c263fe6cd0625c0ec4e79458 Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Sun, 18 Oct 2026 11:34:51 +0800 Subject: [PATCH 09/18] fix(skills): condense early dependency guidance after main integration --- skills-manifest.json | 6 +++--- skills/hyperframes/SKILL.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/skills-manifest.json b/skills-manifest.json index ec3874ae536..ef5b81a8870 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -18,7 +18,7 @@ "files": 6 }, "hyperframes": { - "hash": "44700184328c21b5", + "hash": "89be3f5aa66084a4", "files": 31 }, "hyperframes-animation": { @@ -30,7 +30,7 @@ "files": 8 }, "hyperframes-cli": { - "hash": "3c8d1fac9e0a02fe", + "hash": "55ea39113dce2b44", "files": 11 }, "hyperframes-core": { @@ -58,7 +58,7 @@ "files": 112 }, "motion-graphics": { - "hash": "7e4af0881390ac2e", + "hash": "c5dc2da9562455c7", "files": 23 }, "music-to-video": { diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index e06244a4c14..b2da6631d28 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -47,7 +47,7 @@ If a fresh request does not identify the subject or input, ask what the video is ### Check local video dependencies early -For creation or edits that will produce a locally rendered video, run `npx hyperframes doctor --json` from the project directory after initialization or resume, before design work. Fresh setup still writes `BRIEF.md` as its first action after `init`; run the dependency check next. Read [the CLI's dependency check](../hyperframes-cli/references/doctor-browser.md#check-local-video-dependencies-before-design) and inspect **FFmpeg** and **FFprobe** individually; optional-tool failures in the report's top-level `ok` do not block local encoding. Apply this on entry to the selected workflow, including a resumed `BRIEF.md`, and retain the result for the run. Project operations follow their existing command contracts; deck-only, source-port, and explicit cloud-render work use their own prerequisites. +Before designing a locally rendered video, follow [the CLI's dependency check](../hyperframes-cli/references/doctor-browser.md#check-local-video-dependencies-before-design) after project setup or resume; fresh setup still writes `BRIEF.md` first. Check **FFmpeg** and **FFprobe** individually and retain the result for the run; other project operations and deck, source-port, or explicit cloud-render work follow their own prerequisites. ### Keep the project's CLI current From 066ef3add713b4a4cfa95d1beaf136a5c4158804 Mon Sep 17 00:00:00 2001 From: "Abdullah M. Nazif" Date: Sat, 24 Oct 2026 13:55:15 +0800 Subject: [PATCH 10/18] chore: prepare conflict resolution against current main --- skills-manifest.json | 78 ++-------- skills/hyperframes-cli/SKILL.md | 251 ++++++++++---------------------- skills/hyperframes/SKILL.md | 188 +++++++----------------- skills/motion-graphics/SKILL.md | 176 ---------------------- 4 files changed, 139 insertions(+), 554 deletions(-) delete mode 100644 skills/motion-graphics/SKILL.md diff --git a/skills-manifest.json b/skills-manifest.json index ef5b81a8870..e6442718b8a 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -1,89 +1,33 @@ { "source": "heygen-com/hyperframes", "skills": { - "embedded-captions": { - "hash": "1dc7ec2fd4a6e3fc", - "files": 145 - }, - "faceless-explainer": { - "hash": "395653774d035d3a", - "files": 29 - }, "figma": { - "hash": "f8cf9f2c78ea8374", + "hash": "af57c9b6411c81f5", "files": 2 }, - "general-video": { - "hash": "f288a7bc7eb1a1cf", - "files": 6 - }, "hyperframes": { - "hash": "89be3f5aa66084a4", - "files": 31 - }, - "hyperframes-animation": { - "hash": "1c91404cdf888540", - "files": 122 - }, - "hyperframes-audio": { - "hash": "780c9d4d8d23ab40", - "files": 8 + "hash": "8fc4b05db245cbbb", + "files": 77 }, "hyperframes-cli": { - "hash": "55ea39113dce2b44", - "files": 11 - }, - "hyperframes-core": { - "hash": "66fc3e623a910923", - "files": 11 - }, - "hyperframes-creative": { - "hash": "043c4bc84b16a96f", - "files": 79 - }, - "hyperframes-keyframes": { - "hash": "a3d43b98955b1366", - "files": 3 + "hash": "d82c156c1b2069d1", + "files": 13 }, "hyperframes-registry": { - "hash": "d7c1885fb4cce2cf", - "files": 12 - }, - "hyperframes-studio": { - "hash": "9c347bc86335c354", - "files": 1 + "hash": "221af9e7fbffe732", + "files": 13 }, "media-use": { - "hash": "c4c3c723aa04bb7d", - "files": 112 - }, - "motion-graphics": { - "hash": "c5dc2da9562455c7", - "files": 23 - }, - "music-to-video": { - "hash": "ac33d950e9a2e1e9", - "files": 169 - }, - "pr-to-video": { - "hash": "5e69368e66a27179", - "files": 35 - }, - "product-launch-video": { - "hash": "14d03406b4fc6904", - "files": 37 + "hash": "1082bd1c4e3f033b", + "files": 116 }, "remotion-to-hyperframes": { - "hash": "d02be65b7f3f4a63", + "hash": "3bf96d306215e384", "files": 77 }, "slideshow": { - "hash": "efc3c0be622fa9a1", + "hash": "c8a591e2aa7a6d86", "files": 2 - }, - "talking-head-recut": { - "hash": "4b2cf6d7b6e336b4", - "files": 28 } } } diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.md index 1a937c9ae35..7f51bc528ab 100644 --- a/skills/hyperframes-cli/SKILL.md +++ b/skills/hyperframes-cli/SKILL.md @@ -1,196 +1,97 @@ --- name: hyperframes-cli -description: > - Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, - compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, - cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, timeline, history, clean, docs, - benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build - or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, - HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering. +description: The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures. --- -**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below. +**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. # HyperFrames CLI -Run commands as `npx hyperframes ...` unless project instructions provide a wrapper. Obey the wrapper when present. The CLI requires Node.js 22 or newer and FFmpeg. +Run `npx hyperframes ` unless the project gives a wrapper; then use the wrapper. It needs Node.js 22+ and FFmpeg. Every command has `--help`; most take `--json`, and a failure prints `✗ …`, a `Fix:` line and exits non-zero. -## Development loop +## Commands by job -1. **Scaffold and check dependencies:** `npx hyperframes init ` (centered blank). Or capture a site. Pass `--example=` only to start from a named example. For a local video, run `npx hyperframes doctor --json` from the initialized or resumed project before step 2; follow [the dependency check](references/doctor-browser.md#check-local-video-dependencies-before-design) for the FFmpeg and FFprobe results. -2. **Find the move:** if the request names an asset, sound, image, voice or fast visual edit, resolve it through `/media-use` before proposing a plan. Otherwise, before authoring motion by hand, search for a primitive that already does it: `npx hyperframes catalog --query "reveal a headline one line at a time"`. Ask for the effect you want rather than the mechanism you have in mind. Install with `npx hyperframes add ` (see `/hyperframes-registry`). Author by hand only once nothing fits. -3. **Author:** write the composition using `/hyperframes-core`. To know what is on a project's timeline (tracks, clips, starts, ends, what plays), run `npx hyperframes timeline --json` instead of reading `index.html` and every sub-composition file: nested rows carry absolute main-timeline `absStart`/`absEnd` and their owning `file`, not just their local, per-sub-composition time. Prefer `--json` over the text form; it costs fewer tokens for the same or better correctness. See `references/upgrade-info-misc.md` for one-liners that answer common questions without reading the whole output. -4. **Get fast feedback while editing:** run `npx hyperframes lint` after the first HTML pass and after structural changes. -5. **Run the final gate:** run `npx hyperframes check`; it reruns lint before opening the browser. Do not prepend a redundant standalone lint invocation. Add `--snapshots` for annotated overview frames and finding crops. -6. **Inspect sub-compositions:** when `index.html` mounts `data-composition-src`, capture midpoint snapshots and inspect each mounted scene. Inspect the opening 30 seconds and reported problem times at full resolution; zoom into fine geometry, text, and WebGL edges rather than judging a contact sheet alone. -7. **Open the final Studio preview:** run `npx hyperframes preview --background`, verify the URL returns HTTP 200, hand the timeline project URL to the user, and ask whether to revise or render. Keep it alive until review ends. -8. **Render only after approval:** use `--quality draft` while iterating, `--quality looks` for the first real encode (the CLI default), and `--quality delivery` for final delivery. -9. **Hand the project to the desktop app (on offer):** when the render's Framey line ends in `hyperframes open …`, offer `npx hyperframes open [dir]`. It opens the project in the HyperFrames desktop app and adds it to Home; under Claude Code, Codex or Grok its chat picks up this conversation. Without the app it exits 1 and prints the download link. `--json` for agents. When `open` says to run `catch-up` once the person is back, or any command ends with a line naming it, run `npx hyperframes catch-up [dir]` before your next change: it lists what was asked and changed in the app since the hand-off. An older CLI has no `catch-up`. -10. **Verify the output:** confirm the file exists and is non-empty. Read the render summary's second line (`beginframe` vs `screenshot`, GPU, stage timings). `screenshot` + `software gpu` on Linux is the slow path. `ffprobe -v error -show_format -show_streams` and compare duration (and fps if the brief set it) to the root `data-duration`. Visually inspect decoded output frames at the same times as the preview, including close-ups; a successful check or encode does not certify the pixels inside a canvas. +| Job | Commands | +| --- | --- | +| Start | `init ` (blank; `--example ` only when asked), `capture ` | +| Read a project | `info`, `compositions`, `timeline --json`, `docs ` | +| Check it | `lint` while writing; `check --json` as the gate (lint, runtime, layout, contrast) | +| Look at it | `snapshot` (`--at `, `--range START,END`, `--composition `, `--zoom`, `--angle`, `--against