用途:把已有的 Remotion(基于 React)视频合成转换为 HyperFrames(HTML + GSAP)合成。仅在用户明确要求移植、转换时使用。多数 Remotion 写法有直接对应,约 80% 的典型合成可机械翻译;对不适合 HyperFrames seek 驱动模型的模式会拒绝翻译,并建议采用 PR #214 的运行时互操作方案。
主要能力与流程:
- 源码检查:运行 scripts/lint_source.py 扫描 Remotion 源码目录。阻断项(拒绝并建议互操作):useState、useReducer、带非空依赖的 useEffect/useLayoutEffect、异步 calculateMetadata、第三方 React UI 库(MUI、Chakra、Mantine、antd、shadcn、Radix、NextUI)。警告项(丢弃该结构后翻译):@remotion/lambda 配置、delayRender、useCallback、useMemo、自定义 hooks。信息项(带注释翻译):staticFile、interpolateColors。出现阻断项即停止,阅读 references/escape-hatch.md 并给出建议。
- 规划翻译:阅读 references/api-map.md,按源码所用 API 加载对应主题参考(parameters、sequencing、timing、media、transitions、lottie、fonts),不必全部加载。
- 生成 HF 合成:输出 index.html,包含带 data-composition-id、data-start、data-duration、data-fps、data-width、data-height 及标量 prop 的根 div#stage;扁平场景 div 列表;内联样式;底部单个暂停的 gsap.timeline;通过 window.__timelines 注册时间线;自定义 React 子组件以内联重复 HTML 表达。
- 验证:分别渲染 Remotion 基线与 HF 翻译,用 scripts/render_diff.sh 做 SSIM 对比,阈值约为源复杂度档位 p05 以下 0.02。两次渲染须使用匹配像素格式(Config.setVideoImageFormat("png") 与 Config.setColorSpace("bt709")),否则差异来自编码器而非翻译保真度。
- 记录缺口:未干净翻译之处写入 TRANSLATION_NOTES.md。
适用场景:需要把 Remotion 合成迁移到 HyperFrames 的确定性逐帧渲染流程。
限制:不翻译 React 状态机(useState + useEffect 驱动的动画在 seek 模型下非确定性);不并行运行 Remotion 渲染管线(属运行时互操作方案)。@remotion/lambda 不是阻断项,仅作为警告丢弃。自带 T1–T4 测试语料,可用 ./assets/test-corpus/run.sh 自评。