remotion-best-practices

Overview

What is the remotion-best-practices skill?

remotion-best-practices 技能是一套经过整理的指南和规则，用于在 Remotion（基于 React 的视频创作框架）中构建视频。它把与动画、音频、字幕、FFmpeg 使用方式、素材管理、3D 场景等相关的领域经验，汇总到 rules/ 目录下的一组聚焦型规则文件中。

有了这个技能，你不必从零东拼西凑示例，而是可以获得有明确观点的建议：如何组织 Remotion 代码，让渲染稳定可靠、可扩展到复杂项目，并在长期维护中保持清晰易管。

Who is this skill for?

在以下情况中，建议安装此技能：

• 使用 Remotion 和 React 制作营销、产品介绍或社交媒体视频
• 需要以编程方式生成视频（例如数据驱动或模板化内容）
• 处理以音频为主的内容，如播客、audiogram 或音乐可视化
• 希望有清晰的字幕、双语字幕和 SRT 流程规范
• 正在为 Remotion 合成场景加入 3D 或 Three.js 内容

它对前端工程师、会写代码的动效设计师，以及希望统一 Remotion 项目写法的团队都很有帮助。

What problems does it solve?

Remotion best-practices 技能聚焦解决真实 Remotion 项目中常见的实战问题，例如：

• 通过 逐帧驱动所有动画，保证渲染稳定且结果可预测
• 通过 public/ 文件夹和 staticFile() 正确导入和引用 图片、视频、音频和字体
• 创建 结构清晰的视频合成，确保时间轴、转场和参数一致
• 处理 音频（分层、裁剪、延迟、音量、速度、循环、音效 SFX）
• 生成 音频可视化（频谱柱、波形、低音响应特效）
• 使用和管理 字幕与双语字幕，包括 SRT 导入与转写
• 使用 FFmpeg 进行裁剪、抽帧、检测静音等操作
• 通过 @remotion/three 集成 3D，并结合 Three.js 和 React Three Fiber
• 在渲染前动态计算 合成元数据（时长、尺寸、props）
• 在渲染前通过 Mediabunny 验证媒体兼容性

只要你的需求超出了简单的 Remotion demo，这些规则都能为真实生产环境提供经过实战验证的模式。

When is this skill a good fit?

在以下情况下使用 remotion-best-practices 技能：

• 项目已经在用 Remotion，或你正在评估用 Remotion 做视频生成
• 希望对动画、素材、音频、字幕和 3D 有一套统一的规范
• 需要代码层面的示例，而不仅仅是高层文档

它不是 Remotion 官方文档的替代品，也不是学习 React 的完整教程。前提是假设你已掌握 React 基础，并至少通读过 Remotion 文档。

How to Use

1. Installation and setup

Install the skill into your agent environment

使用 skill 管理器，从上游仓库安装 Remotion best-practices 技能：

npx skills add https://github.com/remotion-dev/skills --skill remotion

安装完成后，remotion-best-practices 的知识就会对你的 agent 可用，它可以在协助你的 Remotion 项目时引用各个规则文件。

Review the core documentation files

安装后，优先查看以下文件：

• SKILL.md – 顶层说明、适用场景以及核心规则文件链接
• rules/animations.md – 如何用 useCurrentFrame() 和 useVideoConfig() 驱动动画
• rules/assets.md – 如何正确导入图片、视频、音频和字体
• rules/audio.md – 音频处理、裁剪、延时和分层
• rules/audio-visualization.md – 音频数据、波形和频谱可视化
• rules/3d.md – 通过 @remotion/three 使用 Three.js 和 React Three Fiber 构建 3D 场景

这些规则构成了大多数 Remotion 视频编辑工作流的基础。

2. Core concepts and best practices

Drive all animations by frame

参考 rules/animations.md 了解 Remotion 动画的核心原则：

• 使用 useCurrentFrame() 读取当前帧
• 使用 useVideoConfig() 获取 fps
• 先用 秒 计算动画时间，再转换为帧数（seconds * fps）
• 使用 interpolate() 等辅助函数，把帧数映射到位置、透明度等属性
• 避免使用 CSS transitions、CSS animations 和 Tailwind 的动画类，它们在 Remotion 中渲染不够稳定

基于帧的方式可以确保输出结果在任何播放速度或运行环境下都保持一致。

Manage assets via public/ and staticFile()

rules/assets.md 定义了媒体素材的推荐用法：

