aidemo

aidemo — 由你的编码 Agent 制作演示视频

aidemo.top · 观看真实的 51s 输出 ▶ · 编写指南 · 在 CI 中渲染

告诉你的编码 Agent “录制一段 45s 的结账流程演示”，即可获得一段 精致的 MP4，带配音、同步字幕和自动缩放。任何支持 MCP 的 Agent（Claude Code、Codex CLI、Gemini CLI）都会编写一个 storyboard.json；无头引擎会驱动真实的 Chrome，录制确定性回放，为其配音、添加字幕并剪掉多余片段。由于回放具有确定性，产品变更时，演示可在 CI 中重新渲染——无需重新录制，无需 API 密钥，每次渲染约 0 美元。这是一个**开源（MIT）**替代方案，可取代 Screen Studio、Clueso 或 Demosmith，适合希望让编码 Agent 制作演示的场景。

安装： Claude Code /plugin marketplace add tandryukha/aidemo · 任意 Agent npx skills add tandryukha/aidemo（仅安装技能；使用 repo-init 添加 MCP 服务）· CI uses: tandryukha/aidemo@stable · CLI npx -y @tandryukha/aidemo · Homebrew brew install tandryukha/aidemo/aidemo
已发布至 GitHub Marketplace、npm、Homebrew tap 和 MCP Registry。

_{真实输出——一段约 51 s、带自述旁白的 Wikipedia 游览（门户搜索 → Ada Lovelace → 聚焦缩放 → 点击进入 Analytical Engine 页面 → 平滑滚动），由 Claude 根据一个 storyboard.json 编写，并以确定性回放方式录制。预览 GIF 没有声音； 观看带旁白的完整版本 ▶。}

三种使用方式

1. 通过编码 Agent 使用——最快的方式。在 Claude Code 中： /plugin marketplace add tandryukha/aidemo，然后 /plugin install record-demo@aidemo（同时包含技能 和 MCP 服务）。在 Codex / Gemini / 任意 MCP Agent 中： npx -y github:tandryukha/aidemo#stable repo-init。然后只需说 “录制一段 45s 的 <flow> 演示”，Agent 就会编写并渲染演示。
2. 本地免费离线使用—— AIDEMO_TTS_PROVIDER=local aidemo render <dir> --headless。进程内语音模型搭配按脚本定时的字幕，意味着无需 API 密钥，费用约为 $0，完全离线。 请参阅 docs/LOCAL_MODELS.md。
3. 在 CI 中自维护——将 uses: tandryukha/aidemo@stable 放入 工作流。产品变更时，它会重新播放已提交的分镜脚本并提交新媒体——在免费运行器时长内无需密钥、无需 LLM 令牌，费用约为 $0。 请参阅 docs/CI.md。

免费且开源。采用 MIT 许可证。可在 GitHub 免费 Actions 层级上运行，也可完全在本地以 $0 运行，并使用进程内语音——无需 API 密钥、无需上传到云端、无遥测。适用于localhost 和有身份验证限制的应用（使用你自己的 Chrome）。

从一句话到带旁白的 MP4

你输入一句话，Agent 会编写一份可阅读和编辑的产物，渲染引擎负责录制并剪辑：

1 · 你输入的内容——向任意支持 MCP 的 Agent 输入一行文字（此处以 Claude Code 为例）：

claude "record a 45s demo touring Wikipedia: search for Ada Lovelace,
open the Analytical Engine, then glide down the article"

2 · Agent 编写的内容——一份简单、可编辑的 storyboard.json（摘录： 旁白与固定的浏览器操作规范并列呈现——不含生成的代码）：

