synthetic-screen-recording

合成屏幕录制（Remotion TerminalScene）

此技能解答的问题： 当用户想要一段看起来像终端、CLI 工具或编码工作流的屏幕录制演示时，我应该录制真实桌面（通过 screen_recorder、Windows-MCP、Cap 或 Playwright 进行操作系统屏幕录制），还是使用 TerminalScene 组件在 Remotion 中合成演示？

经验法则： 如果 Agent 能预先编写精确的命令／输出序列，就进行合成。只有当实际行为不可预测、需要真实应用 UI，或用户明确要求真实录制时，才进行实时录制。

为什么需要它

OpenMontage 展示项目的 v3 版尝试使用 Windows-MCP + screen_recorder 驱动 Git-Bash 窗口来演示安装过程，但卡在窗口定位、焦点竞争和任务栏隐私问题上。于是我们改为完全通过 Remotion 渲染——使用一个名为 TerminalScene 的 React 组件绘制虚拟终端，并逐字符输入命令。输出在视觉上与真实屏幕录制无异（相同的红黄绿窗口装饰、闪烁光标和滚动输出），但具有确定性、保护隐私、在 1080p 下像素级精准，并且可以精确控制每一帧的节奏。

该组件及其模式正是此技能要帮助发现的能力。

何时使用合成（TerminalScene）

适合合成的场景：

• 演示内容是终端／CLI／编码会话，命令和输出可预测
• 用户想要精致的教程风格（清晰的字体、悬浮徽标、光标闪烁）
• 安装演示、设置演示、API 密钥配置、make 目标、git clone 流程
• 需要与旁白紧密同步——每条命令都必须在特定节拍出现
• 希望结果可复现（重新渲染会得到完全相同的像素）
• 用户的真实桌面上显示着私人应用／窗口，否则就必须裁剪画面

适合录制真实屏幕的场景：

• 演示内容是无法伪造的真实应用 UI（Figma、Photoshop、具有实时状态的 Web 应用、浏览器流程）
• 用户明确要求录制其实际屏幕
• 行为取决于无法脚本化的时序（大模型流式输出、真实网络延迟）
• 存在只有在实时环境中才会出现的视觉细节（光标效果、插件弹窗）

浏览器演示 → 使用 playwright-recording 技能，而不是本技能。 真实桌面 → 使用 screen_recorder 工具或通过 cap_recorder 使用 Cap。

组件 — TerminalScene

位于：remotion-composer/src/components/TerminalScene.tsx 导出自：remotion-composer/src/components/index.ts 接入调度：remotion-composer/src/Explainer.tsx（if (cut.type === "terminal_scene")）

属性：

interface TerminalSceneProps {
  title?: string;           // shown in the window title bar
  steps: TerminalStep[];    // the timeline
  prompt?: string;          // "$", ">", etc.
  accentColor?: string;     // pill + prompt glow
  backgroundColor?: string;
}

步骤类型：

{ kind: "cmd",   text: string, typeSpeed?: number, holdSeconds?: number }
{ kind: "out",   text: string, holdSeconds?: number }
{ kind: "pause", seconds: number }
{ kind: "pill",  text: string, color?: string, durationSeconds?: number }

• cmd — 输出提示符，逐字符输入文本（typeSpeed 表示每个字符的秒数，默认为 0.035），然后停留 holdSeconds（默认为 0.3）
• out — 一行程序输出，带短暂淡入效果，即时显示
• pause — 静止时间。终端停留在最后一个可见状态。请用它与旁白同步。
• pill — 非阻塞悬浮徽标（右上角）。弹入、停留、弹出。不会推进光标——下一步会并行运行。

编写模式

通过向 build_composition.py（或等效的属性构建器）添加一个 cut 来编写新场景：

install_steps = [
    {"kind": "pause", "seconds": 7.0},                 # wait for intro narration
    {"kind": "cmd", "text": "git clone https://github.com/calesthio/OpenMontage.git",
     "typeSpeed": 0.045, "holdSeconds": 0.3},
    {"kind": "out", "text": "Cloning into 'OpenMontage'..."},
    {"kind": "out", "text": "remote: Enumerating objects: 2847, done."},
    {"kind": "pill", "text": "repo cloned", "color": "#34D399", "durationSeconds": 2.6},
    {"kind": "pause", "seconds": 3.8},                 # bridge to next narration cue
    # ...
]

cuts.append({
    "id": "install-terminal",
    "type": "terminal_scene",
    "terminalTitle": "bash — OpenMontage setup",
    "prompt": "$",
    "accentColor": "#22D3EE",
    "steps": install_steps,
    "in_seconds": 50.0,
    "out_seconds": 110.0,
})

规则：节奏跟随旁白，绝不超前

**头号失败模式：**步骤连续运行，在场景前 40% 就耗尽所有内容，导致终端在剩余 60% 时间里冻结。这正是 v3 首轮失败的原因——功能菜单在 t=80s 时已渲染出来，但旁白直到 t=92s 才介绍它。

