Content & Media Creation · heygen-com/hyperframes

motion-graphics

Name: motion-graphics
Author: heygen-com/hyperframes

A short, design-led motion graphic where motion is the message — kinetic typography, stat count-up, chart/data-viz hit, logo sting / brand lockup, lower-third / callout / social overlay, animated map (highlight regions, connect places, zoom to a location), animated tweet / news-article / headline, webpage / UI animation (scroll, cursor, callouts), or fusing a real image's geometry into a chart. Usually under 10s (up to ~30s), no narration or live-action subject; renders to MP4 or transparent overlay. Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

Author heygen-comGitHub heygen-com/hyperframes ↗Stars 44283License Apache-2.0（仓库根 LICENSE 为 Apache License Version 2.0；池内值亦为 Apache-2.0）Commit b8328f9573

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The design orientation focuses on 'design-led motion graphics' (motion is the message), setting the pipeline to autonomous mode: at most one clarifying question (Director Part 1), followed by uninterrupted execution through building and verification without intermediate review gates; only rendering remains user-gated.

skills/motion-graphics/SKILL.md

This workflow is **autonomous by design** — at most one clarifying question (`agents/director.md`), then build through verification without intermediate review.

What is happening here: Unlike product-launch-video / faceless-explainer workflows with multiple review gates, storyboarding and real-time handholding offer insufficient ROI in short-form scenarios, compressing reviews down to a single question: 'preview or render'.

Asset-first approach: Determine the asset strategy and retrieve real materials first, design shots around available assets, and finally assemble using catalog capabilities; pure code/text categories skip the sourcing step entirely.

skills/motion-graphics/SKILL.md

**Asset-first**: decide the asset strategy and source real material _before_ designing the shot, then design the shot around what you have, then compose by reusing catalog capabilities.

What is happening here: Inverting the failure-prone sequence of 'designing before finding assets'. The stage table explicitly specifies that `source ◇` only executes when the category declares assets ('Pure code/text categories (e.g. `kinetic-type`, most `charts`/`stat`) have `asset_needs: []` and skip straight from plan to design').

Taxonomy branches based on whether search is needed: format-driven categories (kinetic-type / stat / charts / logo-reveal / lower-thirds / maps) use user-provided content; search-driven categories (webpage / news / tweet / asset-fusion) search first and decide animation style based on returned content.

skills/motion-graphics/SKILL.md

`plan`'s **first decision is: does this need a search?** That fork splits the categories into two groups; then the specific category is picked — for search-driven, **by the type of content the search returns**.

What is happening here: Each category is defined in `categories/<id>/module.md` (planning + building rules), sharing vocabulary in references/motion-vocabulary.md. Extension rules specify: drop in a folder, register a category row in director.md, and add a line to catalog-map.md, leaving the pipeline untouched.

Building follows 'reuse-first': Run `npx hyperframes add <block>` to fetch catalog blocks and modify them in place; only functional gaps and asset-fusion expressions are written from scratch.

skills/motion-graphics/SKILL.md

**Reuse-first**: `npx hyperframes add <block>` + customize in place; hand-author only gaps + the asset-fusion affordance. Output `compositions/index.html` honoring the HF contract (paused GSAP timeline on `window.__timelines`, `class="clip"` + stable ids, `tl.seek(0)`, deterministic).

What is happening here: Replacing 'LLM template generation' with 'official block assembly + deterministic rules', equivalent to templates in the Remotion ecosystem; outputs must still satisfy Hyperframes' paused GSAP timeline, clip classes, and determinism contracts.

Coordinates are resolved via the locate protocol rather than model estimation: discrete grid-strip selection is used (far more reliable than direct pixel regression), reserving the one-call auto path only when a strong detector key exists in the environment.

skills/motion-graphics/grounding/PROTOCOL.md

Author models are unreliable at **regressing pixel coordinates** on a cluttered full image (measured: weak vision models ~16–24% center error → rings land off-target) but reliable at **picking a numbered strip** (~3–4% with the loop below). So: never eyeball coordinates; localize by discrete choice.

What is happening here: Turning visual grounding into a deterministic pipeline: overlay (9x9 strips) -> region (6x6 subdivision) -> final -> mark (draw bounding box and verify visually), requiring retries along known directions on failure rather than coordinate guessing. Guard rails state: '**Never assume the key exists.** No key → path 2.'

Base maps for map categories must be baked into MP4 inside headless Chrome: not for smoothness, but because Hyperframes forbids runtime network calls and mandates deterministic output—live tiles shift across renders.

skills/motion-graphics/categories/maps/bake-basemap.mjs

