制作带旁白的演示视频
您编写一个场景文件：每个场景包含一段旁白文本以及该旁白播放时触发的点击操作。这些脚本会将旁白文本合成为语音，在固定 1600×900 分辨率的无头 Chromium 中驱动应用并捕获屏幕，最终生成一个带有语音解说和硬编码字幕的 MP4 视频。页面上还会叠加可见光标、点击波纹、高亮环和标题卡片等视觉元素。
以下所有命令均使用 PY，在 Windows 上表示 python，在 macOS 上表示 python3；DV 表示 "${CLAUDE_SKILL_DIR}/scripts/demo_video.py"。每条命令都会输出清晰的状态行（SCENE …、RECORDED …、CHECK OK、ERROR …），请直接阅读这些输出而不是猜测。
1. 环境设置（每台机器只需执行一次）
PY "${CLAUDE_SKILL_DIR}/scripts/setup_env.py"
该脚本会在 ~/.claude-demo-video 目录下创建一个私有环境，包含 Playwright、Chromium 和 edge-tts，然后检查 ffmpeg 是否可用。成功时输出 READY，失败时精确指出缺失的组件。ffmpeg 是系统工具：在安装前请先获取用户许可（Windows 上使用 winget install --id Gyan.FFmpeg -e，macOS 上使用 brew install ffmpeg）。脚本也会在常见的安装目录中查找（WinGet、Chocolatey、Scoop、Homebrew）。如果 ffmpeg 安装在其他位置，请为每条命令设置环境变量 DEMO_VIDEO_FFMPEG_DIR 指向其所在文件夹。
2. 在编写任何内容之前，先与用户确认视频方案
请询问用户或从上下文中确认：
- 谁将观看以及原因（评审功能审批人、客户、新员工）。这决定了视频的基调和需要解释的内容。
- 要展示什么，以及展示顺序。 提出一个每行一个场景的场景列表，并取得用户同意。目标时长控制在 3 到 8 分钟。
- 语音。 默认使用自然的英语神经语音（edge-tts）。请告知用户旁白文本会被发送到微软的语音服务以生成音频。 旁白中应仅包含功能说明，绝不包含实际数据。替代方案是离线系统语音（
--offline）：所有处理都在本地进行，但语音听起来像机器人。 - 数据。 仅录制演示数据：虚构人物、
@example.com邮箱、明显是虚构的项目。切勿录制真实的客户或员工记录，也切勿将录制器指向生产环境。
3. 准备应用
- 应用必须正在运行并且可从本机访问，通常是一个本地构建。
- 如果某些页面需要数据，请编写一个种子脚本以及一个用于清理这些演示数据的配套清理脚本，然后运行种子脚本。为演示数据行添加标记（例如 ID 以
DEMO-开头），这样清理脚本就不会误删其他数据。 - 确保外发邮件和通知已关闭，或者仅发送到虚假地址，因为演示会点击真实按钮（提交、审批等）。
- 更改数据（审批、删除）的场景每次种子只能录制一次。每次重录前需要重新执行种子脚本。
4. 编写场景文件
请在用户的项目目录中创建场景文件，例如 demo-videos/<name>.py，切勿放在技能文件夹内。从 ${CLAUDE_SKILL_DIR}/reference/scenes-template.py 模板文件开始。完整的实际示例请参考 ${CLAUDE_SKILL_DIR}/reference/zentrio-timesheet-example.py，它制作了一个 6 分钟的审批视频。
CONFIG = {'url': 'https://localhost:7101/MyTimesheet', 'ready': '#tsCards .tsw-card', 'sign_in': True}
async def week(r):
await r.click('.tsw-row:has-text("Approval screen")')
await r.spot('.tsw-panel', 3)
SCENES = [
('week', "点击任务行，日志面板会在其下方打开。", week),
]
CONFIG['url']是第一个页面的 URL。ready是一个选择器，只有当该页面加载完成并且登录成功后才会可见。录制器通过它来判断登录是否成功。- 旁白：每个场景附加一到三句简短的语言。解释为什么某个功能重要，而不是仅描述屏幕上看到的内容。用数字和符号的读音写法（例如“二点三零”）。不要在旁白中包含真实数据。
- 动作在旁白播放时执行。请确保动作时长小于旁白播放时长；录制器会等待旁白播放结束后才开始下一个场景。
场景辅助函数（r 是录制器对象；其他属性可通过 r.page 访问 Playwright 页面）：
| 辅助函数 | 功能 |
|---|---|
await r.goto('/path', wait_for=sel) | 打开一个页面（相对于 CONFIG['url']） |
await r.click(target, dx=.5, dy=.5) | 将可见光标移动到目标位置并点击；dx/dy 用于选择元素内部的点击点 |
await r.move_to(target) | 移动光标但不点击 |
await r.type(target, 'text') | 点击一个字段并逐个字符输入文本 |
await r.select(target, value) | 选择下拉框中的选项 |
await r.press('ControlOrMeta+K') | 键盘快捷键（Windows 上为 Ctrl，macOS 上为 Cmd） |
await r.spot(target, seconds, pad) | 显示橙色高亮环 |
await r.card(kicker, title, lines, bullets) / await r.uncard() | 全屏标题卡片（用于开头、总结、结尾） |
await r.confirm_click(target, show=4) | 用于调用 confirm() 的按钮：显示一个模拟对话框，然后确认 |
await r.download(target) | 点击下载按钮并返回已保存文件的路径 |
await r.show_file(path) | 显示本地文件，例如您生成的下载报告的 HTML 预览 |
await r.scroll_top()、await r.scroll_x(selector, px) | 平滑滚动 |
await r.clear_toasts(selector) | 移除遮挡按钮的通知提示条 |
await r.wait(seconds) | 暂停指定秒数 |
target 参数是 CSS 或 Playwright 选择器字符串（例如 'button:has-text("Approve")'）或一个 Locator 对象（例如 r.page.locator('tr', has_text='Aarav').first）。
5. 生成旁白、录制及预览
PY DV voice demo-videos/<name>.py # 为每个场景生成音频；输出每个场景的时长
PY DV record demo-videos/<name>.py # 驱动应用并捕获帧
PY DV stills demo-videos/<name>.py # 每个场景截取两张静态图片，保存在 <name>-video/stills/ 目录下
登录。 如果 'sign_in': True 且应用尚未登录，会打开一个浏览器窗口，同时录制器输出 SIGN_IN_NEEDED。请告知用户在该窗口中手动登录。切勿输入凭据或索要密码。 会话会保存在 <name>-video/.profile 文件中，因此重录时无需再次登录。
构建视频前必须检查每张静态图片，通过查看图像确认：
- 页面正确、面板已打开、光标位于旁白所述位置；
- 没有遮挡操作的元素（提示条、Cookie 横幅、个人菜单）；
- 画面未拉伸或截断；
- 屏幕上没有真实的个人数据。
如果某行输出 SCENE_ERROR 或静态图不正确，则需要修复对应的场景函数后重新录制（如果场景修改了数据，则需先重新执行种子脚本）。reference/lessons.md 文件中列出了之前出现过的故障及其修复方法。当发现异常时，请阅读该文件。
6. 构建、检查并交付
PY DV build demo-videos/<name>.py [--out "path/Name.mp4"]
PY DV check "path/Name.mp4" --size 1600x900
run 命令可以将 voice、record、stills、build、check 一步完成，适用于场景已确认无误的情况。告知用户视频的路径、时长以及所展示的内容。除非用户要求，否则不要自行上传或分享视频。
7. 清理
PY DV clean demo-videos/<name>.py会删除保存的登录会话。请务必在完成时执行此操作，因为该会话持有真实的会话信息。使用--all参数可同时删除帧、静态图和音频文件。- 运行演示数据的清理脚本，并停止您启动的任何应用进程。
平台说明
- macOS：使用
python3。字幕由 Chromium 绘制并叠加在视频上，因此在不同的平台上看起来一致，并且不需要使用 libass 编译的 ffmpeg（Homebrew 默认的 ffmpeg 没有此功能）。录制采用无头模式，因此 Retina 显示屏不会影响视频尺寸。 --headed参数会在可见窗口中录制。仅当应用拒绝无头浏览器时才使用该选项，并且请告知用户在录制期间不要触摸或调整窗口大小。DEMO_VIDEO_HOME环境变量用于更改私有环境的路径；DEMO_VIDEO_FFMPEG_DIR用于指向 ffmpeg 的文件夹。