Tourwright

无需剪辑，即可制作配有旁白的产品演示和操作视频。 只需在应用中点击操作一次，或让 AI Agent 为你制作视频：Tourwright 会编写脚本，在演播室画面中录制真实浏览器，引导观众关注每个元素，以自然语音进行讲解，并交付带字幕、章节和缩略图的 .mp4 视频。UI 发生变化时，重新渲染即可。专为人类和 AI Agent 打造，可运行在任何服务器上，从笔记本电脑到集群均可。

阅读西班牙语版

_{Tourwright 根据 examples/app.yaml 制作，无需任何人操作键盘。▶ 听声音观看（77 秒）}

# tour.yaml
title: Your first invoice
voice: lessac
baseUrl: https://app.example.com
steps:
  - goto: /invoices/new
  - title: { text: Your first invoice, subtitle: Step by step }
  - say: Pick the <b>customer</b> first.
  - click: { role: combobox, name: Customer }
  - say: Then save. That's it.
  - click: { role: button, name: Save }

tourwright render tour.yaml        # → videos/tour/tour.mp4 (+ captions.srt/.vtt, .jpg, .json)

为什么选择 Tourwright

屏幕录制工具（Loom）和点击式演示工具（Arcade、Supademo、Scribe）都需要有人录制，每次重新设计都意味着要重新录制。Tourwright 视频是代码：

	屏幕录制工具	演示 SaaS	Tourwright
UI 变化后重新录制	手动	手动	tourwright render
检测视频何时过时	否	否	CI 中的 tourwright check 会指出出错的步骤和修复方法
旁白	自己配音，需反复录制	无或额外付费	提供多种音色的文本转语音，支持离线或在线使用
为 50 位客户或多种语言制作相同演示	50 个录制视频	50 个演示	一个使用 {{variables}} 的脚本
屏幕上的个人数据	手动剪掉	手动剪掉	mask 会将其替换为虚构数据
存储位置	供应商的云端	供应商的云端	你的 Git 仓库和服务器；MIT 许可
AI Agent 能否制作	否	否	MCP 服务和 Claude Code 插件

你将获得

• 浏览器演示：真实的 Chromium、流畅的动画光标、点击波纹、高亮、聚光灯、说明气泡、镜头缩放、拖放、模糊处理的个人数据，以及采用你的配色和 Logo 的标题卡片与字幕。
• 引导聚焦：应用首次打开时显示的导览。除目标元素外，其他内容都会变暗；目标元素会被圆环标出，说明气泡带有 2/4 徽标，镜头也会推近，精准聚焦语音正在讲解的词语。
• 配音幻灯片：标题卡片、图片（带缓慢平移和缩放效果）、HTML、交叉淡化。无需网站。
• 自由选择语音：Pocket TTS（离线、开放、自然：tourwright install --pocket）、Piper（离线、开源、轻量）、Microsoft Edge 神经语音、任何兼容 OpenAI 的 TTS 服务（OpenAI、Kokoro、LocalAI……），或你自己的命令。每句话都会缓存：重新渲染时不会再次合成语音。
• 角色阵容与台词演绎方式：每段视频可使用多种语音；任何引擎都支持逐句设置语速、音高和音量；支持精确停顿（[[1s]]）、发音词典、音效预设（温暖、广播、播客……）、点击、打字等音效，以及带淡入淡出的音乐。
• 可随需求扩展的脚本：变量（{{name}}，也可通过命令行或 API 传入）、可复用代码块、重复、条件和可失败的步骤。一份脚本，制作多段视频。
• 插件：通过小型模块添加新操作、TTS 引擎和语音（文档）。
• 自动精细剪辑：移除页面加载、缓慢等待和语音合成耗时；旁白不会重叠；背景音乐会在语音播放时自动降低音量。
• 交付内容：带章节和内嵌字幕的 H.264/AAC .mp4、.srt、.vtt、缩略图，以及供自动化使用的 JSON 清单（时长、章节、字幕）。
• 四种接入方式：命令行、带任务队列和 Webhook 的 HTTP API、供 AI Agent 使用的 MCP 服务、Node 库。
• 可横向扩展：无状态 API 副本、任意数量的工作进程和服务器、Redis/BullMQ 队列、兼容 S3 的存储。也可在 Raspberry Pi 上通过单个进程和文件夹运行。

安装

Docker（推荐）

docker run --rm -v "$PWD:/work" -w /work ghcr.io/cxmiloxx/tourwright render examples/slides.yaml --out videos/

完整服务（API + 2 个工作进程 + Redis）：

cp .env.example .env    # set TOURWRIGHT_API_TOKENS
docker compose up -d --build
docker compose up -d --scale worker=6