// Why bake the imagery at all (this is the real reason, not "smoothness"): HF forbids render-time // network and requires deterministic output. Live raster tiles re-fetch every render and can change // → non-deterministic. Baking FREEZES the imagery into pixels = deterministic + offline-reproducible.

What is happening here: A script drives MapLibre via puppeteer-core to record a camera zoom-and-hold sequence into image frames, projecting requested country borders to screen coordinates in coords.json; borders, fills, and labels remain in editable real-time SVG layers in Hyperframes. Driven entirely by env vars (NAME/STYLE/CENTER/ZSTART/ZEND/FPS/DUR/COUNTRIES), dynamically resolving the Chrome binary.

Verification requires selecting three proof frames—opening state, hero action, and final hold—for human contact sheet review; failures trigger only one in-place fix (finalize subagent), strictly prohibiting duration adjustments to mask flaws.

skills/motion-graphics/SKILL.md

Choose proof times that show the opening state, signature move, and final hold. Inspect the generated contact or snapshot sheet before continuing. On `lint`, `check`, or snapshot failure, dispatch the repair subagent (`agents/finalize.md`) for one in-place fix pass, then rerun the failed gate. Never change a fixed duration merely to hide a defect.

What is happening here: Enforcing 'one fix is enough' and 'no duration masking' as explicit rules, paired with a Resume table (missing shot-plan.json -> return to plan; asset_needs without assets/ -> return to source; index.html without snapshots -> return to verify...) to support interruption recovery.

2Core Capabilities

01Kinetic typography / single-stat callouts / chart data visualization / logo sting and brand lockup / lower-thirds and social overlays

02Animated maps (vector lane or baked basemap lane; highlight regions, connect points, zoom to location)

03Search-driven formats: webpage/UI animations (scroll, reveal, cursor, callouts), news headline cards, tweet cards, and asset-fusion integrating real image geometry into charts

04Visual coordinate grounding protocol (discrete grid-strip selection + optional detector fast-path + bounding-box visual self-check)

05Basemap baking (MapLibre + headless Chrome -> frame sequence + projected country border screen coordinates)

06MP4 or transparent overlay output (webm/mov) with proof frames and contact sheets

07Resume interrupted workflows based on disk state and modular taxonomy expansion (add module.md + register two lines)

3External Dependencies

Kind	Dependency / Endpoint
cli	hyperframes CLI（init / doctor / add / lint / check / snapshot / preview / render / skills update）
cli	ffmpeg / ffprobe（探帧率与时长、抽帧、编码）
api	Google Generative Language API（可选的视觉检测快路径，仅在环境存在 key 时使用）
api	可选图像生成 key（media-use resolve 的生成分支；未设置则只搜索或不生成）
network	底图瓦片与矢量数据（仅在 maps 分类烘焙底图时联网；烘焙后离线可复现）
package	puppeteer-core + 无头 Chrome（底图烘焙录制）
network	GSAP CDN（示例资产 _ref-circle-highlight.html 引用）
package	兄弟 skill 依赖（/media-use 的 resolve 与 search 提供者、/hyperframes-animation 的 rules/blueprints、/hyperframes-core 的 brief-contract、/figma）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Local script and command execution: node grounding/locate.mjs overlay|region|final|mark|auto <img> ... (ffmpeg/ffprobe)
网络端点: Declared external network access: https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent
本地工作目录: File I/O and artifact generation: videos/<project>/hyperframes.json, context.log, shot-plan.json (IR), composition.html

Audit Notes: Both amber-tier warning criteria are met: 1) **Credential/environment variable access** — grounding/locate.mjs reads process.env.GEMINI_API_KEY directly and appends it to query parameters calling generativelanguage.googleapis.com (`?key=${key}`), with GEMINI_API_KEY/GOOGLE_API_KEY listed as optional capability keys in SKILL.md; 2) **Third-party remote packages and mirrors** — the maps category loads maplibre-gl/topojson-client/world-atlas from jsdelivr inside headless Chrome, fetching map tiles from ArcGIS (arcgisonline.com) and CartoCDN, alongside third-party search integrations (SerpAPI/Google Images/Noun Project). All behaviors reflect deliberate functional design (map tiles, detector APIs) with local fallbacks (grid sweeps when keys are absent, fallback to assetless states when search is unavailable). No TLS degradation, anti-scraping bypasses, or arbitrary code execution risks were identified (subprocesses invoke fixed binaries and bundled scripts).

5Second-Pass Verification

