@json-render/remotion 渲染器演进全解:从时间线 Spec 到生成式视频渲染

原创2026-09-21 14:31:191,973 阅读
文章标签:前端人工智能AI 应用

@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 的实际执行器,其核心流程:

  1. 合并组件注册表:{ ...standardComponents, ...customComponents },自定义组件同名覆盖标准组件;
  2. 轨道分离:将 clips 按 trackId 拆分为 main(主轨)与 overlay(覆盖轨)两组,主轨在前、覆盖轨在后渲染;
  3. Sequence 映射:每个 clip 渲染为一个 Remotion <Sequence from={clip.from} durationInFrames={...}>,天然获得时间定位;
  4. ClipErrorBoundary 兜底:单个 clip 渲染出错时仅该 clip 静默消失(返回 null)并在控制台打印 [json-render/remotion] Rendering error in clip ...,不会让整个合成白屏——这正是 CHANGELOG 0.5.1 引入错误边界的直接证据;
  5. 空态处理:无 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 表达式,渲染器解析绑定并向下传递 bindings map,实现写回 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 接受可选 store prop 进入受控模式;
  • 提供 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 时需关注:

  1. 表达式语法(0.6.0 起):所有 $path/path 引用改写为 $state/$item/$index,可见性 and/or/not 改写为 $and/$or + not 运算符;
  2. Provider props:actionHandlers 更名 handlers,DataProvider 更名 StateProvider(0.5.0);
  3. 状态回调(0.9.0 起):onStateChange 处理函数需适配数组签名;若引入外部 store,需确认 initialState/onStateChange 在受控模式下被忽略的语义;
  4. 旧 API 移除:createCatalog、generateCatalogPrompt、createRendererFromCatalog、rewriteRepeatTokens、traverseTree 等已删除,迁移到 defineCatalog、traverseSpec 等新 API;
  5. 服务端安全:在 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>

登录后查看全文
json-render