HyperFrames 迁移指南：将 @remotion/lottie 组件翻译为 HF Lottie 适配器

HyperFrames 迁移指南：将 @remotion/lottie 组件翻译为 HF Lottie 适配器

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

本文是 HyperFrames（HF）项目 Remotion 迁移技能（remotion-to-hyperframes）的专题参考，讲解如何把基于@remotion/lottie的 React 组件翻译为 HyperFrames 的 HTML 组合。读完本文，你将掌握 lottie-web 与 dotlottie-web 两种播放器的接入方式、window.__hfLottie注册机制、资产处理流程，以及 HF 内建 Lottie 适配器在逐帧 seek、时长推断上的底层实现原理，从而以接近零成本的代价完成 Lottie 动画的迁移。

Lottie 是 Remotion 迁移中最"干净"的一类

在 HyperFrames 的 Remotion → HF 迁移工作流中，Lottie 动画被明确标注为"最容易翻译的部分"。原因是动画逻辑本身已经完全自包含：Lottie 文件（JSON 或二进制 .lottie）编码了自身确定性的时间线，无论是 Remotion 还是 HyperFrames，都不需要"驱动"它的动画——双方都只是把播放器 seek 到指定时间点而已。因此翻译成本接近零，几乎没有信息丢失。

这一判断有源码支撑：HyperFrames 核心包中内置了专用适配器createLottieAdapter，同时支持lottie-web与@lottiefiles/dotlottie-web两套播放器 API。适配器通过鸭子类型（duck typing）识别播放器实例，并自动发现注册在window.__hfLottie上的动画，逐帧调用goToAndStop完成 seek。

迁移前：Remotion 侧的典型用法

在 Remotion 项目中，Lottie 动画通常以如下方式嵌入：

import { Lottie } from "@remotion/lottie"; import animationData from "./hello.json"; export const MyComp = () => ( <AbsoluteFill> <Lottie animationData={animationData} loop={false} /> </AbsoluteFill> );

这里@remotion/lottie是一个 React 包装组件，通过 webpack 把hello.json打包进 bundle。翻译到 HyperFrames 后，这个 React 包装器被完全丢弃（见 API 映射表 中 Lottie 一节的映射规则），换成 HTML 容器 + 原生播放器脚本。

核心翻译模式：lottie-web

<Lottie>组件翻译为如下 HTML 结构：

<div id="stage" ...> <div id="lottie-anim" style="width:100%;height:100%"></div> <script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script> <script> const anim = lottie.loadAnimation({ container: document.getElementById("lottie-anim"), renderer: "svg", loop: false, autoplay: false, path: "assets/hello.json", }); window.__hfLottie = window.__hfLottie || []; window.__hfLottie.push(anim); </script> </div>

翻译的关键在于理解 HF 的运行时模型：HyperFrames 是seek 驱动（seek-driven）的确定性渲染模型，运行时通过适配器的seek(ctx)把组合的绝对时间写入各个动画引擎。这与 Remotion 的 React 渲染循环有本质区别，因此有三点与普通 Lottie 嵌入的关键差异：

• autoplay: false——HF 通过逐帧 seek 驱动播放，不允许播放器自行播放；
• loop: false（典型情况）——除非 Remotion 侧原本写了loop={true}；
• window.__hfLottie.push(anim)——这是把动画挂接到 HF 逐帧 seek 机制的关键注册步骤，缺失它适配器将无法定位到该实例。

注意：renderer: "svg"指定 SVG 渲染器，保证与 Remotion 中@remotion/lottie默认的 SVG 渲染一致，避免渲染差异（Remotion 的<Lottie>内部同样基于 lottie-web 的 SVG renderer）。

资产处理：JSON 文件落盘与路径引用

Remotion 通过 webpack import 把动画 JSON 打包进 bundle，而 HF 需要 JSON 以磁盘文件形式存在于assets/目录下，并通过路径引用。整个资产处理流程与媒体资源（media.md中staticFile的处理）一致：

