Duo 小剧场短片（Nerd + Claude）

Duo 小剧场短片（Nerd + Claude） 是做什么的？

一部 3D 小短剧，Nerd 抓狂，Claude（橙色机器人）面无表情地回答。一切都是程序化 Blender 生成：布景、两套骨骼、表演、灯光、摄像机、显示器、叠加内容、配乐和音效全部基于每集一个 storyboard.json 文件构建。新的一集只是数据，不是代码。没有图像或视频生成步骤。

每集是一个文件夹：<任意内容>/<YYYY-MM-DD>_<slug>/，内含 storyboard.json 和 research.md。流水线将其余所有内容写入该文件夹（assets/、project/、renders/、final.mp4、cover.png、qa/）。仓库的 examples/ 目录下有已完成的两集示例：拷贝一份即可开始。

工作流（按顺序，不要跳过）

1. 主题（5 分钟）。一个能与开发者产生共鸣的开发者/AI 痛点，以及一条开发者今天就能用上的实用技巧。笑点围绕观众如何与自己的 AI 互动展开，而不是关于某个工具。规则和灵感库：references/retention.md。
2. 研究 → research.md：屏幕上/旁白中/字幕里的每个事实都必须有 URL 和日期并已核对，优先使用主要来源（官方文档、README、源代码）。剧本中虚构的故事情节部分（时间、数量、名字）放在独立的“虚构”章节。无法核实的部分直接删除，并说明原因。
3. 剧本 + 分镜 → storyboard.json（复制示例并改写）。结构和词汇表：references/storyboard.md。目标时长 30-40 秒，10-14 句台词，第一个单词在 0.5 秒内开始，每 1.5-3 秒切换一个镜头，Nerd 开场，Claude 收尾，最后一帧切回第一帧。
4. 免费草稿（macOS）：pipeline.sh <episode> --say stills（使用系统语音，无版权声明）。查看 renders/stills/sheet.jpg（每句节奏结束处的一帧）。修正构图/叠加内容碰撞后重新运行。 不在 macOS 上？跳过 --say：先录制或生成声音（步骤 5），然后运行 stills。
5. 声音。每句台词对应一个音频文件，放在 assets/audio/dialogue_raw/<beat id>.mp3（L01.mp3、…）。参考剧集使用 ElevenLabs eleven_v4 模型和两个库角色声音——Nerd = "Quinn - Soft Nerd Boy"，Claude = "Sarcastic Nigel"——并在每句的 tts 中添加音频标签（如 [deadpan] It was ugly.）。使用 Claude 的 ElevenLabs 连接器：先估算每句台词（≈ 每字符 1 个积分，含标签），然后逐句生成，并从其 content_url 下载每个音频片段。一集 11-14 句台词大约需要 700-900 积分。您也可以自己录制：文件名相同。
6. 真实构建 + 布局预览：pipeline.sh <episode> stills。project/whisper_check.txt 列出每句台词的原文与识别结果的对比（比率 < 0.8 表示需要认真听）。实际录制的声音时长比 say 草稿更长：再次检查布局预览图。
7. 最终渲染：pipeline.sh <episode> final（16 个采样，3 个渲染线程，M 系列 Mac 上每帧 ≈ 3 秒：一个 38 秒的短片约需 1 小时；请在后台运行）。它会渲染 final.mp4、B 版本 final_b.mp4、cover.png，并运行 qa.py → qa/report.md（必须显示 Blocking: none）。

硬性规则

• 角色：不要重新设计 Nerd 或 Claude（engine/scene/nerd.py、mascot.py）。Claude 没有嘴巴：它通过身体挤压、弹跳、眼睛和手臂来“说话”。
• 剧本可以虚构故事（这是喜剧），但绝不能虚构产品功能、数字、基准测试结果或引用。
• 视觉提示（印章、按键、对勾）应在它们要说明的单词之前 0.2-0.3 秒出现，绝不能落在最后一个单词上。
• 先做免费草稿，再做付费声音；先做布局预览，再做最终渲染。

文件

• pipeline.sh <episode> [--say] [build|stills|draft|final]
• engine/scene/ Blender 端：build_scene.py（入口）、animate.py（根据分镜控制表演/灯光/摄像机）、env.py（环境）、nerd.py、mascot.py、lights.py、tl.py（锚点，与脚本共享）。
• engine/scripts/：build_timeline.py（音频片段→时间线 + Whisper 单词 + 唇形同步）、make_screens.py（显示器模板）、make_overlay.py（钩子、字幕、物品、标题卡、captions.srt）、make_audio.py + synth.py（配乐/音效）、master_audio.py（-14 LUFS）、stills.py、draft.sh、render_final.sh、encode.sh、make_cover.py、cover_title.py、qa.py、make_textures.py。
• 工具和路径（环境变量，macOS 默认值）：BLENDER（Blender 5.x 可执行文件）、DUO_PYTHON（包含 numpy、scipy、soundfile、pillow 的 Python，默认 ~/.venvs/duo-reel/bin/python）、WHISPER_MODEL（whisper.cpp 模型，默认 ~/whisper-models/ggml-medium.en.bin）、PATH 中需包含 whisper-cli 和 ffmpeg、字体 DUO_FONT_DISPLAY / DUO_FONT_MONO / DUO_FONT_SANS / DUO_FONT_EMOJI。
• references/storyboard.md（结构和所有预设）、references/retention.md（钩子/结构/主题）、references/lessons.md（曾经出过的问题）.