Stitch + Remotion Walkthrough 视频合成检查清单：composition-checklist 完整解读与实战

• AI 技能
• AI 插件

导读：本文以 stitch-skills 仓库中 remotion 技能所附的 composition-checklist.md 为核心骨架，系统讲解如何用 Remotion 把 Stitch 项目截图编排成带转场、缩放与文字覆盖的 Walkthrough 演示视频。读完你将掌握从项目初始化、素材准备、组件编写、动画配置、预览调试到最终渲染的完整质量关卡，并了解每一关背后的仓库源码与脚本实现。

该清单是 remotion 技能工作流的"质量门禁"：技能的 SKILL.md 负责告诉 Agent 如何检索 Stitch 屏幕、搭建 Remotion 工程、生成组件并渲染，而这份清单负责在每一步交付前逐项自检，确保合成结构完整、动画流畅、输出专业。它不是一次性读完就扔的文档，而是每次生成 Walkthrough 视频时都要对照执行的"完工验收表"。

一、清单定位：为什么需要一份合成检查清单

Remotion 是一套用 React 写视频的编程式视频库，而 stitch-skills 的 remotion 技能把它的能力与 Google Stitch（UI 设计平台）打通：Agent 通过 Stitch MCP 拉取项目中每个屏幕的截图与元数据，再在 Remotion 工程里把它们编排为带转场、缩放和文字注释的演示视频。

这类"多屏幕合成"任务最容易在以下环节出错：

• 素材缺失或路径写错（截图没下载全、public/相对路径对不上）；
• 组件结构不完整（缺ScreenSlide或主合成，转场没接上）；
• 时序计算错误（帧率、时长、转场偏移不匹配）；
• 动画参数不自然（spring 阻尼/刚度不合适，画面生硬）；
• 渲染前才发现构建错误。

composition-checklist 正是为此设计：把整个生产流程切成 13 个自检区块，每个区块内有可勾选的验收项，从项目搭建一直覆盖到最终成片与可选增强，让 Agent 和人类开发者都能在渲染前发现隐患。清单末尾的 Notes 还明确建议：每完成一项就把[ ]改为[x]，并允许针对具体项目追加自定义检查项。

二、阶段一：项目初始化与依赖（Project Setup）

清单的第一组勾选项是视频工程的"地基"：

• Remotion 项目已初始化（或已有工程已确认可用）
• 依赖已安装（@remotion/transitions等）
• 素材目录已创建（public/assets/screens/）
• 屏幕清单已创建（screens.json）

对应到 SKILL.md 中的实际操作：

# 没有现成工程时，用官方模板创建空白 TypeScript 工程 npm create video@latest -- --blank # 进入工程后安装转场等核心依赖 cd video npm install @remotion/transitions @remotion/animated-emoji

这里有两个关键约定：

1. 素材必须放在public/assets/screens/：Remotion 的静态资源加载以public/为根，清单中imagePath写的是相对public/的路径（如assets/screens/home.png），这样<Img>组件才能正确解析；
2. screens.json是"单一事实来源"：项目名、视频配置、每屏的标题/描述/尺寸/时长/转场类型全部由它驱动，组件代码只负责消费它，从而避免在组件里硬编码任何数值——这正是清单"Best Practices Verified"区块中"No hardcoded values"的落地方式。

仓库 examples/screens.json 给出了黄金标准结构：

{ "projectName": "Calculator App", "projectId": "projects/13534454087919359824", "videoConfig": { "fps": 30, "width": 1920, "height": 1080, "durationInSeconds": 20 }, "screens": [ { "id": "1", "screenId": "12345", "title": "Home Screen", "description": "Main calculator interface with number pad and basic operations", "imagePath": "assets/screens/home.png", "width": 1200, "height": 800, "duration": 5, "transitionType": "fade" }, { "id": "2", "screenId": "12346", "title": "History View", "description": "View of previous calculations with option to reuse results", "imagePath": "assets/screens/history.png", "width": 1200, "height": 800, "duration": 4, "transitionType": "slide" } ] }

注意清单中的结构比 SKILL.md 里的简版示例更完整：除了每屏的duration（停留秒数），还多了transitionType（每屏可单独指定 fade / slide / zoom）和videoConfig（全局 fps、画幅、总时长）。durationInSeconds是参考值，实际总帧数通常由组件端按各屏时长累加计算。

三、阶段二：素材准备（Asset Preparation）

清单要求逐项核对：

• 所有 Stitch 截图已下载
• 图片使用有描述性的命名
• 图片尺寸已记录到清单
• 图片已按需优化体积
• 素材路径正确且相对public/书写

