midi ctrl

MIDICtrl

用AI控制Arturia MicroFreak合成器

MIDICtrl是基于HTTP的 模型上下文协议（MCP） 将MCP兼容LLM与Arturia MicroFreak合成器桥接的服务器。通过自然语言对话调整参数、切换振荡器类型或探索声音。适用于支持MCP协议的任何LLM客户端。

You: "Make the filter brighter and increase resonance"
AI: *adjusts Filter Cutoff (CC 23) and Resonance (CC 83) on your MicroFreak*

YouTube上的演示


这是什么？

MIDI（乐器数字接口）

MIDI是一种让电子乐器、计算机和音频设备通信的协议。MIDI不发送音频，而是发送“播放音符C4”或“将过滤器截止设置为80”等消息

关键MIDI概念：

• MIDI接口：用于发送/接收MIDI消息的连接点（如USB或硬件连接）
• MIDI通道：16个单独的通道（0-15），用于将消息路由到不同的仪器
• CC（控制权变更）：调整音量、滤镜或效果等参数的消息（0-127范围）
• 端口方向:

- *输入端口* 接收MIDI（例如，从键盘到计算机） - *输出端口* 发送MIDI（例如，从您的计算机发送到合成器）

MCP（模型上下文协议）

MCP是Anthropic的开放协议，允许AI助手与外部工具和数据源安全交互。MIDICtrl将MIDI功能作为MCP工具公开，任何兼容的LLM都可以在对话中调用。

工作原理：

You chat with an MCP-compatible AI client (e.g., Claude Desktop)
         ↓
The AI uses MIDICtrl tools (list ports, send CC messages, etc.)
         ↓
MIDICtrl translates requests to MIDI
         ↓
Your Arturia MicroFreak responds

特性

• MIDI端口发现：列出所有连接的MIDI设备
• MicroFreak控制变化：调整MicroFreak上的任何CC参数
• 批量操作：在一个命令中发送多个参数更改
• 命名振荡器类型：使用友好名称在22种振荡器类型之间切换
• LLM友好：自然语言界面——基本使用不需要MIDI知识
• 文档即资源：AI可以访问完整的MicroFreak MIDI参考

快速开始

先决条件

对于macOS用户（预构建版本）：

• macOS计算机
• Arturia MicroFreak通过USB连接
• MCP兼容的AI客户端（例如，Claude Desktop）

对于Linux/Windows/Mac用户或开发人员：

• Elixir 1.19+和Erlang/OTP
• Arturia MicroFreak通过USB连接
• MCP兼容的AI客户端（例如，Claude Desktop）

安装

选项1：预构建版本（仅限macOS Apple Silicon）

# Download the macOS release
wget https://github.com/nanassound/midi_ctrl/releases/download/v0.1.0/midi_ctrl-macos-arm.tar.gz

# Extract
tar -xzf midi_ctrl-macos-arm.tar.gz
cd midi_ctrl

# Start the server (no Elixir/Erlang required!)
./bin/midi_ctrl start

# Server runs on http://localhost:3000

选项2：来源（Linux/Windows/Mac）

# Clone the repository
git clone https://github.com/nanassound/midi_ctrl.git
cd midi_ctrl

# Install dependencies
mix deps.get

# Run the server
elixir run_mcp.exs

# Server starts on http://localhost:3000

构建自己的版本（可选）：

如果你想为你的平台创建一个独立版本：

# Build release
MIX_ENV=prod mix release

# The release will be in _build/prod/rel/midi_ctrl/
# Start it with:
_build/prod/rel/midi_ctrl/bin/midi_ctrl start

注： 发布是特定于平台的。基于macOS的版本在Linux/Windows上无法运行。

配置您的MCP客户端

将MIDICtrl添加到MCP客户端配置中。以下是Claude Desktop的示例：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "midi_ctrl": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

重新启动MCP客户端 保存配置后。

验证连接

1. 启动MIDICtrl服务器（请参阅上面的安装）
2. 打开您的MCP客户端（例如，Claude Desktop）
3. 在LLM UI中查找工具名称
4. 试试：“你看到了什么MIDI端口？”

AI应该使用以下命令列出您连接的MIDI设备 list_ports 工具。

使用示例

基本：列出您的MIDI设备

You: "What MIDI devices are connected?"

AI: *uses list_ports tool*

I can see you have these MIDI devices:
- Arturia MicroFreak (output, port 2)
- USB MIDI Interface (input, port 0)

控制更改消息

You: "Set the filter cutoff to 100 and resonance to 80 on my MicroFreak"

AI: *uses microfreak_cc tool with CC 23 (cutoff) and CC 83 (resonance)*

I've adjusted your MicroFreak:
- Filter Cutoff: 100
- Filter Resonance: 80

切换振荡器类型

You: "Switch my MicroFreak to the Wavetable oscillator"

AI: *uses microfreak_set_oscillator tool*

Done! Your MicroFreak is now using the Wavetable oscillator.

创意音效设计

You: "Create a warm pad sound on my MicroFreak"

AI: I'll set up a warm pad for you:
- Oscillator: SuperWave (for richness)
- Filter Cutoff: 60 (darker tone)
- Resonance: 30 (subtle emphasis)
- Attack: 40 (slow fade-in)
- Release: 70 (long tail)

*sends multiple CC changes*

Try playing now—you should have a lush, warm pad sound!

可用工具

1. list_ports

发现所有连接的MIDI设备。

论据： 无

退货： MIDI端口列表，包括：

• name：设备名称（例如“Arturia MicroFreak”）
• direction: input 或 output
• num：端口号标识符

