product-video
实机录制 + 事件日志 -> 声明式计划（YAML）-> pvk render -> 联系表 -> 最终视频。
脚本负责计时、缩放、叠加和音频；您负责故事板、编写计划和检查帧。
PVK=~/.claude/skills/product-video/bin/pvk # 或 `pip install -e ~/.claude/skills/product-video` 后使用 `pvk`
何时使用
| 用户想要 | 制作 | 首先阅读 |
|---|---|---|
| 让用户学习某个功能或整个应用（"视频 hướng dẫn"、教程、新手引导） | 教程：每章1-3分钟，然后 pvk join | references/storyboard.md |
| 为产品或发布吸引关注（"视频 quảng cáo"、宣传、发布、预告） | 宣传片：一个30-45秒的16:9剪辑，依据节拍切换 | references/storyboard.md |
| 简短的Web应用演示或Bug重现片段 | 单独使用web-video技能 | - |
硬性规则
- 真实应用，样本数据。 使用真实的、虚构的样本数据拍摄实际产品。不使用模拟图，也绝不使用
真实客户数据、密钥或生产账户（
references/privacy.md）。 - 先故事板，再获得批准。 用通俗语言编写故事板，在任何拍摄前获得批准。
- 项目的设计。 在项目上运行
theme init，并根据其设计指南检查结果。 - 音乐和音效是强制性的。 每个视频都有背景音乐和UI音效；总响度控制在-16 LUFS。
- 草稿、检查、然后最终版。 渲染
--draft --check，打开每张联系表，修正，然后才进行--final。 - 未经所有者同意，不得将任何内容传出机器（上传、发布、附件问题）。
- 绝不驱动安全、钥匙串或登录对话框。 将这些交给用户。
步骤0. 设置（每台机器一次）
$PVK doctor # 检查 ffmpeg、Python 3.11+、包、Chromium、字体、可选工具
python3 -m pip install -r ~/.claude/skills/product-video/requirements.txt && python3 -m playwright install chromium
$PVK fonts # 下载 Inter、Playfair Display、JetBrains Mono（OFL）到 ~/.cache/product-video
$PVK sfx gen && $PVK music beds
$PVK selftest # 使用捆绑的演示渲染一个短章节和宣传片（约1分钟）
缺少工具：打印安装命令并询问；不要静默安装。
步骤1. 从项目中提取主题
cd <video-folder> # 例如 <project>/video（将输出文件保留在git之外）
$PVK theme init --repo <project> --out theme.json
$PVK fonts --theme theme.json
$PVK overlay chapter title="Preview" --theme theme.json --out preview.png # 查看它
根据设计指南手动修正 theme.json 中的颜色、字体、brand 和 logo（references/theme.md）。
步骤2. 故事板
教程：用户需要学习的每个任务对应一个章节；每个章节 = 章节卡片、带有3-8个编号字幕的录制、回顾卡片。宣传片：5-8个亮点，每个亮点由一张短标题卡片和一个2-4秒的录制片段组成，接着是结束卡片。将其编写为表格（时间、屏幕、字幕、声音）并获取批准。详情：references/storyboard.md。
步骤3. 捕获
| 产品 | 方式 |
|---|---|
| 原生macOS应用 | 编写 scene.py（参见 examples/scene_native.py），然后 $PVK capture native scene.py --app "App" --out takes/s1 --rehearse，然后去掉 --rehearse 运行 |
| Web应用 | 使用web-video录制（record.py --slug x），然后 $PVK capture import video-out/x/v1 --name w1 |
| 其他任何情况 | 将 raw.mp4 和 events.json（参见 references/plan-format.md）放在 takes/<name>/ 目录下 |
| 尚无应用/试用 | $PVK demo --out takes/demo |
每次拍摄前：加载样本数据、关闭通知（勿扰模式）、关闭旧的通知提示、固定窗口大小。
每次拍摄后：$PVK check popups takes/s1 和 $PVK check grab takes/s1 grab.png 1 5 9 进行检查。
macOS陷阱（Mission Control按键、Cmd与Ctrl、真实指针、HUD）：references/pitfalls.md。
步骤4. 计划
将 examples/tutorial.yaml 或 examples/promo.yaml 复制到takes目录旁边并编辑。录制片段中的时间以源秒为单位，基于该take的events.json；框以源像素为单位。完整格式：references/plan-format.md。
$PVK render ch01.yaml --only-plan # 快速：out/plan/ch01.md 列出每个片段、字幕、缩放、声音、警告
修正每个警告（短字幕、重叠、跨越缩放的标注、两位数的步骤编号）。
步骤5. 草稿与检查
$PVK render ch01.yaml --draft --check # 720p；out/drafts/ch01.mp4 + out/check/ch01/contact-*.png
$PVK render ch01.yaml --frames 3.2,7.5 # 在输出时间点的静止帧，用于更仔细的查看
$PVK promo promo.yaml --draft --check # 宣传片：相同引擎，剪辑对齐到节拍网格
打开每张联系表（阅读PNG）。检查：字幕可读且不覆盖操作区域，缩放位置正确，无操作系统弹窗或残留通知，光标位于点击位置，卡片拼写正确，响度约为-16 LUFS。最多进行3次修正，然后向用户展示草稿和联系表。
步骤6. 最终版与完整剪辑
$PVK render ch01.yaml --final # 1080p，out/final/ch01.mp4
$PVK join out/final/tutorial.mp4 out/final/ch0*.mp4
$PVK check out/final/tutorial.mp4
报告：文件路径、时长、响度、无法检查的内容（您无法听到混音：请说明）。
音乐与声音
music: bed:soft-piano | bed:ambient | bed:promo 是合成的背景音乐（原创，免费）。对于授权曲目：
$PVK music fetch（获取位置），然后 $PVK music add track.mp3 --title ... --author ... --source URL --license ...（标准化至-20 LUFS并记录到 music/LICENSES.md）。绝不要提交第三方曲目。
音效映射、闪避和响度：references/audio.md。
参考文档
references/storyboard.md：教程与宣传片对比、章节结构、字幕编写、节拍剪辑references/plan-format.md：所有计划键、events.json格式、时间线计算references/theme.md：theme.json、theme init、字体（OFL）、logoreferences/audio.md：背景音乐、授权音乐、音效映射、响度目标references/capture.md：原生macOS捕获、web-video导入、take目录布局references/pitfalls.md：真实项目中出过的所有问题及其解决方案references/privacy.md：数据和分享规则