1. 把hello.json从 Remotion 项目复制到hf-src/assets/；
2. 在loadAnimation中引用为path: "assets/hello.json"（相对组合index.html的路径）。

对于二进制的 dotlottie 格式（.lottie），则切换到@lottiefiles/dotlottie-web：

<script src="https://unpkg.com/@lottiefiles/dotlottie-web"></script> <canvas id="anim" style="width:100%;height:100%"></canvas> <script> const player = new DotLottie({ canvas: document.getElementById("anim"), src: "assets/hello.lottie", autoplay: false, }); window.__hfLottie = window.__hfLottie || []; window.__hfLottie.push(player); </script>

这里渲染目标从div换成了canvas（dotlottie-web 默认走 canvas 渲染），其余注册逻辑完全一致。HF 适配器对两套播放器 API 做了统一处理：它会鸭子类型检测实例上是否存在goToAndStop（lottie-web）、setCurrentRawFrameValue/seek（dotlottie-web 不同版本），从而决定调用哪条 seek 路径。

多个 Lottie 动画：全部注册、同步 seek

一个组合中可以有多个<Lottie>实例，翻译时逐个 push 到window.__hfLottie即可，适配器会同步 seek 全部实例：

window.__hfLottie.push(anim1); window.__hfLottie.push(anim2); window.__hfLottie.push(anim3);

这一行为在适配器源码中有明确注释与实现：seek阶段会遍历__hfLottie数组中的每个实例逐个 seek（lottie.ts），并且对单个实例的 seek 失败做了容错——swallow("runtime.adapters.lottie.site2", err)后继续处理其余实例，不会因为一个动画报错而中断整个组合的渲染。

源码级原理：HF Lottie 适配器的工作机制

理解翻译产物如何被 HF 运行时消费，是写出正确迁移代码的前提。适配器实现了RuntimeDeterministicAdapter接口，核心能力如下：

discover：自动发现与去重

discover()尝试通过全局lottie对象自动发现动画：如果页面中存在lottie.getRegisteredAnimations()（lottie-web 提供的注册表 API），就把它返回的实例并入__hfLottie，并用Set去重，避免重复注册（lottie.ts）。这意味着即使你的组合忘记手动push，只要通过lottie.loadAnimation创建了动画，适配器仍能在 discover 周期中把它纳入管理。单元测试覆盖了自动发现与"不重复已有实例"两个分支（lottie.test.ts）。

seek：按播放器类型分派

seek(ctx)接收组合绝对时间（秒），对每个注册实例分派：

• lottie-web：调用anim.goToAndStop(time * 1000, false)——以毫秒为单位的绝对时间；
• dotlottie-web v2+：存在setCurrentRawFrameValue时，用frame = time * fps计算原始帧号，并钳制到totalFrames - 1；
• dotlottie-web v1：只有seek方法时，把时间换算成 0–100 的百分比(time / duration) * 100，并钳制到 100。

其中"时间 × fps → 帧号"以及百分比换算，在测试中有精确断言：例如totalFrames: 60, frameRate: 30的播放器在time: 1时收到setCurrentRawFrameValue(30)；time: 10时被钳制为 59（lottie.test.ts）。负时间被统一钳制为 0。

pause 与 revert

pause()对两类播放器调用各自的pause()方法；revert()则刻意不清空__hfLottie——动画对象归组合所有，交给垃圾回收自然处理即可（lottie.ts）。

getInferredDurationSeconds：时长自动推断

非 GSAP 运行时（CSS、WAAPI、Lottie）没有window.__timelines条目，组合总时长要么由根元素data-duration显式声明，要么由适配器通过getInferredDurationSeconds()推断。Lottie 适配器会遍历所有实例，取其中最长的时长（lottie-web 用totalFrames / frameRate，dotlottie 优先用duration字段，缺失时回退到帧数计算），并返回null表示"无可用推断"（lottie.ts）。