3.1 下载截图

Stitch MCP 的get_screen会返回screenshot.downloadUrl（以及可选的htmlCode.downloadUrl、屏幕width/height和标题描述）。下载有两种方式：直接web_fetch，或使用 Bash 调 curl。仓库为此提供了专用脚本 download-stitch-asset.sh：

./download-stitch-asset.sh "https://storage.googleapis.com/..." "assets/screens/home.png"

该脚本有两个值得注意的工程细节：

• curl -L -f组合：-L跟随重定向（Stitch 的签名 URL 常见跳转），-f让 HTTP 错误直接失败——防止"下载到一张错误页却当成素材保存"；
• 下载后立即打印文件大小：用stat做跨平台取 size 的回退，方便 Agent 判断是否拿到了完整的高清图而不是残缺文件；
• 失败即清理：下载失败时删除残留的OUTPUT_PATH并退出非零码，避免脏文件进入public/assets/screens/。

3.2 命名与记录

"描述性命名"指按屏幕语义命名（如home.png、history.png），而非screenshot-1.png；"尺寸记录到清单"指把 Stitch 返回的width/height写进screens.json对应条目，供后续等比缩放与文字定位使用。图片优化（压缩、选格式）则遵循清单 Best Practices 中的原则：UI 截图用 PNG，照片类用 JPG。

四、阶段三：组件结构（Component Structure）

清单的核心组件关卡：

• ScreenSlide.tsx已创建
  • Props 接口已定义
  • 缩放动画已实现
  • 淡入淡出动画已实现
  • 文字覆盖已包含
• WalkthroughComposition.tsx已创建
  • 已导入屏幕清单
  • 每屏使用<Sequence>组件
  • 屏间转场已配置
  • 时序偏移已正确计算

4.1 ScreenSlide：单屏展示组件

按 SKILL.md 的架构约定，ScreenSlide.tsx的 props 为imageSrc、title、description、width、height，内部用 Remotion 的useCurrentFrame()与spring()实现缩放入场、淡入淡出与文字覆盖，默认每屏展示 3~5 秒（可在清单中按屏调整）。TS 接口化 props 正是清单"TypeScript interfaces used for props"项的要求。

4.2 WalkthroughComposition：主合成组件

仓库 examples/WalkthroughComposition.tsx 给出了可直接照抄的黄金标准实现，它同时回答了清单里"Sequence 组件、转场配置、时序偏移"三个勾选项：

import {Composition} from 'remotion'; import {Sequence} from 'remotion'; import {fade} from '@remotion/transitions/fade'; import {slide} from '@remotion/transitions/slide'; import {TransitionSeries} from '@remotion/transitions'; import {ScreenSlide} from './ScreenSlide'; import screensManifest from '../screens.json'; // Calculate total duration in frames const calculateDuration = () => { const totalSeconds = screensManifest.screens.reduce( (sum, screen) => sum + screen.duration, 0 ); return totalSeconds * screensManifest.videoConfig.fps; }; export const WalkthroughComposition: React.FC = () => { const {fps, width, height} = screensManifest.videoConfig; return ( <TransitionSeries> {screensManifest.screens.map((screen, index) => { const durationInFrames = screen.duration * fps; // Select transition based on screen config const transition = screen.transitionType === 'slide' ? slide() : screen.transitionType === 'zoom' ? fade() // Can customize with zoom effect : fade(); return ( <TransitionSeries.Sequence key={screen.id} durationInFrames={durationInFrames} > <ScreenSlide imageSrc={screen.imagePath} title={screen.title} description={screen.description} width={screen.width} height={screen.height} /> {index < screensManifest.screens.length - 1 && ( <TransitionSeries.Transition presentation={transition} timing={{ durationInFrames: 20, // 20 frames for transition }} /> )} </TransitionSeries.Sequence> ); })} </TransitionSeries> ); };

这段代码揭示了清单勾选项背后的三个要点：

1. TransitionSeries才是转场的正确载体：它来自@remotion/transitions，与裸<Sequence>的区别在于能在前后两段之间插入<TransitionSeries.Transition>，实现真正的重叠转场而非生硬切换；
2. 转场类型由清单数据驱动：transitionType为slide用slide()，zoom或fade落到fade()（注释提示 zoom 可自定义缩放效果），完全契合"No hardcoded values"原则；
3. "时序偏移"的计算公式：durationInFrames = screen.duration * fps，而总时长calculateDuration()累加所有屏幕的秒数再乘 fps——因此清单中remotion.config.ts的 duration 必须与这个计算结果一致，否则合成会在结尾出现空帧或截断。