{
  "title": "A quick tour of Wikipedia",
  "zoom": {},                                  // Screen-Studio-style auto-zoom
  "scenes": [
    { "id": "search",
      "narration": "Start at the Wikipedia portal and search for Ada Lovelace.",
      "actions": [
        { "op": "goto", "url": "https://www.wikipedia.org/" },
        { "op": "type", "target": { "selector": "#searchInput" }, "text": "Ada Lovelace" },
        { "op": "click", "target": { "selector": "button[type=submit]" } } ] },
    { "id": "engine",
      "narration": "Her notes on Babbage's Analytical Engine hold the first computer program.",
      "actions": [
        { "op": "focus", "target": { "selector": "#firstHeading" } },
        { "op": "click", "target": { "selector": "a[href*='Analytical_Engine']" } },
        { "op": "scrollBy", "dy": 900, "easing": "glide" } ] }
  ]
}

3 · 录制和剪辑方式——aidemo render 驱动真实的 Chrome（平滑的动画光标、符合人类节奏的输入、自动缩放），然后剪掉空白时段并与旁白同步：

storyboard.json
   → voice     OpenAI / ElevenLabs / local TTS → audio/narration.mp3 + voice.json
   → record    drives Chrome, animated cursor  → recordings/raw.{webm,mp4} + timeline.json
   → captions  Whisper word timestamps         → generated/captions.{srt,vtt,cues.json}
   → compose   trim idle · sync · auto-zoom · cards · caption · mux → output/final-demo.mp4

4 · 最终产物——output/final-demo.mp4，以及可直接用于 README 的 GIF （aidemo gif）和从同一录制片段生成的命名静帧（aidemo stills）。界面有变化？ 针对同一份分镜脚本重新运行即可——无需手动重新录制。

设计目标：制作看起来像人工制作、节奏明快的演示，而不是像 AI 在界面上乱点、在截图之间等待——通过将编写（耗时，只需一次——理清流程）与录制（快速、确定性的重放，配有平滑动画光标）分开实现。

团队如何使用它进行渲染

• GitHub README 演示——aidemo gif demos/onboarding，将自动播放的 GIF 放入 readme（本页面上的 GIF 正是如此生成的）。
• 落地页主视觉视频——aidemo.top 上静音自动播放的 MP4 是渲染生成的演示，包含封面帧等内容。
• 发布 / 新功能演示——为新功能配上旁白，然后运行 gh release upload v1.4.0 demos/whats-new/output/final-demo.mp4。
• 客户和潜在客户演示——针对真实应用的个性化流程： localhost、有身份验证限制的应用、已登录的自有 Chrome；内容不会离开本机。

在 CI 中渲染（自维护演示）

提交一份分镜脚本后，aidemo GitHub Action 会让演示媒体保持同步——每次相关变更后，都会生成新的带旁白、带字幕的 MP4（和 GIF）。确定性重放加上本地语音意味着无需 API 密钥、无需 LLM 令牌， 费用约为 $0（只需使用免费的运行器时长）。这是屏幕录制工具无法实现的循环：演示会自动维护自身。