例子：

name: Arturia MicroFreak
direction: output
num: 2

2. microfreak_cc

发送MIDI控制更改消息以调整Arturia MicroFreak参数。

论据：

• port_pattern （字符串，必填）：与MIDI端口名称匹配的模式（例如“MicroFreak”）
• cc_changes （数组，必填）：CC更改列表 [{cc: number, value: number}]
• channel （整数，可选）：MIDI通道0-15（默认值：0）
• delay_ms （整数，可选）：消息之间的延迟（毫秒）（默认值：0）

常见的MicroFreak CC编号：

• CC 23：滤镜截止（0-127，亮度）
• CC 83：滤波器谐振（0-127，强调）
• CC 12：音色（0-127，音调特征）
• CC 13：形状（0-127，波形形状）
• CC 105：信封攻击（0-127，淡入时间）
• CC 106：信封衰减（0-127，淡出时间）
• CC 29：包络维持（0-127，保持水平）
• CC 9：振荡器类型（0-127，见振荡器类型）

完整CC参考： 看 docs/microbreak_midi_reference.md

例子：

{
  "port_pattern": "MicroFreak",
  "cc_changes": [
    {"cc": 23, "value": 100},
    {"cc": 83, "value": 60}
  ],
  "channel": 0
}

3. microfreak_set_oscillator

使用友好的名称在Arturia MicroFreak上的22种振荡器类型之间切换。

论据：

• port_pattern （字符串，必填）：与MIDI端口名称匹配的模式
• oscillator_type （字符串，必填）：振荡器名称（见下文）
• channel （整数，可选）：MIDI通道0-15（默认值：0）

可用振荡器类型（共22种）：

例子：

{
  "port_pattern": "MicroFreak",
  "oscillator_type": "Wavetable",
  "channel": 0
}

示例提示

以下是一些通过人工智能助手与MicroFreak互动的创造性方法：

探索：

• “你能在我的MicroFreak上控制什么？”
• “显示我连接了哪些MIDI设备”
• “有哪些振荡器类型可供选择？”

声音设计：

• “营造明亮、咄咄逼人的领先声音”
• “做一个低沉、隆隆的低音补丁”
• “给我一个太空环境垫”
• “随机化5个参数，给我一个惊喜”

学习：

• “解释滤波器谐振的作用，然后通过从0到127的扫描来演示它”
• “给我看看Wavetable和V.模拟振荡器之间的区别”
• “通过调整不同的参数教我MIDI CC”

精确控制：

• “将滤波器截止设置为80，共振设置为40，攻击设置为50”
• “切换到模态振荡器并将音色设置为100”
• “将值为64的CC 12发送到我的合成器”

高级主题

面向开发人员和贡献者

看 CLAUDE.md 用于：

• 架构和代码结构
• 添加新的MCP工具
• 开发工作流程
• 测试和格式化
• 构建发布以供分发
• CI/CD设置

MicroFreak MIDI参考

看 docs/microbreak_midi_reference.md 用于：

• 完整的CC参数列表（30+个参数）
• 振荡器特定参数
• 声音设计示例
• MIDI实现图

添加对其他合成器的支持

目前，MIDICtrl仅支持Arturia MicroFreak。要添加对其他合成器的支持：

1. 在合成器手册中查找MIDI实现（CC编号和范围）
2. 在中创建新的MCP工具 lib/midi_ctrl/router.ex
3. 在中添加操作逻辑 lib/midi_ops.ex
4. 文档中的CC映射 docs/your_synth_midi_reference.md

工具名称示例： moog_cc, roland_cc, korg_patch_select

欢迎为其他合成器添加支持的贡献！

故障排除

“未找到MIDI端口”

• 确保您的MIDI设备已通电并连接
• 检查系统的MIDI设置/驱动程序
• 在macOS上：检查音频MIDI设置应用程序
• 在Linux上：验证ALSA/JACK配置
• 尝试拔下并重新连接设备

“端口模式与任何端口都不匹配”

• 跑 list_ports 首先查看确切的设备名称
• 使用部分匹配（例如，“Micro”而不是“Arturia MicroFreak”）
• 检查端口模式中的拼写错误

“我的MCP客户端看不到MCP工具”

• 验证MIDICtrl服务器是否正在运行（检查http://localhost:3000)
• 确认您的MCP客户端配置已正确保存
• 配置更改后重新启动MCP客户端
• 检查 npx 可利用性： which npx 终端中

“服务器无法启动”

• 检查端口3000是否已在使用中： lsof -i :3000
• 尝试其他端口： PORT=8080 elixir run_mcp.exs
• 更新配置以匹配： "http://localhost:8080/mcp"

贡献

欢迎投稿！请看 CLAUDE.md 用于开发设置和指南。

贡献领域：

• 支持其他合成器（Moog、Korg、Roland、Novation等）
• MicroFreak的更多MIDI功能（程序更改、sysex等）
• 更好的错误处理和用户反馈
• Linux和Windows的预构建版本
• 文档改进

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

版权所有（c）2025 Nanas Sound

致谢

• MIDI功能通过 Midiex
• 实现 模型上下文协议（MCP） 通过Anthropic
• 受到人工智能辅助音乐制作的创造性可能性的启发

链接

• 文档： CLAUDE.md （开发者）， docs/ （MIDI参考）
• MCP规范： https://modelcontextprotocol.io
• 克劳德桌面： https://claude.ai/download
• 问题和反馈：

______________________________________________________________________

使用Claude Code在人工智能的帮助下制作 🎹🤖