Carla MCP Server

🚀 Carla MCP 服务器

Carla MCP 服务器是一个全面的模型上下文协议（MCP）服务器，可对 Carla 音频插件宿主进行完全控制。该服务器通过大语言模型，实现了对专业音频制作工作流程的自然语言控制。

🚀 快速开始

Carla MCP 服务器提供了跨 7 个功能类别共 45 种工具，可实现对音频制作的全面控制。它基于 Python 3.12+ 构建，为 AI 助手和专业音频软件之间提供了一个可用于生产环境的接口。

你可以向 AI 助手提出专业音频任务需求，例如：

• “加载我的混音项目，并设置一个带有压缩效果的鼓总线”
• “在主合成器上创建一个滤波扫频效果，并与节奏同步”
• “分析我的混音，并为改善频率平衡提出建议”
• “为 vocals 设置并行压缩，并针对不同的主歌/副歌设置不同参数”
• “为现场表演准备此会话，确保低延迟”

✨ 主要特性

• 🤖 原生支持 AI：专为通过大语言模型进行自然语言控制而设计。
• 🎛️ 全面控制：45 种工具涵盖音频制作的各个方面。
• ⚡ 实时处理：具备低延迟监控和分析能力。
• 🔧 专业可靠：可用于生产环境，具备全面的错误处理和类型安全机制。
• 📈 可扩展性：模块化架构支持复杂的工作流程。

📦 安装指南

前提条件

1. Carla 音频插件宿主

# Ubuntu/Debian
sudo apt install carla carla-dev

# 或者从源代码构建以获取最新功能
git clone https://github.com/falkTX/Carla.git
cd Carla
make
sudo make install

2. Python 环境

# 需要 Python 3.12+
python3 --version  # 版本应在 3.12 或更高

3. 音频系统

# JACK 音频连接套件（推荐）
sudo apt install jackd2 jack-tools

# 若要在 Linux 上支持 Windows VST
sudo apt install wine wine32 wine64

安装步骤

1. 克隆并安装

git clone https://github.com/your-org/carla-mcp-server.git
cd carla-mcp-server

# 安装依赖项
pip install -r requirements.txt

# 或者使用开发工具进行安装
pip install -e ".[dev]"

2. 配置环境

# 设置 Carla 路径（根据你的安装情况进行调整）
export CARLA_PATH=/usr/share/carla
export PYTHONPATH=$CARLA_PATH/source/frontend:$PYTHONPATH
export LD_LIBRARY_PATH=/usr/lib/carla:$LD_LIBRARY_PATH

3. 测试安装

# 运行测试套件
pytest tests/

# 测试 Carla 集成
python -c "import carla_backend; print('Carla 集成正常！')"

💻 使用示例

基础用法

# 启动 MCP 服务器
python server.py

# 或者开启调试模式
python server.py --debug --log-level INFO

MCP 客户端集成

将以下内容添加到你的 MCP 客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "carla-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/carla-mcp-server/server.py"],
      "env": {
        "CARLA_PATH": "/usr/share/carla",
        "PYTHONPATH": "/usr/share/carla/source/frontend"
      }
    }
  }
}

快速设置：复制提供的 .mcp.json.example 文件，并根据你的系统调整路径。

自然语言示例

连接到 LLM 后，你可以使用自然语言处理复杂的音频任务：

基本混音会话

用户：“加载我的摇滚歌曲项目，并添加一个均衡器，以消除人声低频杂音并提高人声清晰度。”

AI：没问题！我已加载你的项目，并为你的麦克风均衡器进行了优化，以实现专业的人声质量：

  🎯 已应用人声优化：

  ✅ 低频杂音消除：
  - 50Hz：-12dB（消除次低音低频杂音）
  - 100Hz：-8dB（减少低频噪音）
  - 156Hz：-6dB（清理浑浊的中低频）

  ✅ 清晰度增强：
  - 2500Hz：+4dB（增强人声存在感）
  - 3500Hz：+6dB（提高语音清晰度）
  - 5000Hz：+3dB（增强清晰度和辨识度）

  ✅ 咝音抑制：
  - 10000Hz：-4dB（抑制刺耳的 's' 和 't' 音）

  你的麦克风信号现在已通过优化后的均衡器进行路由，提供更干净、更专业的人声效果，减少了低频杂音，增强了清晰度，并控制了咝音。这些设置遵循标准的流行/摇滚人声处理技术。

创意音效设计

用户：“在合成器垫上创建一个逐渐增强紧张感的滤波扫频效果”

AI：我将创建一个动态的滤波自动化效果，以增强紧张感：
1. 找到你的合成器垫插件
2. 设置指数型滤波频率自动化
3. 添加共振自动化以增加特色
4. 将扫频效果与你的项目节奏同步

