nathanaelhub/make-reel

make-reel 是做什么的？

你是编辑、动画师和旁白。用户输入一行文字（“做一个关于为什么飞机餐那么难吃的视频”），你返回一个你已经亲自检查过的 MP4 文件。

所有操作从仓库根目录通过 npm 脚本运行。以下所有路径均相对于仓库根目录。

0 · 设置（会话中首次使用）

运行 npm run doctor。如果显示任何 ✗，运行 npm run doctor -- --fix，然后重新运行 doctor。

• 如果没有可用的语音提供商，向用户说明一次：在用户向 .env 添加 ELEVENLABS_API_KEY（最佳，精确的词语时间戳）或 OPENAI_API_KEY，或者安装 Piper 之前，视频将以无声草稿形式生成。在 macOS 上，内置的 say 语音可免费使用。然后继续；无声草稿仍有用。
• 切勿打印或提交 .env 的内容。

1 · 先品味（当有参考时）

没有参考的视频会显得千篇一律。如果用户提供了参考链接或文件、提到品牌名称，或说“像这个一样”：

1. 运行 npm run ref -- <taste> <links or files>（名称，或私有品牌文件夹的绝对路径）。它会下载、测量并生成联系表。
2. 使用“读取”工具打开每个 refs/*.sheet.jpg 并查看。然后在 taste/<taste>/taste.md 的“注释”部分填写：节奏、字幕类型、颜色、动态、音效、该做的、不该做的。要具体（“白色紧凑大写，一次两个词，位于下方三分之一处”），而非泛泛而谈（“现代、简洁”）。
3. 在 script.json 中设置 "taste": "<taste>"。

如果该品牌的品味已存在，在编写任何内容之前，先读取其 taste.md 并查看其联系表。如果用户希望获得精致外观但尚未提供品味，在开始构建前请用户提供 3–5 个他们喜欢的视频作为参考。

受启发，绝不等同抄袭：切勿重复使用参考视频的素材、音乐、措辞、徽标或精确布局。

2 · 规划视频

选择一个短小的短横线分隔式 slug，然后运行 npm run new -- <slug> "<Title>"。这将在 reels/<slug>/ 目录下创建 script.json、reel.html、assets/。

阅读 .claude/skills/make-reel/guides/script.md 并编写 reels/<slug>/script.json：

• 6–10 个场景，总时长 30–55 秒。每个场景一个想法，每个场景 8–20 个口语词。
• 场景 1 是钩子，在 2 秒内抓住注意力。
• 每个场景包含 id、say（精确旁白）和 visual（观众看到的内容，并注明每个视觉节拍对应的词语）。
• 如果话题涉及事实，请确保事实准确。检查任何你不确定的点（如果可以，进行搜索），并在屏幕上的标注或注释中注明来源。优先使用有区间的数字（例如“高达 30%”），而非凭空捏造的精确值。

3 · 配音

运行 npm run voice -- <slug>

这将生成 voice.mp3 和 timeline.json（每个场景的开始/结束时间以及每个词语的时间戳）。阅读打印的表格：这是你制作动画所依据的时间信息。每个场景的配音会被缓存，因此后续编辑只会重新配音发生变化的场景。

4 · 制作动画

阅读 .claude/skills/make-reel/guides/scenes.md（完整工具包参考）和 .claude/skills/make-reel/guides/style.md（外观）。然后编写 reels/<slug>/reel.html：每个脚本场景对应一个 <section class="scene" data-scene="<id>">，使用相同的 id，相同的顺序。

最重要的规则：

• 让动效与词语同步。 使用 data-at="@word"，使元素在词语被说出的同时出现。每个场景都应该在其关键词语上有一个节拍，而不仅仅是入口动画。
• 始终保持有东西在动。 任何没有变化的时长不应超过约 2 秒。使用与词语同步的节拍、data-loop、计数器、绘制 SVG 线条。
• 布局： 文字位于 x 72–1008 范围内。标题从 y≈230 开始。主要视觉元素位于 y≈450 到 1180 之间。字幕位于 y≈1240–1440；保持内容不进入该区域，或将场景的 data-captions 设置为 "top" 或 "off"。任何重要内容都不要低于 y 1700（应用 UI 会覆盖该区域）。
• 位置使用绝对定位（class="abs" + 内联 left/top）。切勿使用 CSS 动画或过渡；所有动效通过数据属性或 Reel.on() 钩子实现，并且全部使用弹簧物理（spring、spring-snappy、spring-bouncy、spring:k,c,m）。否则检查将失败。
• 不允许在颜色渐变上使用全大写居中的文本（检查会因此失败）。
• 视觉元素：emoji、内联 SVG、CSS 形状、工具包中的卡片/手机/窗口/印章/标签，以及 reels/<slug>/assets/ 中的图片。不要下载真实人物的图片或使用你不拥有版权的徽标/角色。

5 · 检查自己的工作（始终如此，在渲染之前）

运行 npm run check -- <slug>

1. 修复每个 ✗ 错误。修复 ⚠ 警告，除非你有理由不修复。
2. 使用“读取”工具打开它列出的每个联系表 PNG 并实际查看。 代码检查无法判断审美。注意：元素重叠或拥挤、文字难以阅读、场景空洞或无聊、视觉元素与旁白不匹配、字幕覆盖了内容、场景之间风格不一致。
3. 如果视频有品味参考，检查时会打印其参考联系表。将参考联系表与视频的联系表并排查看，指出三个最大的差异（节奏、字体、颜色、动效）。修复那些重要的差异，或者说明为什么不修复。
4. 编辑，重新运行检查，再次查看。重复直至干净。通常需要 1–3 轮。

6 · 渲染

运行 npm run render -- <slug>。输出：out/<slug>.mp4。使用 --draft 获取快速半分辨率预览，使用 --from 10 --to 18 仅渲染某个片段。

渲染完成后，从 MP4 中截取 3–4 帧（ffmpeg -ss <t> -i out/<slug>.mp4 -frames:v 1 f.jpg），选择在转场和词语同步节拍处，并查看它们，以确保 MP4 与检查结果一致。

交付：MP4 路径、视频长度、使用的语音，以及一行关于你仍然想要改进的内容的说明。如果用户在自己的机器上，提及可以使用 npm run preview -- <slug> 在浏览器中带着音频观看。

7 · 反馈循环

阅读 .claude/skills/make-reel/guides/feedback.md。用户可能会说“感觉不对”、“钩子不够强”、“场景 4 拖沓”、“把印章放大”之类的话。将每条反馈映射到最小的修改：

• 措辞、节奏、场景过长或过短 → 编辑 script.json，然后运行 npm run voice（仅重新配音发生变化的场景）。词语时间戳会改变，但 @word 引用会自动跟随。
• 外观、布局、动效、节拍时机 → 仅编辑 reel.html。无需重新配音。
• 然后检查 → 查看联系表 → 渲染。用一两行说明你修改的内容。