rendiv-video

Rendiv 视频技能

在编写 rendiv 代码时，请使用这些技能——无论是编写合成、制作元素动画、嵌入媒体，还是渲染输出。

核心思维模型

Rendiv 将视频视为帧编号的纯函数。每个视觉属性（位置、不透明度、颜色、缩放）都通过 useFrame() 根据当前帧计算得出。它没有时间轴状态机，也没有命令式关键帧 API。你只需编写一个接收帧并返回 JSX 的 React 组件——其余工作由 rendiv 处理。

import { useFrame, interpolate } from '@rendiv/core';

export const FadeIn: React.FC = () => {
  const frame = useFrame();
  const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: 'clamp' });
  return <div style={{ opacity }}>Hello rendiv</div>;
};

核心原则

• 所有动画都必须由 useFrame() 驱动。禁止使用 CSS 动画和过渡——它们基于墙上时钟运行，在逐帧渲染时会不同步。
• 线性映射使用 interpolate()，基于物理的运动使用 spring()。
• 使用来自 @rendiv/core 的 <Img>、<Video>、<Audio> 和 <AnimatedImage>，而不是原生 HTML 元素——这些组件通过 holdRender 与渲染生命周期集成。
• 合成通过 <Composition> 和 <Still> 以声明式方式注册——它们会渲染 null，仅向框架提供元数据。

快速入门

一个最简的 rendiv 项目入口：

// FadeIn.tsx — composition component
import { useFrame, interpolate, CanvasElement } from '@rendiv/core';

export const FadeIn: React.FC = () => {
  const frame = useFrame();
  const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: 'clamp' });
  return (
    <CanvasElement id="FadeIn">
      <div style={{ opacity }}>Hello rendiv</div>
    </CanvasElement>
  );
};

// index.tsx — entry point
import { setRootComponent, Composition } from '@rendiv/core';
import { FadeIn } from './FadeIn';

const Root: React.FC = () => (
  <>
    <Composition
      id="FadeIn"
      component={FadeIn}
      durationInFrames={90}
      fps={30}
      width={1920}
      height={1080}
    />
  </>
);

setRootComponent(Root);

渲染为 MP4：rendiv render src/index.tsx FadeIn out/fade-in.mp4

主题指南

根据当前任务加载相应的规则文件：

任务	规则文件
使用 interpolate、spring、Easing、blendColors 制作动画	animation.md
设置合成、静帧、文件夹和入口点	composition-setup.md
使用 Sequence、Series、Loop、Freeze 调整时间	sequencing-and-timing.md
控制 z 轴顺序和时间轴覆盖	timeline-overrides.md
嵌入图像、视频、音频、GIF、iframe	media-components.md
渲染可控制播放的动画 GIF	gif.md
添加字幕、解析 SRT、突出显示词语	captions.md
了解 holdRender、环境模式和渲染管线	render-lifecycle.md
使用 TransitionSeries 在场景间制作动画	transitions.md
生成 SVG 形状或操作路径	shapes-and-paths.md
添加噪声驱动的运动或运动模糊	procedural-effects.md
按字符、单词或行制作文本动画	text-animation.md
应用视觉效果和 CSS 滤镜	visual-effects.md
加载 Google Fonts 或本地字体文件	typography.md
嵌入 Lottie 动画	lottie.md
使用 Three.js / R3F 添加 3D 场景	three.md
使用 CLI、Studio 或 Player	cli-and-studio.md

关键限制

1. 禁止使用 CSS 动画或过渡。 所有内容都必须由 useFrame() 驱动。
2. 使用 rendiv 媒体组件（<Img>、<Video>、<Audio>、<AnimatedImage>）， 不要使用原生 HTML 元素。它们会自动管理 holdRender。
3. 始终使用 <CanvasElement id="..."> 包裹合成内容。 这样可确保合成独立运行，使其时间轴覆盖在嵌套于其他合成时也能正常工作。id 必须与 <Composition> 的 id 一致。
4. <Composition> 不会渲染内容。 它只注册元数据。实际组件由 Player、Studio 或 Renderer 渲染，而不是由 <Composition> 本身渲染。
5. setRootComponent 只能调用一次。 它会注册定义所有合成的根组件。
6. interpolate() 和 blendColors() 中的 inputRange 必须单调不减。 两个范围的长度必须相同，且至少包含 2 个元素。
7. <Series.Sequence> 必须是 <Series> 的直接子元素。 如果在 <Series> 父级之外渲染，就会抛出错误。
8. morphPath 要求路径的线段匹配。 两条路径必须包含数量相同且命令类型匹配的线段。

包

包	用途
@rendiv/core	钩子、组件、动画、上下文
@rendiv/player	浏览器 <Player> 组件
@rendiv/renderer	使用 Playwright + FFmpeg 进行渲染
@rendiv/bundler	基于 Vite 的项目打包器
@rendiv/cli	CLI：渲染、静帧、合成、Studio
@rendiv/studio	带渲染队列的 Studio 开发服务器
@rendiv/transitions	TransitionSeries，支持淡入淡出、滑动、擦除、翻转、时钟擦除
@rendiv/shapes	SVG 形状生成器（圆形、矩形、星形、多边形等）
@rendiv/paths	SVG 路径解析、测量、变形、描边显示
@rendiv/noise	Simplex 噪声（2D、3D、4D）
@rendiv/fonts	使用 holdRender 加载本地字体
@rendiv/google-fonts	使用 holdRender 加载 Google Fonts
@rendiv/motion-blur	MotionTrail 和 ShutterBlur 组件
@rendiv/gif	支持速度控制和适配模式的 GIF 动画播放
@rendiv/captions	SRT/Whisper 解析、逐词高亮、字幕叠加
@rendiv/text	动画文本：按字符／单词／行拆分、错开显示、预设
@rendiv/effects	视觉效果：可组合的 CSS 滤镜、发光、故障效果、暗角
@rendiv/lottie	通过 lottie-web 实现逐帧精准的 Lottie 动画
@rendiv/three	通过 React Three Fiber 创建 3D 场景，并桥接上下文

示例资源

• 动画条形图 — 使用 Spring 动画并错开入场的条形
• 文本显示效果 — 逐字符播放的文本动画