已创建一个 16 小节的滤波扫频效果，从微妙开始逐渐增强到强烈的峰值，非常适合在你的编曲中营造紧张感。

问题解决

用户：“我的混音听起来有些浑浊，并且有轻微的反馈”

AI：让我来分析并解决这些问题：
1. 运行频谱分析以确定浑浊的频率
2. 扫描你的路由以查找反馈回路
3. 应用校正均衡器以消除浑浊
4. 修复我找到的反馈路径

分析完成！发现 200 - 300Hz 附近有频率堆积（已应用校正均衡器），并修复了你的混响发送和输入之间的反馈回路。
现在你的混音应该听起来干净多了。

分析混音的歌曲结构

用户：“分析我歌曲时长内的 VU 表电平，并使用历史测量数据，确定每段主歌、副歌和独奏部分在时间码中的起始位置。”

AI：让我开始分析你的 VU 表插件，时长为 05:32 分钟（你的混音的确切长度，再加上两秒以适应播放时的轻微延迟）。

...

我已完成对你的 VU 表电平的分析！以下是根据我处理的历史测量数据得出的你歌曲的音乐结构分解：

1. 00:02 - 前奏
2. 00:28 - 第一段主歌
3. 01:20 - 第一段副歌
4. 01:50 - 第二段主歌
5. 2:45 - 第二段副歌
6. 3:32 - 独奏
7. 4:02 - 过渡段
8. 4:20 - 最后一段副歌
9. 5:12 - 尾奏

📚 详细文档

🎛️ 完整功能集

🗂️ 会话管理（8 种工具）

• 自动连接加载/保存项目
• 创建 A/B 快照以进行比较
• 跨渐变切换会话
• 导出/导入多种格式
• 会话清理和优化

🔌 插件控制（8 种工具）

• 加载 VST2/3、LV2、LADSPA、DSSI、AU、SF2/SFZ 插件
• 扫描目录以查找可用插件
• 克隆并替换带有参数映射的插件
• 使用插件链进行批量处理
• 实时控制插件状态

🔗 音频路由（7 种工具）

• 复杂的音频/MIDI 路由矩阵
• 创建和管理带有分组的总线
• 配置压缩的侧链
• 实时检查路由矩阵

🎚️ 参数自动化（8 种工具）

• 多种曲线类型的高级自动化
• 自定义范围的 MIDI CC 映射
• 多个参数的宏控制
• 直接获取/设置参数操作
• 实时参数控制和监控

📊 实时分析（5 种工具）

• 可自定义 FFT 的频谱分析
• 音频电平计量（峰值、RMS、LUFS）
• 延迟测量和优化
• 反馈回路检测和预防
• 随时间捕获参数

🔊 JACK 集成（6 种工具）

• JACK 端口管理和连接
• 系统音频路由
• 端口监控和状态
• 插件自动连接
• 连接稳定性验证

🖥️ 硬件控制（3 种工具）

• 音频接口配置
• 设备发现和管理
• 控制表面映射
• 支持显示器校准

🎓 MixAssist 集成

• 直接访问 MixAssist 研究数据集
• 专业音频工程对话数据库
• 来自专家的实际混音建议和技术
• 上下文相关的混音指导和故障排除资源

🧩 完整工具参考

会话管理

• load_session - 加载 Carla 项目文件
• save_session - 保存当前会话状态
• create_snapshot - 创建 A/B 比较快照
• switch_session - 热切换会话
• list_sessions - 显示可用会话
• delete_session - 删除会话
• export_session - 导出为音频格式
• import_session - 从外部格式导入

插件控制

• load_plugin - 加载任何插件格式
• scan_plugins - 发现可用插件
• control_plugin - 激活/旁路/独奏/移除
• batch_process - 对音频应用插件链
• list_plugins - 显示已加载的插件
• get_plugin_info - 获取详细的插件信息
• clone_plugin - 复制带有设置的插件
• replace_plugin - 用参数映射交换插件

音频路由

• connect_audio - 创建音频连接
• create_bus - 构建音频总线以进行分组
• setup_sidechain - 配置侧链路由
• get_routing_matrix - 查看完整的路由
• disconnect_audio - 移除连接
• create_send - 设置发送/返回效果
• set_connection_gain - 调整连接电平

参数自动化

• automate_parameter - 创建自动化曲线
• map_midi_cc - MIDI 控制器映射
• set_parameter - 直接设置插件参数值
• get_parameter - 获取插件参数值和信息
• create_macro - 多参数宏
• record_automation - 捕获参数变化
• randomize_parameters - 创意随机化
• morph_parameters - 平滑参数过渡

实时分析

• analyze_spectrum - FFT 频谱分析
• measure_levels - 峰值/RMS/LUFS 计量
• capture_plugin_parameters - 随时间监控参数
• detect_feedback - 反馈回路检测
• analyze_latency - 系统延迟测量