请这样做：

1. 了解旁白提示点——为每个场景记下每段旁白的准确视频时间。
2. 先加入暂停，确保在第一个旁白提示点到来前没有命令开始输入。
3. 让每条命令的时机与旁白对应——cmd 应在旁白说到对应内容时开始输入，而不是提前输入。
4. 在命令组之间加入暂停，衔接到下一个旁白提示点。
5. 结尾留出停顿——暂停足够长，让观众在旁白结束后能看清最终状态。

渲染前检查步骤是否合理——Remotion 的每一分钟渲染都很宝贵。把步骤时长相加，确认总时长与场景时长相等：

import math
def trace(steps, scene_start, fps=30):
    t = 0.0
    for s in steps:
        k = s["kind"]
        if k == "cmd":
            tf = math.ceil(len(s["text"]) * s.get("typeSpeed", 0.035) * fps)
            t += tf / fps + s.get("holdSeconds", 0.3)
        elif k == "out":
            t += max(2, math.ceil(0.08 * fps)) / fps + s.get("holdSeconds", 0.15)
        elif k == "pause":
            t += s["seconds"]
        # "pill" is non-blocking — does NOT advance cursor
        print(f"  {t + scene_start:6.2f}s  {k}: {s.get('text', '')[:40]}")
trace(install_steps, 50)

查看输出列。每个旁白提示点的视频时间都应紧邻其所介绍的命令／输出。如果某条命令比提示点早或晚 10s，就调整暂停时长。

请参阅 lib/verify_scene_pacing.py，获取可重复使用的脚本版本。

设计规则（继承自 v3 调整版）

• 开场暂停——每个终端场景开始时，至少留出 2s 的空终端和闪烁光标，然后才开始输入。观众需要时间注意到窗口。
• 提示徽标时机——提示徽标应在其所标示的事件于屏幕上完成的确切时刻出现（例如，最后一行 Receiving objects 出现后立即显示 repo cloned）。提示徽标是对真实 UI 通知的替代。
• 输入后的命令停留时间——每个 cmd 的 holdSeconds 都应 ≥ 0.3，让观众在首条输出滚入前看清已输入完成的命令。
• 输出节奏——输出行的 holdSeconds 应在 0.4 到 1.0 之间。输出滚动过快会让人觉得像出了故障，过慢则会令人厌倦。
• 自动滚动有效——终端会保留最近的 18 行。无需担心屏幕外的内容。
• 输入过程中，光标只在最新的命令行上闪烁；输入结束后还会继续闪烁约 0.2s。

ProviderChip（配套组件）

.agents/skills/synthetic-screen-recording 模式还包含 ProviderChip——一种循环切换徽标覆盖层，会按固定节奏轮流显示提供商名称列表。v3 展示版在“generated motion”部分使用它，轮流展示全部 11 个 AI 视频生成提供商。

overlays.append({
    "type": "provider_chip",
    "providers": ["Veo 3.1", "Seedance 2.0", "Kling 2.5", ...],
    "cycleSeconds": 2.5,
    "position": "bottom-right",
    "accentColor": "#22D3EE",
    "label": "generated with",
    "in_seconds": 195.0,
    "out_seconds": 222.5,
})

接入位置：remotion-composer/src/Explainer.tsx 的覆盖层渲染器（overlay.type === "provider_chip"）。

添加新的合成 UI 组件

此模式可推广使用。当你需要模拟其他 UI 界面时（Claude Code 聊天气泡、Jira 工单视图、GitHub PR 差异、Slack 消息、VS Code 状态栏）：

1. 将 TerminalScene.tsx 复制为模板。
2. 为相关时间轴基元定义一个 steps 接口。
3. 将 frame 与累计的开始／结束时间进行插值，渲染每个步骤。
4. 在 Explainer.tsx 的 SceneRenderer 分发中接入它，并添加新的 cut.type。
5. 在 Explainer.tsx 的 Cut 接口和 components/index.ts 中添加该类型。
6. 在此技能中新增一个章节进行说明。
7. 使用新的 cut 类型更新 remotion-composer/SCENE_TYPES.md。

相关技能

• .agents/skills/remotion — Remotion 通用编写指南（hooks、springs、sequences）
• .agents/skills/playwright-recording — Web 应用的真实浏览器流程录制
• tools/capture/screen_recorder — 基于 ffmpeg 的桌面录制
• tools/capture/cap_recorder — Cap.so 精修桌面录制
• skills/pipelines/screen-demo/asset-director.md — 为屏幕演示项目选择合成或真实录制方式

来源

引入版本：OpenMontage showcase v3 渲染（2026-04-16）。最初的动机：v3 设置引导部分需要一个 60 秒的安装演示，其中每条命令都与 Chirp 3 HD 旁白提示同步，而由 Windows-MCP 驱动的实际捕获在实践中太不稳定。参考实现见 projects/openmontage-showcase/build_composition.py。