remotion-markup

这是编写 Remotion React Markup 的指南。 如果这与当前任务无关，请改为加载 Remotion Best Practices。

保留用户更改

用户可能会在对话之外编辑代码。

如果你发现期间出现了意外更改，请不要覆盖，假定这是有意为之，或请求确认。

通用规则

将 useCurrentFrame() 放在需要它的最小组件中。将依赖帧的音量、标题和叠加层提取到各自的组件中，而不是让整个合成或场景订阅帧；否则，无关的后代组件会在每一帧重新渲染。跨越时间边界提取时，保留现有的帧坐标，并将可编辑的插值内联在项目的 props 中。

在合成或场景组件内部，通过 useVideoConfig() 获取 fps，用于所有秒到帧的计算，包括 from、trimBefore 和 durationInFrames 等时间 props。将表达式保留在 JSX 节点上，例如 trimBefore={4 * fps}，可让 Studio 编辑时间，并确保合成帧率变化时结果仍然正确。

使用 useCurrentFrame() 和 interpolate() 驱动动画。
CSS transition 或 animation 无法正确渲染，需要重构。
Tailwind 动画类无法正确渲染，需要重构。

使用 Easing.bezier() 和 Easing.spring() 自定义时间效果。

选择标记语言层级之前，请先阅读可编辑时间线结构。 先选择编辑单元，再选择它们所需的轨道或共享时间边界。文中包含一个带交互组件及其注册方式的完整示例。如需了解可编辑源代码的样式、架构和关键帧，请参阅 Remotion Interactivity。

import { useCurrentFrame, useVideoConfig, Easing, interpolate, Interactive } from "remotion";

export const FadeIn = () => {
  const frame = useCurrentFrame();
  const {fps} = useVideoConfig();

  return (
    <Interactive.Div
      name="Title"
      style={{
        opacity: interpolate(frame, [0, 2 * fps], [0, 1], {
          extrapolateRight: "clamp",
          extrapolateLeft: "clamp",
          easing: Easing.bezier(0.16, 1, 0.3, 1),
        }),
      }}
    >
      Hello World!
    </Interactive.Div>
  );
};

将 interpolate() 调用内联在 style prop 中。 优先使用 CSS 属性 scale、translate、rotate，而不是 transform。

// 👍 Inline editable keyframes and transform shorthands
style={{
  scale: interpolate(frame, [0, 100], [0, 1], {
    extrapolateLeft: 'clamp',
    extrapolateRight: 'clamp',
    easing: Easing.spring({damping: 200}),
    output: 'perceptual-scale' // For `scale` animations, use "output: 'perceptual-scale'"
  }),
  translate: interpolate(frame, [0, 100], ["0px 0px", "100px 100px"], {
    extrapolateLeft: 'clamp',
    extrapolateRight: 'clamp',
    easing: Easing.spring({damping: 200}),
  }),
  rotate: interpolate(frame, [0, 100], ["20deg", "90deg"], {
    extrapolateLeft: 'clamp',
    extrapolateRight: 'clamp',
    easing: Easing.spring({damping: 200}),
  }),
}}

// 👎 Non-inline values and transform strings become harder to edit in Studio
const scale = interpolate(frame, [0, 100], [0, 1]);

style={{
  transform: `scale(${scale})`,
}}

资源

将资源放在项目根目录下的 public/ 文件夹中。 使用 staticFile() 引用 public/ 文件夹中的文件。

媒体组件

使用 @remotion/media 中的 <Video> 和 <Audio> 添加视频和音频。
使用 <CanvasImage> 组件添加图片。 使用 <AnimatedImage> 添加动画 GIF、APNG、WebP 或 AVIF 图片；如果不使用 Chrome，则使用 @remotion/gif。 对于 public/ 中的文件，请使用 staticFile()；也可以直接传入远程 URL：

import { Audio, Video } from "@remotion/media";
import { staticFile, CanvasImage, AnimatedImage } from "remotion";

