json-render Remotion 渲染器实战:用 JSON 时间线规格驱动 AI 视频生成
json-render Remotion 渲染器实战:用 JSON 时间线规格驱动 AI 视频生成
导读
@json-render/remotion 是 json-render(The Generative UI framework)框架中面向视频领域的渲染器,其核心使命是把"JSON 时间线规格(Timeline Spec)"直接转换为 Remotion 视频合成(composition)。本文将以 skills/remotion/SKILL.md 为主线,结合 packages/remotion 包源码与 examples/remotion 完整示例,系统讲解时间线规格结构、标准组件与转场、自定义组件扩展、声明式 motion 动画系统、以及如何用 AI 生成视频时间线。读完本文,你将能够独立搭建一个"用户描述一句话 → AI 输出受约束的 timeline JSON → Remotion 实时渲染预览"的完整视频生成链路。
一、设计思想:为什么视频渲染器需要完全不同的 Spec
json-render 的核心理念是 "JSON to render"——Spec 格式与组件完全由各渲染器自由定义。React 渲染器使用嵌套的元素树(Element tree),而 Remotion 渲染器采用完全不同的时间线(Timeline)模型:
| 维度 | @json-render/react | @json-render/remotion |
|---|---|---|
| Spec 格式 | 嵌套组件元素树 | 时间线(tracks + clips) |
| 组件类型 | UI 组件(Button、Card) | 视频组件(场景、覆盖层) |
| 时序机制 | 用户交互事件 | 基于帧(frame)的动画 |
| 输出目标 | React DOM | Remotion 视频 |
这一差异在 packages/remotion/src/schema.ts 中被明确注释:"This schema is fundamentally different from the React element tree schema. It's timeline-based, designed for video composition",并以此证明 json-render 是真正的渲染器无关(agnostic)框架。
二、安装与快速上手
2.1 安装依赖
npm install @json-render/remotion @json-render/core remotion @remotion/player zod
四个核心依赖各司其职:@json-render/remotion 提供渲染器与标准组件;@json-render/core 提供 defineCatalog 等目录构建能力;remotion 与 @remotion/player 负责实际渲染与浏览器内播放;zod 用于定义组件 props 的校验与类型推导。
2.2 第一步:定义视频目录(Catalog)
import { defineCatalog } from "@json-render/core";
import {
schema,
standardComponentDefinitions,
standardTransitionDefinitions,
standardEffectDefinitions,
} from "@json-render/remotion";
export const videoCatalog = defineCatalog(schema, {
components: standardComponentDefinitions,
transitions: standardTransitionDefinitions,
effects: standardEffectDefinitions,
});
这里的 schema 是 Remotion 专属的时间线 schema(见 packages/remotion/src/schema.ts),它规定了 AI 生成的 spec 长什么样、目录必须提供什么。目录(catalog)是 json-render 的关键抽象:它把"组件清单 + 约束 + 提示词模板"打包成一份可由 AI 消费的能力契约。
2.3 第二步:用 Player 渲染预览
import { Player } from "@remotion/player";
import { Renderer, type TimelineSpec } from "@json-render/remotion";
function VideoPlayer({ spec }: { spec: TimelineSpec }) {
return (
<Player
component={Renderer}
inputProps={{ spec }}
durationInFrames={spec.composition.durationInFrames}
fps={spec.composition.fps}
compositionWidth={spec.composition.width}
compositionHeight={spec.composition.height}
controls
/>
);
}
Renderer(实现见 packages/remotion/src/components/Renderer.tsx)是连接 JSON spec 与 Remotion 运行时的心脏:它把 composition 配置映射为 Player 的播放参数,把每个 clip 包装进 Remotion 的 <Sequence> 中按帧播放。
三、Timeline Spec 结构详解
3.1 完整字段定义
SKILL.md 给出了一个最小示例,而包内 README 与源码类型(packages/remotion/src/components/types.ts)提供了完整字段语义:
{
"composition": {
"id": "intro-video",
"fps": 30,
"width": 1920,
"height": 1080,
"durationInFrames": 300
},
"tracks": [
{ "id": "main", "name": "Main Video", "type": "video", "enabled": true },
{ "id": "overlay", "name": "Overlays", "type": "overlay", "enabled": true }
],
"clips": [
{
"id": "clip-1",
"trackId": "main",
"component": "TitleCard",
"props": {
"title": "Welcome",
"subtitle": "To the future",
"backgroundColor": "#1a1a2e",
"textColor": "#ffffff"
},
"from": 0,
"durationInFrames": 90,
"transitionIn": { "type": "fade", "durationInFrames": 15 },
"transitionOut": { "type": "fade", "durationInFrames": 15 }
}
],
"audio": { "tracks": [] }
}
3.2 各字段语义与约束
composition:全局画布配置。fps固定为 30 帧/秒(1 秒 = 30 帧,10 秒 = 300 帧),width/height决定视频分辨率,durationInFrames为总时长。tracks:时间线轨道(类似剪辑软件中的图层)。type支持"video" | "audio" | "overlay" | "text",enabled控制轨道是否显示。从 Renderer 的实现看,主内容放在main轨道,覆盖层(LowerThird、TextOverlay 等)放在overlay轨道——两个轨道在渲染时分层叠放(Renderer.tsx)。clips:放置到时间线上的片段。关键字段:component:来自 catalog 的组件名,必须与目录定义一一对应;props:组件专属属性,由 catalog 中的 Zod schema 约束;from:起始帧号;durationInFrames:持续帧数;transitionIn/transitionOut:入场/出场转场,type必须是 catalog 中注册的转场名;motion:声明式动画配置(见下文专节)。
audio:音频轨道,每个音轨包含src、from、durationInFrames、volume等字段。
从源码可以看出 main 轨道的 clip 按顺序衔接(后一个 from = 前一个 from + durationInFrames),这是 AI 生成 prompt 中的硬性规则之一。
四、标准组件与标准转场
4.1 标准组件一览
SKILL.md 的组件表对应到源码中的两处:运行时组件(packages/remotion/src/components/standard.tsx)与目录定义(packages/remotion/src/catalog.ts)。完整清单与关键 props:
| 组件 | 类型 | 用途 | 关键 Props |
|---|---|---|---|
TitleCard |
scene | 全屏标题卡,适合片头/片尾/章节分隔 | title、subtitle、backgroundColor、textColor(默认深底 #1a1a2e 白字) |
TypingText |
scene | 终端风格逐字打字动画,适合代码演示 | text、charsPerSecond(默认 15)、showCursor、cursorChar、fontFamily |
ImageSlide |
image | 全屏图片展示 | src、alt、fit(cover/contain)、backgroundColor |
SplitScreen |
scene | 左右双栏对比 | leftTitle、rightTitle、leftColor、rightColor |
QuoteCard |
scene | 引言卡片 | quote、author、transparent(叠加图片时设 true) |
StatCard |
scene | 大号数字统计展示(自带数字滚动动画) | value、label、prefix、suffix |
TextOverlay |
overlay | 居中/顶部/底部文字覆盖层 | text、position(top/center/bottom)、fontSize(small/medium/large) |
LowerThird |
overlay | 人名/头衔字幕条 | name、title |
LogoBug |
overlay | 角落 Logo 水印 | position(四个角落)、opacity(默认 0.5) |
VideoClip |
video | 视频文件播放 | src、startFrom、volume |
每个组件的默认时长(defaultDuration)定义在 catalog 中,例如 TitleCard 默认 90 帧(3 秒)、ImageSlide 默认 150 帧、TypingText 默认 180 帧,生成时会被写进 AI 提示词作为参考。
4.2 标准转场一览
转场定义在 catalog.ts,运行时由 useTransition 钩子实现(hooks.ts):
| 转场 | 默认帧数 | 效果说明 |
|---|---|---|
fade |
15 | 淡入淡出 |
slideLeft |
20 | 从右向左滑入(前进感) |
slideRight |
20 | 从左向右滑入(后退感) |
slideUp |
15 | 从下向上滑入(覆盖层出现) |
slideDown |
15 | 从上向下滑入(覆盖层消失) |
zoom |
20 | 缩放强调(入场 0.8→1,出场 1→1.2) |
wipe |
15 | 水平擦除切换 |
none |
0 | 硬切,无转场 |
4.3 渲染器内部工作方式
Renderer 的渲染流程值得注意(Renderer.tsx):
- 合并组件注册表:
{ ...standardComponents, ...customComponents },自定义组件同名可覆盖标准组件; - 无 clips 时渲染空态提示;
- 将 clips 按
trackId拆分为main与overlay两组,先渲染主轨道再渲染覆盖层; - 每个 clip 包一层
<Sequence from={clip.from} durationInFrames={...}>实现时间切片; - 每个 clip 再包一层
ClipErrorBoundary——单个 clip 渲染出错只影响该片段(渲染null并打印错误日志),不会拖垮整个合成。
五、自定义组件:从目录定义到运行时实现
5.1 定义自定义组件(目录侧)
在 defineCatalog 中扩展 standardComponentDefinitions,用 Zod 描述 props:
import { z } from "zod";
const catalog = defineCatalog(schema, {
components: {
...standardComponentDefinitions,
MyCustomClip: {
props: z.object({ text: z.string() }),
type: "scene",
defaultDuration: 90,
description: "My custom video clip",
},
},
});
目录定义中的 description 会被注入 AI 提示词(见 schema.ts 的组件枚举逻辑),defaultDuration 会以 [default: 90 frames] 的形式提示给模型。
5.2 实现组件(运行时侧)
import { Renderer, standardComponents, ClipWrapper } from "@json-render/remotion";
import type { Clip } from "@json-render/remotion";
function CustomOverlay({ clip }: { clip: Clip }) {
return (
<ClipWrapper clip={clip}>
<div style={{ backgroundColor: clip.props.color }}>
{clip.props.message}
</div>
</ClipWrapper>
);
}
const customComponents = {
...standardComponents,
CustomOverlay,
};
<Player
component={Renderer}
inputProps={{ spec, components: customComponents }}
// ...
/>;
所有标准组件的实现都遵循 { clip }: { clip: Clip } 的函数签名,Clip 类型包含 id、trackId、component、props、from、durationInFrames、transitionIn/Out、motion(见 types.ts)。用 ClipWrapper 包裹内容即可自动获得转场与 motion 动画,无需手写帧计算。
六、useTransition、useMotion 与 ClipWrapper:动画系统三件套
6.1 useTransition:转场样式计算
useTransition(clip, frame) 基于当前帧与 transitionIn/transitionOut 计算透明度、位移与缩放,内部使用 Remotion 的 spring 做缓动,出场阶段通过 Math.min 与入场样式做叠加(hooks.ts)。
6.2 useMotion:声明式 motion 系统
这是 SKILL.md 未展开但源码最富特色的部分。clip.motion 提供三种声明式动画,见 schema 定义(schema.ts)与实现(hooks.ts):
enter:从给定值动画到中性值(如{opacity: 0, y: 50}表示从透明下方进入),默认时长 20 帧;exit:从中性值动画到给定值(退场),默认时长 20 帧;spring:物理弹簧配置,damping(阻尼,默认 20)、stiffness(刚度,默认 100)、mass(质量,默认 1)——阻尼越低弹性越强:20=平滑,10=有弹性,5=非常弹;loop:循环动画,property可选"scale" | "rotate" | "x" | "y" | "opacity",easing可选"linear" | "ease" | "spring"(默认 ease,内部用正弦缓动实现无缝循环)。
典型 motion 配置示例(与 AI 提示词模板一致):
"motion": {
"enter": { "opacity": 0, "y": 30, "duration": 20 },
"spring": { "damping": 10 }
}
6.3 ClipWrapper:自动合成
ClipWrapper(ClipWrapper.tsx)把两套动画合成到同一个 AbsoluteFill 上,合成规则明确:透明度相乘、位移相加、缩放相乘、旋转仅来自 motion。因此转场与 motion 可以自由叠加而不互相覆盖。
七、AI 生成:从提示词到时间线 JSON
7.1 提示词模板与 JSONL Patch 协议
Remotion schema 内置了专属提示词模板 remotionPromptTemplate(schema.ts),它要求模型输出 JSONL(每行一个 JSON 对象)的 JSON Patch 操作来增量构建时间线,与 React 渲染器采用同一协议。示例输出:
{"op":"add","path":"/composition","value":{"id":"intro","fps":30,"width":1920,"height":1080,"durationInFrames":300}}
{"op":"add","path":"/tracks","value":[{"id":"main","name":"Main","type":"video","enabled":true},{"id":"overlay","name":"Overlay","type":"overlay","enabled":true}]}
{"op":"add","path":"/clips","value":[]}
{"op":"add","path":"/clips/-","value":{"id":"clip-1","trackId":"main","component":"TitleCard","props":{"title":"Welcome"},"from":0,"durationInFrames":90,"transitionIn":{"type":"fade","durationInFrames":15},"motion":{"enter":{"opacity":0,"y":50,"scale":0.9,"duration":25}}}}
{"op":"add","path":"/audio","value":{"tracks":[]}}
模板中的硬性 RULES(可在 catalog.prompt({ customRules }) 中追加自定义规则)包括:只输出 JSONL patch、必须先添加 /composition、fps 恒为 30、主轨道 clip 顺序衔接、覆盖层组件放 overlay 轨道等。
7.2 生成提示词
const systemPrompt = videoCatalog.prompt();
// 包含:组件描述与 props、转场类型、特效定义、时间线规格要求
调用 videoCatalog.prompt() 会基于目录内容动态生成一份完整提示词。示例项目 examples/remotion/lib/catalog.ts 演示了如何注入 customRules(如"图片用 Picsum 免费图源、随机参数区分不同图片")。
7.3 服务端入口与流式编译
examples/remotion/app/api/generate/route.ts 展示了服务端实现:以 getVideoPrompt() 为 system prompt,通过 streamText 流式调用模型;客户端 examples/remotion/app/page.tsx 则用 createSpecStreamCompiler 逐块解析 JSONL patch,边生成边把部分构建的 spec 交给 Player 实时预览——这正是"AI → json-render → Video"(示例站点主标题)的完整闭环。
7.4 服务端安全入口
对于 Server Component、API 路由等场景,包提供了 /server 子路径入口(packages/remotion/src/server.ts),只导出 schema 与目录定义,不携带任何 React/Remotion 运行时依赖:
import { schema, standardComponentDefinitions } from "@json-render/remotion/server";
示例项目的 catalog 正是从 /server 导入,保证了服务端 bundle 的轻量与安全。
八、完整导出清单与类型
组件与工具
import {
Renderer, // 渲染器
standardComponents, // 标准组件注册表
TitleCard, ImageSlide, SplitScreen, QuoteCard,
StatCard, LowerThird, TextOverlay, TypingText,
LogoBug, VideoClip,
ClipWrapper, // 转场+motion 自动包裹器
useTransition, // 转场样式钩子
} from "@json-render/remotion";
类型
import type {
Clip, TimelineSpec, AudioTrack,
TransitionStyles, MotionStyles, Motion,
MotionState, MotionLoop, SpringConfig,
ClipComponent, ComponentRegistry,
} from "@json-render/remotion";
Schema 与目录定义
import {
schema,
standardComponentDefinitions,
standardTransitionDefinitions,
standardEffectDefinitions,
} from "@json-render/remotion";
标准特效(standardEffectDefinitions)还包括 kenBurns(图像推拉摇移)、pulse(脉动强调)、shake(镜头抖动)三类定义,可被提示词模板引用,供未来渲染器实现。
九、实战要点小结
- 主轨道与覆盖层分离:把字幕、水印等放
overlay轨道,渲染器会自动分层叠加,这是 AI 生成时最重要的结构规则之一; - 先定义目录,再生成 spec:所有组件名、转场名、props 必须以 catalog 为准,Zod schema 保证了类型安全与 AI 输出约束;
- 动画二选一或叠加:简单进出场用
transitionIn/Out,需要弹性、循环或组合动画用motion,二者可经ClipWrapper无缝叠加; - 服务端只引
/server:避免把 Remotion 运行时带进 Node 端 bundle; - 流式体验:借助
createSpecStreamCompiler边生成边预览,大幅提升 AI 视频生成的交互体验。
相关资源:技能文档 skills/remotion/SKILL.md、包 README packages/remotion/README.md、运行时实现 packages/remotion/src/components、目录与 schema packages/remotion/src/catalog.ts 与 packages/remotion/src/schema.ts、端到端示例 examples/remotion。