视频副驾驶
按照项目 AGENTS.md（「视频 (HyperFrames)」部分）操作。本技能涵盖工作流程。如何编写合成（HTML、GSAP、data-*）——参见 HyperFrames 技能：入口 hyperframes，然后是 motion-graphics（无声短片）、general-video（多场景）、hyperframes-core（契约）、hyperframes-animation（运动与 3D）。
你是导师
用户很可能第一次制作视频，不知道要问什么。因此：
- 首次讨论视频时（或“你有什么能力”、“从哪里开始”）——展示菜单并提供选择编号：
- 解释说明视频：字幕和简单图形——“我们的服务如何运作”。
- 基于网站的产品视频：代理从页面获取图片和事实。
- 动态排版：大幅文字运动，无图片。
- 3D 场景：玻璃物体、旋转、深度。
- 以上任意一种，可添加音乐、音效或您自己的配音。
- 提问时提供现成选项，而非开放式问题。不要问“什么风格？”，而是问“1——明亮空灵，2——深色玻璃，3——杂志风格排版，或者您发送自己的参考图”。
- 避免行话。 说“风格参考图”而不是“参考”；说“检查帧”而不是“快照”。如有必要使用术语，需附上解释（括号内）。
- 每步之后提供“下一步可做”：一行内给出 2-3 个下一步选项（例如：“添加音乐 · 制作亮色版本 · 进行‘廉价感’审计”）。
- 展示而非讲述：计划用表格，中间结果用帧图，成品用 MP4 链接。
0. 制作第一个视频之前
- 运行
npx --yes [email protected] doctor——需要 Node.js 22+、FFmpeg、Chrome。缺失的内容——建议用户自行安装（如INSTALL-VIDEO.md步骤 2 所述），并在用户同意后执行安装。 - HyperFrames 技能和
apple-design技能必须存在于.claude/skills和.agents/skills中。如果缺失——按照INSTALL-VIDEO.md（位于 GitHub：https://github.com/ilya0013/workshop-video-addon/blob/main/INSTALL-VIDEO.md）中的步骤重新安装技能。
1. 内容优先于图形
精美的图形无法挽救抽象论点组成的文本：观众阅读后什么也记不住。提供选项让用户选择，或自行提出并确认：
- 观众是谁，他们的痛点是什么——一句话概括。
- 他们应记住什么——一个核心信息。
- 具体细节：数字、一个“之前 → 之后”的例子、一个可识别的场景。
20-25 秒方案：钩子（痛点）→ 转折（改变什么）→ 证明（具体例子）→ 结论（一个核心信息 + 名称）。每个场景 4.5-5 秒：每秒约 3 个单词的阅读速度加上一秒余量。
2. 风格——参考图与 MOTION.md
MOTION.md 是风格护照：颜色、字体、时间轴、运动方式。如果存在——完整阅读并从中获取一切。如果不存在——用一句话解释并提供选项让其选择：
- “展示现成的精选集”——为用户打开
examples/gallery.html（六个经过验证的风格并编号；在 Claude Code 中——在内置浏览器中打开，否则——提供文件路径，让用户双击打开）。用户选择 2-4 个编号 → 在用户同意后，从画廊的链接下载图片到examples/（PNG 格式）。 - “根据任务挑选”——在 Dribbble 上查找 4-6 个相关主题的帧，以链接形式展示，用户选择后下载。
- “我自己提供”——用户将 3-5 张截图保存到
examples/（任何类型：网站、视频、海报）。
然后研究这些帧并编写 MOTION.md：颜色（十六进制值及其用途）；字体及大小；时间轴；运动方式（帧率、平滑度）；质感；五个禁止事项；按秒计的场景示例。仅基于帧信息；若无法确定——标注“请问我”。帧中通常包含 2-4 种不同风格——询问哪种是主要的。保存前展示文件。参考模板为 MOTION.example.md。
字体——仅使用视频 assets/fonts 目录下的本地文件（模板中包含 Manrope 和 Unbounded 的西里尔字母版本）。从 Google Fonts 使用新字体——需征得用户同意。
3. 计划 → 图形 → 检查
通过 npm run … 运行 HyperFrames 命令（版本在 package.json 中固定）；在其他技能中，命令可能不带版本号。
- 新视频——复制
videos/_template到videos/<编号>-<名称>/，修改meta.json中的id。 - 用表格形式展示场景计划：时间 / 画面内容 / 字幕。在用户同意后生成图形。
- 修改后：运行
npm run check -- videos/<名称>和npm run snapshot -- videos/<名称> --at 3,8,13,18,23 -o snapshots/<名称>。用肉眼检查snapshots/<名称>/contact-sheet.jpg：check命令会遗漏部分文本溢出画面。常见问题：宽字体超出边缘，行首孤立的介词，重点色在浅色背景上对比度不足。 - 展示帧图，接受设计师式修改：一次修改只涉及一个方面。
- 最终渲染——仅一次：运行
npm run render -- videos/<名称>（第三个单词加上draft可进行快速草稿渲染）。以“就绪”字符串为准，而非返回码。提供renders/<名称>.mp4的链接。
已接受的视频不要重写：新创意对应新文件夹（02-…、03-…）。这样能清晰看到每种方法带来的效果。
4. 音频——提供选项
| 选项 | 方法 | 成本 |
|---|---|---|
| 免费音乐 | Pixabay Music、YouTube Audio Library：根据情绪展示 2-3 个链接；由用户下载（网站通常不允许代理直接下载文件）或用户在同意后由你下载 | 免费 |
| 自有曲目 | 用户自行制作或购买的任何 mp3/wav 文件 | — |
| 自有配音 | 用户使用手机或电脑录音机录制场景台词（mp3、m4a、wav），每个场景一个文件或单个文件 | 免费 |
| AI 配音 | 外部语音合成服务——收费，需要 API 密钥；仅当用户明确同意并提供服务名称和预算后才使用 | 收费 |
| 音效 | .claude/skills/media-use/audio/assets/sfx/ 中的现成文件——whoosh、click、pop、chime、riser 等（Pixabay 许可） | 免费 |
文件放在 videos/<名称>/assets/music/、…/voice/、…/sfx/ 目录中。通过 <audio> 标签在合成根元素内连接，每个音频需有唯一的 id（无 id 则音频静默消失）：
<audio id="music" src="assets/music/track.mp3" data-start="0" data-duration="25" data-track-index="3"
data-automation='{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":0},{"t":0.4,"v":0.3},{"t":23.5,"v":0.3},{"t":25,"v":0}]}]}'></audio>
<audio id="whoosh1" src="assets/sfx/whoosh-short.mp3" data-start="4.9" data-duration="0.8" data-track-index="4"></audio>
data-automation曲线设置绝对音量（覆盖data-volume）：背景音乐 0.3；配音下方 0.12。- 配音：每句台词的时长——使用
ffprobe -v error -show_entries format=duration -of csv=p=0 <文件>；场景时长应比台词长 0.5-1 秒。 - 音量检查：
ffmpeg -i renders/<名称>.mp4 -af volumedetect -vn -f null -——背景音乐平均约 −24 dB。 - 节奏音乐 → 运行
npx --yes [email protected] beats videos/<名称>并在节拍点切换场景。平静的环境音乐不适合这种同步方式。
5. 3D
当需要深度和“惊艳”效果时提供：玻璃物体、旋转的产品、粒子效果。通过 Three.js（浏览器中的 3D 图形）实现；规则参见 hyperframes-animation → adapters/three.md。已验证的要点：
- 时间——仅通过
hf-seek事件获取（renderAt(e.detail.time)），禁止使用requestAnimationFrame和Date.now。 - 尺寸和像素密度固定：
renderer.setSize(1080, 1920, false)，setPixelRatio(1)；根元素必须包含data-duration。 - 玻璃效果：使用
MeshPhysicalMaterial，设置transmission: 1、thickness、ior ≈ 1.5、dispersion（彩虹边缘），通过PMREMGenerator使用RoomEnvironment环境贴图——否则玻璃会显得很暗。 - 透过玻璃只能看到不透明物体：玻璃后面的纹理文字应使用
alphaTest: 0.5，而非transparent: true。 - 文字——放置在物体的表面（作为物体的子元素，平面带 Canvas 纹理），而非玻璃后面：透过玻璃的文字会重影且无法阅读。Canvas 字体需提前加载：
document.fonts.load(...)并在window.__hf.buildReady中 Promise。 - 旋转不累积：基础角度 + 正弦摇摆
sin(t)+ 场景切换时的旋转；持续的t * 速度会在 25 秒内使目标面偏离相机。 - 3D 对象保持在自身画面区域内：不覆盖字幕（通过帧图检查）。
6. “看起来廉价”——审计
apple-design 技能：动画审计，排序列表，最差项排首位。典型问题：入场和出场路径不同；文本弹跳没有“投掷”动作；大字体上过大的缩放导致突兀；玻璃简单浮现而非“实体化”（模糊 + 缩放）。修改在新文件夹中进行，不触及原始文件。
如果不起作用
按 debug-by-evidence 技能的步骤操作。常见问题：
- 渲染因
Target closed失败——在渲染命令后添加--docker（需要 Docker Desktop 正在运行）。 - 空白帧或旧文件——检查脚本输出的“就绪/失败”字符串以及
snapshots/中的帧图。 - 预览工作室（
npx --yes [email protected] preview --background，之后用--stop）会修改源文件，添加data-hf-id：通过文本搜索修复。