RayMorTwinkle/anytomanim

AnyToManim — 用于生成带旁白的3b1b风格视频的CLI工具链

该产品是一个 CLI，而不是 API 封装。你（宿主代理）需要完成创意阶段——根据工具包中附带的规范文件编写摘要、节拍表、故事板和场景代码。CLI 只做确定性工作：TTS、时长测量、渲染、拼接。

安装与检查

pipx install anytomanim          # 或在虚拟环境中执行：pip install -e .
anytomanim doctor                # 报告缺失的依赖并给出修复提示

工作流程——导出规范，按规范操作

anytomanim export-guides ./guides   # 导出 WORKFLOW/DIGEST/SCRIPT/SCENE_GUIDE 及对应 schema

然后按照 guides/WORKFLOW.md 的指引操作：

1. 根据 DIGEST.md 编写 brief.md
2. 根据 SCRIPT.md（+ beats-schema.json）编写 beats.json。请先阅读 SCRIPT.md：旁白必须连贯成链，而非简单罗列。
3. 阅读 ORCHESTRATION.md，然后根据 STORYBOARD.md 编写 storyboard.json。打开你选择的卡片对应的可运行配方。运行 anytomanim storyboard storyboard.json --beats beats.json 并修复问题。
4. anytomanim tts --beats beats.json —— 合成每一个节拍的语音，并将 audio_file 和实际的 audio_seconds 写回文件（重新编辑后再次运行：仅重新合成变更的节拍）
5. 根据 SCENE_GUIDE.md 编写 scenes/*.py（使用 NarratedScene + MiMoService(beats_file=...)，with self.voiceover(beat="b01") as tr）。遵循故事板；从对应的 recipes/ 开始。
6. anytomanim render scenes/X.py --quality ql —— 出错时修复并重试
7. anytomanim preview <mp4> —— 阅读 sheet.png 和每个节拍的报告（检查重叠、超时、冻结节拍、内容过小、空条带、固定标题、故事板未提及的阶段变更等）；修复并重新渲染，直到无问题
8. 执行 --quality qh 渲染，anytomanim assemble a.mp4 b.mp4 -o final.mp4，anytomanim subtitles beats.json --mux final.mp4

无需 API 密钥、零成本迭代：设置环境变量 ANYTOMANIM_TTS=draft（使用本地语音）。

anytomanim run "<topic>" 命令也存在——一个嵌入式 LLM 参考驱动程序，用于自动化批量评估（需要 LLM API 密钥；交互式代理应使用规范驱动的流程）。

约定

• beats.json 是接口——公开的中间表示（旁白 + 视觉 + audio_seconds）。
• 音频优先同步：合成 → 测量 → 每个 run_time 从 tr.duration 派生，渲染时精确回放这些 wav 文件。永远不要人为指定时长。
• 渲染干净不等于完成——每次都要查看预览表。
• 连续性优先。在某个对象消失之前，先考虑它是否可以转变为下一个对象。淡出并重绘是最后的手段。
• 尽可能绘制关系，而不是将其写成标签。
• 语音：--voice baihua|moli|milo；通过 assets/voice/<name>.mp3 + voices.json 条目克隆自己的声音。支持中文和英文。
• 有关完整的端到端示例，请参见仓库中的 examples/ 目录。