remotion-motion-graphics

Remotion 动态图形

Remotion 会逐帧将 React 组件渲染成视频。代码质量不是瓶颈——动态设计的专业功底才是。未经训练的生成会产生线性缓动、只改变透明度的淡入淡出、同时入场、平淡的颜色，以及毫无纹理的画面。这就是“千篇一律的 AI 视频”观感。本技能旨在避免这种情况。

不容妥协的规则（适用于每个合成）

1. 绝不使用线性插值。 每个 interpolate() 都要设置缓动曲线；入场动画优先使用 spring()。始终设置 extrapolateLeft/Right: "clamp"。
2. 入场动画要同时驱动 2–3 个属性（透明度 + translateY + scale）。禁止只做淡入。
3. 所有元素都要错开入场。 列表、单词、光线、卡片：错开 3–6 帧。不能让任何元素同时入场。
4. 必须设置退场动画，且退场要比入场快（约 10 帧，对比入场的约 20 帧）。
5. 每个场景都要使用五层堆叠，从底到顶：背景网格 → 素材 → 图形／文字 → 色彩分级 → 颗粒 + 暗角。绝不使用纯色平面背景。
6. 每张静态图片都要添加 Ken Burns 效果（缓慢缩放 1→1.08 + 平移）。每个视频素材都使用 <OffthreadVideo>，绝不使用 <Video>。
7. 静止元素要有呼吸感：屏幕上停留超过 2 秒的任何元素都要有正弦波微动。
8. 所有时间都必须通过 useVideoConfig() 从 fps 推导。 不得使用固定帧数。
9. 在项目顶部定义一个主题对象（颜色、缓动、弹簧预设、字体）。绝不在组件中内联十六进制颜色或缓动设置。
10. 渲染、提取帧、查看画面、修复、重新渲染。 绝不交付未经验证的渲染结果。此循环是强制要求——参见下方的验证部分。

工作流

步骤 1 — 确定范围

确定：时长、fps（默认 30；仅在动作密集且快速时使用 60）、尺寸（Reels／Shorts 为 1080×1920，横屏为 1920×1080）、现有素材（图片、视频片段、音频、徽标），以及这是新建合成还是编辑现有项目。 如果是编辑现有项目：先完整阅读 src/，找到主题（或创建一个），然后在添加功能前修复违反上述规则的内容。

步骤 2 — 设置

新建项目：

npm install remotion @remotion/cli react react-dom
# optional: @remotion/transitions @remotion/motion-blur @remotion/google-fonts

将此技能中的 assets/theme.ts 复制到 src/theme.ts，并根据用户的品牌调整配色。项目结构：src/index.ts（registerRoot）→ src/Root.tsx（Composition、时长／fps／尺寸）→ src/scenes/*.tsx → src/components/*.tsx。将用户素材放入 public/，并通过 staticFile() 加载。

步骤 3 — 构建

阅读 references/motion-patterns.md，了解可复用组件的实现（BgMesh、Grade、Grain、Vignette、KenBurns、WordReveal、Stagger、Counter、Spark、转场、视差）。基于这些模式组合场景。有关节奏、律动、排版、配色方案和声音设计规则，请阅读 references/design-rules.md。

场景节奏：冲击 → 停留（15–20 帧静止画面）→ 推进 → 冲击。前 15 帧内必须有元素开始运动。不得超过 90 帧没有新的视觉元素出现。

步骤 4 — 渲染

npx remotion render src/index.ts <CompId> out/video.mp4 --codec h264 --crf 17

Remotion 需要 Chromium 二进制文件。如果自动下载失败（沙箱、离线 CI），请找到一个并显式传入：

which chromium chromium-browser google-chrome 2>/dev/null
ls /opt/pw-browsers 2>/dev/null   # Playwright installs live here
npx remotion render ... --browser-executable=<path>

如果完整的 Chrome 报错 "Old Headless mode has been removed"，请改用 headless_shell 二进制文件（Playwright 会附带一个，路径为 chromium_headless_shell-*/chrome-linux/headless_shell）。