示例末尾的RemotionRoot把合成注册进Composition（id="WalkthroughComposition"、fps/width/height均取自videoConfig），这就是阶段四配置检查的依据。

五、阶段四：合成配置（Configuration）

清单要求核对：

• remotion.config.ts已更新
  • Composition ID 已设置
  • 视频尺寸已配置
  • 帧率已设置（30 或 60 fps）
  • 时长计算正确
• 视频元数据已设置（如适用）
  • 标题
  • 描述

Composition ID就是npx remotion render <ID>时使用的标识符，仓库示例固定为WalkthroughComposition；尺寸直接复用videoConfig.width/height（示例为 1920×1080，与 Stitch 屏幕 1200×800 存在比例差，需按"Maintain aspect ratio"原则等比缩放）；帧率建议 30 或 60 fps——60 fps 尤其用于修复清单"Common Issues"中的顿挫动画问题；时长必须与calculateDuration()的输出一致。

元数据（标题/描述）写入输出文件的标签信息，用于发布到 YouTube 等平台时的自动填充，属于"Final Output"阶段"Metadata embedded"项的前提。

六、阶段五：动画与转场（Animations & Transitions）

清单的质量关卡：

• Spring 动画使用合适配置
  • Damping 值（典型 8~15）
  • Stiffness 值（典型 60~100）
• 转场流畅平滑
• 文字覆盖时序正确
• 无突兀、生硬的画面变化

6.1 Spring 参数区间

Remotion 的spring()是物理弹簧动画，两个核心参数的经验区间在清单中被明确定死：

SKILL.md 的 Hotspot 示例给出了基准配置{damping: 10, stiffness: 100}，可用于缩放强调动画。若画面"choppy"，清单建议升到 60 fps 并重新校准这两个值。

6.2 转场与文字时序

转场用@remotion/transitions的三种效果：fade（交叉淡入淡出）、slide（方向性滑入）、zoom（用 spring 驱动的缩放强调）。示例中单次转场占 20 帧（约 0.67s @30fps），节奏适中。文字覆盖（屏幕标题、功能标注、描述文字、进度指示）必须与所在屏幕的duration对齐，淡入淡出时间要留给读者阅读，否则就是清单"Text has time to be read"项的失败。

七、阶段六：视觉质量（Visual Quality）

清单的视觉验收项：

• 文字任何时刻均可读
• 文字与背景对比度足够
• 字号适配视频分辨率
• 图片无变形
• 宽高比保持

这些项的实践依据：字号要按最终输出分辨率（如 1920×1080）而非原始屏幕尺寸设计；图片放进合成时若强制拉伸会破坏宽高比，应等比缩放或使用object-fit类策略；文字叠层应避免与截图内容同色，必要时加半透明背景条提升对比度——这与 SKILL.md Best Practices 第 3 条"Readable text"一一对应。

八、阶段七：节奏把控（Timing）

清单要求：

• 每屏展示时长合适
• 视频总长度合理（不过长/过短）
• 转场不显得仓促
• 文字有足够阅读时间

SKILL.md 的常见模式给出了节奏基准：每屏 3~5 秒、转场采用交叉淡入淡出；需要强调的屏幕可延长至 5 秒以上（示例清单中 Home 与 Scientific 均为 5s，其余 4s）。清单"Consistent timing"最佳实践提示：除非刻意强调某屏，否则保持各屏时长一致。总长度需考虑目标平台习惯（如社交媒体短视频应控制在数十秒内），示例工程 4 屏合计 20 秒即属合理区间。

九、阶段八：预览与测试（Preview & Testing）

清单的调试关卡：

• 在 Remotion Studio 中预览（npm run dev）
• 拖动时间线检查所有帧
• 确认播放流畅
• 检查渲染错误
• 在多种屏幕尺寸下测试（若响应式）

npm run dev启动 Remotion Studio 浏览器预览，是 SKILL.md 执行步骤第三步"Preview and Refine"的核心：Agent 在此实时调整每屏时长、转场平滑度与文字时序。时间线逐帧检查能提前暴露清单 Common Issues 中的模糊图、错位文字与断帧问题——所有问题都应在这个阶段解决，而不是留到渲染阶段。

十、阶段九：渲染与最终输出（Rendering & Final Output）

清单的收尾关卡：

