video-assembler-mcp

MCP 工具集：把你自己的素材 + Edge-TTS 旁白 + 烧入字幕，组装成短视频。 不依赖任何素材搜索服务，不依赖外部引擎进程，pip install 完就能跑。

它做什么 / 不做什么

设计定位很明确：创作智能在调用方（agent），本包只负责「把给定的东西变成帧」。 素材从哪来是 agent 的事（它有自己的搜索工具），本包不替它决定画面内容。

安装

pip install video-assembler-mcp
# 或直接用 uvx 免安装运行
uvx video-assembler-mcp

依赖只有两个：edge-tts（旁白合成）和 imageio-ffmpeg（随包带 ffmpeg 二进制）。

关于 ffmpeg

按以下顺序自动定位，一般无需任何配置：

1. 环境变量 VAM_FFMPEG / VAM_FFPROBE
2. 系统 PATH 里的 ffmpeg / ffprobe
3. imageio-ffmpeg 随包附带的二进制（兜底，保证装完即用）

实测 imageio-ffmpeg 附带的 gyan.dev essentials 构建带 --enable-libass + libfreetype，所以 ASS 字幕烧制可用。

MCP 客户端配置

{
  "mcpServers": {
    "video-assembler": {
      "command": "uvx",
      "args": ["video-assembler-mcp@latest"],
      "env": {
        "VAM_OUTPUT_DIR": "/tmp/vam_output"
      }
    }
  }
}

Windows 上把 VAM_OUTPUT_DIR 换成 D:\\vam_output 这类路径。

工具

分镜协议

最少只需要 title + scenes[{text, local_path|url}]：

{
  "title": "demo",
  "resolution": "1080x1920",
  "transition": "fade",
  "tts": { "voice": "zh-CN-YunxiNeural", "rate": "+10%" },
  "subtitle": { "font_size": 66, "margin_v": 290 },
  "scenes": [
    { "text": "第一段旁白，十五到四十五字口语最佳。", "subtitle": "开场",
      "local_path": "D:/clips/a.mp4", "trim": { "start": 0, "end": 8.5 } },
    { "text": "第二段旁白。", "subtitle": "第二幕",
      "url": "https://example.com/b.jpg", "kind": "image", "min_sec": 3 }
  ]
}

字段

规则

• scenes 顺序 = 成片顺序，第 i 个场景铺第 i 份素材，无隐式映射。
• 场景时长 = clamp(max(min_sec, 旁白时长 + 0.35s), 1.2s, 20s)。
• 素材失败即报错：local_path 缺文件、url 下载失败都会立刻返回错误并带场景序号。 不存在「降级成纯色」的静默行为 —— 你给的素材是精确指定的，换掉等于偷偷改需求。
• 素材比场景短会自动补足（视频复制末帧 / 图片缓慢推拉），比场景长按 trim 截断。
• 中文长句自动按像素折行。

环境变量

输出路径权限

写到哪里必须由调用方知情，所以做了两层：

1. 引擎侧：resolve_output_target() 把路径 resolve 后判断是否落在白名单内， 越界直接报错，不静默改写到别的目录。
2. MCP 客户端侧：你所用客户端（如 CowAgent / Claude Desktop）的工具级权限， 可以按 agent 或分组禁用 assemble_*。

字体

ASS 里写的是字体名，字形由系统提供。按 VAM_FONT_FALLBACKS 顺序探测：

Microsoft YaHei（Windows）→ Noto Sans CJK SC（Linux 容器）→ WenQuanYi Zen Hei → Source Han Sans SC → PingFang SC（macOS）→ DejaVu Sans

Linux 容器里通常没有中文字体，需要先装：

apt-get install -y fonts-noto-cjk   # Debian/Ubuntu

否则中文会渲染成方块（tofu）。assemble_health 的 subtitle_font 字段 会告诉你实际选中了哪个字体。

命令行

video-assembler-mcp            # 前台跑 MCP stdio 服务（主用法）
video-assembler-mcp --health   # 打印自检信息
video-assembler-mcp --demo     # 渲染一个内置演示片验证端到端

Python 库用法

MCP 不是唯一入口，也可以直接当库调：

from video_assembler import assemble, load_config

cfg = load_config()
manifest = assemble({
    "title": "hello",
    "scenes": [{"text": "你好世界。", "local_path": "D:/clips/a.mp4"}],
}, cfg)
print(manifest["video"])

许可

MIT