# .github/workflows/demo.yml
- uses: actions/checkout@v4
- run: sudo apt-get update && sudo apt-get install -y ffmpeg   # ubuntu ships Chrome, not ffmpeg
- uses: tandryukha/aidemo@stable
  with:
    demos: demos/*
    tts: local        # in-process voice → no keys, no tokens
    gif: "true"

完整指南、模板（自动提交 / PR 评论 / 定时刷新）以及保持嵌入内容始终最新的技巧：docs/CI.md、 docs/EMBEDS.md、docs/recipes/。

快速开始（自包含冒烟测试）

内置的夹具存储（搜索 → 结果 → 购物车 → 结账），无需任何外部依赖即可生成完整的演示：

npm install                                # Node 20+, system Chrome, ffmpeg on PATH
node examples/local-demo/serve.mjs         # terminal 1: fixture on :8787
node bin/aidemo.mjs render examples/local-demo --headless   # terminal 2
open examples/local-demo/output/final-demo.mp4   # xdg-open on Linux, start on Windows

语音/字幕需要在 .env 中设置 OPENAI_API_KEY——或者设置 AIDEMO_TTS_PROVIDER=local （无需密钥，可离线运行），或者使用本地服务的 OPENAI_BASE_URL。请参阅 docs/LOCAL_MODELS.md。无需下载 Playwright 浏览器—— 引擎使用系统中的 Chrome（channel: "chrome"）。

_{内置夹具已端到端渲染完成 — 配有旁白、字幕并自动剪辑。 静音预览；完整版 ▶。}

CLI

每个步骤都可以独立运行和重新运行——无需重新录制即可重新生成语音，无需重新转录即可重新合成，等等。

aidemo init <name>            # scaffold demos/<name>/ with a starter storyboard
aidemo init <name> --from-url <url>   # …drafted from the live page's headings + real selectors
aidemo import-trace trace.zip --name <name>   # …or from a Playwright trace / *.spec.ts (actions + selectors → scenes)
aidemo voice   <dir>          # per-scene TTS → narration.mp3 + voice.json
aidemo record  <dir>          # drive Chrome → raw video + timeline.json
aidemo probe   <dir>          # record-only dry run (verify selectors), no key needed
aidemo validate <dir>         # schema-check the storyboard, no browser (non-zero exit on issues)
aidemo lint    <dir>          # predict freezes/cuts + selector pitfalls before spending a take
aidemo captions <dir>         # Whisper → captions.{srt,vtt,cues.json} (--offline for no network)
aidemo compose <dir>          # trim + sync + zoom + cards + caption + mux → final-demo.mp4
aidemo gif     <dir>          # final-demo.mp4 → README-ready GIF (autoplays on GitHub)
aidemo frames  <dir>          # evenly spaced PNGs from the video for review (--source raw)
aidemo render  <dir>          # voice → record → captions → compose
aidemo guide                  # print the canonical authoring guide
aidemo doctor                 # check Node, ffmpeg, Chrome, voice endpoint

在 CI/夹具场景下添加 --headless；对于需要使用已登录会话的真实网站，则省略该选项。--profile <dir> 用于指定 Chrome 用户数据目录；--fresh 会在清空后的目录中录制；--storage-state <file> / --cookie "name=value;domain=host" 可在首次操作前为受 Cookie 限制的网站设置 Cookie（也可以在分镜中声明 setup，它还能在每次录制前运行 preflight 脚本）；--capture native|obs 可切换为高保真屏幕录制。voice/render 会跳过未更改场景的 TTS，而 record 会保留失败录制的成果（保留视频片段，并在 logs/ 中保存截图/帧转储）。

Agent 接口（MCP）

aidemo mcp 会运行一个 stdio MCP 服务（不监听网络），将引擎提供给任何 MCP 客户端使用。Claude Code 插件会将其打包在内；aidemo repo-init 会以与 Agent 无关的方式注册它（Claude Code 使用 .mcp.json，Gemini 使用 .gemini/settings.json；Codex 使用 codex mcp add aidemo -- npx -y github:tandryukha/aidemo#stable mcp）。

• 创作工具 — get_authoring_guide 提供与引擎版本匹配的 docs/AUTHORING.md（不会过时）；get_storyboard_schema、validate_storyboard、init_demo、doctor。
• 流水线工具以作业形式运行 — probe/record/render/voice/captions/ compose/gif 会立即返回 jobId；job_status 会报告阶段、各场景进度，以及（失败时）截图/帧转储路径。

这样构建的原因

• 确定性回放，而非让大模型参与执行。 录制会以全速运行固定的 操作规范，因此视频流畅。Agent 只负责编写分镜（并确认一次选择器），录制过程中不会参与。
• 声明式操作规范 + 固定播放器（而非生成 spec.ts）。更安全、可编辑，而且会自动生成时间线——合成时会通过裁剪/加速仅调整空闲片段，使每个场景的视频时长适配旁白；剩余部分则冻结静态页面，而不是生成难看的慢动作。
• 通过叠加 PNG 实现字幕，而非使用 libass。 许多 ffmpeg 构建版本缺少 subtitles/drawtext；aidemo 会用无头 Chrome 将每条字幕栅格化，再通过受时间控制的 enable 进行叠加——任何带有 overlay 的 ffmpeg 都可使用。
• 电影感润色在合成时完成，而非录制时完成——缩放效果不佳时，只需重新合成，无需重新录制。请参阅 docs/POLISH.md。

更深入的文档

• docs/AUTHORING.md — 权威的分镜脚本架构、动作词汇和演示导演原则（由引擎提供）。
• docs/LOCAL_MODELS.md — 无需密钥即可渲染：进程内 Kokoro 语音、本地语音服务（speaches）、ElevenLabs、离线字幕。
• docs/POLISH.md — 自动缩放、滚动缓动、音乐闪避、片头/片尾卡片、运动模糊、光标控制、原生/OBS 高保真录制。
• docs/CHATGPT_APPS.md — 录制 ChatGPT Apps SDK 小组件（专用配置、嵌套 iframe、waitForWidget）。
• docs/CI.md · docs/EMBEDS.md · docs/recipes/ — CI 渲染、始终保持最新的嵌入内容、在 CI 中使用 Agent 的教程。

设置

前置条件：Node 20+、Google Chrome、PATH 中有 ffmpeg + ffprobe。 在 macOS 上开发和测试；Linux 支持默认的（Playwright）录制方式和 --capture obs。运行 aidemo doctor 检查设置。

npm install
cp .env.example .env      # add OPENAI_API_KEY, or use AIDEMO_TTS_PROVIDER=local (no key)

项目布局（每个演示）

demos/<name>/          ← your working area (untracked; scaffold with `aidemo init`)
  input/      brief.md
  generated/  storyboard.json  timeline.json  captions.{srt,vtt,cues.json}
  recordings/ raw.webm (or raw.mp4 for native/OBS capture)
  audio/      scene-*.mp3  narration.mp3  voice.json
  output/     final-demo.mp4
  logs/       <command>.log  fail-<scene>-<n>.{png,json} (on a failed action)

安全与信任

• 无遥测、无分析、安装时不运行脚本（package.json 中没有 postinstall/preinstall）。
• 网络请求仅由用户发起：api.openai.com（仅用于 voice/captions， 使用你的密钥，或通过 OPENAI_BASE_URL 指向本地服务）、api.elevenlabs.io（可选）、 huggingface.co（仅下载一次，用于 AIDEMO_TTS_PROVIDER=local），以及 github.com（使用你自己的 gh，用于 aidemo feedback）。录制/合成完全在本地进行。 MCP 服务仅使用 stdio，不会监听端口。
• **代码规模小，易于审查：**约 20 个源文件、7 个运行时依赖、MIT 许可证。如果你担心会变动的 #stable 标签，可固定到不可变版本： npx -y github:tandryukha/aidemo#v0.14.0（任意已发布的标签）。
• 详情：docs/LOCAL_MODELS.md · 按照 SECURITY.md 的说明私下报告漏洞。

路线图

• 视频评论（暂停并评论）和原位编辑转录文本： 字幕与场景对应，因此编辑一行会将该场景标记为待更新，运行 aidemo voice --scene <id> 和 compose 即可只重新生成变更部分。
• Web UI、项目历史记录、品牌套件、变更日志集成。
• 托管的公共 MCP（参见 docs/plans/public-mcp.md）。

已发布：GitHub Action（在 CI 中重新渲染）、电影级润色（自动缩放、 滚动缓动、音乐闪避、片头/片尾卡片、运动模糊、事后光标控制）、原生/OBS 录制、与 Agent 无关的 MCP 服务 + 编写指南、 ElevenLabs 和进程内本地语音提供方，以及 Claude Code 插件。

参与贡献

欢迎提交问题和 PR — 开发环境设置、冒烟测试及 DCO 签署要求请参阅 CONTRIBUTING.md。关于录制过程的反馈有快速通道：aidemo feedback demos/<name> 会预先填入结构化问题。

许可证

MIT © Andrii Taran