• 渲染命令已测试且可用
• 输出格式已选择（MP4、WebM 等）
• 质量设置已配置
• Codec 已指定（推荐 h264）
• 最终视频无错误渲染成功
• 视频文件生成成功
• 文件大小合理
• 视频可在播放器中正常播放
• 已包含音频（如适用）
• 已嵌入元数据（如需）

对应 CLI 渲染方式（SKILL.md 执行步骤第四步）：

npx remotion render WalkthroughComposition output.mp4

可用优化参数：--quality（质量档位）、--codec h264（推荐）或h265（体积更小但兼容性略低）、--concurrency（并行渲染加速）。选择 MP4 + h264 是目前跨平台播放兼容性最好的组合；WebM 适合体积敏感的场景。文件大小应在渲染后核验，异常巨大通常意味着码率或分辨率设置偏高。音频（背景音乐/旁白）与元数据（标题/描述）按需在渲染阶段一并处理。

十一、可选增强（Optional Enhancements）

清单的可选加分项，全部在 SKILL.md Advanced Features 中有对应实现方案：

• 进度指示器（显示当前屏位）
• 自定义 Logo 或品牌标识
• 背景音乐或音效
• 旁白配音
• 交互热点（高亮功能区域）
• 片尾行动号召（CTA）

交互热点是其中最具"产品演示"价值的一项，SKILL.md 给出了骨架代码：

import {interpolate, useCurrentFrame} from 'remotion'; const Hotspot = ({x, y, label}) => { const frame = useCurrentFrame(); const scale = spring({ frame, fps: 30, config: {damping: 10, stiffness: 100} }); return ( <div style={{ position: 'absolute', left: x, top: y, transform: `scale(${scale})` }}> <div className="pulse-ring" /> <span>{label}</span> </div> ); };

旁白配音流程为：由屏幕描述生成配音脚本 → 文本转语音或录音 → 用 Remotion<Audio>组件导入 → 让屏幕切换节奏与配音语速对齐。动态文字提取则可下载 Stitch 的htmlCode.downloadUrl，解析出标题、按钮、标签等文本，自动生成定时文字标注，减少手写文案成本。

十二、最佳实践与常见问题（Best Practices & Common Issues）

12.1 最佳实践验收

清单要求最终核对工程规范：

• 组件代码模块化、可复用
• Props 使用 TypeScript 接口
• 无硬编码值（一律使用清单/配置）
• 代码遵循 Remotion 惯例
• 复杂逻辑添加注释
• 素材组织在清晰的目录结构中

这与示例代码直接呼应：WalkthroughComposition.tsx里calculateDuration有注释、转场选择逻辑是数据驱动的、目录结构按video/src/、video/public/assets/screens/、根目录screens.json、output.mp4组织（完整结构见 SKILL.md 的 File Structure 与 README.md）。

12.2 常见问题排查

清单的"Common Issues Checked"（无模糊图、无文字错位、无动画顿挫、无素材缺失、无构建错误）对应到 SKILL.md Troubleshooting 表中的完整解法：

素材缺失类问题可从源头避免：download-stitch-asset.sh的curl -f失败即删，防止坏文件混入；构建错误则以npm run build作为最终冒烟测试。

十三、如何使用这份清单

该清单是 remotion 技能的标准参考资源，被 SKILL.md 明确引用为"Followresources/composition-checklist.mdfor completeness"。使用方式：

1. Agent 工作流中：remotion 技能执行到组件生成、配置、预览、渲染各步骤时，对照清单逐项勾选，未通过的项先修复再进入下一阶段；
2. 人工开发中：以[x]标记已完成项，按 Notes 建议追加项目专属检查项（如特定平台的画幅要求、内部品牌规范），并在目标平台（YouTube、社交媒体等）做最终播放测试；
3. 作为验收报告：渲染完成后，把勾选完毕的清单作为交付质量的依据。

该技能的整体定位与安装方式可参见 README.md（npx skills add google-labs-code/stitch-skills --skill remotion --global）以及仓库根 README.md 中stitch-build插件的能力矩阵；composition-checklist.md与其配套的黄金示例（WalkthroughComposition.tsx、screens.json）、素材下载脚本（download-stitch-asset.sh）共同构成了一套"清单驱动、示例佐证、脚本兜底"的完整视频生产链路。

结论：这份 checklist 的价值不在于列了多少项，而在于它把"看起来专业"拆解成了可勾选、可验证、可复用的工程标准。从工程初始化到最终成片，每一项都有仓库源码或示例作为落地依据；照单执行，即可稳定产出无模糊、无错位、节奏流畅、渲染零错误的 Stitch Walkthrough 演示视频。

• AI 技能
• AI 插件