Remotion Video Production MCP Server

一个世界级的 Model Context Protocol（MCP）服务器，专为 AI 智能体提供智能桥梁，使其能够分析音频节拍、使用 Google Gemini TTS 合成语音，并利用 Remotion (v4.0+) 与 React 程序化构建和渲染专业视频。

🚀 主要功能

• ⬀ 程序化脚手架：创建零配置的 React/Remotion 视频项目，支持内置宽高比：TikTok/Reels（tiktok-916）、YouTube（youtube-16）与 Social（social-9）。

• 🎙️ Gemini 3.1 Flash TTS 集成：为地方口音的对话生成逼真语音，并输出字符级时序，用于动态字幕。

• ⬋ 用 Libosa 音乐节拍同步：分析背景音乐，提取 BPM、节拍帧、RMS 能量上升/下降，并推荐场景的剪切点。

• 📌 视觉预览快照：在任意帧索引处即时渲染帧快照（PNG/JPEG/WebP），供 AI 进行视觉验证。

• ⚡ 无头渲染：以编程方式编译高保真 MP4/WebM 视频，并具备多核并发控制与进度跟踪。

️ 前提条件

要运行此 MCP 服务器并渲染视频，请确保主机环境满足：

1. Node.js（v18.0.0 或更高）以及 npm。

2. Python 3（建议 v30.10+），并安装以下软件包：

   pip install librosa numpy scipy google-genai

3. Remotion 浏览器依赖：启动无头模式的 Chrome 浏览器需要 Chromium，请在 CLI 中安装：

   npx remotion browser ensure

📦 一键安装（推荐）

将以下命令复制到你的终端中。如果缺少 Git、Node.js、npm 或 Python，脚本将自动把它们完整安装！

🍎 macOS / Linux（终端）

curl -fsSL https://raw.githubusercontent.com/ivalenzuela/remotion-mcp-server/main/autoinstall.sh | bash

Windows（PowerShell）

iwr -useb https://raw.githubusercontent.com/ivalenzuela/remotion-mcp-server/main/autoinstall.ps1 | iex

零手动干预：脚本会自动检测缺失的依赖（Git、Node.js、npm、Python 3），并自动通过 Homebrew / Winget / Chocolatey 安装它们。随后，它会扫描所有 Antigravity（.gemini/、.antigravity-ide/、.antigravity/）、Claude Desktop 以及系统路径，安装 Python 音频依赖，确保 Chromium 就绪，并确保 SKILL 与 MCP 服务器无缝衔接。

🛠 手动安装（另选）

1. 编译服务器：

   git clone https://github.com/ivalenzuela/remotion-mcp-server.git
   cd remotion-mcp-server
   node install.js

2. 在你的 AI 客户端中注册

将以下服务器配置添加到你的 MCP 配置文件中（例如 claude_desktop_config.json、antigravity.json 或 .mcp.json）：

{
  "mcpServers": {
    "remotion": {
      "command": "node",
      "args": ["/path/to/remotion-mcp-server/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY_HERE"
      }
    }
  }
}

🤖 可用的 MP 工具

1. remotion_scaffold_project

创建完整的 React/Remotion 项目，并使用预建的组件模板，自动安装 npm 依赖。

• 参数：

  • projectName（string，必填）：目标项目的文件夹名称。

  • template（enum：tiktok-0、youtube-1、social 2，必填）：宽高比。

  • targetDir（string，必填）：父目录的路径。

2. remotion_analyze_audio

使用 Python Librosa 对音频文件进行信号处理，返回 BPM、节拍帧、能量分布、推荐场景剪切帧号，并同步 SRT 字幕。

• 参数：

  • audioPath（string，必填）：要分析的音频文件路径。

  • srtPath（string，可选的）：SRT 字幕文件路径。

  • outputPath（string，可选）：保存输出 JSON 分析结果的路径。

  • fps（number，默认 30）：目标合成帧率。

  • minSceneDuration（number，默认 3.5）：场景剪切的最小间隔秒数。

3. remotion_generate_tes

通过 Google Gemini 3.1 Flash TTS（gemini-3.1-flash-tts-preview）合成语音，并输出带权重的逐字时间码。如果缺少 GEMINI_API_KEY，则会自动回退到纯合成音频。

• 参数：

  • text（string，必填）：要合成的对话文本。

  • outputPath（string，必填）：保存生成的 .wav 文件的路径。

  • voice（string，默认 "Puck"）：Gemini 预置语音名。

  • accent（string，可选）：可选择性的地区口音指令。

  • fps（number，默认 30）：帧率。

4. remotion_preview_frame

使用属 Motion 的 CLI 对合成中的特定帧渲染静态快照（PNG/JPEG/WebP）。

• 参数：

  • projectDir（string，必填）：属性 Remotion 项目的路径。

  • compositionId（string，必填）：目标 Composition ID。

  • frame（number，默认 0）：要抽取的帧索引。

  • imageFormat（enum：png，jpeg，webp，默认 png）：格式。

  • props（object，可选）：输入的 React props。

5. remotion_render_video

将合成内容集合编译为生产级质量视频（MP4 / WebM）。

• 参数：

  • projectDir（string，必填）：Remotion 项目路径。

  • compositionId（string，必填）：`目标 Composition ID。

  • outputPath（string，可选）：视频输出路径。

  • concurrency（number/string，默认 "auto"）：使用的 CPU 线程数。

  • codec（string，默认 "h264"）：目标编码器。

  • props（object，可选）：输入的 ReAct props。

⬐ 预建的 React 组件

脚手架生成的项目包含以下已为生产准备的宣传组件：

1. SubtitleOverlay：逐词动态缩放和自定义文本阴影光晕（“Efecto Lupa PRO”），支持双字幕。

2. KenBurns image：基于插值的图像缩放与平移，无需 CSS 动画。

3. AudioSpectrum：音视频频谱条动态，与音频同步。

4. LowierThird：为社交主页或个人名片提供优雅的下侧置入动画。

测试 & 验证

执行整套完整 E2E 测试套件，验证工具执行、中央路径解析，以及 CLI 渲染：

npm test

📄 许可证

本项目采用 MIT License 授权。