内容
# 视频生成应用程序
从故事板生成动画“面条式”解释视频，配备神经TTS语音配音、免版税背景音乐和ffmpeg编码。通过 **Web UI**、**CLI** 或作为 **MCP服务器** 为Claude Desktop和其他代理驱动。
## 功能
- **故事板驱动渲染** - JSON故事板通过Jinja2 + Playwright HTML渲染器变为动画场景。
- **神经语音配音** - piper-TTS（ONNX）首次使用时自动下载模型。
- **音乐和音效** - 将免版税曲目放入`assets/music/`和`assets/sfx/`。
- **三个接口** - Web UI、Typer CLI和FastMCP服务器（SSE传输）。
- **自包含** - 在项目的`bin/`文件夹中查找`ffmpeg.exe`，然后回退到系统PATH。
## 要求
- Python **3.12+**
- [`uv`](https://docs.astral.sh/uv/) （推荐）或`pip`
- `ffmpeg` - 放置在`bin/ffmpeg.exe`（Windows）或可在PATH上使用。参见 [bin/README.md](bin/README.md)。
- Playwright浏览器（安装后依赖项安装一次）
## 安装
```bash
git clone https://github.com/kamal-manick/video-generator.git
cd video-generator
# 从pyproject.toml解析依赖项，创建.venv/，生成uv.lock，
# 并在一步中安装运行时+开发额外功能
uv sync --extra dev
# 安装渲染器使用的无头浏览器
uv run playwright install chromium
```
将`ffmpeg.exe`放入 [bin/](bin/) （参见 [bin/README.md](bin/README.md))。
> 更喜欢纯粹的`pip`？ `python -m venv .venv && .venv\Scripts\activate && pip install -e ".[dev]"` 是等效的。
## 用法
### Web UI + MCP 服务器（默认）
```bash
uv run python -m vga serve
```
然后打开：
- Web UI → http://127.0.0.1:8765/
- MCP SSE 端点 → http://127.0.0.1:8765/mcp/sse
### CLI
```bash
uv run python -m vga --help
uv run python -m vga list-projects
```
### 仅MCP（Claude Desktop的标准输入输出）
```bash
uv run python -m vga serve --transport stdio --no-web
```
或将Claude Desktop连接到上面的SSE端点：
```json
{ "mcpServers": { "vga": { "url": "http://127.0.0.1:8765/mcp/sse" } } }
```
## 配置
所有设置都可以通过前缀为 `VGA_` 的环境变量或通过项目根目录中的 `.env` 文件覆盖。
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `VGA_PORT` | `8765` | HTTP/SSE端口 |
| `VGA_HOST` | `127.0.0.1` | 绑定地址 |
| `VGA_TRANSPORT` | `sse` | `sse` 或 `stdio` |
| `VGA_DEFAULT_FPS` | `30` | 渲染帧率 |
| `VGA_KEEP_TEMP` | `false` | 保留中间帧 |
## 项目布局
```
src/vga/
__main__.py Typer CLI + 服务器入口
config.py Pydantic设置
web/ FastAPI路由 + SPA在static/index.html
server/ FastMCP服务器 + 工具处理程序
pipeline/ 渲染编排
renderer/ HTML构建 + Playwright帧捕获 + ffmpeg编码器
audio/ piper-TTS包装器
music/ 背景音乐库
models/ Pydantic故事板/作业模型
storage/ 项目存储
templates/ Jinja2面条场景 + stepper.js
assets/ music/ 和 sfx/
models/tts/piper/ 自动下载的TTS权重（gitignored）
bin/ ffmpeg.exe（用户提供，gitignored）
output/ 渲染视频（gitignored）
projects/ 保存的故事板（gitignored）
```
## 开发
测试套件位于 [tests/](tests/) （`test_models.py`、`test_music_library.py`、`test_project_store.py`）。 [pyproject.toml](pyproject.toml) 已经设置了 `testpaths = ["tests"]` 和 `asyncio_mode = "auto"`，因此裸 `pytest` 发现并运行所有内容：
```bash
uv run pytest # 运行完整套件
uv run pytest -k music # 只运行匹配“music”的测试
uv run pytest -v # 详细输出
```
## 许可证
[MIT](LICENSE)
