remotion-markup

这是编写 Remotion React 标记的指南。 如果这不适用，请改为加载 Remotion 最佳实践。

保留用户的更改

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

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

一般规则

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

在合成或场景组件中，使用 useVideoConfig() 获取 fps，用于所有秒到帧的换算，包括 from、trimBefore 和 durationInFrames 等时间属性。将表达式保留在 JSX 节点上（例如 trimBefore={4 * fps}），Studio 才能编辑时间设置，而且合成帧率变化时表达式也能保持正确。

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

使用 Easing.bezier() 和 Easing.spring() 自定义时间曲线。

选择标记层级之前，请先阅读 可编辑时间线结构。 先选择编辑单元，再确定它们需要的轨道或共享时间边界。该文档包含交互式组件及其注册方式的完整示例。有关可在源代码中编辑的样式、架构和关键帧，请参阅 Remotion 交互性。

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 属性中。 优先使用 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。

延迟与裁剪

使用序列编排选择时间边界，并参阅时间属性了解支持的属性及其操作顺序。

地图

如果想在视频中加入地图，请参阅 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-in-canvas 方案、预览要求和替代方案。

视觉和像素效果

添加视觉效果时，首先确定效果应作用于哪个元素或组。 如果目标组件支持 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，了解如何在 Remotion 中嵌入 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 中导航到场景自身的时间轴，请使用 connected compositions。

高级序列编排

参见 sequencing.md，了解更多序列编排模式——延迟、裁剪、限制项目时长。

安装模块

使用 npx remotion add，以正确版本添加新包：

npx remotion add @remotion/media

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

视觉检查

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

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