mercadoa1234-arcDANTE/Motion-Voice-Studio
GitHub: mercadoa1234-arcDANTE/Motion-Voice-Studio
一个 AI 驱动的动画视频生成工具，集成语音合成与多语言支持，专注于本地 CPU 部署。
Stars: 0 | Forks: 0
# 动画语音工作室
将此技能上传至AI聊天以获得最佳效果，或者将仓库链接粘贴到聊天中。
**将一个问题、想法或数学论文通过AI生成的配音，转化为计算机动画图形！**
**提供提示、问题或论文；AI会将其制作为JSON故事板版本并转换为带旁白的动画视频。完全在CPU上运行——无需GPU、云端或API密钥。**
音频首先通过 [Kokoro TTS](https://github.com/thewh1teagle/kokoro-onnx) (ONNX, fp16, 内置) 合成。帧的计时与测量的音频时长相匹配。输出是一个带软字幕的MP4文件。
设计为可供人类和AI智能体使用。如果你是智能体，请先阅读 [`AGENT-GUIDE.md`](./AGENT-GUIDE.md) ——它会告诉你该加载什么以及跳过什么。
## 它能产出什么
一个完整渲染的讲解视频：Manim动画 + Kokoro旁白 + 软字幕字幕，混合为MP4文件。输入一个故事板JSON，输出一个 `final.mp4`。
通过Kokoro的多语言语音集支持80多种语言。包含可选的CAD/3D动画、WebGPU 3D重建以及从源文档到视频的流程——但对于基础课程而言，这些都不是必需的。
## 系统要求
**系统依赖** (由 `setup.sh` 安装)
- ffmpeg
- espeak-ng
- libpangocairo
- dvisvgm
- texlive-latex-extra *(可选 — 仅在需要 `MathTex` 场景时使用；设置 `INSTALL_LATEX=0` 可跳过)*
**Python 3.10+**
- manim 0.20.1
- onnxruntime ≥ 1.20
- phonemizer-fork ≥ 3.3
- soundfile, numpy < 2.0, scipy, Pillow, opencv-python-headless
[完整依赖列表](./requirements.txt)
## 安装
```
git clone https://github.com/mercadoa1234-arcDANTE/Motion-Voice-Studio.git
cd Motion-Voice-Studio
bash setup.sh
```
`setup.sh` 按顺序执行五件事：
1. 安装系统包（apt / brew / dnf — 自动检测）
2. 从 `requirements.txt` 安装Python依赖
3. 从内置的拆分部分组装Kokoro fp16 ONNX模型 → `model/kokoro-v1_0_fp16.onnx`
4. 将语音放入 `voices/` 目录
5. 运行冒烟测试
幂等操作——安全运行两次。已组装的模型和已放置的语音将被跳过。
**验证安装：**
```
python3 scripts/mvs_doctor.py
# 预期: 19 pass · 0 warn · 0 fail
```
任何FAIL打印单行修复说明。修复后，重新运行。
## 快速开始
**1. 运行冒烟测试故事板** (验证整个流程端到端)：
```
python3 scripts/voiceover.py examples/smoke.storyboard.json --out-dir /tmp/mvs-smoke
```
输出：`/tmp/mvs-smoke/final.mp4` + `/tmp/mvs-smoke/final.srt`
**2. 编写你自己的故事板：**
```
{
"title": "Your Lesson",
"output": { "basename": "lesson", "dir": "/tmp/lesson-out" },
"video": { "width": 1280, "height": 720, "fps": 30 },
"default_voice": "af_bella",
"default_speed": 1.0,
"shots": [
{
"id": "intro",
"narration": "Welcome. Today we cover the basics.",
"action": { "kind": "title", "primary": "The Basics" }
},
{
"id": "formula",
"narration": "Here is Euler's identity.",
"action": { "kind": "formula", "tex": "e^{i\\pi} + 1 = 0" }
}
]
}
```
保存后，运行：
```
python3 scripts/voiceover.py my_lesson.json --out-dir /tmp/my-lesson
```
## 场景类型
| `action.kind` | 渲染内容 | 必填字段 |
|---|---|---|
| `title` | 全屏标题卡 | `primary` |
| `formula` | LaTeX方程展示 | `tex` |
| `bullets` | 带标题的项目符号列表 | `items` (数组) |
| `highlight` | 带箭头的标注框 | `text` |
| `lower_third` | 底部横幅 | `title`, `subtitle` |
| `custom` | 原始Manim场景 (Python字符串) | `code`, `scene_name` |
## 语音
内置12种语音，无需网络连接。
| 语音名称 | 备注 |
|---|---|
| `af_bella` | NaN安全默认值。如果不确定，请使用此选项。 |
| `af_heart` | 温暖，语速稍慢 |
| `af_nicole` | 清晰，中性 |
| `am_fenrir` | 低沉男声 |
| `am_michael` | 仅在语速 ≥ 1.0 时使用 — 低于此阈值可能出现NaN |
| `am_puck` | 活力男声 |
| `bf_emma` | 英式女声 |
| `bm_daniel` | 英式男声 |
| `bm_george` | 英式男声，正式 |
| `jf_alpha` | 日语女声 |
| `pf_dora` | 葡萄牙语女声 |
| `zf_xiaoyi` | 普通话女声 |
语速范围：0.85–1.15。`voiceover.py` 中内置了NaN防护——在1.0语速下会自动回退到 `af_bella`。
## 流程工作原理
音频是计时的真实来源。切勿从字数猜测时长。
```
1. generate_narration() → synthesize per-shot WAV files, measure real durations
2. plan_timeline() → build timeline from measured durations (not estimates)
3. write_srt() → captions derived from the same durations
4. mix_audio_timeline() → combine per-shot audio onto one master bus
5. render_action() → render Manim frames timed to match each shot's duration
6. mux_final() → frames + audio + soft-sub SRT → final.mp4
```
字幕始终为软字幕（可切换）。不支持像素烧录的字幕。
内容哈希缓存意味着重新渲染未更改的镜头是免费的。更改一行旁白，只需重建该镜头。
## 仓库结构
```
Motion-Voice-Studio/
├── AGENT-GUIDE.md ← agents: start here
├── setup.sh / setup.ps1 ← one-shot installer (Linux/Mac/Windows)
├── requirements.txt
├── Dockerfile
│
├── scripts/
│ ├── voiceover.py ← main pipeline entrypoint
│ ├── render_manim.py ← Manim scene renderer
│ ├── manim_scenes.py ← scene kind builders
│ ├── mvs_doctor.py ← health check
│ └── ... ← CAD, recon, source-doc passes
│
├── engines/
│ └── text_display.py ← TextDisplayEngine (kerning, overlap detection)
│
├── examples/
│ └── smoke.storyboard.json ← minimal working storyboard
│
├── Kokoro_TTS_Agent_Skill_Pack/ ← model assembly (combine.py + manifest)
├── Kokoro_Model_Split_Files/ ← split ONNX parts (assembled by setup.sh)
├── kokoro-voices/ ← .pt voice files
├── brain/ ← cognitive orchestration skill (opt-in)
├── handoffs/ ← SAM3D / 3D recon templates
└── MVS-README-DOCS-FOR-AGENTS-START-HERE/
├── PIPELINE.md
├── AUDIO.md
├── RENDER.md
├── TEXT_DISPLAY.md
├── CAD.md
├── BROWSER.md
└── Core Production Contract - Readme Second.md
```
## 常见问题
| 症状 | 修复方法 |
|---|---|
| `FileNotFoundError: kokoro-v1_0_fp16.onnx` | `bash setup.sh` — 从拆分部分组装模型 |
| `ModuleNotFoundError: manim` | `pip install -r requirements.txt` |
| `pangocairo >= 1.30.0 is required` | `bash setup.sh` — 重新运行apt安装 |
| NaN音频 / 静音 | 将语音切换为 `af_bella`，语速设为 1.0 |
| `MathTex` 渲染空白 | `apt install texlive-latex-extra` 或使用 `Text()` 替代 |
| `KeyError: 'shots'` | 故事板使用了 `"scenes"` — 补丁后两者均支持 |
| 音频/视频长度不匹配 | 你是在合成前渲染的 — 始终先处理音频 |
其他问题：首先运行 `python3 scripts/mvs_doctor.py`。
## Docker
```
docker build -t mvs .
docker run --rm -v "$PWD/output:/out" mvs \
python3 scripts/voiceover.py examples/smoke.storyboard.json --out-dir /out
```
标签：3D动画, AI代理兼容, AI动画生成, CAD动画, CNCF毕业项目, CPU推理, Manim动画, MP4输出, ONNX模型, TTS文本转语音, WebGPU渲染, 多语言支持, 安全测试框架, 故事板生成, 教育技术, 数学动画, 无GPU应用, 自动部署, 视频制作工具, 解释性视频, 语音合成, 软字幕, 逆向工具