从 npm 安装（最快上手）

Node.js 22+，支持 Linux、macOS 或 Windows：

npm install -g tourwright
tourwright install                    # ffmpeg, Piper + voices, edge-tts, Chromium (no root)
tourwright install --plan             # only show what it would use from this PC and what it would download
tourwright config set quality fullhd  # your own defaults: quality, voice, fps… (tourwright config lists them)
tourwright record https://app.example.com --out tour.yaml   # do the tour by hand: you get the script and the video
tourwright guide tour.yaml --open     # the same tour as a step-by-step guide with screenshots (HTML, PDF, Markdown)
tourwright narrate tour.yaml --write  # your AI (Claude, OpenAI, Ollama) rewrites the narration from the screens
tourwright translate tour.yaml --to en  # the same video in English (or pt, fr, de, it): tour.en.yaml
tourwright check videos/*.yaml        # which videos broke after a deploy, at which step, and the fix
tourwright fix tour.yaml --write      # puts the new targets in the script
tourwright render tour.yaml --step 7  # film one step with its voice, without the whole video
tourwright install --pocket           # + Pocket TTS: natural offline voices (about 1 GB)
tourwright clean                      # what each part takes on disk; removes downloads and leftovers
tourwright doctor                     # what works on this machine

无需全局安装任何内容：npx tourwright <command>。使用 pnpm：pnpm add -g tourwright （在 2.0.0 中，请添加 --no-optional）。

Redis 队列和用于 narrate 的 Claude 均为可选项：使用时，请在 Tourwright 旁安装 bullmq ioredis 或 @anthropic-ai/sdk（npm install -g bullmq ioredis）。Docker 镜像已包含这些依赖。

无需 Docker（Linux、macOS、Windows）

需要 Node.js 22+。tourwright install 会将 ffmpeg、Piper、语音、edge-tts 和 Chromium 安装到 TOURWRIGHT_HOME，无需 root 或管理员权限；系统已有的内容会保留。

git clone https://github.com/CXmiloxx/tourwright && cd tourwright
./scripts/install.sh           # Linux / macOS (Windows: powershell -ExecutionPolicy Bypass -File scripts\install.ps1)
node bin/tourwright.js doctor  # what works on this machine
npm link                       # optional: the `tourwright` command

每个组件都会先在电脑上查找，只有缺失时才会下载：

	Linux（x64、arm64）	macOS（Intel、Apple Silicon）	Windows 10/11（x64、ARM）
Chromium	Chrome、Edge 或 Chromium（apt、dnf、pacman、Raspberry Pi OS），否则下载	Chrome、Edge 或 Chromium，否则下载	Chrome 或 Edge，否则下载
ffmpeg	PATH、Homebrew、Nix，否则下载	Homebrew、MacPorts、Nix，否则运行 brew install ffmpeg	PATH、winget、scoop、Chocolatey、C:fmpeg，否则下载
Piper（离线语音）	PATH、pip、pipx、conda，否则下载	PATH、pip、pipx、conda，否则下载	PATH、pip、pipx、conda，否则下载
Piper 语音	Hugging Face 缓存、TOURWRIGHT_PIPER_VOICE_DIRS，否则下载	同上	同上
edge-tts（Microsoft 语音）	PATH、pip、pipx、conda，否则安装	同上	同上
Python（用于 edge-tts、Pocket、Whisper）	系统中的 3.10–3.13 版本，否则下载 3.12	同上	同上（不是 Microsoft Store 占位程序）
捕获	使用 Xvfb 的 screen（画质最佳），否则使用 screencast	screencast	screencast

还会复用其他 Playwright 或 Puppeteer 版本安装的 Chromium，以及 CHROME_PATH、CHROME_BIN 或 PUPPETEER_EXECUTABLE_PATH。会跳过 Snap 和 Flatpak 浏览器（它们的沙盒会阻止 Playwright）。 TOURWRIGHT_SYSTEM_BROWSER=0 时始终使用 Playwright 自带的 Chromium。tourwright doctor 会显示查找结果。

系统中不会安装任何内容：下载的内容都存放在一个文件夹（TOURWRIGHT_HOME）中，Python 包则运行在虚拟环境里，因此不会更改你已有的环境。要卸载，只需删除该文件夹。

Xvfb（仅限 Linux，使用 apt install xvfb 安装）可提供画质最佳的捕获；没有它时，Tourwright 会进行无头录制 （screencast），适用于所有能运行 Chromium 的环境。HTTP API 或 MCP 的客户端可以在任何系统上运行。

使用方法

无需手动编写选择器，即可将网站制作为视频：

tourwright explore https://app.example.com/login --draft app.yaml   # asks for the login, writes the script
tourwright render app.yaml --dry-run                               # checks every step in seconds
tourwright render app.yaml --open                                  # the video, in ./videos/app/

草稿会遍历网站的每个部分，并使用页面中的内容生成旁白；你可以用自己的文字编辑草稿。 凭据只会询问一次，不会显示，也不会写入脚本（tourwright secret list； tourwright forget 会删除凭据）。

tourwright init video.yaml                  # an example script
tourwright validate video.yaml
tourwright render video.yaml --dry-run      # runs every step fast: tests selectors, no voice/video
tourwright render video.yaml --safe         # the same, pressing nothing: no real sign-up, payment or SMS
tourwright render video.yaml --keep         # keeps the recording: tourwright recompose videos/video remakes it without the browser
tourwright render video.yaml --quality fullhd --voice salome --out out/
tourwright voices                           # voices available here
tourwright install-voice en_GB-alba-medium  # any voice from huggingface.co/rhasspy/piper-voices
tourwright say "Hello there" --voice lessac --out hello.wav

脚本格式、所有操作和语音：docs/SCRIPTS.md。 供编辑器和 Agent 使用的 JSON Schema：schema/script.schema.json。

HTTP API

TOURWRIGHT_API_TOKENS=secret tourwright serve --worker --port 4700
curl -X POST localhost:4700/v1/jobs -H 'authorization: Bearer secret' -H 'content-type: application/json' \
  -d '{"script": {"type": "slides", "slides": [{"title": "Hello", "say": "Hello from the API."}]}}'
curl localhost:4700/v1/jobs/<id> -H 'authorization: Bearer secret'   # → status, result, download links

端点、资源和 Webhook：docs/API.md。

AI Agent（MCP）

将 Claude Code 作为插件使用（包含 MCP 服务，以及用于编写、检查和渲染脚本的技能）：

/plugin marketplace add CXmiloxx/tourwright
/plugin install tourwright@tourwright

其他 MCP 客户端（Claude Desktop、Cursor、VS Code……）：

{ "mcpServers": { "tourwright": { "command": "tourwright", "args": ["mcp"] } } }

工具：tourwright_guide、tourwright_voices、tourwright_validate、tourwright_check、tourwright_render、tourwright_job、 tourwright_jobs、tourwright_delete_job（以及在 TOURWRIGHT_MCP_ALLOW_FILES=true 时使用的 tourwright_render_file）。使用 TOURWRIGHT_API_URL 和 TOURWRIGHT_API_TOKEN 指定远程 API。详情：docs/AGENTS.md。

GitHub Action

在每次发布时重新渲染你的导览，或者在部署出现问题时让构建失败：

- uses: CXmiloxx/tourwright@v2
  with:
    scripts: videos/*.yaml
    command: check            # or render: the videos become a workflow artifact
  env:
    TOURWRIGHT_SECRET_APP_PASSWORD: ${{ secrets.APP_PASSWORD }}

输入项：scripts、command、out、voice、quality、voices、version、upload（action.yml）。

Node 库

import { loadFile, render } from 'tourwright'
const result = await render(await loadFile('tour.yaml'), { out: 'videos/', quality: 'hd' })
console.log(result.paths.video, result.duration, result.chapters)

扩展

规模	配置
一台机器	tourwright serve --worker — 本地文件夹队列，文件存储在磁盘上
一台大型机器	docker compose up --scale worker=N — Redis 队列，共享卷
多台机器	API 副本部署在负载均衡器后，工作器可运行在任意位置，共用同一个 Redis 和 S3 存储桶
Kubernetes	deploy/kubernetes/tourwright.yaml，工作器自动扩缩

每个工作器一次渲染 TOURWRIGHT_CONCURRENCY 个视频（每个视频各需一个 Chromium 和 ffmpeg：720p 下每个视频约需 1–2 个 CPU 和约 1 GB RAM）。工作器以较低的 CPU 和磁盘优先级运行，确保共享服务器保持响应。更多信息：docs/DEPLOYMENT.md · 配置：docs/CONFIGURATION.md。

安全性

API 作业在沙箱中运行：仅支持数据脚本（不支持 JavaScript），文件范围限制为作业的资源，可选主机允许列表和私有网络屏蔽，默认不启用密钥，按令牌隔离作业，并提供签名下载链接。向不受信任的客户端开放 API 前，请阅读 SECURITY.md。

许可证

MIT。Piper 语音有各自的许可证（请参阅每种语音的模型卡）；Edge 语音是一项 Microsoft 在线服务，请查看其使用条款。