SergeoDev01/talking-head-reels

Talking-head reels

你将一段人物对镜头说话的录像转变为成品竖屏短视频（MP4）。画面风格是编辑式且快速的：说话者是视频的主线，每2-4秒画面会变化——推进、大字幕、B-roll插入、分屏——始终由当前所说的内容驱动。

所有技术流程都是脚本化的：剪掉停顿、语音母带处理、蒙版，以及一个根据编辑决策列表（EDL）逐帧渲染的渲染器。你的工作是编辑部分：理解讲话内容，决定每个节拍应该呈现什么，寻找或生成匹配的素材，编写EDL，检查静态截图，以及和用户一起进行修改轮次。

需求

macOS（原生渲染目标）—— Python 3.9+ 并安装 numpy 和 faster-whisper，以及带 libass 的 ffmpeg（Homebrew ffmpeg 或 imageio-ffmpeg）。可选——Xcode 命令行工具（用于 Apple Vision 蒙版）。

Windows 10/11 渲染机：渲染引擎与平台无关。Python 3.9+ 并安装 numpy 和 faster-whisper，以及一个包含 libass 的 ffmpeg 构建（gyan.dev "full" 构建）就足够了——然后使用 assets/fonts/win/ 中提供的免费替代字体（Playfair Display 400/700/italic + Inter Medium，OFL 授权）：

1. 设置一次用户环境变量——REEL_FONT_FILES = 四个 .ttf 文件的路径，以分号分隔。引擎通过自己的 REEL_FONT_FILES 钩子（textass.py）获取它们，并将字体文件提取到 libass 文件夹中；
2. 在每个 EDL 中添加内置的 EDL 字体覆盖： "fonts": {"anton": "Anton-Regular", "serif": "PlayfairDisplay-Bold", "didot": "PlayfairDisplay-Regular", "sub": "Inter-Medium"} （reel_plan.py 中的默认映射保持不变——macOS EDL 不需要覆盖）；
3. Apple Vision 剪切蒙版在 Windows 上不存在：跳过那些节拍。 python scripts/check_setup.py 会报告 Windows 感知的结果。

没有版权问题：B-roll 来自用户自己的素材和免费库（Pixabay / thesvg MCP 连接器，Wikimedia Commons）；付费生成附录（Higgsfield / Seedance）仅在用户明确要求时才使用。

你的交付物

• PROJECT/render/<name>_vN.mp4——1080x1920，H.264，AAC 320 kbps，语音大约 -14 LUFS。
• PROJECT/edl.json（以及每轮修改的 edl_vN.json 副本）——整个编辑以数据形式存在；重新渲染总能得到相同的视频。
• 用于审核的 QA 静态截图（PROJECT/qa/.../sheet.jpg）。

步骤 0 - 设置和输入

运行 python3 scripts/check_setup.py（此文件中的路径相对于技能文件夹）并修复它报告的问题。对所有脚本使用相同的 Python；使用包含 numpy faster-whisper imageio-ffmpeg 的虚拟环境是最简单的方法。ffmpeg 必须包含 libass（所有文本都通过它绘制）——检查脚本会显示它找到了哪个二进制文件。

然后确保你知道（只询问缺失的信息——一条简短消息）：

1. 录像文件（路径）。理想情况下是 4K 水平或 1080x1920 竖屏，说话者大致居中。
2. 语言，以及如果有的话，脚本（有助于发现填充词和转录错误）。
3. 颜色分级：已经分级好的文件、.cube LUT，或“使用相机颜色”。
4. 视频结尾的行动号召（例如“评论 WORD，我会发送链接”）。
5. B-roll 可能来自哪里：他们自己的素材（默认）、免费素材和档案（Pixabay MCP、Wikimedia Commons）、通过 thesvg MCP 获取的徽标/图标（回退到 Commons PNG 渲染）。询问他们拥有哪些素材的版权。付费 AI 生成（Higgsfield / Seedance）仅在用户明确要求时才使用。
6. 保存项目文件夹的位置（默认：在视频旁边，<name>_reel/）。

步骤 1 - 准备和分析（脚本化）

python3 scripts/prepare_project.py VIDEO.mov [--graded GRADED.mov | --lut grade.cube] [--project DIR]
python3 scripts/transcribe.py DIR [--language en] [--model small|medium|large-v3]
python3 scripts/cut_pauses.py DIR [--remove 2.40-2.72 ...]
python3 scripts/master_audio.py DIR
python3 scripts/presenter_mattes.py DIR        # 需要 swiftc；如果不可用则跳过