步骤 5 — 验证（必做，绝不可跳过）

提取关键时刻的帧，并逐帧目视检查。可移植的方法——无需系统 ffmpeg 即可在机器上运行，并渲染出精确帧：

for f in 15 45 90 150; do
  npx remotion still src/index.ts <CompId> out/check_$f.png --frame $f --overwrite
done

如果系统中有 ffmpeg，也可以从最终 mp4 中提取帧，以验证编码本身（-ss 定位比 select= 筛选器更具可移植性，后者的引号在某些 shell 和 Remotion 捆绑的 ffmpeg 中会出问题）：

ffmpeg -v error -ss 1.5 -i out/video.mp4 -frames:v 1 check_1.png

按出现频率从高到低查找并修复以下问题：

• 间距问题：gap/margin 使用 em 时，会根据父级字号（通常为 16px）计算，而非文本字号——大号文字周围的 flex 容器应使用 px 值。
• 文本溢出或贴到画面边缘（对于 9:16 画面，重要内容应保持在垂直方向中间 75% 的范围内——平台 UI 会遮挡顶部和底部）。
• 元素在入场前或退场后仍可见（缺少 clamp）。
• 颜色/对比度问题：每帧中主色出现在多个元素上，或暗色文本在调色后难以辨认。
• 图层顺序错误（颗粒/暗角必须置于最上层，调色层必须位于内容上方）。 修复 → 重新渲染 → 重新提取 → 重新检查。只有全部检查通过后才能交付。 然后运行 references/design-rules.md 底部的最终检查清单。

编辑用户现有的素材

若要增强现有 mp4（添加字幕、调色、片头/片尾），而不是从头开始构建：将文件放入 public/，使用 <OffthreadVideo src={staticFile("clip.mp4")} /> 将其渲染为素材图层，根据片段长度设置合成时长，并在其上方叠加图形/调色/颗粒效果。设置合成之前，先用 ffprobe 获取片段时长和 fps。要为语音添加与单词同步的字幕，请参阅 references/motion-patterns.md 中的字幕部分。

参考文件

• references/motion-patterns.md — 可直接复制粘贴的组件库：背景、调色/颗粒/暗角、Ken Burns 效果、文字显现、计数器、转场、视差、音频同步、字幕。编写组件前请阅读。
• references/design-rules.md — 调色板、排版规则、场景架构、声音设计、交付前检查清单。设计场景前和最终交付前请阅读。
• assets/theme.ts — 要复制到每个项目中的主题模板。

应主动避免的常见失败模式

• 使用 Emoji 作为图标。 Emoji 会渲染为全彩平台字形（绿色 ✳️、蓝色 🌐），不受调色板约束，并会悄然破坏“一种主色”的规则；它们还会显示在所设定的任意背景上（橙色吉祥物放在橙色底块上 = 看不见）。请使用主题色通过 CSS/SVG 绘制字形，或逐帧核验所有 Emoji。
• 没有 SFX 素材不是交付无声作品的理由。 使用 Node 脚本合成一套精简音效素材，保存为 16 位 WAV（噪声脉冲呼啸声、降调弹出声、正弦波重击踢鼓/低音、微失谐正弦波铺底），放入 public/sfx/——请参阅代码库中的 examples/scripts/。无需下载，完全可重复生成。
• 生成一个庞大的组件，而不是主题统一、可复用的组件。
• durationInFrames 与 Composition 和场景内容的时长不匹配（出现空白时段）。
• 重新渲染时忘记添加 --overwrite，之后检查的还是旧文件。
• 字体：主视觉文字绝不要依赖系统默认字体；通过 @remotion/google-fonts 或 @font-face + staticFile 加载展示字体。
• 只向用户“描述”结果，而不实际渲染并验证。