• 将所有静态素材（图片、字体、音频、视频）放在 public/ 文件夹中
• 使用 staticFile("my-file.ext") 引用 public/ 中的资源
• 将 staticFile() 与 <Img>、<Video>、<Audio> 等 Remotion 组件搭配使用
• 当文件托管在公网时，可以直接使用远程 URL

这套模式可以避免路径错误，自动处理 URL 编码，并适配不同的部署环境。

Build robust audio and sound design

rules/audio.md 涵盖了音频相关工作流：

• 使用 @remotion/media 中的 <Audio> 导入音频
• 用基于帧的 trimBefore 和 trimAfter 裁剪音频片段
• 使用 <Sequence> 包装器延时音频或与画面对齐
• 通过多个 <Audio> 组件叠加音乐、配音和音效

对于音频驱动的可视化效果，可结合 rules/audio-visualization.md：

• 安装 @remotion/media-utils
• 使用 useWindowedAudioData() 读取某一时间窗口内的音频采样
• 使用 visualizeAudio() 生成频谱数据，用于频谱柱等效果

这样就可以轻松制作 audiogram、节奏响应标题和音乐可视化动画。

Handle captions and subtitles

顶层的 SKILL.md 会指向字幕相关规则：

• rules/subtitles.md – 字幕使用模式
• rules/display-captions.md – 在画面中渲染字幕
• rules/import-srt-captions.md – 导入 SRT 字幕文件
• rules/transcribe-captions.md – 转写与字幕生成工作流

在以下场景中可以使用这些规则：

• 为社交媒体内容烧录内嵌字幕
• 管理多语言字幕轨道
• 构建自动化或半自动化的字幕流程

Use FFmpeg for advanced video operations

rules/ffmpeg.md 指南说明了如何在 Remotion 之外配合 FFmpeg 完成更底层的视频操作，例如：

• 精确裁剪或拼接源视频
• 检测音频中的静音片段
• 抽取视频帧或生成 GIF

Remotion 专注于场景合成与渲染，而 FFmpeg 负责对原始媒体文件进行重度处理。在生产级视频管线中，二者结合往往是最高效的方案。

Bring in 3D with Three.js and React Three Fiber

如果你希望在 Remotion 视频中加入 3D 场景，请查看 rules/3d.md：

• 使用推荐命令 npx remotion add @remotion/three 安装 @remotion/three（或使用你偏好的包管理器的等价命令）
• 将 3D 内容包裹在 <ThreeCanvas> 中，并从 useVideoConfig() 传入 width 和 height
• 配置基础灯光（例如 ambientLight 和 directionalLight）
• 用 useCurrentFrame() 而不是 @react-three/fiber 中的 useFrame() 驱动 3D 动画

这样可以确保 3D 内容逐帧渲染，避免闪烁或音画不同步问题。

3. Dynamic compositions and metadata

Calculate duration and dimensions dynamically

rules/calculate-metadata.md 展示了如何在 <Composition> 上使用 calculateMetadata：

• 根据外部数据动态调整 durationInFrames（例如基于输入视频的时长）
• 让合成尺寸匹配输入视频或其他动态参数
• 在渲染开始前预处理和转换 props

配合 rules/get-video-duration.md 和 rules/get-video-dimensions.md 等辅助规则，你可以：

• 为上传的内容自动匹配合成尺寸
• 让片头片尾与主媒体时长精确对齐

这对用户生成内容（UGC）或模板化视频系统尤其有用。

4. Media validation and compatibility

Check if a video can be decoded

rules/can-decode.md 介绍了如何用 Mediabunny 做兼容性检查：

• 使用 npx remotion add mediabunny 安装 Mediabunny
• 使用内置的 canDecode() 帮助函数，检测来自 URL 的视频是否可被浏览器解码
• 对上传的 Blob 源使用 canDecodeBlob() 变体

在构建上传流程时，这可以帮助你在开始昂贵的渲染任务之前先验证媒体文件。

5. Additional focused rules

除了核心主题，rules/ 目录中还包含一系列可以按需查阅的专门指南：

• rules/compositions.md – 如何组织和管理 Remotion 合成
• rules/timing.md、rules/sequencing.md、rules/transitions.md、rules/text-animations.md – 精细控制运动节奏和时间安排
• rules/fonts.md、rules/measuring-text.md、rules/measuring-dom-nodes.md – 排版与布局精度
• rules/gifs.md、rules/images.md、rules/videos.md、rules/transparent-videos.md、rules/trimming.md、rules/extract-frames.md – 针对不同媒体格式与操作的实践
• rules/maps.md、rules/charts.md、rules/lottie.md、rules/light-leaks.md – 面向特定视觉场景的模式
• rules/voiceover.md、rules/sfx.md – 配音与音效工作流
• rules/tailwind.md – 如何在 Remotion 中合理使用 Tailwind（同时排除不允许的动画类）