export const MyComposition = () => {
  return (
    <>
      <Video src={staticFile("video.mp4")} style={{ opacity: 0.5 }} />
      <Audio src={staticFile("audio.mp3")} />
      <CanvasImage
        src={staticFile("logo.png")}
        style={{ width: 100, height: 100 }}
      />
      <Video src="https://remotion.media/video.mp4" />
      <AnimatedImage src={staticFile('nyancat.gif')} />
    </>
  );
};

如果合成主要由视频或音频片段的时间线构成，请在选择源结构之前阅读 video-editing.md。

延迟与裁剪

使用序列编排选择时间边界，并通过timing props了解支持的 props 和操作顺序。

地图

如果想在视频中加入地图，请参阅 Remotion Maps。

文本高亮与注释

如需了解文本高亮（高亮标记）、圆圈、下划线、删除线、划掉的文本和方框，请参阅 text-highlights.md。

多场景视频

如果计划制作包含多个连续场景的视频，请参阅 multi-scene-video.md。

关联合成

如果某个场景或组需要自己的可编辑时间线，或需要处理 Studio 预合成请求，请阅读关联合成。 其中介绍了在父级视图和独立视图中进行提取、注册、继承样式和验证的方法。

旁白

如需了解如何使用 ElevenLabs TTS 为 Remotion 合成添加 AI 生成的旁白，请参阅 voiceover.md。

嵌入视频

如需了解嵌入视频的高级知识——裁剪、音量、速度、循环和音高，请参阅 embedding-videos.md。

嵌入音频

如需了解裁剪、音量、速度和音高等高级音频功能，请参阅 audio.md。

裁剪

如需裁剪组件的可见矩形，请参阅 cropping.md。

转场

如需了解场景转场模式，请参阅 transitions.md。

动态模糊

添加动态模糊或运动轨迹时，请阅读 motion-blur.md，了解推荐的画布内 HTML 方案、预览要求和替代方案。

视觉效果和像素效果

添加视觉效果时，先确定要应用效果的元素或元素组。 如果目标组件支持 effects，且下方的内置效果符合需求，应优先使用该效果，而不是用 CSS 近似实现。例如，如果晕影效果应作用于某个 <Video>，请直接将 vignette() 应用到它的 effects 属性。

以下组件可直接接受 effects：

导入自	组件
remotion	<Img>、<CanvasImage>、<AnimatedImage>、<Solid>、<HtmlInCanvas>
@remotion/media	<Video>
@remotion/gif	<Gif>
@remotion/rive	<RemotionRiveCanvas>
@remotion/shapes	<Arrow>、<Callout>、<Circle>、<Ellipse>、<Heart>、<Pie>、<Polygon>、<Rect>、<Spark>、<Star>、<Triangle>

普通 HTML 元素、<Interactive.*> DOM 封装器、<AbsoluteFill> 和 <Sequence> 均不能直接接受 effects。要对其内容应用效果，请将它们 包裹在 <HtmlInCanvas> 中，并将 effects 属性设在封装器上。

对于其他元素，适合时优先使用常规 HTML 和 CSS。如果适合对整个元素组进行后期处理，且环境支持，可考虑将其包裹在 <HtmlInCanvas> 中。

应用效果前，请阅读 effects.md，了解导入方式、参数和设置方法。该文档还介绍了当没有合适的内置效果时，如何使用 createEffect() 创建可复用的自定义效果。

可用效果

@remotion/effects 中的内置效果：

