json-render Remotion 渲染器实战:用 JSON 时间线规格驱动 AI 视频生成

原创2026-09-21 13:47:062,171 阅读
文章标签:人工智能AI 应用前端UI组件跨平台开发工具

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):

  1. 合并组件注册表:{ ...standardComponents, ...customComponents },自定义组件同名可覆盖标准组件;
  2. 无 clips 时渲染空态提示;
  3. 将 clips 按 trackId 拆分为 main 与 overlay 两组,先渲染主轨道再渲染覆盖层;
  4. 每个 clip 包一层 <Sequence from={clip.from} durationInFrames={...}> 实现时间切片;
  5. 每个 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。

登录后查看全文
json-render