JACK 集成

• list_jack_ports - 显示可用的 JACK 端口
• connect_jack_ports - 连接 JACK 端口
• disconnect_jack_ports - 断开 JACK 端口连接
• get_jack_connections - 查看端口连接
• connect_system_to_plugin - 将系统音频路由到插件
• connect_plugin_to_system - 将插件路由到系统输出

硬件控制

• configure_audio_interface - 设置音频硬件
• list_audio_devices - 发现音频设备
• map_control_surface - 配置 MIDI 控制器

🔧 配置

服务器配置 (config/config.yaml)

server:
  host: localhost
  port: 8765
  log_level: INFO

carla:
  path: /usr/share/carla
  wine_prefix: ~/.wine
  auto_start_engine: true

audio:
  driver: JACK
  sample_rate: 48000
  buffer_size: 512
  auto_connect: true

plugins:
  scan_paths:
    - /usr/lib/lv2
    - /usr/lib/vst
    - ~/.wine/drive_c/Program Files/Common Files/VST3
  cache_enabled: true

monitoring:
  audio_enabled: true
  cpu_enabled: true
  update_interval_ms: 100

环境变量

# 必要路径
export CARLA_PATH=/usr/share/carla
export PYTHONPATH=$CARLA_PATH/source/frontend:$PYTHONPATH
export LD_LIBRARY_PATH=/usr/lib/carla:$LD_LIBRARY_PATH

# 可选配置
export CARLA_MCP_LOG_LEVEL=INFO
export CARLA_MCP_HOST=localhost
export CARLA_MCP_PORT=8765

🔧 技术细节

项目结构

carla-mcp-server/
├── server.py              # 主 MCP 服务器
├── carla_controller.py     # Carla 后端包装器
├── tool_registry.py       # 工具注册系统
├── carla_types.py         # 类型定义和模式
├── base_tools.py          # 基础工具框架
├── mixassist_resources.py # MixAssist 数据集集成
├── mixassist_schema.py    # MixAssist 数据模式
├── tools/                 # MCP 工具实现
│   ├── session_tools.py   # 会话管理
│   ├── plugin_tools.py    # 插件控制
│   ├── routing_tools.py   # 音频路由
│   ├── parameter_tools.py # 参数自动化
│   ├── analysis_tools.py  # 实时分析
│   ├── jack_tools.py      # JACK 集成
│   └── hardware_tools.py  # 硬件控制
├── monitors/              # 实时监控
│   ├── audio_monitor.py   # 音频电平监控
│   ├── cpu_monitor.py     # 性能监控
│   └── event_monitor.py   # 事件流
├── tests/                 # 全面的测试套件
├── .mcp.json.example      # 示例 MCP 配置
└── LICENSE                # GPL-2.0 或更高版本许可证

运行测试

# 运行所有测试
pytest

# 运行带覆盖率的测试
pytest --cov=carla_mcp_server --cov-report=html

# 运行特定测试类别
pytest tests/test_server.py::TestSessionManagement

# 运行集成测试（需要 Carla）
pytest tests/test_complete_suite.py

代码质量

# 格式化代码
black carla_mcp_server/

# 排序导入
isort carla_mcp_server/

# 类型检查
mypy carla_mcp_server/

# 代码检查
flake8 carla_mcp_server/

# 运行所有质量检查
pre-commit run --all-files

添加新工具

1. 在适当的 tools/ 模块中 创建工具方法：

async def my_new_tool(self, param1: str, param2: int = 10) -> dict:
    """工具文档描述。"""
    try:
        # 实现代码
        return {"success": True, "result": data}
    except Exception as e:
        return {"success": False, "error": str(e)}

2. 在 tool_registry.py 中 注册工具：

ToolDefinition(
    name="my_new_tool",
    description="MCP 客户端的描述",
    handler="tool_class_name",
    input_schema={/* JSON 模式 */}
)

3. 在 tests/ 中 添加测试：

async def test_my_new_tool():
    # 测试实现

🤝 贡献项目

我们欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

快速贡献步骤：

1. 分叉仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保所有测试通过
5. 提交拉取请求

📄 许可证

本项目采用 GPL-2.0 或更高版本许可证 - 详情请参阅 LICENSE 文件。

🙏 鸣谢

• 基于 falkTX 的 Carla 构建
• 使用了 Anthropic 的 Model Context Protocol
• 受音频制作社区的启发

📞 支持

• 问题反馈：GitHub Issues
• 讨论交流：GitHub Discussions
• 文档查阅：请查看 docs/ 目录
• 加入社区：加入 Carla Discord 社区

准备好借助 AI 辅助彻底改变你的音频制作工作流程了吗？立即开始吧！ 🎵✨