你可以根据项目需求，选择性参考这些专门规则。

6. Workflow tips for using this skill

With an AI agent

如果你在使用已安装此技能的 AI 助手：

• 在需要更深入示例时，让它 打开指定规则文件（例如 rules/audio.md）
• 让它生成符合这些规则的代码片段（不使用 CSS transitions、所有动画通过 useCurrentFrame() 驱动、正确使用 staticFile() 等）
• 在代码评审或重构 Remotion 项目时，将该技能当作检查清单

In a team setting

在团队内推广这套技能的方式包括：

• 在内部文档中分享相关 rules/*.md 文件的链接
• 将技能中的模式整理到团队内部编码规范中
• 在新成员加入 Remotion 项目时，以此作为入门参考

FAQ

Is this skill the same as the Remotion framework?

不是。Remotion 是用 React 创建视频的底层框架，而 remotion-best-practices 技能是在 Remotion 之上提供的一组最佳实践和规则文件，用于指导你如何组织代码、管理媒体，并避免常见坑点。

Do I need to know React to benefit from this skill?

需要。Remotion 生态是基于 React 的，规则文件中的示例默认你理解组件、props 和 hooks。此技能专注于 Remotion 相关 的实践，并不会从零讲解 React。

How do I install the Remotion best-practices skill?

在你的 agent 或 skills 环境中运行：

npx skills add https://github.com/remotion-dev/skills --skill remotion

然后打开 SKILL.md 和 rules/ 文件夹浏览可用主题。

Can I use this skill without a Remotion project yet?

可以直接阅读其中的内容和示例，但在你已经有一个 Remotion workspace 之后，这个技能会更有价值。许多规则会提到 @remotion/media、@remotion/media-utils、@remotion/three 或 Mediabunny 等包，你通常需要在自己的项目中安装这些依赖。

Does this skill cover 3D content with Three.js?

有。rules/3d.md 专门讲解如何在 Remotion 中通过 Three.js 和 React Three Fiber（经由 @remotion/three）实现 3D。它会说明如何安装相关包、如何使用 <ThreeCanvas> 包裹内容，以及如何用 useCurrentFrame() 驱动 3D 动画。

Where do I find guidance on audio visualizations and audiograms?

请查看 rules/audio-visualization.md。其中介绍了如何安装 @remotion/media-utils，使用 useWindowedAudioData() 获取音频数据，并用 visualizeAudio() 转换为频谱和波形，用于构建 audiogram 的视觉效果。

What if I need to work with captions and subtitles?

从 SKILL.md 开始，它会指向：

• rules/subtitles.md：通用字幕模式
• rules/display-captions.md：在画面中渲染字幕
• rules/import-srt-captions.md：导入 SRT 文件
• rules/transcribe-captions.md：字幕转写工作流

这些指南基本涵盖了基于 Remotion 的常见字幕需求。

When should I use FFmpeg instead of pure Remotion code?

当你需要对原始媒体文件进行操作时应考虑 FFmpeg，例如精确裁剪、拼接、多段合成、检测静音或抽取帧等。Remotion 擅长在 React 中编排和渲染场景，而 rules/ffmpeg.md 讲解了如何以及何时在你的 Remotion 流水线旁边集成 FFmpeg。

Can this skill help me avoid performance and rendering issues?

可以。许多规则就是为避免常见性能和渲染问题而设计的，例如：

• 在 3D 中误用 useFrame() 而不是 useCurrentFrame() 导致的闪烁
• 依赖 CSS transitions 导致动画无法正常渲染
• 资源路径错误或 URL 编码不正确
• 媒体无法在渲染时解码而导致失败

遵循 rules/animations.md、rules/assets.md、rules/3d.md 和 rules/can-decode.md 中的模式，有助于构建更稳定可靠的 Remotion 项目。

How do I explore all available rule files?

安装完成后，在你的环境中打开 rules/ 目录。关键文件包括：

• rules/3d.md
• rules/animations.md
• rules/assets.md
• rules/audio-visualization.md
• rules/audio.md
• rules/ffmpeg.md
• rules/compositions.md
• rules/timing.md
• rules/subtitles.md
• rules/voiceover.md

你可以通过 Files 标签或代码编辑器浏览其余文件，了解更多如 charts、maps、GIFs 和 Tailwind 等更细分的主题。