应用教学视频
制作真实应用的专业培训视频。视频采用约 1920 × 1080 H.264 编码，配有 AAC 旁白。每个口语句子都配有字幕，每个章节以卡片开始，长时间等待会被剪除。视频可重现：当 UI 变化时，重新运行捕获和渲染即可生成最新版本。
工作原理：
- 故事板 包含旁白文本、章节和品牌信息。
narrate.py使用离线 Kokoro 语音朗读每个片段：无需云服务、无需账户、零成本。- 捕获脚本 使用 Playwright 驱动真实应用（真实鼠标移动、可见光标和点击涟漪）。它会录制 Chrome 的屏幕帧，并让每个片段保持显示直到旁白结束。
render.py组装视频片段、卡片、字幕带以及响度归一化后的旁白音轨。review.py检查结果并生成接触页，供发布前预览。
脚本位于此文件旁的 scripts/ 目录中。在撰写旁白前请阅读 references/storyboard.md，在编写捕获脚本前请阅读 references/capture-guide.md。两者包含的经验教训可避免常见的重录问题。
0. 一次性设置
bash <skill>/scripts/setup.sh
此命令会在 ~/.cache/app-training-video/ 目录下创建（可通过 TRAINING_VIDEO_HOME 环境变量覆盖）：
- 一个私有的 Python 3.10–3.13 环境，包含固定版本的包；
- Kokoro 语音模型（约 350 MB）及 Inter 字体文件，经过 SHA-256 校验；
- Chromium 浏览器。
所有脚本都应使用该环境中的 Python 运行（PY=~/.cache/app-training-video/venv/bin/python），并传递故事板路径。如果模型文件已存在于其他位置，可先设置 MODEL_SOURCE=<dir> 以复用它们。ffmpeg 已通过 imageio-ffmpeg 集成；不会在系统中全局安装任何东西。
1. 了解应用和受众
在编写任何内容之前，请亲自试用应用（或阅读其用户指南），明确以下几点：
- 谁观看： 新客户、现场员工、内部用户。
- 他们必须掌握的一个工作流程： 从输入到结果。
- 可以展示哪些演示数据： 确保安全。
- 如何以干净状态启动应用： URL 或启动命令，以及全新的数据文件夹或演示账户。
- 品牌信息： 公司名称、产品名称、版本号、Logo PNG 图片、强调色、结尾画面上方的联系信息。
对于无法找到的信息，请向用户询问。完整工作流程的视频时长建议为 6 到 7 分钟，单一功能则为 60 到 90 秒。
2. 编写故事板
将 assets/storyboard.example.json 复制到项目旁，命名为 storyboard.json，并按照 references/storyboard.md 编写。简要说明：
- 每个片段时长 10–35 秒；
- 章节使用
"n · Title"格式，每个章节的第一个片段设置card: "chapter"； - 包含
intro和outro卡片； - 缩写需要在
speech中拼读出来，并通过caption_replacements恢复为书写形式。
在录制前将旁白展示给用户：现在修改成本很低，后期更改则代价高昂。
3. 生成旁白
$PY <skill>/scripts/narrate.py storyboard.json
此命令会打印每个片段的时长。它只重新朗读文本发生变化的片段。如果发音很重要，可以试听 video-build/audio/ 中的一两个 WAV 文件，调整拼写后重新运行。
4. 编写并运行捕获脚本
将 scripts/capture_template.py 复制到故事板旁，命名为 capture.py，设置技能 scripts/ 目录的路径，然后按照故事板顺序为每个录制的片段编写一个 with rec.segment('<id>'): 代码块。在该代码块内部，精确执行旁白描述的操作：
rec.click、rec.hover、rec.type、rec.drag、rec.scroll、rec.park；- 在耗时的操作周围使用
rec.cut()，并等待可见结果。
录制器拒绝非空的 frames/ 文件夹，因此旧帧永远不会混入。
$PY capture.py storyboard.json
每个片段都会打印其录制时长与旁白时长。如果遇到第一个出错的步骤、任何页面错误或未被录制的片段，则运行失败（状态为 incomplete）。修复出错的步骤，清空 video-build/frames/，然后重新运行。
5. 渲染与审查
$PY <skill>/scripts/render.py storyboard.json
$PY <skill>/scripts/review.py storyboard.json
输出文件位于构建文件夹中：
<output_name>.mp4.srt字幕文件-chapters.txt（可粘贴到 YouTube 描述中）-poster.jpg-timeline.json-review.jpg：每个片段一张静态截图。
打开接触页并仔细查看，同时抽样检查 MP4 文件本身。检查以下内容：
- 每个片段中显示的是正确的界面；
- 没有错误横幅、空白图表或无关对话框；
- 光标从未遮挡正在解释的内容；
- 字幕阅读正确。
选择器可能匹配但屏幕内容错误，因此在宣布视频完成前必须进行此检查。
6. 交付
向用户提供 MP4 文件、SRT 字幕文件（多数播放器在文件名匹配时会自动加载）以及章节列表。注明视频时长和文件大小。发布时，将 MP4 和 SRT 一同上传。请保留 storyboard.json 和 capture.py 与项目在一起：下次 UI 变更后，重新运行步骤 4–5（如果措辞也更改了则运行步骤 3）。
故障排除
| 症状 | 解决方法 |
|---|---|
Need Python 3.10–3.13 | 安装 python3.12，或在运行 setup.sh 前设置 PYTHON= |
launch() 超时但应用已启动 | 应用缓冲了输出：使用 python -u 运行 Python 服务器，或检查 ready 正则表达式 |
| Chromium 在 Linux 上启动失败 | $PY -m playwright install --with-deps chromium |
| 定位器超时或匹配到两个元素 | 将范围限定到一个区域，或使用 get_by_role 配合 exact=True（参见捕获指南） |
| 片段时长远大于旁白时长 | 某些慢操作未包含在 rec.cut() 中 |
| 发音错误 | 在 speech 中重新拼写，添加 caption_replacements 规则，重新运行 narrate.py |
| 字幕不同步 | 字幕时间跟随旁白长度：缩短长句，或拆分片段 |