演示视频工作室
将正在运行的 Web 应用转化为一部精美的演示影片：真实的录制交互（不是幻灯片，不是 mock）+ 本地 TTS 旁白 + 词语级同步字幕 + 轻柔的背景音乐，使用 HyperFrames 确定性组合而成。
何时使用
制作任何 Web 应用的演示/走查/产品/发布/黑客松视频，尤其是需要展示真实产品运行过程并配有旁白和字幕的场景。可录制已部署的 URL 或本地开发服务器。
管线
① 录制 Playwright 驱动你的在线应用，显示可见光标 → out/clips/*.webm
② 旁白 为每个场景编写 VO 脚本 → Kokoro TTS（本地） → narration/*.wav
③ 转录 Whisper 输出词语级时间戳 → *.transcript.json
④ 字幕 组合成短语 + 修复品牌误听 → captions.js
⑤ 音乐 ffmpeg 环境音轨（混合在语音下方的低声层）→ music/bed.wav
⑥ 合成 HyperFrames HTML 单时间轴：画面+语音+字幕+音乐 → MP4
录制和合成是独立的：可只重新录制某个场景，或只重新运行旁白，无需重做其他工作。代码生成的 GIF 轨道（HTML 场景直接渲染为 MP4，无需录制）作为可选的辅助路径，用于文档页面。
工作流程
- 先理解产品。 阅读其 README / 演示文档。在接触工具之前先编写演示流程：问题 → 产品走查 → 证据 → 结论。选择推荐的点击路径以及每个场景必须达到的可见结果。参见 references/templates.md。
- 录制。 复制
scripts/record.mjs，设置APP和SIZE，将scenes替换为你的编排（滑动 → 暂停 → 操作 → 停留）。以 1:1 设备缩放录制。node scripts/record.mjs [scene]。引擎 + 工作示例：references/recording.md。 - 旁白 → 字幕。 为每个场景编写一个
assets/narration/NN-*.txt文件（用 VO 口吻，像在对观众说话，而不是朗读 README）。然后：bash scripts/tts.sh && bash scripts/transcribe.sh && node scripts/build-captions.mjs。在build-captions.mjs中编辑PHRASE_FIX以适应你的品牌名称。指南：references/narration-and-captions.md。 - 合成与渲染。 从 references/composition-skeleton.html 开始（一个画面 + 字幕轨道 + 音频），扩展时间轴，然后运行
npx hyperframes render . --resolution landscape --fps 30 --crf 17 --quality high。以 1:1 比例渲染（1080p 创作 → 1080p 输出）——永远不要缩放到 4K，那会让 UI 变模糊。references/composition.md。 - 发布前质检。 使用 ffprobe 检查时长/音频，抽样检查 1–2 帧（没有黑屏，没有空帧），字幕在画面内，旁白没有截断，关键结果页面实际可见。修复流程/时间轴，然后重新渲染。
快速开始
# 系统依赖
brew install node ffmpeg
npx playwright install chromium
# 本地 TTS + 转录的 Python 虚拟环境（一次性）
python3 -m venv .ttsvenv && .ttsvenv/bin/pip install kokoro-onnx soundfile
export PATH="$(pwd)/.ttsvenv/bin:$PATH"
# 1) 录制 2) 旁白 3) 字幕 4) 合成+渲染
node scripts/record.mjs
bash scripts/tts.sh && bash scripts/transcribe.sh && node scripts/build-captions.mjs
npx hyperframes render . --resolution landscape --fps 30 --crf 17 --quality high --output out/demo.mp4
首次运行 TTS 会下载约 340 MB（Kokoro），首次转录约 466 MB（Whisper small.en）；两者都会缓存在 ~/.cache/hyperframes/ 中。
实践总结的规则
- 真实交互胜过幻灯片——录制产品实际运行。
- 1:1，绝不 2× 放大——以 2× DPR 录制再渲染 4K 会让每一个 UI 画面变模糊。创作和渲染应在 1080p。
- 确定性合成——HTML 中不能出现
Date.now()、Math.random()或网络请求；HyperFrames 会按帧定位，所以运动必须是可重现的。 - 可见光标 + 在结果上停留——故意慢慢滑动，在关键画面上暂停。
- VO，不是文档——旁白跟随画面；它不是把 README 读一遍。
- 视频时长 ≥ 旁白时长——填充剪辑时间，确保画面不会在语音结束前结束。
依赖
Node 22+、FFmpeg、Playwright（Chromium）以及 HyperFrames CLI（npx hyperframes，使用 npx skills add heygen-com/hyperframes 安装其技能）。本地 TTS/Whisper 需要 Python + kokoro-onnx。有关 HyperFrames 设置的详细信息，请参见 references/composition.md。
参考资料
- references/pipeline.md — 六个阶段与数据流
- references/recording.md — 导演引擎 + 工作示例 + 录制陷阱
- references/narration-and-captions.md — VO 编写、TTS、Whisper、字幕修复
- references/composition.md — HyperFrames 时间轴、交叉淡入淡出、1080p、渲染
- references/composition-skeleton.html — 可直接复制的极简可渲染合成文件，作为 index.html 使用
- references/templates.md — 黑客松 + 产品演示结构及 VO 框架
- references/troubleshooting.md — 字幕、白屏、音频、字体问题