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-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()、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() 效果进行色彩校正，或使用 lut() 应用 3D .cube 色彩分级。

3D 内容

关于在 Remotion 中使用 Three.js 和 React Three Fiber 创建 3D 内容，请参阅 ./3d.md。

音效

需要使用音效时，请加载 ./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 schema 让合成可参数化。

测量 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 将一帧或多帧渲染为图像进行检查。