这里有一个值得注意的细节：尚未加载完成的动画会报告totalFrames = 0，此时适配器返回null而非 0——因为"仍在加载"不能等同于"时长真的为零"，后续 discover 周期会拿到真实值。运行时把该返回值并入时长下限（见RuntimeDeterministicAdapter接口对getInferredDurationSeconds的说明），从而让根元素的data-duration变为可选。测试覆盖了"取多个实例的最大值"（30 帧 + 300 帧 → 10 秒）与"未加载返回 null"两个场景（lottie.test.ts）。

After Effects → Lottie 的功能限制

Lottie 只支持 After Effects 功能的一个子集。表达式（Expressions）、大多数 Effects（如投影 drop shadow、颜色覆盖 color overlay）、除 Normal/Add/Multiply 之外的所有混合模式、luma matte（亮度遮罩）、以及大部分 3D 参数都不被支持。

这一点对迁移决策至关重要：如果 Remotion 组合使用的 Lottie 文件依赖了上述特性，动画在Remotion 和 HF 中都会表现异常——这不是翻译问题，而是 Lottie 格式本身的限制。完整支持特性清单可参考 Lottie 官方（airbnb/lottie）的 after-effects.md 文档，迁移前先核对源文件的特性使用情况，可以避免在渲染阶段才发现"两边都坏了"的尴尬。

循环行为与播放速率

Remotion 的loop={true}让动画持续循环播放。翻译时，务必在检查过生成的帧之后，再决定是否把loop选项传给播放器。原因在适配器的 seek 语义里：HF 适配器 seek 的是组合的绝对时间，它不会在播放器之上叠加取模循环（modulo looping）或播放速率缩放（playback-rate scaling）。

因此：

• 如果确实需要精确的重复循环，或非默认的播放速率，应把时序烘焙进 Lottie 资产本身，或者围绕 Lottie 图层手写一条显式时间线；
• 无论哪种方式，都要验证渲染输出是否符合预期。

例如loop={true}的<Lottie>翻译时，可以先按loop: false输出并渲染检查帧，再依据实际表现决定是否在播放器层开启循环，避免出现"适配器 seek 到组合末尾之后动画又自行循环"这类难以排查的时序问题。

性能注意点：毫秒级 seek 精度

性能层面有一条来自适配器文档的硬核提示：lottie-web 的goToAndStop(time, isFrame=false)第二参数传false时，第一个参数的单位是毫秒；适配器为此传入time * 1000以获得更高精度。这比直接传帧号更准确——尤其当动画内部 fps 与 HF 渲染 fps 不一致时，帧号换算会产生累积偏差，而毫秒时间戳可以精确对齐组合绝对时间（lottie.ts的注释明确写了这一设计意图）。

迁移验证

翻译完成后，遵循技能工作流（SKILL.md）的验证步骤：用npx hyperframes render渲染 HF 组合，与 Remotion 基线渲染做 SSIM 差异对比（阈值约在源复杂度层级 p05 之下 0.02），差异过大时用frame_strip.sh定位分帧分歧。由于 Lottie 动画时间线自包含、双方都只是 seek，Lottie 场景通常能直接达到高质量基线，是迁移中最省心的环节。

小结

Lottie 迁移的完整心法可以浓缩为四步：

1. 丢弃@remotion/lottieReact 包装器，改用 CDN 引入的lottie-web（或@lottiefiles/dotlottie-web）原生脚本；
2. 把动画 JSON / .lottie 文件复制到hf-src/assets/，以相对路径引用；
3. 关闭autoplay，把每个实例 push 进window.__hfLottie；
4. 依据渲染帧检查确认loop与播放速率行为，必要时把时序烘焙进资产。

掌握这套模式后，配合 HF 适配器的自动发现、毫秒级 seek 与时长推断能力，Lottie 动画从 Remotion 到 HyperFrames 的迁移几乎可以做到"零翻译成本"。源码入口见 适配器实现 与其 单元测试，本技能完整参考位于 lottie.md。

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes