HyperFrames 核心
输出框架为 Remotion。 一个合成组件是一个使用 <Composition> 注册的 React 组件树;当前帧是唯一的时钟;媒体播放归属于 Remotion 的 <Video> / <Audio> 组件,而非 DOM。
本技能是 技术合约:如何构建一个项目。以下正文为构建指南;各主题详情存在于 references/ 中,按需阅读。其他关注点位于同属的领域技能中:hyperframes-animation,hyperframes-creative,media-use,hyperframes-cli,hyperframes-registry。/hyperframes 中的能力图指明了每个技能涵盖的内容。
移植说明。 此合约取代了旧的 HTML +
data-*+ 暂停的 GSAP 时间线合约。如果你发现某个项目的index.html带有data-composition-id/data-start/data-duration,或者有描述window.__timelines的参考文件,说明你正在查看旧合约。在操作之前请阅读references/legacy-html-contract.md。
参考文件
| 文件 | 阅读目的… |
|---|---|
references/minimal-composition.md | 从最小的可渲染项目骨架开始 |
references/project-structure.md | 布局 src/,将场景拆分为组件,决定单体式还是模块化 |
references/timing.md | 将秒转换为帧,放置 <Sequence>,使用 <Series> / <TransitionSeries>,相对其他场景计时 |
references/layers-and-order.md | 堆叠图层,控制 z 轴顺序,在同一个时间段内重叠两个场景 |
references/props-and-schemas.md | 声明 props,编写 Zod schema,连接 defaultProps 和 calculateMetadata |
references/media.md | 放置 <Video> / <OffthreadVideo> / <Audio> / <Img>,裁剪,设置音量,使用 staticFile |
references/determinism-rules.md | 保持渲染可寻址和可重现;禁止项;通过 delayRender 实现的异步资源加载 |
references/editing-recipes.md | 裁剪/修整/重新排序/重新计时/冻结/相机/遮罩/交叉淡入淡出/音频操作及其限制 |
references/legacy-html-contract.md | 识别并迁移仍基于旧 HTML + data-* 合约的项目 |
references/tailwind.md | 在 Tailwind v4 项目中工作 |
references/storyboard-format.md | 编写 STORYBOARD.md 计划(+ 解析后的清单) |
references/review-loop.md | 在活板子上运行计划 → 草图 → 构建审查流程 |
references/production-loop.md | 将已批准的计划转化为交付的视频 |
references/brief-contract.md | 简要的规则:模式推导、共享字段登记、问题不变性 |
references/brief-format.md | 编写 BRIEF.md |
references/script-format.md | 编写可选的 SCRIPT.md 锁定旁白 |
references/subagent-dispatch.md | 将子代理调度动词映射到你的 harness |
references/frame-worker-core.md | 共享的帧工作角色合约 |
关于动画细节(弹簧配置、缓动函数、运行时适配器),请参考 hyperframes-animation。
构建合成
项目的形状
package.json # remotion, react, react-dom;studio/render 的脚本
remotion.config.ts # 渲染时配置(编解码器、图像格式、Tailwind/webpack 覆盖)
tsconfig.json
public/ # staticFile() 解析的所有内容
src/
index.ts # registerRoot(Root)
Root.tsx # 每个 <Composition> 都位于此处
<名称>/
index.tsx # 合成的顶层组件
scenes/*.tsx # 每个场景一个组件
schema.ts # Zod schema + 推断的 props 类型
src/index.ts 是入口点,仅做一件事:
import { registerRoot } from "remotion";
import { Root } from "./Root";
registerRoot(Root);
注册合成
每个可渲染的东西都是 Root.tsx 中的一个 <Composition>。id 是 CLI 按名称渲染的内容。
import { Composition } from "remotion";
import { LaunchVideo } from "./LaunchVideo";
import { launchSchema } from "./LaunchVideo/schema";
const FPS = 30;
export const Root: React.FC = () => (
<>
<Composition
id="launch"
component={LaunchVideo}
durationInFrames={45 * FPS}
fps={FPS}
width={1920}
height={1080}
schema={launchSchema}
defaultProps={{ productName: "Acme", accent: "#5B8CFF" }}
/>
</>
);
durationInFrames 是渲染长度。它是 帧,而非秒,弄错这一点是最常见的创作错误。从命名的 FPS 常量派生,而不是直接写 1350。
帧是唯一的时钟
每个动画值都是 useCurrentFrame() 的纯函数。这是使渲染可寻址的合约:渲染器跳转到第 812 帧并必须获得与逐帧播放相同的像素。
import { AbsoluteFill, useCurrentFrame, useVideoConfig, interpolate, spring } from "remotion";
export const Title: React.FC<{ text: string }> = ({ text }) => {
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
const enter = spring({ frame, fps, config: { damping: 18 } });
const y = interpolate(enter, [0, 1], [40, 0]);
return (
<AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
<h1 style={{ opacity: enter, transform: `translateY(${y}px)` }}>{text}</h1>
</AbsoluteFill>
);
};
始终对映射帧范围的 interpolate 进行钳制,否则值会超出范围继续外推,导致淡入变成不透明度 4:
const opacity = interpolate(frame, [0, 15], [0, 1], {
extrapolateLeft: "clamp",
extrapolateRight: "clamp",
});
时间控制是 <Sequence>
<Sequence> 对其子组件进行时间偏移:在其内部,useCurrentFrame() 在序列自己的起始处返回 0。这种局部基准重算正是关键所在,因为场景组件永远不需要知道它在主时间轴上的位置。
<AbsoluteFill>
<Sequence durationInFrames={90}>
<Hook />
</Sequence>
<Sequence from={90} durationInFrames={150}>
<Feature />
</Sequence>
<Sequence from={240} durationInFrames={120}>
<Close />
</Sequence>
</AbsoluteFill>
对于连续的背靠背场景, <Series> 会自动计算偏移量,这样修改一个场景的持续时间就不会级联到手动修复后面所有的 from:
<Series>
<Series.Sequence durationInFrames={90}><Hook /></Series.Sequence>
<Series.Sequence durationInFrames={150}><Feature /></Series.Sequence>
<Series.Sequence durationInFrames={120}><Close /></Series.Sequence>
</Series>
<Series.Sequence offset={-15}> 将场景提前以重叠其前一个场景,这是无需算术即可获得交叉淡入淡出时间段的方法。完整细节以及用于基于演示的转场的 <TransitionSeries>,请参考 references/timing.md。
图层替代轨道
没有轨道索引。堆叠顺序是 <AbsoluteFill> 内的 DOM 顺序:后面的兄弟元素绘制在上面。一个画外音轨道、一个背景音乐和三个视觉场景就是五个兄弟元素。
<AbsoluteFill>
<Audio src={staticFile("music.mp3")} volume={0.18} />
<Audio src={staticFile("vo.mp3")} />
<Sequence durationInFrames={90}><Hook /></Sequence>
<Sequence from={90}><Feature /></Sequence>
<Overlay /> {/* 绘制在所有上述内容之上 */}
</AbsoluteFill>
<Sequence layout="none"> 会丢弃隐式的 <AbsoluteFill> 包装器。当子元素必须参与父元素的 flex 或 grid 布局而不是绝对定位时使用它。
媒体属于 Remotion
永远不要使用原生的 <video>、<audio> 或 <img> 标签。Remotion 的组件才能让渲染器确定性地进行寻址和提取帧。
| 需求 | 使用 |
|---|---|
| 渲染中的视频 | <OffthreadVideo src>(优先使用) |
| 需要 DOM 级别控制的视频 | <Video src> |
| 音频 | <Audio src volume trimBefore trimAfter> |
| 静态图像 | <Img src> |
| 嵌入页面 | <IFrame src> |
public/ 下的任何文件 | staticFile("dir/name.ext") |
<OffthreadVideo> 使用 FFmpeg 在浏览器外提取帧,对于渲染来说既更快也更准确;仅在需要真实元素时才使用 <Video>(例如,根据其 currentTime 驱动某些东西)。staticFile() 对于本地资源是强制性的。裸的 "/music.mp3" 字符串在 Studio 中有效,但在 Lambda 渲染中会失效。裁剪、音量渐变和播放速率详见 references/media.md。
Props 和 schema
合成输入是 React props,由 Zod schema 进行类型化,这样 Studio 可以为它们渲染可编辑控件,并且错误的 --props 负载会大声报错而不是渲染出错误结果。
import { z } from "zod";
import { zColor } from "@remotion/zod-types";
export const launchSchema = z.object({
productName: z.string(),
accent: zColor(),
features: z.array(z.object({ title: z.string(), body: z.string() })),
});
export type LaunchProps = z.infer<typeof launchSchema>;
当持续时间取决于 props 时(一个长度未知的特性列表,一个长度未知的音频文件),在 calculateMetadata 中计算它,而不是硬编码一个猜测值。参见 references/props-and-schemas.md。
不可协商的规则
类型检查无法捕获的静默错误。完整理由见 references/determinism-rules.md。
- 禁止墙钟。 不得使用
Date.now()、new Date()、performance.now()。时间来自useCurrentFrame()。 - 禁止非种子随机性。
Math.random()每帧给出一个不同的值,这会导致闪烁。使用 Remotion 的random(seed):相同的种子,相同的值,每帧和每次渲染都一致。 - 禁止状态驱动动画。
useState/useReducer/useEffect不得驱动任何视觉内容。渲染器会乱序并在并行工作进程中挂载帧;通过正向播放累积的状态不存在。应改为从frame派生。 - 禁止 CSS 动画、过渡或
requestAnimationFrame。 它们运行在浏览器自己的时钟上,而渲染器不会推进该时钟。所有这些都会渲染成冻结的第一帧。 - 使用
delayRender等待异步工作。 对于 fetch、字体、测量布局:在之前调用delayRender(),在之后调用continueRender(handle),否则帧会在工作完成前被捕获。 - 钳制你的插值。 未钳制的
interpolate会在输入范围之外进行外推。 - 对任何动画内容使用绝对定位。 在正常流中移动的转换元素会拖动其兄弟元素。
编辑现有合成
- 首先读取文件。保留无关的时间、props、id 和资源路径。
- 匹配现有的
Compositionid。CLI、任何渲染脚本和 CI 都通过 id 寻址合成。重命名它是一个破坏性变更。 - 添加场景:优先使用
<Series>以便偏移量自动重新计算。在手写偏移量的<Sequence>列表中,修正后面所有的from。 - 更改持续时间:同时检查
<Composition>上的durationInFrames。超过合成长度的场景会被静默截断。 - 添加组件:保持它是 props 和
frame的纯函数。
验证
命令详情见 hyperframes-cli。
-
npx tsc --noEmit,确保 schema 和 prop 类型实际匹配 - 在几个场景中间点执行
npx remotion still <id> out/probe.png --frame <n>,检查每个图像 - 执行
npx remotion studio供审查,以便用户自行擦洗和调整 props - 仅在用户批准后执行
npx remotion render <id>