SuperAPI AI 工具集

synthetic-screen-recording

编程与开发

查看项目

更新于 11-15 04:50

技能介绍

Synthetic Screen Recording(Remotion TerminalScene)

用途

该技能回答一个选型问题:当用户想要一段看起来像屏幕录制的终端、CLI 工具或编码流程演示时,应该捕获真实桌面,还是在 Remotion 中用 TerminalScene 组件合成?

判断原则:如果智能体能够提前编写出确切的命令与输出序列,就合成;只有当真实行为不可预测、需要真实应用界面,或用户明确要求真实录制时,才进行实拍。

为什么使用它

OpenMontage 展示视频 v3 曾尝试用 Windows-MCP 与 screen_recorder 驱动 Git-Bash 窗口录制安装演示,但卡在窗口定位、焦点竞争和任务栏隐私问题上。后来改为纯 Remotion 渲染:由 TerminalScene 组件绘制一个假终端并逐字符敲出命令,输出在视觉上与真实录屏难以区分(同样的交通灯窗口边框、闪烁光标、滚动输出),但具备确定性、隐私安全、1080p 像素精确、可按帧控制节奏的特点。

何时合成、何时真实捕获

适合合成:命令与输出可预测的终端、CLI 或编码演示;需要精致教程观感(干净排版、浮动胶囊、光标闪烁);安装引导、环境配置、API key 设置、make 目标、git clone 流程;需要与旁白严格同步;需要可复现渲染结果;真实桌面中存在不宜展示的私有窗口。

适合真实捕获:无法伪造的真实应用界面(Figma、Photoshop、带实时状态的 Web 应用、浏览器流程);用户明确要求录自己的屏幕;依赖无法脚本化的时序(流式大模型输出、真实网络延迟);只在真实环境中出现的视觉细节。浏览器演示应使用 playwright-recording 技能,真实桌面应使用 screen_recorder 或 cap_recorder。

组件 TerminalScene

位置:remotion-composer/src/components/TerminalScene.tsx;从 remotion-composer/src/components/index.ts 导出;在 remotion-composer/src/Explainer.tsx 中通过 cut.type === "terminal_scene" 接入调度。

属性:

interface TerminalSceneProps {
  title?: string;           // 显示在窗口标题栏
  steps: TerminalStep[];    // 时间线
  prompt?: string;          // "$"、">" 等
  accentColor?: string;     // 胶囊与提示符光晕颜色
  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},                 # 等待开场旁白
    {"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},                 # 衔接到下一个旁白提示
    # ...
]

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% 终端冻结。做法是:先记录每个场景中每段旁白开始的精确视频时间;以一个 pause 开场,等到第一条旁白提示出现后再输入任何命令;让每条命令在其旁白播出的时刻开始输入;在命令组之间插入 pause 衔接到下一旁白提示;结尾保留足够长的 pause,让旁白结束后最终状态仍可阅读。

渲染前用脚本核算总时长是否与场景时长一致:

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" 非阻塞,不推进光标
        print(f"  {t + scene_start:6.2f}s  {k}: {s.get('text', '')[:40]}")
trace(install_steps, 50)

检查输出列中每条旁白提示的视频时间是否与其命令或输出相邻,偏差过大时调整 pause。可复用脚本见 lib/verify_scene_pacing.py。

设计规则

  • 开场停顿:每个终端场景至少先展示 2 秒仅带闪烁光标的空终端,让观众识别窗口。
  • 胶囊时机:胶囊应在对应事件于屏幕上完成的瞬间触发,用于替代真实 UI 通知。
  • 命令后保持:每个 cmd 的 holdSeconds 保持 ≥ 0.3,让观众看清命令后再滚动输出。
  • 输出节奏:输出行的 holdSeconds 建议在 0.4 到 1.0 之间;过快像故障,过慢显无聊。
  • 自动滚动:终端保留最近 18 行,无需担心屏幕外内容。
  • 光标仅在最新命令行输入时闪烁,输入完成后约 0.2 秒内停止。

配套组件 ProviderChip

该技能模式还包含 ProviderChip:一个按固定节奏轮播供应商名称的徽章覆盖层,v3 展示视频曾用它轮播 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 diff、Slack 消息、VS Code 状态栏):复制 TerminalScene.tsx 作为模板;为相关时间线原语定义 steps 接口;按累计起止时间对帧做插值渲染每个步骤;在 Explainer.tsx 的 SceneRenderer 调度中接入新的 cut.type;在 Explainer.tsx 的 Cut 接口和 components/index.ts 中添加类型;在本文档中新增章节;更新 remotion-composer/SCENE_TYPES.md 中的 cut 类型。

相关技能

  • .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 展示视频 v3 渲染(2026-04-16)。原始动机:v3 的安装引导部分需要一段 60 秒安装演示,每条命令都要与 Chirp 3 HD 旁白提示对齐,而 Windows-MCP 驱动的真实捕获在实践中过于不稳定。参考实现见 projects/openmontage-showcase/build_composition.py。