cut_pauses.py 会打印每个保留的片段及其单词。对照转录文本阅读：使用 --remove start-end（源秒数）移除错误的开头、重复的拍摄和填充词，然后再次运行。向用户报告删除了多少内容（例如“81.5 s -> 73.4 s”）。后续步骤都使用程序时间线（analysis/program_words.json）。

步骤 2 - 规划编辑（你的判断）

阅读 references/style-guide.md（画面风格和规则）和 references/edit-planning.md（如何将讲话转换为节拍），然后编写一个节拍表：每个节拍一行，包含程序时间、说话内容、屏幕上的内容（说话者全景/特写、插入类型、布局）、文字处理方式和素材构思。在寻找素材之前向用户展示——现在修改成本低，以后修改成本高。

步骤 3 - 素材

遵循 references/broll-sourcing.md：寻找什么，素材可能来自哪里，许可信息，以及经过测试的免费获取方法（Pixabay MCP 搜索 + URL 验证，Wikimedia Commons API + curl UA/重试 + SHA-1 校验，用于徽标的 thesvg MCP，ffmpeg 转码）。付费生成（通过 Higgsfield 的 Seedance）在附录中——仅当用户明确要求 AI 生成镜头并批准成本时才使用。将所有内容放入 PROJECT/broll/ 和 PROJECT/logos/。使用 scripts/clip_sheet.py 审核候选素材。如果用户已经有片段或插入素材，请使用它们——不要重新获取已有的内容。

步骤 4 - EDL 和验证

编写 PROJECT/edl.json，遵循 references/edl-schema.md（一个完整的工作示例——基于此风格构建的 reel——位于 assets/examples/example_edl.json）。然后：

python3 scripts/validate_edl.py DIR/edl.json

修复每个错误；阅读每个警告，要么修复它，要么有意识地接受它。

步骤 5 - 静态截图，然后渲染

python3 scripts/render_reel.py DIR/edl.json --stills 0.6 2.4 4.8 ... --out-dir DIR/qa/stills_v1
python3 scripts/render_reel.py DIR/edl.json --out DIR/render/<name>_v1.mp4

静态截图只需要几秒钟：在每个节拍内选一个时刻，加上每个过渡的中间时刻，然后对照 references/style-guide.md 中的检查清单检查联系表（没有空白边缘，文字可读且在画面内，没有任何东西覆盖眼睛，文本在中心堆叠，颜色处理正确）。修复 EDL 并重新检查直到干净。然后渲染完整的 reel（在较新的 Mac 上需要几分钟；参见 references/renderer.md）并将路径以及渲染器打印的数字（大小、帧率、时长、响度）提供给用户。

步骤 6 - 修改轮次（按用户希望的方式工作）

• 用户逐条发送意见，通常是带有几个字的截图。给它们编号（1、2、3……），简洁确认，并且在用户说完成之前（“开始”、“继续”、“就这些”），不要做任何改动。然后一次性应用所有修改。
• 每一轮都是一个新版本：在编辑前将 edl.json 复制为 edl_vN.json，渲染为 <name>_vN.mp4。永远不要覆盖用户已经看过的渲染或 EDL 版本。
• 首先使用 --stills 检查更改的时刻，然后只渲染一次完整视频。
• 在各轮中保持相同的风格；当一条意见暗示了一条通用规则（“没有空白边缘”、“更大的字幕”）时，应将其应用于所有地方，而不仅仅是屏幕截图中的部分。
• 如果用户想要更改某个镜头的素材，只需在 EDL 中更改该片段（参见 references/edl-schema.md 中的“交换片段”）——其他内容不动。

其他工具

• scripts/render_reel.py --stills ...——任意时刻，输出为 PNG 文件加联系表。
• scripts/clip_sheet.py——候选片段的帧和硬切时间。
• references/renderer.md——渲染器的工作原理、速度、字体、故障排除。

基本规则

• 素材：只使用用户拥有版权的内容——他们自己的素材、已授权或免费授权的素材，或为他们生成的片段。生成的人物不能看起来像真实的演员或名人，不能重现知名角色、服装、徽标或电影场景。
• 每个渲染都是一个新文件。永远不要覆盖用户已经审阅过的内容。
• 项目文件中使用英语；与用户交流时使用他们的语言。