Content & Media Creation · heygen-com/hyperframes
remotion-to-hyperframes
Port an existing Remotion (React) composition's source to HyperFrames HTML. Use ONLY on an explicit ask to port/convert/migrate/translate a Remotion source — one-way, Remotion-only. A passing Remotion mention, reference-only code, or "make something like my Remotion video" is a fresh build (/general-video). Unclear → /hyperframes.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite FileDual-pass Audit
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
Run static linting first to determine translatability: A script scans Remotion source code against rules, categorizing findings into three levels: blocker (refuse translation and recommend runtime interop instead), warning (drop the construct and proceed with translation, logging the gap in TRANSLATION_NOTES.md), and info (translate and note).
skills/remotion-to-hyperframes/scripts/lint_source.py
Blockers (skill should refuse to translate): - r2hf/use-state React state machine drives animation - r2hf/use-effect-deps useEffect/useLayoutEffect with non-empty deps (side effects) - r2hf/use-reducer useReducer drives animation - r2hf/async-metadata calculateMetadata returns a Promise - r2hf/third-party-react-ui Imports a React UI library (shadcn, mui, antd, mantine, chakra)
What this is doing: Shifting the detection of "which Remotion patterns cannot be deterministically represented in HF's seek-driven model" upfront into an executable static check. Hitting a blocker stops execution immediately, redirecting to references/escape-hatch.md with recommendations for PR #214 runtime interop; warnings do not block translation. The script itself performs only text/regex analysis (imports only argparse/json/re/sys/dataclasses/pathlib) and never executes the scanned code.
Translation follows mechanical mapping + on-demand loading of topical references: api-map.md serves as an index, loading only the topic references matching APIs present in the source (parameters/sequencing/timing/media/transitions/lottie/fonts) rather than reading everything at once.
skills/remotion-to-hyperframes/SKILL.md
Translate Remotion (React-based) video compositions into HyperFrames (HTML + GSAP) compositions. Most Remotion idioms have direct HyperFrames equivalents — the translation is mechanical for ~80% of typical compositions. This skill encodes the mapping and guards against the lossy 20% by refusing to translate patterns that don't fit HF's seek-driven model
What this is doing: The author explicitly notes that ~80% can be mechanically translated while 20% involves lossiness—explicitly stating uncertainties and handling that 20% via "rejection + recommendation" rather than forcing out broken HTML.
Fixed output structure: A single <div id="stage"> carrying data-* attributes for composition-id/start/duration/fps/dimensions and scalar props, flat scene divs with data-start/data-duration/data-track-index, and a paused GSAP timeline at the bottom registered to window.__timelines.
skills/remotion-to-hyperframes/SKILL.md
A single `<script>` tag at the bottom containing one paused `gsap.timeline({paused: true})`. Every Remotion `useCurrentFrame()` derivation becomes a tween on this timeline at the right offset. - `window.__timelines["<composition-id>"] = tl;` registers the timeline with HF's runtime.
What this is doing: Replacing React's "per-frame re-evaluation" paradigm with a "tweens on a paused timeline" paradigm—the exact root cause of why useState/useEffect-driven animations cannot be translated (as they are not frame-deterministic).
Verification is quantifiable SSIM rather than "looks right": Bundled 4-tier test corpora (T1–T4) provide average SSIM and baseline thresholds, requiring matching pixel formats across both renders to avoid measuring encoder discrepancies.
skills/remotion-to-hyperframes/SKILL.md
Threshold: ~0.02 below `p05` of the source's complexity tier (see `eval.md`'s validated thresholds table). If the diff fails, run [`scripts/frame_strip.sh`](scripts/frame_strip.sh) to see _which_ frames diverged, then re-read the relevant timing/sequencing/media reference.
What this is doing: Turning "translation fidelity" into a regressible metric. Baseline table (2026-04-27): T1 single-element fade-in 0.974 / threshold 0.95; T2 multi-scene + spring + audio + image 0.985 / 0.95; T3 data-driven + custom subcomponents + counter 0.953 / 0.90; T4 eight lint escape cases 8/8 pass. The section also highlights a critical pitfall: 'both renders must use matching pixel format' (omitting png + bt709 will introduce a ~0.05 SSIM encoder discrepancy).
Dedicated difference debugging tools: frame_strip.sh generates side-by-side "baseline | translated" comparison strips to pinpoint diverging frames; render_diff.sh outputs frame-by-frame SSIM and writes summary.json (mean/min/p05/p95/frame_count/pass).
skills/remotion-to-hyperframes/scripts/render_diff.sh
# render_diff.sh — compute per-frame SSIM between two video files. # # The eval primitive for the remotion-to-hyperframes skill: given a Remotion # render and a HyperFrames render of the same composition, report whether the # translation is visually equivalent.
What this is doing: Breaking down "looks similar" into an actionable diagnostic chain—first evaluate failure via p05/mean, locate the exact frame using film strips, then consult corresponding topical references (timing/sequencing/media) to fix it.
All gaps must be documented: Any construct not cleanly translated (volume ramps, custom presentations, font substitutions) must be recorded in TRANSLATION_NOTES.md alongside the HF output; explicitly declares what this skill does not do (reverse exports, non-Remotion sources, React state machines, running parallel render pipelines with Remotion).
skills/remotion-to-hyperframes/SKILL.md
Anything that didn't translate cleanly (volume ramps dropped, custom presentations approximated, fonts substituted) gets a `TRANSLATION_NOTES.md` written next to the HF output.
What this is doing: Preventing "silent lossiness"—lossy conversions must be explicitly tracked. It also clarifies decision boundaries (e.g., @remotion/lambda is not a blocker since it pertains to deployment rather than animation) to avoid false rejections.
2Core Capabilities
01One-way source porting from Remotion → HyperFrames (strictly this direction only)
02Executable translatability linting (3-tier findings + line/column + rule id + suggestions; supports --json)
03API topic mapping index (Composition/Sequence/Series/Loop/Freeze/useCurrentFrame/interpolate/spring/Audio/Video/Img/IFrame/staticFile/TransitionSeries/lottie/google-fonts…)
04Tiered test corpora + SSIM regression baselines (T1 single-element fade-in / T2 multi-scene + spring + audio + image / T3 data-driven + subcomponents / T4 eight lint escape cases)
05Discrepancy localization tools: side-by-side frame strips (frame_strip.sh) and per-frame SSIM reports (render_diff.sh, including p05 and pass/fail verdict)
06Self-testing/smoke testing: Script layer verifies harness output validity without requiring real Remotion or HF pipelines (uses ffmpeg testsrc to generate synthetic input)
07Rejection and recommendation paths: Recommends PR #214 runtime interop upon hitting blockers instead of emitting broken HTML
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | hyperframes CLI（渲染翻译产物：npx hyperframes render --skill=remotion-to-hyperframes） |
| cli | Remotion CLI（生成基准渲染：npx remotion render <CompositionId> out/baseline.mp4） |
| cli | ffmpeg / ffprobe（SSIM 比较、帧抽取、条带拼图；脚本缺它即 exit 2） |
| cli | python3（lint_source.py 与 frame_strip.sh 内嵌的 python 片段） |
| package | HF 侧可选包（shader-transitions / lottie 适配器等，由 api-map 引用；HF 侧的 blocks 目录） |
| network | 文档外链（仅参考；fonts.md 里的 Google Fonts 预连接示例属于产出 HTML 的写法，非本 skill 调用） |
| cli | hyperframes skills update（自刷新，需网络） |
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/: Executes local script or command: python3 scripts/lint_source.py <remotion-src> [--json] (statically analyzes text in scanned directory; does not execute scanned code)
- 本地工作目录: File read/write & artifact output: Translation artifacts: hf-src/index.html (HF composition) and TRANSLATION_NOTES.md
Audit Notes: The behavioral surface is clean and verifiable: all scripts are local utilities (python3 static linter + ffmpeg/ffprobe SSIM calculation and strip generation) that only read and write local files. The entire directory involves zero network calls, zero credential reading, and zero external package downloads (no pip/npm install). The only environment requirements are ffmpeg/ffprobe and (user-executed) npx render commands. It avoids Yellow because it performs no external egress; it avoids Green because it does execute local scripts and performs file reads on user source directories as well as writing artifacts. Note: The user's Remotion source directory is read (the model inspects it to generate translations), and test corpora contain fetch examples (used solely as lint test inputs, never executed).
5Second-Pass Verification
- [ok] 是否真的零网络 / 零凭证（蓝档判定的关键） — 脚本层 fetch/curl/wget/http.request 0 命中；process.env 命中仅 3 处且在 tier-4 的 validate.sh 里读路径变量；无 API_KEY/TOKEN/SECRET/.env/Bearer 命中。27 处 URL 全部可解释为文档链接、示例 HTML 资源或测试夹具端点。
- [ok] 测试夹具里的 fetch / example.com 是否会被执行（是否构成隐藏外发） — 逐文件确认：tier-4 的 8 个 .tsx 与 scripts/tests/fixtures/*.tsx 只被 lint_source.py 以文本方式扫描（脚本无 subprocess/无 import 被扫描模块），run.sh 的 T4 分支只跑 lint 校验（'It runs T1, T2, T3 (render + diff) and T4 (lint validation)'）。不会被渲染或执行，因此不构成外发。
- [ok] 『外部资源』逐条回查调用点 — npx remotion render 与 npx hyperframes render 在 SKILL.md Step 4 原文；ffmpeg/ffprobe 的存在性检查与调用在 render_diff.sh/frame_strip.sh 原文；python3 调用在 frame_strip.sh 原文；shader-transitions 与 lottie 适配器链接在 api-map.md/lottie.md 原文。无推测项。
- [ok] lint 规则是否真能拦住它宣称拦的东西（blocker 是否只是文档口号） — lint_source.py 的 docstring 与 THIRD_PARTY_UI_PACKAGES 集合、rule id（r2hf/use-state、r2hf/use-effect-deps、r2hf/use-reducer、r2hf/async-metadata、r2hf/third-party-react-ui 等）在源码中真实存在，并配有 8 个 tier-4 用例与 validate.sh 断言（'8/8 pass' 基线）。规则实现与文档口径一致。
- [unlocatable] 验证：SSIM 阈值基线表是否可在源码内复算 — SKILL.md 的基线表（T1 0.974、T2 0.985、T3 0.953、T4 8/8，日期 2026-04-27）是历史测量值；复算需要执行 Remotion 与 HF 两条渲染管线（本任务禁止构建/渲染，且环境未验证具备 Remotion）。故该表按『文档声明』记录，不在结论中当作已验证事实。
- [ok] meta.official_desc 与 SKILL.md 原文的逐字比对（体检工具的 ⚠ 项） — 本 skill 的 frontmatter 用 YAML 单引号风格书写：`description: 'Port an existing Remotion (React) composition''s source to …'`——文件里的两个连续单引号是 YAML 的转义语法，解析后的字符串值是带**一个**撇号的 `composition's`。本 JSON 的 meta.official_desc 记录的是解析后的真实描述文本（与 YAML 解析结果一致），因此对**原始文件字节**做朴素逐字比对时会出现一处不可避免的差异（源码里的 `composition''s` vs 记录值的 `composition's`）。这不是改写，也不影响展示层：如实记录为报告口径差异，而非内容出入。
6Verdict & Scenarios
Best for: Ideal for projects with existing Remotion (React) composition source code and an explicit requirement to port it to HyperFrames HTML. Especially suitable for teams needing regressible verification—this skill provides 4-tier test corpora and SSIM thresholds to integrate translation fidelity into CI or manual regression testing. Also fit for evaluating whether a given Remotion codebase is translatable (running lint_source.py yields an immediate list of blockers and warnings).
Not for: Not suitable for: ① Creating new HyperFrames projects from scratch (even with a similar Remotion video on hand) — use /general-video instead; ② Loose requests like "make something like my Remotion video" (description mandates treating this as a fresh build); ③ Reverse export (HF → Remotion or other frameworks); ④ Non-Remotion sources (After Effects .aep, Framer Motion, pure React/CSS); ⑤ State-machine-driven Remotion compositions (hits blocker; should use runtime interop instead); ⑥ Scenarios where render-level eval is skipped—without running evaluations, correctness cannot be verified.
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload remotion-to-hyperframes.tar.gz
sha256:
Option B · Copy Guide for Agent7dc73746cff19b96…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit b8328f9573.