内容
# aidemo — 你的编码代理创建演示视频
**[aidemo.top](https://aidemo.top)** · [观看一个51秒的实际输出 ▶](https://github.com/tandryukha/aidemo/releases/download/v0.3.0/wikipedia-showcase-demo.mp4) · [作者指南](docs/AUTHORING.md) · [在CI中渲染](docs/CI.md)
告诉你的编码代理 *"记录结账流程的45秒演示"* — 得到一个带有旁白、同步字幕和自动缩放的精美 **MP4**。任何MCP-capable代理（Claude Code、Codex CLI、Gemini CLI）都编写一个 `storyboard.json`；无头引擎驱动一个真正的Chrome，记录一个 **确定性重放**，配音，添加字幕，并修剪死时间。因为重放是确定性的，所以 **演示在CI中重新渲染** 当产品更改时 — 无需重新录制，无需API密钥，成本约为 **0美元**。一个 **开源（MIT）替代品**，适用于Screen Studio、Clueso或Demosmith，当你希望你的编码代理创建演示时。
[](https://aidemo.top)
[](https://github.com/tandryukha/aidemo/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.npmjs.com/package/@tandryukha/aidemo)
[](https://github.com/tandryukha/homebrew-aidemo)
[](https://github.com/marketplace/actions/aidemo-demo-video)
[](https://registry.modelcontextprotocol.io)
[](#三种使用方式)
**安装：** Claude Code `/plugin marketplace add tandryukha/aidemo` · CI `uses: tandryukha/aidemo@stable` · CLI `npx -y @tandryukha/aidemo` · Homebrew `brew install tandryukha/aidemo/aidemo`
<br>发布于 [GitHub Marketplace](https://github.com/marketplace/actions/aidemo-demo-video)，[npm](https://www.npmjs.com/package/@tandryukha/aidemo)，一个 [Homebrew tap](https://github.com/tandryukha/homebrew-aidemo)，和 [MCP Registry](https://registry.modelcontextprotocol.io)。
[](https://github.com/tandryukha/aidemo/releases/download/v0.3.0/wikipedia-showcase-demo.mp4)
<sub>实际输出 — 一个约51秒的自我叙述的维基百科之旅（门户搜索 → 阿达·洛夫莱斯 → 焦点缩放 → 点击跳转到分析引擎 → 滑动滚动），由Claude根据一个 `storyboard.json` 编写并录制为确定性重放。预览GIF是无声的； **[观看完整版配音 ▶](https://github.com/tandryukha/aidemo/releases/download/v0.3.0/wikipedia-showcase-demo.mp4)**。</sub>
## 三种使用方式
1. **从你的编码代理** — 最快的路径。在 **Claude Code** 中： `/plugin marketplace add tandryukha/aidemo` 然后 `/plugin install record-demo@aidemo`（捆绑技能 **和** MCP服务器）。在 **Codex / Gemini / 任何MCP代理** 中： `npx -y github:tandryukha/aidemo#stable repo-init`。然后只需说 *"记录<流程>的45秒演示"*，代理编写并渲染它。
2. **本地，免费和离线** — `AIDEMO_TTS_PROVIDER=local aidemo render <dir> --headless`。进程内语音模型 + 脚本计时字幕意味着 **无需API密钥，约0美元，完全离线**。参见 [docs/LOCAL_MODELS.md](docs/LOCAL_MODELS.md)。
3. **在CI中，自维护** — 在工作流中添加 `uses: tandryukha/aidemo@stable`。当产品更改时，它重放提交的故事板并提交新鲜媒体 — **无需密钥，无LLM代币，约0美元** 在免费的运行分钟数上。参见 [docs/CI.md](docs/CI.md)。
**免费和开源。** MIT许可。在GitHub的免费Actions层上运行，或使用进程内语音完全本地，成本约为0美元 — 无需API密钥，无需云上传，无需遥测。与 **localhost和认证墙应用**（您自己的Chrome）一起工作。
## 从一句话到一个有旁白的MP4
你输入一句话，代理编写一个你可以阅读和编辑的工件，引擎记录并剪辑它：
**1 · 你输入的内容** — 任何MCP-capable代理的一行（这里是Claude Code）：
```
claude "记录一个45秒的维基百科之旅：搜索阿达·洛夫莱斯，打开分析引擎，然后滑动浏览文章"
```
**2 · 代理编写的内容** — 一个普通的，可编辑的 `storyboard.json`（摘录：旁白 + 固定的浏览器动作规范， side by side — 无生成的代码）：
```jsonc
{
"title": "维基百科快速游览",
"zoom": {}, // Screen-Studio风格的自动缩放
"scenes": [
{ "id": "search",
"narration": "从维基百科门户开始，搜索阿达·洛夫莱斯。",
"actions": [
{ "op": "goto", "url": "https://www.wikipedia.org/" },
{ "op": "type", "target": { "selector": "#searchInput" }, "text": "阿达·洛夫莱斯" },
{ "op": "click", "target": { "selector": "button[type=submit]" } } ] },
{ "id": "engine",
"narration": "她的关于巴贝奇分析引擎的笔记包含了第一个计算机程序。",
"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
→ 语音 OpenAI / ElevenLabs / 本地TTS → audio/narration.mp3 + voice.json
→ 记录 驱动Chrome，动画光标 → recordings/raw.{webm,mp4} + timeline.json
→ 字幕 Whisper字幕时间戳 → generated/captions.{srt,vtt,cues.json}
→ 组合 修剪空闲时间 · 同步 · 自动缩放 · 卡片 · 字幕 · mux → output/final-demo.mp4
```
**4 · 你得到的内容** — `output/final-demo.mp4`，以及一个README-ready GIF（`aidemo gif`）和来自同一拍摄的命名静态图像（`aidemo stills`）。UI更改？对同一个故事板重新运行 — 不需要手动重新录制。
设计目标：演示看起来 **人造且流畅**，不像AI点击并在截图之间等待 — 通过将 **编写**（缓慢，一次性 — 找出流程）与 **录制**（快速确定性重放，带有平滑的动画光标）分开。
## 团队使用它来渲染的内容
- **GitHub README演示** — `aidemo gif demos/onboarding`，将自动播放的GIF放入readme（此页面的GIF正是如此）。
- **登录页面英雄视频** — [aidemo.top](https://aidemo.top)上的静音自动播放MP4是一个渲染的演示，包括海报帧。
- **发布/新增功能演示** — 讲述新功能，然后 `gh release upload v1.4.0 demos/whats-new/output/final-demo.mp4`。
- **客户和前景演示** — 针对您实际应用的个性化流程：localhost，认证墙，您的登录Chrome；没有任何内容离开机器。
## 在CI中渲染（自维护演示）
提交一个故事板， **[aidemo GitHub Action](docs/CI.md)** 保持其演示媒体同步 — 一个新鲜的有旁白，字幕的MP4（和GIF）在每次相关更改时。确定性重放 + 本地语音意味着 **无需API密钥，无LLM代币，约0美元** （仅免费的运行分钟数）。它是一个屏幕录制器无法运行的循环：您的演示自行维护。
```yaml
# .github/workflows/demo.yml
- uses: actions/checkout@v4
- run: sudo apt-get update && sudo apt-get install -y ffmpeg # ubuntu自带Chrome，不带ffmpeg
- uses: tandryukha/aidemo@stable
with:
demos: demos/*
tts: local # 进程内语音 → 无密钥，无代币
gif: "true"
```
完整的配方，模板（自动提交/PR注释/定时刷新）和始终保持新鲜的嵌入技巧： **[docs/CI.md](docs/CI.md)**， **[docs/EMBEDS.md](docs/EMBEDS.md)**， **[docs/recipes/](docs/recipes/)**。
## 快速入门（自包含烟雾测试）
一个捆绑的fixture商店（搜索 → 结果 → 购物车 → 结账），在没有任何外部依赖的情况下渲染一个完成的演示：
```bash
npm install # Node 20+，系统Chrome，ffmpeg在PATH上
node examples/local-demo/serve.mjs # 终端1：fixture在：8787上
node bin/aidemo.mjs render examples/local-demo --headless # 终端2
open examples/local-demo/output/final-demo.mp4 # xdg-open在Linux上启动，Windows上启动
```
语音/字幕需要 `.env` 中的 `OPENAI_API_KEY` — **或** `AIDEMO_TTS_PROVIDER=local` （无密钥，离线），**或** `OPENAI_BASE_URL` 在本地服务器上。参见 [docs/LOCAL_MODELS.md](docs/LOCAL_MODELS.md)。不需要Playwright浏览器下载 — 引擎使用您的系统Chrome（`channel: "chrome"`）。
[](https://github.com/tandryukha/aidemo/releases/download/v0.3.0/quickstart-demo.mp4)
<sub>捆绑的fixture端到端渲染 — 有旁白，字幕，自动修剪。无声预览； **[完整版本 ▶](https://github.com/tandryukha/aidemo/releases/download/v0.3.0/quickstart-demo.mp4)**。</sub>
## CLI
每个步骤都是独立运行和可重新运行的 — 在不重新录制的情况下重新生成语音，在不重新转录的情况下重新合成等。
```bash
aidemo init <name> # 为 demos/<name>/ 搭建一个启动故事板
aidemo voice <dir> # 每场景TTS → narration.mp3 + voice.json
aidemo record <dir> # 驱动Chrome → raw video + timeline.json
aidemo probe <dir> # 仅记录干运行（验证选择器），无需密钥
aidemo captions <dir> # Whisper → captions.{srt,vtt,cues.json}（--offline表示无网络）
aidemo compose <dir> # 修剪 + 同步 + 缩放 + 卡片 + 字幕 + mux → final-demo.mp4
aidemo gif <dir> # final-demo.mp4 → README-ready GIF（在GitHub上自动播放）
aidemo render <dir> # voice → record → captions → compose
aidemo guide # 打印规范的作者指南
aidemo doctor # 检查Node，ffmpeg，Chrome，语音端点
```
添加 `--headless` 用于CI/fixtures；省略它用于需要您登录会话的真实站点。 `--profile <dir>` 选择Chrome用户数据目录； `--capture native|obs` 切换到高保真屏幕捕获。 `voice`/`render` **跳过TTS对于不变的场景**，而 `record` **保留失败的拍摄** （保留录像并在 `logs/`中添加截图/帧转储）。
## 代理接口（MCP）
`aidemo mcp` 运行一个 **stdio** MCP服务器（无网络监听器）将引擎暴露给任何MCP客户端。Claude Code插件捆绑了它； `aidemo repo-init` 以代理中立的方式注册它（`.mcp.json`用于Claude Code，`.gemini/settings.json`用于Gemini； `codex mcp add aidemo -- npx -y github:tandryukha/aidemo#stable mcp`用于Codex）。
- **作者工具** — `get_authoring_guide` 提供 [docs/AUTHORING.md](docs/AUTHORING.md) 版本匹配的引擎（不能过时）； `get_storyboard_schema`， `validate_storyboard`， `init_demo`， `doctor`.
- **管道工具作为作业运行** — `probe`/`record`/`render`/`voice`/`captions`/ `compose`/`gif` 立即返回一个 `jobId`； `job_status` 报告阶段，逐场景进度和（在失败时）截图/帧转储路径。
## 为什么这样构建
- **确定性重放，而不是循环中的LLM。** 记录运行固定的动作规范以全速运行，因此视频流畅。代理仅 **编写** 故事板（并确认选择器一次），而不在捕获期间。
- **声明式动作规范 + 固定的播放器** （不是生成的 `spec.ts`）。更安全，可编辑，并免费发出 **时间线** — compose适合每个场景的视频以修剪/加速仅空闲部分，冻结保持静态页面以适应剩余部分，而不是丑陋的慢动作。
- **通过叠加PNG字幕，而不是libass.** 许多ffmpeg构建缺少 `subtitles`/`drawtext`； aidemo栅格化每个字幕并使用无头Chrome叠加它，并使用时间门控 `enable` — 在任何ffmpeg上都有效，带有 `overlay`。
## 更深层次的文档
- **[docs/AUTHORING.md](docs/AUTHORING.md)** — 规范的故事板架构，动作词汇和演示导演原则（由引擎提供）。
- **[docs/LOCAL_MODELS.md](docs/LOCAL_MODELS.md)** — 无密钥渲染：进程内Kokoro语音，本地语音服务器（speaches），ElevenLabs，离线字幕。
- **[docs/POLISH.md](docs/POLISH.md)** — 自动缩放，滚动缓和，音乐减音，介绍/结尾卡片，运动模糊，事后光标控制，原生/OBS高保真捕获。
- **[docs/CHATGPT_APPS.md](docs/CHATGPT_APPS.md)** — 记录ChatGPT Apps SDK小部件（专用配置文件，嵌套iframe，`waitForWidget`）。
- **[docs/CI.md](docs/CI.md)** · **[docs/EMBEDS.md](docs/EMBEDS.md) · **[docs/recipes/](docs/recipes/)** — CI渲染，始终保持新鲜的嵌入，代理在CI中的配方。
## 设置
前提条件： **Node 20+**，**Google Chrome**，`PATH`上的`ffmpeg`和`ffprobe`。在默认的（Playwright）捕获和 `--capture obs`下在Linux上开发和测试。运行 `aidemo doctor` 检查您的设置。
```bash
npm install
cp .env.example .env # 添加OPENAI_API_KEY或`AIDEMO_TTS_PROVIDER=local（无密钥）
```
## 贡献
欢迎提出问题和PR - 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取开发设置，烟雾测试和DCO签署要求。录制会话反馈有快速通道：`aidemo feedback demos/<name>` 预填充结构化问题。
## 许可
[MIT](LICENSE) © Andrii Taran
