演示视频工作室 是做什么的？
将正在运行的 Web 应用转化为精美的演示电影：真实的录制交互（非幻灯片、非模拟）+ 本地 TTS 旁白 + 逐词同步字幕 + 安静的 背景音乐，通过 HyperFrames 确定性合成。
使用时机
在需要为 Web 应用制作任何演示/导览/产品/发布/黑客马拉松视频时使用，尤其是要展示真实产品运行并附带旁白和字幕的场景。支持录制已部署的 URL 或本地开发服务器。
流水线
① 录制 三种引擎之一（见下） → out/*.mp4|webm
② 旁白 按场景编写旁白稿 → Kokoro TTS（本地） → narration/*.wav
③ 转录 Whisper 逐词时间戳 → *.transcript.json
④ 字幕 分组为短语 + 修复品牌名称误识别 → captions.js
⑤ 音乐 ffmpeg 氛围背景音乐（在语音下低音量混合） → music/bed.wav
⑥ 合成 HyperFrames HTML 单时间线：片段+语音+字幕+音乐 → MP4
① 有三种引擎 —— 根据目标选择 （references/screen-studio-look.md）
| 目标 | 引擎 | 外观 |
|---|---|---|
| Web/桌面应用，macOS | Cap CLI — scripts/record-cap.mjs | Screen Studio 原生：从真实点击自动缩放、弹簧光标+运动模糊、壁纸/圆角/阴影、GPU 渲染 |
| CLI 工具 | VHS 磁带 → mp4 | 样式化终端（内边距、外边距填充、边框圆角、窗口栏），确定性 |
| 无头 / CI / Linux | Playwright — scripts/record.mjs | 合成光标+涟漪；写入 <scene>.events.json（时间戳+坐标），供后期缩放合成使用 |
无论使用哪种引擎录制，其输出仅是片段，用于②–⑥阶段——录制和合成保持独立：可以重录某一场景，或重新运行旁白，而无需重做其他部分。代码生成的 GIF 轨道（直接将 HTML 场景渲染为 MP4 而不录制）是可选的辅助路径，适用于文档页面。
工作流程
- 与用户一起选择引擎 —— 绝不可自行决定。 查看实际项目（Web 应用？CLI？桌面？当前机器是否有 GUI 会话？是否需要在 CI 中运行？），然后向用户展示引擎选项 （包含针对此项目的利弊分析），让用户选择。例如，对于 Mac 上的 Web 应用：“Cap CLI 原生提供 Screen Studio 外观，但需要屏幕录制权限和首次运行校准；Playwright 可在任何地方运行并快速重录单场景，但无自动缩放；VHS 不适用于此场景。”引擎详情：references/screen-studio-look.md。
- 先理解产品。 阅读其 README / 演示文档。在接触工具之前编写演示流程：问题 → 产品导览 → 证据 → 结论。确定推荐的点击路径以及每个场景必须展示的可见结果。参见 references/templates.md。
- 录制。 复制
scripts/record.mjs，设置APP和SIZE，将scenes替换为你的编排动作（滑动 → 暂停 → 操作 → 保持）。以 1:1 设备比例录制。node scripts/record.mjs [scene]。引擎及实例：references/recording.md。 - 旁白 → 字幕。 每场景编写一个
assets/narration/NN-*.txt文件，使用画外音口吻（你是在对观众说话，而不是在朗读 README —— 这与营销文案是不同技巧；营销技能提供主题/钩子/故事板，本技能编写口头台词）。然后运行：bash scripts/tts.sh && bash scripts/transcribe.sh && node scripts/build-captions.mjs。 在build-captions.mjs中编辑PHRASE_FIX以处理品牌名称。 语音是可替换的（按合约）：每场景的旁白是一个单独的 wav 文件（narration/NN-*.wav）—— 可以用人工朗读、剪映配音或其他 TTS 替换任意 wav，重新运行转录+字幕，重新合成；其他部分无需更改。Kokoro（本地，Apache-2.0 许可）是默认引擎，支持中文普通话；edge-tts 是一个免费的在线替代方案。指南：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
# Python 虚拟环境用于本地 TTS + 转录（一次性）
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 会跳转帧，因此运动必须可重复。 - 可见光标 + 在结果上保持 —— 故意滑动，在关键画面上暂停。
- 画外音，非文档 —— 旁白跟随画面；它不是 README 的朗读版本。
- 视频时长 ≥ 旁白时长 —— 为片段增加缓冲时间，确保视觉效果不会在语音之前结束。
依赖
Node 22+、FFmpeg、Playwright（Chromium）以及 HyperFrames CLI（npx hyperframes，通过 npx skills add heygen-com/hyperframes 安装其技能）。本地 TTS/Whisper 需要 Python + kokoro-onnx。各引擎（可选）：Cap 路径需要 cap（curl -fsSL https://cap.so/install-cli.sh | sh）+ cliclick（brew install cliclick）+ 屏幕录制权限；终端路径需要 vhs（brew install vhs）。所有工具均免费 —— 许可表详见 references/screen-studio-look.md。HyperFrames 设置指南见 references/composition.md。
参考
- references/pipeline.md —— 六个阶段和数据流
- references/screen-studio-look.md —— 三种录制引擎；Cap CLI 生命周期、缩放聚类、VHS 磁带、不应构建的内容
- references/recording.md —— Director 引擎 + 实例 + 录制陷阱
- references/narration-and-captions.md —— 旁白编写、TTS、Whisper、字幕修复
- references/composition.md —— HyperFrames 时间线、交叉淡入淡出、1080p、渲染
- references/composition-skeleton.html —— 可渲染的最小合成模板，可复制为 index.html
- references/templates.md —— 黑客马拉松 + 产品演示的结构和画外音模板
- references/troubleshooting.md —— 字幕、白屏、音频、字体