• 色彩和色调：brightness()、colorCorrection()、colorKey()、contrast()、curves()、duotone()、exposure()、grayscale()、hue()、invert()、levels()、linearGradient()、linearGradientTint()、lut()、saturation()、shadowsHighlights()、thermalVision()、tint()、vibrance()、whiteBalance()。
• 模糊和轨迹：blur()、lightTrail()、linearProgressiveBlur()、radialProgressiveBlur()、regionBlur()、zoomBlur()。
• 光照：dropShadow()、longShadows()、glow()、lightLeak()、shine()、starburst()、vignette()。
• 畸变和变换：barrelDistortion()、chromaticAberration()、cornerPin()、fisheye()、mirror()、noiseDisplacement()、scale()、skew()、tile()、uvTranslate()、wave()、xyTranslate()。
• 纹理和图案：burlap()、checkerboard()、contourLines()、dotGrid()、emboss()、flannel()、gridlines()、halftone()、halftoneLinearGradient()、lines()、liquidContours()、noise()、paper()、pattern()、rings()、scanlines()、speckle()、tvSignalOff()、waves()、whiteNoise()、zigzag()。
• 边缘：outline()、roughenEdges()、shrinkwrap()、tear()。
• 像素化和转场：evolve()、linearProgressivePixelate()、pixelate()、pixelDissolve()、radialProgressivePixelate()、venetianBlinds()。

颜色校正

请阅读 color-correction.md，了解使用 colorCorrection() 进行主要调整、使用 levels() 或 curves() 进行色调映射、相应的 Studio 编辑器，以及使用 3D .cube 文件进行 lut() 调色。

3D 内容

查看 ./3d.md，了解如何在 Remotion 中使用 Three.js 和 React Three Fiber 制作 3D 内容。

音效

需要使用音效时，请加载 ./sfx.md 文件以了解更多信息。

音频可视化

需要将音频可视化（频谱条、波形、低音响应效果）时，请加载 ./audio-visualization.md 文件以了解更多信息。

地图

对于静态地图、动画路线和标记、地理信息讲解、Mapbox、MapLibre、MapTiler、GeoJSON 或 3D 地理飞行效果，请加载 Remotion Maps。

字幕

处理字幕或标题时，请加载 Remotion Captions 技能以了解更多信息。

阿拉伯语和从右向左书写的文本

对于阿拉伯语、波斯语、乌尔都语或希伯来语文本，请阅读 arabic-text.md：设置基础书写方向，按词语制作动画，并且只以能保持字母连写的方式拆分字母。

Google Fonts

这是在 Remotion 中加载字体的推荐方式。查看 google-fonts.md，了解如何加载 Google Fonts。

本地字体

查看 local-fonts.md，了解如何加载本地字体。

GIF

查看 gifs.md，了解如何让 GIF 与 Remotion 的时间轴同步显示。

高级图像

查看 images.md，了解图像的尺寸和定位、动态图像路径以及如何获取图像尺寸。

Lottie 动画

查看 lottie.md，了解如何嵌入 Lottie 动画。

时间

查看 timing.md，了解更多 interpolate() 的时间控制技巧。

参数化视频

查看 parameters.md，了解如何通过添加 Zod 模式使合成可参数化。

测量 DOM 节点

查看 measuring-dom-nodes.md，了解如何测量 Remotion 中 DOM 元素的尺寸。

测量文本

查看 measuring-text.md，了解如何测量文本尺寸、使文本适应容器以及检查溢出。

使用 FFmpeg

对于某些视频操作，例如剪辑视频或检测静音，应使用 FFmpeg。请加载 ./ffmpeg.md 文件以了解更多信息。

静音检测

需要检测并剪掉视频或音频文件中的静音片段时，请加载 ./silence-detection.md 文件。

动态时长、尺寸和数据

查看 calculate-metadata.md，了解如何动态设置合成时长、尺寸和 props。

合成和静帧

注册 <Composition> 或 <Still> 元素之前，请阅读 compositions.md，了解可通过源代码编辑的注册方式、文件夹、默认 props 和嵌套。如需在 Studio 中导航到场景自身的时间轴，请使用关联合成。

高级序列编排

查看 sequencing.md，了解更多序列编排模式：延迟、修剪和限制项目时长。

安装模块

使用 npx remotion add 添加版本匹配的新包：

npx remotion add @remotion/media

这适用于 @remotion/* 包、mediabunny、@mediabunny/*、zod 和 @huggingface/transformers。

视觉检查

打开 Remotion Studio 检查视觉变化。 更改时间轴结构时，请检查完整合成以及所有关联组件；确认可见图层、剪辑时间和同步内容。

你也可以使用 Rendering 将一帧或多帧渲染为图像进行检查。