[ok] GEMINI_API_KEY 是否真的被读取并外发（橙档判定的关键证据） — locate.mjs:192 `const key = process.env.GEMINI_API_KEY;`；紧接着 key 缺失即报错退出（'auto needs GEMINI_API_KEY; use the grid loop instead (overlay→region→final→mark)'）；存在时把 base64 图像与目标描述 POST 到 generativelanguage.googleapis.com（`?key=${key}`）。调用点真实存在，且仅在 `auto` 子命令触发。
[ok] 『不假设有检测器』的守卫是否真的生效（避免第一遍误判为『总是联网』） — PROTOCOL.md 明写 '**Never assume the key exists.** No key → path 2.'，且把网格循环列为『the normal case』；SKILL.md 的可选键表也把 GEMINI_API_KEY 标为 optional 并给出 fallback（skip generate / search-only）。因此网络外发是有条件、可预期的，而非默认路径。
[discrepancy] Step 2 引用的 resolve.mjs 是否随包分发 — SKILL.md Step 2 给出 `(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/source/resolve.mjs --plan ./shot-plan.json --out ./assets)`，但 **phases/source/ 下只有 guide.md，没有 resolve.mjs**（全量文件清单已确认）。guide.md 末尾也标了 '> Illustrative: … — or drive media-use's `resolve` procedure directly.'。结论：该命令是示意而非可执行入口，实际取材须由 /media-use 的 resolve 流程驱动；SKILL.md 自身有 'illustrative' 标注，故不算虚假声明，但读者若照抄命令会直接失败——这是对 pin commit 有效的真实出入。
[ok] 底图烘焙是否真是本地行为而非渲染期联网 — bake-basemap.mjs 头注释与实现一致：在无头 Chrome 内加载 MapLibre + 瓦片，录帧到 frames-<NAME>/，导出 coords.json；SKILL.md 只在该分类下引用它。渲染期（hyperframes render）不触发任何取瓦片行为，符合 HF 的『渲染期禁网』契约——这也是文档给出的烘焙理由，自洽。
[ok] 『外部资源』逐条回查调用点 — hyperframes init/doctor/add/lint/check/snapshot/preview/render 均在 SKILL.md 出现；ffmpeg/ffprobe 在 locate.mjs 与 bake-basemap.mjs 的 execFileSync/spawnSync 可验；瓦片 URL 与 CDN 在 bake-basemap.mjs:106-119 与 :153 原文；gsap CDN 在 samples HTML 原文；media-use resolve 在 guide.md 原文。
[unlocatable] 验证：视觉定位协议的准确率声明是否可在源码内定位 — PROTOCOL.md 给出的误差数字（弱模型 16–24%、网格循环 3–4%、'eyeballing 6.5% → this protocol 2.3%'）引用的是一项测量结论，源码内无复现脚本或数据文件；本次为只读侦查且不得运行构建/渲染，故不验证这些数值，仅作为『文档声明』记录，不在结论中当作已核事实使用。

6Verdict & Scenarios

Clear, extensible taxonomy: branched by search requirements with isolated category modules (module.md) and trivial two-line registration.

Asset-first and reuse-first disciplines eliminate common bottlenecks like designing without assets or scaffolding templates from scratch.

Deterministic visual grounding via discrete grid strips and visual verification instead of speculative model regression.

Explicitly designed network access for map assets ensuring determinism and offline reproducibility rather than hidden runtime rendering requests.

Disciplined remediation: capped at a single in-place fix without duration masking, supported by state-driven resume tables.

Justified autonomous pipeline reducing friction for short-form content where manual review checkpoints yield minimal returns.

Best for: Ideal for single short motion graphic assets (typically under 10s, up to ~30s) without voiceover or live-action footage: kinetic typography titles, stat/metric callouts, chart data visualizations, logo reveals/brand lockups, lower-thirds/callouts/social overlays, animated maps, tweet/news headline cards, webpage/UI product walkthroughs, and asset-fusion charts. Also suitable for generating transparent overlays (webm/mov) for post-production compositing, and for users who prefer an autonomous workflow (at most one question) with a final render decision.

Not for: Not suitable for: 1) Videos longer than ~30s, narrated, or multi-scene projects (use /general-video); 2) Live-action footage or on-camera human presenters; 3) Pure caption generation (use /embedded-captions or talking-head-recut pipelines); 4) Windows or non-x64 environments (due to prerequisites); 5) Strictly offline environments lacking search capabilities (search-driven categories fail to retrieve assets, rendering asset-fusion unusable); 6) Users unwilling to send visual frames to Google APIs (auto locate path should be avoided in favor of local grid sweeps); 7) Commercial workflows requiring strict copyright clearance (provenance is logged without license validation).

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload motion-graphics.tar.gz

sha256: 7966ceeccd29cbdd…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit b8328f9573.