talking-clip 是做什么的？
一个视频剪辑包含四个步骤：编写台词、生成语音、规划表演、构建和渲染。 输出：一个 HyperFrames 项目和一个 mp4 文件（默认垂直 1080×1920）。
1. 台词 你编写，使用角色的语气
2. 语音 scripts/tts.py （ElevenLabs 消耗点数；say 和 none 免费）
3. 规划 你编写 plan.json （手势和表情对应到单词）
4. 视频 scripts/build_clip.py -> scripts/verify.py -> scripts/render.py
路径相对于本包的根目录：即包含 .claude-plugin/ 的文件夹，位于此文件向上两级（先解析符号链接）。需要公开的 HyperFrames 技能（hyperframes、hyperframes-cli）：在手动编辑任何合成之前，先阅读一次 hyperframes。
0. 预检（始终优先执行）
运行 python3 scripts/setup.py doctor（添加 --json 可解析输出）。它会列出每个依赖项、用途以及适用于本机的确切安装命令；如果缺少必需项，则退出并返回代码 1。
- 必需缺失（ffmpeg、Node.js 18+、HyperFrames 技能，以及配置了该语音时的 ElevenLabs 密钥或
say）：用一行告诉用户每个依赖项的用途，并建议打印出的命令。仅在用户同意后执行。切勿自行输入或询问 API 密钥：告知用户在其 shell 中导出ELEVENLABS_API_KEY。 - 可选缺失：向用户提供一次，并说明每个依赖项解锁的功能。Playwright 提供带元素缩放框的网页截图和整页截图，tesseract（OCR）提供截图的秘密扫描，ASR（mlx-whisper / openai-whisper）提供音频检查和精确的字词时间。如果用户拒绝，则跳过；相应的检查将变为手动的
review步骤。 - HyperFrames 技能（
hyperframes、hyperframes-cli、hyperframes-registry、media-use）：如果缺失，建议运行npx hyperframes skills。在构建或编辑任何合成之前，先阅读hyperframes（以及遇到渲染问题时参考hyperframes-cli）。
设置（首次运行，或用户想要更改某些内容时）
查找配置：python3 scripts/setup.py show。如果没有配置，或者用户要求更改角色、语音、渲染或样式，则进行询问（每次简短一个问题，提供默认值），然后使用标志写入：
| 问题 | 标志 | 选项 |
|---|---|---|
| 哪些部分？ | --features | character、explainer 或两者 |
| 哪个角色？ | --character | 捆绑的示例（pkg:characters/host/character.json）或其角色文件路径（存储为绝对路径） |
| 叙述语言 | --language | ISO 代码；使用 say 时会选择清晰的语音（setup.py voices --lang <code> 列出，--say-voice 覆盖） |
| 哪个语音？ | --voice | elevenlabs（用户的 ELEVENLABS_API_KEY 和 --voice-id）、say（macOS，免费）、none |
| 信用额度保护（ElevenLabs） | --max-chars、--max-seconds、--daily-credit-cap | 用户选择的数字；留空 = 无保护 |
| 如何渲染？ | --render | local（免费，本机）、cloud（HyperFrames 云，需要 npx hyperframes auth login）、preview（仅 Studio） |
| 尺寸 | --size | 1080x1920、1920x1080、1080x1080 |
python3 scripts/setup.py init --features character --voice say --render local --yes
init 首先运行 doctor 并提供相同的安装。如果配置已存在，则会在覆盖前询问，非交互模式下需要 --force。
用户自己的角色：python3 scripts/setup.py new-character --name "<名称>" --out ./characters/<名称> --activate 复制示例并使其激活（无需第二次 init）。然后帮助用户填写打印出的键：description、personality、speaking_style.rules、rig.colors（或 sprites）、expressions / poses / gestures、set、voice_moods。
切勿询问、打印或写入 API 密钥。如果缺少 ELEVENLABS_API_KEY，告知用户在其 shell 中导出。配置文件架构在 config/config.schema.json；角色文件格式在 README 中（"你自己的角色"）。
为此剪辑选择风格
没有固定外观。对于每个剪辑，根据主题、受众以及用户的品牌或品味选择风格：场景（{"type": "color"|"gradient"|"image", ...}）、构图（close、medium、wide）和动作强度（calm、normal、lively）。当选择很重要时询问用户，例如剪辑用于品牌、公共频道或系列时。在不同剪辑之间变化风格，而不是重复上一个。如果配置包含 brand 套件，则其 background 将覆盖你的选择。将其写入文件并传递 --style：
{"set": {"type": "gradient", "colors": ["#FFF4E6", "#FFD9B3"]}, "framing": "medium", "motion": "lively"}
台词也是如此：在角色个性范围内匹配受众的语气，并且不要重复使用上一个剪辑的开场白或结束语。
1. 编写台词
读取配置中命名的角色文件（character 键）：personality 和 speaking_style.rules 是语气。遵循它们；用户的要求在冲突时优先。
- 长度：最多
styles.talking_clip.max_seconds。以speaking_style.chars_per_second（约 14）计算，20 秒的剪辑约 260 字符以内。一个想法，一句结束语。 - 语言：用户的语言，除非另有要求。
- 带有音频标签的 ElevenLabs 模型（v3 及更高版本）接受英文情感标签，放在要强调的词之前的方括号内：
[excited]、[calm]、[whispers]、[laughs]、[pause]。say和none会忽略它们（会被移除）；改为用手势表演。
2. 生成语音
python3 scripts/tts.py estimate --text "<台词>" --max-seconds 20
python3 scripts/tts.py speak --text "<台词>" --out out/voice.wav [--mood excited] [--confirm]
- ElevenLabs：始终先运行
estimate并告知用户费用；speak在没有--confirm时会拒绝，并且当用户设置的保护（最大字符数、最大秒数、每日信用额度上限）将被打破时也会拒绝。--takes 2生成替代方案。单词时间信息存储在out/voice.wav.words.json中。 --mood从角色的voice_moods中选择一种情绪（ElevenLabs 设置 + 可选的 ffmpeg 滤镜）。say/none：免费。使用none时没有音频；改为向构建器传递--text。
3. 规划表演
python3 scripts/timings.py out/voice.wav --text "<台词>" 提供单词开始时间。编写 plan.json：
{"expression": "neutral",
"events": [{"t": 0.0, "gesture": "hello"},
{"t": 2.1, "gesture": "explain", "dur": 2.5},
{"t": 5.0, "expression": "happy"},
{"t": 6.2, "gesture": "wink"}]}
gesture和expression的 ID 来自角色文件（gestures、expressions）；每个手势都有描述和典型的dur。规划前请阅读它们。- 嘴部、眨眼、呼吸和空闲摇摆是自动的。你只需放置表演节拍。
- 在与手势配合的单词前 0.2-0.3 秒放置一个强烈的手势。每个节拍一个反应；同一秒内永远不要有两个手势。以平静、保持的手势结束（它会自动保持到结束）。
4. 构建、验证、渲染
python3 scripts/build_clip.py --audio out/voice.wav --plan out/plan.json --style out/style.json --project out/clip
python3 scripts/render.py out/clip --out out/clip.mp4 --quality draft
python3 scripts/verify.py all --project out/clip --text "<台词>" --video out/clip.mp4
验证是必需的（详细信息请参见 explainer 技能的“验证”部分，流程相同）：build 必须干净，render 会生成一个联系表，你必须检查（嘴部活动、手势按计划进行、无内容截断），audio 使用 ASR 检查单词并验证时长限制。从失败的阶段修复并重新运行。每次 verify.py all 运行算作一次迭代；达到 verify.max_iterations 时，退出代码 2，并告知用户仍然失败的内容，而不是发布。render 保持 review 状态，直到你查看联系表并使用 verify.py mark render pass|fail --project out/clip --note "..." 记录，然后再次运行 verify.py all（重新构建会使标记失效）。
然后使用配置的后端渲染最终版本：python3 scripts/render.py out/clip --out out/clip.mp4（render.max_mb 会重新编码以适应上传限制）。切勿提交 mp4 或 wav 文件。