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 輔助徹底改變你的音頻製作工作流程了嗎？立即開始吧！ 🎵✨