@json-render/remotion 渲染器演进全解:从时间线 Spec 到生成式视频渲染
@json-render/remotion 渲染器演进全解:从时间线 Spec 到生成式视频渲染
@json-render/remotion 是 json-render(The Generative UI framework)生态中的视频渲染器包,其使命是把 LLM 生成的 JSON 时间线规范(Timeline Spec)直接变成可播放、可导出的 Remotion 视频合成(Composition)。本指南以该包官方变更记录 packages/remotion/CHANGELOG.md 为主体,结合源码(schema.ts、Renderer.tsx、hooks.ts、catalog.ts)展开解读,帮助你掌握时间线 Spec 结构、标准组件与转场、声明式 Motion 系统,以及随版本引入的外部状态存储、聊天模式、双向绑定等平台级能力,并据此评估升级路径。
包定位与版本演进概览
@json-render/remotion 当前版本为 0.21.0,依赖 @json-render/core(workspace 版本)以及 peer 依赖 react@^19.2.3、remotion@^4.0.0、zod@^4.0.0,详见 packages/remotion/package.json。它对外提供两个入口:
- 主入口
@json-render/remotion:包含渲染器Renderer、标准组件、Hooks 与类型; - 服务端安全入口
@json-render/remotion/server:仅导出 schema 与 catalog 定义,不携带任何 React / Remotion 运行时依赖,适合在 Next.js Server Component、API 路由或构建脚本中引用(见 server.ts)。
从 CHANGELOG 可以梳理出该包的核心演进主线(所有 Patch Changes 均为对 @json-render/core 的依赖升级):
| 版本 | 关键内容 |
|---|---|
| 0.4.2 | 新增 defineRegistry 函数(依赖 core 0.4.2) |
| 0.4.3 | System Prompt 中加入 remove 操作说明 |
| 0.4.4 | 扁平 Spec 移除 key/parentKey,SpecStream 对齐 RFC 6902 |
| 0.5.0 | 引入事件系统(emit 取代 onAction)、repeat/list 渲染、用户 Prompt 构建器、Spec 校验,DataProvider 更名 StateProvider |
| 0.5.1 | 为所有渲染器加入错误边界,坏组件静默消失而非白屏;修复 Select/Radio 处理非字符串选项 |
| 0.5.2 | 从用户 catalog 动态生成 Prompt 示例防 LLM 幻觉,ComponentDefinition 新增可选 example 字段,输出格式说明中提及 RFC 6902 |
| 0.6.0 | 聊天模式(内联 GenUI)、AI SDK 集成、双向绑定、表达式化 Props 与可见性 |
| 0.9.0 | 外部状态存储(StateStore)、store 适配器包、onStateChange 签名破坏性变更 |
| 0.10.0 ~ 0.16.0 | 持续同步 core 依赖升级 |
时间线 Spec:视频渲染器的"JSON 语法"
与 @json-render/react 的元素树(Element tree)不同,remotion 渲染器采用**时间线(Timeline)**格式,这是它区别于 UI 渲染器的根本设计。官方 README 在 "Why Different from React?" 一节明确指出:json-render 是"JSON to render",Spec 格式与组件完全由每个渲染器自定义,remotion 的 Spec 是 tracks + clips 的时间线,输出是 Remotion 视频而非 React DOM。
完整的 TimelineSpec 结构定义在 types.ts:
export interface TimelineSpec {
composition?: {
id: string;
fps: number;
width: number;
height: number;
durationInFrames: number;
};
tracks?: { id: string; name: string; type: string; enabled: boolean }[];
clips?: Clip[];
audio?: { tracks: AudioTrack[] };
}
一个实际可用的示例 Spec(来自 README.md):
{
"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": "#1a1a1a",
"textColor": "#ffffff"
},
"from": 0,
"durationInFrames": 90,
"transitionIn": { "type": "fade", "durationInFrames": 15 },
"transitionOut": { "type": "fade", "durationInFrames": 15 }
}
],
"audio": { "tracks": [] }
}
每个 Clip 由 from(起始帧)与 durationInFrames(持续帧数)决定时间位置,component 引用 catalog 中的组件名,props 传给对应组件,并可选携带 transitionIn / transitionOut(转场)与 motion(声明式动画),见 types.ts。
从 JSONL Patch 到完整时间线:Schema 与 Prompt 模板
@json-render/remotion 的 schema.ts 通过 defineSchema 定义了两部分内容:AI 应生成的 Spec 形状(composition / tracks / clips / audio)与 catalog 必须提供的能力清单(组件、转场、效果的 props Zod schema、类型、默认时长、描述)。
与 UI 渲染器一致,模型输出采用 JSONL Patch 格式(每行一个 JSON Patch 操作,符合 RFC 6902,这正是 CHANGELOG 0.4.3/0.4.4 强调的合规点)。内置的 remotionPromptTemplate 指导模型按固定顺序构建时间线:
{"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","subtitle":"Getting Started"},"from":0,"durationInFrames":90,"transitionIn":{"type":"fade","durationInFrames":15},"transitionOut":{"type":"fade","durationInFrames":15},"motion":{"enter":{"opacity":0,"y":50,"scale":0.9,"duration":25},"spring":{"damping":15}}}}
{"op":"add","path":"/clips/-","value":{"id":"clip-2","trackId":"main","component":"TitleCard","props":{"title":"Features"},"from":90,"durationInFrames":90,"motion":{"enter":{"opacity":0,"x":-100,"duration":20},"exit":{"opacity":0,"x":100,"duration":15}}}}
{"op":"add","path":"/audio","value":{"tracks":[]}}
Prompt 模板还内置了一系列生成规则(RULES),保证输出可直接渲染:
- 只输出 JSONL Patch,不输出 markdown 或代码围栏;
- 先加
/composition,再建/tracks,逐条 append clips 到/clips/-,最后补/audio; fps恒为 30(1 秒 = 30 帧);main轨 clips 顺序衔接(from= 上一个 clip 的from + durationInFrames),overlay 类组件(LowerThird、TextOverlay)放在overlay轨;- 仅可使用 catalog 中列出的组件,且每个组件会带上
formatZodType(props)格式化的 props 类型说明与defaultDuration提示。
这正是 CHANGELOG 0.5.2 所描述的"从用户 catalog 动态生成 Prompt 示例"的落地实现——组件清单、转场清单、效果清单全部来自 catalog 而非硬编码,从而抑制 LLM 幻觉。
标准组件、转场与效果:开箱即用的视频素材库
catalog.ts 提供三组可直接用于 defineCatalog 的标准定义:
标准组件(standardComponentDefinitions),每个都带 Zod props、类型、默认时长与给 AI 的描述:
| 组件 | 类型 | 默认时长 | 关键 props |
|---|---|---|---|
TitleCard |
scene | 90 帧 | title, subtitle, backgroundColor, textColor |
ImageSlide |
image | 150 帧 | src, alt, fit(cover/contain) |
SplitScreen |
scene | 120 帧 | leftTitle, rightTitle, leftColor, rightColor |
QuoteCard |
scene | 150 帧 | quote, author, backgroundColor, textColor, transparent |
StatCard |
scene | 90 帧 | value, label, prefix, suffix |
TypingText |
scene | 180 帧 | text, charsPerSecond, showCursor, cursorChar, fontFamily |
LowerThird |
overlay | 120 帧 | name, title, backgroundColor |
TextOverlay |
overlay | 90 帧 | text, position(top/center/bottom), fontSize |
LogoBug |
overlay | 300 帧 | position(四角), opacity |
VideoClip |
video | 150 帧 | src, startFrom, volume |
标准转场(standardTransitionDefinitions):fade(15帧)、slideLeft(20)、slideRight(20)、slideUp(15)、slideDown(15)、zoom(20)、wipe(15)、none(硬切,0 帧)。
标准效果(standardEffectDefinitions):kenBurns(图片推拉摇移,参数 startScale/endScale/panX/panY)、pulse(脉冲缩放,intensity)、shake(镜头抖动,intensity)。
声明式 Motion 系统:enter / exit / loop / spring
CHANGELOG 0.5.0 引入 repeat/list 渲染与事件系统后,remotion 渲染器又发展出独立的声明式动画能力。Clip 的 motion 字段允许纯数据驱动动画,无需任何 React 代码:
enter:从给定值动画到中性值(如{"opacity":0,"y":30,"duration":20}表示淡入上浮);exit:从中性值动画到给定值(如{"opacity":0,"x":100,"duration":15});spring:物理参数damping(默认 20,越小越弹)、stiffness(默认 100)、mass(默认 1);loop:循环动画,property可选"scale" | "rotate" | "x" | "y" | "opacity",easing可选"linear" | "ease" | "spring"。
这些能力在 hooks.ts 的 useMotion 中实现:enter 用 spring({ frame, fps, config, durationInFrames }) 计算进度后经 interpolate 从起始值过渡到中性值;exit 反向叠加;loop 用 relativeFrame % duration 取模获得循环相位,ease 模式下通过三节点插值 <a href="https://link.gitcode.com/i/90c7d6e9adab6f44b14406b849596b4d" target="_blank">0, duration/2, duration] → [0, 1, 0] 实现正弦缓入缓出。useTransition 则处理 transitionIn/transitionOut 七种内置转场,同样基于 Remotion 的 spring 与 interpolate(见 [hooks.ts)。
import { useTransition } from "@json-render/remotion";
import { useCurrentFrame } from "remotion";
function MyComponent({ clip }: { clip: Clip }) {
const frame = useCurrentFrame();
const transition = useTransition(clip, frame);
return <div style={{ opacity: transition.opacity }}>Content</div>;
}
Renderer 实现原理:轨道分层与错误边界
Renderer.tsx 是时间线 Spec 的实际执行器,其核心流程:
- 合并组件注册表:
{ ...standardComponents, ...customComponents },自定义组件同名覆盖标准组件; - 轨道分离:将 clips 按
trackId拆分为main(主轨)与overlay(覆盖轨)两组,主轨在前、覆盖轨在后渲染; - Sequence 映射:每个 clip 渲染为一个 Remotion
<Sequence from={clip.from} durationInFrames={...}>,天然获得时间定位; - ClipErrorBoundary 兜底:单个 clip 渲染出错时仅该 clip 静默消失(返回 null)并在控制台打印
[json-render/remotion] Rendering error in clip ...,不会让整个合成白屏——这正是 CHANGELOG 0.5.1 引入错误边界的直接证据; - 空态处理:无 clips 时渲染占位背景(
#1a1a2e+ "No clips")。
import { Player } from "@remotion/player";
import { Renderer } from "@json-render/remotion";
function VideoPlayer({ spec }) {
return (
<Player
component={Renderer}
inputProps={{ spec }}
durationInFrames={spec.composition.durationInFrames}
fps={spec.composition.fps}
compositionWidth={spec.composition.width}
compositionHeight={spec.composition.height}
controls
/>
);
}
0.6.0 平台能力:聊天模式、表达式 Props 与双向绑定
0.6.0 是 CHANGELOG 中信息量最大的版本,虽然这些能力定义在 @json-render/core,但作为 remotion 渲染器所共享的生态能力,直接影响视频渲染的交互方式:
- 聊天模式(Inline GenUI):
catalog.prompt({ mode: "chat" })生成聊天感知的 system prompt,pipeJsonRender()在服务端把混合流中的文本与 JSONL Patch 分离,createJsonRenderTransform()提供底层 TransformStream; - AI SDK 集成:
SpecDataPart类型、SPEC_DATA_PART/SPEC_DATA_PART_TYPE常量、createMixedStreamParser(); - React Chat Hooks:
useChatUI()、useJsonRenderMessage()、buildSpecFromParts()、getTextFromParts(); - 双向绑定:props 支持
$bindState/$bindItem表达式,渲染器解析绑定并向下传递bindingsmap,实现写回 state; - 表达式化 Props 与可见性:
{ $state: "/path" }、{ $item: "field" }、{ $index: true }及可见性条件{ $state: "/path", eq: "value" },比较运算符eq/neq/gt/gte/lt/lte/not,逻辑组合$and/$or。
破坏性变更:{ $path } 改为 { $state }、repeat.path 改为 repeat.statePath、actionHandlers 改为 handlers、移除 AuthState 与 { auth } 可见性条件、移除 createCatalog 等旧 API。
0.9.0 平台能力:外部状态存储与 Store 适配器
0.9.0 引入的 StateStore 接口把状态管理从内置 store 中解耦,允许接入 Redux、Zustand、Jotai、XState 等第三方方案(CHANGELOG 注明该能力已覆盖 react、react-native、react-pdf 等全部平台包):
StateStore接口与createStateStore()工厂位于@json-render/core;StateProvider、JSONUIProvider、createRenderer接受可选storeprop 进入受控模式;- 提供
store时,它是唯一数据源(initialState/onStateChange被忽略);省略时行为与旧版完全一致(向后兼容); - 配套适配器包:
@json-render/zustand、@json-render/redux、@json-render/jotai; createStoreAdapter、immutableSetByPath、flattenToPointers可通过@json-render/core/store-utils获取,用于构建自定义适配器。
破坏性变更:onStateChange 从逐路径回调改为单次接收变更数组:
// Before
onStateChange?: (path: string, value: unknown) => void
// After
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
升级路径与注意要点
基于 CHANGELOG 各版本的破坏性变更,从旧版本升级到当前 0.21.0 时需关注:
- 表达式语法(0.6.0 起):所有
$path/path引用改写为$state/$item/$index,可见性and/or/not改写为$and/$or+not运算符; - Provider props:
actionHandlers更名handlers,DataProvider更名StateProvider(0.5.0); - 状态回调(0.9.0 起):
onStateChange处理函数需适配数组签名;若引入外部 store,需确认initialState/onStateChange在受控模式下被忽略的语义; - 旧 API 移除:
createCatalog、generateCatalogPrompt、createRendererFromCatalog、rewriteRepeatTokens、traverseTree等已删除,迁移到defineCatalog、traverseSpec等新 API; - 服务端安全:在 Next.js App Router API 路由等无 React 上下文环境使用 schema 时,优先从
@json-render/remotion/server子路径导入,避免createContext崩溃(0.9.0 修复项)。
结语
@json-render/remotion 的 CHANGELOG 记录了 json-render 从纯 UI 渲染向"任意领域渲染器"演进的完整轨迹:时间线 Spec 证明 Spec 格式完全由渲染器自定义;聊天模式、双向绑定、外部状态存储则是平台级能力在视频领域的下沉。结合 schema.ts、Renderer.tsx、hooks.ts 与 catalog.ts 的源码,你可以基于这套"JSON 即视频"的管道,构建自己的 AI 生成视频工作流——只要给模型一份 catalog,它就能输出一段可渲染的时间线。
</|DSML|parameter> </|DSML|invoke> </|DSML|tool_calls>