fl-studio-mcp

# FL Studio MCP 集成 v2.0 **(仅限 macOS - 当前版本)** 本指南帮助您设置 FL Studio MCP（模型上下文协议）集成 v2.0，允许通过 MIDI 对 FL Studio 进行 AI 控制。 ## 更改概述 1. **双协议架构**： - **基于 CC 的协议**，用于简单命令（播放、停止等） - **基于 SysEx 的协议**，用于复杂的数据密集型操作（和弦进行、旋律等） 2. **高级音乐制作功能**： - 和弦进行生成 - 基于音阶的旋律创作 - 参数自动化 - 排列控制 - 增强的状态反馈 3. **基础设施改进**： - 更强大的错误处理 - 更好的 MIDI 通信 - 结构化的反馈机制 - 音乐理论实现（音阶、和弦、进行） ## 当前状态（截至 YYYY-MM-DD - 请更新日期） **正在工作的功能：** 根据初步测试，已确认以下核心功能正在工作： * **基本命令：** * `play_note`：播放单个 MIDI 音符。 * `control_transport`：控制播放（播放/停止）。 * `select_pattern`：选择模式。 * `add_audio_effect`：向混音器轨道添加效果。 * **高级命令：** * `create_notes`：创建/清除音符（实现不明确） **非功能性 / 开发中：** 以下功能当前不可靠或正在开发/调试： * **基本命令：** `create_track`、`load_instrument`、`set_tempo`、`set_mixer_level`、`select_channel`、`add_midi_effect`。 * **高级命令：** `create_chord_progression`、`create_melody`、`automate_parameter`、`set_arrangement`、`get_status`。 *注意：状态反映了当前状态，可能会随着进一步的开发和调试而改变。`create_chord_progression` 由于缺少控制器实现而特别不可用。* ## 设置说明 ### 步骤 1：在 macOS 中设置 IAC 驱动程序 1. 打开 **Audio MIDI Setup**（您可以在 Applications/Utilities 中找到它或使用 Spotlight 搜索） 2. 点击 **Window > Show MIDI Studio**，如果 MIDI 工作室尚未可见 3. 双击 **IAC Driver** 图标 4. 选中 **Device is online** 5. 如果不存在，请创建一个名为 **IAC Driver MCP Bridge** 的端口 6. 点击 **Apply** 并关闭窗口 ### 步骤 2：安装 MCP 服务器 1. 克隆存储库 2. 安装所需的 Python 包： ```bash pip install -r requirements.txt ``` 或 ```bash uv install ``` 3. 确保 `flstudio_mcp_iac/server.py` 位于项目结构中的正确位置 ### 步骤 3：安装 FL Studio 控制器脚本 1. 导航到 macOS 上的 FL Studio MIDI 脚本文件夹： `/Applications/FL Studio.app/Contents/Resources/FL/System/Hardware/` 2. 创建一个名为 `FL Studio MCP Controller` 的新文件夹。 3. 将 `device_flstudiocontroller.py` 复制到此新文件夹中。 ### 步骤 4：配置 FL Studio 1. 打开 FL Studio 2. 进入 **Options > MIDI Settings** 3. 在输入设备列表中找到 **IAC Driver MCP Bridge** 4. 启用它并选择 **FL Studio MCP Controller v2.0** 作为控制器类型 5. 确保端口已启用（高亮） 6. 如果控制器没有立即出现，请点击 **Refresh** ### 步骤 5：运行 MCP 服务器 1. 使用提供的脚本运行服务器： ```bash ./run_flstudio_mcp.sh ``` 或直接使用： ```bash python -m flstudio_mcp_iac.server ``` 2. 您应该会看到日志消息，指示服务器已启动并连接到 IAC 驱动程序端口 ## 新功能 ### 和弦进行 直接在 FL Studio 中创建和弦进行，如 C-G-Am-F： ```python # 创建一个 C 大调和弦进行 create_chord_progression( progression=["C", "G", "Am", "F"], duration_beats=4, channel=0, velocity=100 ) # 创建一个带有 7th 和弦的爵士进行 create_chord_progression( progression=["Cmaj7", "Dm7", "G7", "Cmaj7"], duration_beats=2 ) ``` ### 旋律生成 **（注意：`create_melody` 目前不可用）** ```python # 示例：创建 C 大调旋律（目前不可用） # create_melody( # scale="C major", # length=8, # channel=1, # velocity=90 # ) # 示例：创建五声音阶旋律（目前不可用） # create_melody( # scale="A pentatonicminor", # length=16, # channel=2, # seed=42 # 使用种子生成可重复的旋律 # ) ``` ### 参数自动化 **（注意：`automate_parameter` 目前不可用）** ```python # 示例：自动化滤波器截止频率（目前不可用） # automate_parameter( # track_index=1, # plugin_index=0, # parameter_index=12, # 截止参数 # points=[(0, 0.2), (4, 0.8), (8, 0.4), (16, 0.2)] # （时间，值）对 # ) ``` ### 排列控制 **（注意：`set_arrangement` 目前不可用）** ```python # 示例：设置具有循环点的模式序列（目前不可用） # set_arrangement( # pattern_sequence=[0, 1, 2, 3], # loop_start=0, # loop_end=4 # ) ``` ### 增强的状态反馈 **（注意：`get_status` 目前不可用）** ```python # 示例：获取当前状态（ tempo ，播放状态等）（目前不可用） # status = get_status() # print(f"当前 tempo ：{status['data']['tempo']} BPM") # print(f"播放中：{status['data']['playing']}") ``` ## API 参考 ### 基本命令（基于 CC） | 命令 | 描述 | 状态 | |---------|-------------|--------| | `create_notes(clear=False)` | 创建/清除音符（实现不明确） | × 未工作 | | `play_note(note, velocity, duration)` | 播放单个 MIDI 音符 | √ 工作中 | | `create_track(name, track_type)` | 创建新轨道 | × 未工作 | | `load_instrument(instrument_name, channel)` | 加载乐器 | × 未工作 | | `set_tempo(bpm)` | 设置项目 tempo | × 未工作 | | `control_transport(action)` | 控制播放（播放/停止/录制） | √ 工作中 | | `select_pattern(pattern)` | 按编号选择模式 | √ 工作中 | | `set_mixer_level(track, level)` | 设置混音器轨道音量 | × 未工作 | | `select_channel(channel)` | 在通道架中选择通道 | × 未工作 | | `add_audio_effect(track, effect_type)` | 向混音器轨道添加音频效果 | √ 工作中 | | `add_midi_effect(track, effect_type)` | 添加 MIDI 效果（实现不明确） | × 未工作 | ### 高级命令（基于 SysEx） | 命令 | 描述 | 状态 | |---------|-------------|--------| | `create_chord_progression(progression, duration_beats, channel, velocity)` | 创建和弦进行 | × 未工作 | | `create_melody(scale, length, channel, velocity, seed)` | 基于音阶生成旋律 | × 未工作 | | `automate_parameter(track_index, plugin_index, parameter_index, points)` | 自动化插件参数 | × 未工作 | | `set_arrangement(pattern_sequence, loop_start, loop_end)` | 设置模式序列和循环点 | × 未工作 | | `get_status()` | 获取详细项目状态 | × 未工作 | ## 支持的和弦 系统支持以下和弦类型： - 大调：`"C"`、`"G"`等 - 小调：`"Cm"`、`"Am"`等 - 属七和弦：`"C7"`、`"G7"`等 - 大七和弦：`"Cmaj7"`、`"Gmaj7"`等 - 小七和弦：`"Cm7"`、`"Am7"`等 - 减和弦：`"Cdim"`、`"Bdim"`等 - 增和弦：`"Caug"`、`"Faug"`等 - 挂四和弦：`"Csus4"`、`"Gsus4"`等 - 挂二和弦：`"Csus2"`、`"Dsus2"`等 ## 支持的音阶 系统支持以下音阶类型： - 大调：`"C major"`、`"G major"`等 - 小调：`"A minor"`、`"E minor"`等 - 和声小调：`"A harmonicminor"`等 - 旋律小调：`"D melodicminor"`等 - 多利亚调式：`"D dorian"`等 - 弗里吉亚调式：`"E phrygian"`等 - 吕底亚调式：`"F lydian"`等 - 混利地亚调式：`"G mixolydian"`等 - 洛克里亚调式：`"B locrian"`等 - 五声音阶大调：`"C pentatonicmajor"`等 - 五声音阶小调：`"A pentatonicminor"`等 - 布鲁斯音阶：`"E blues"`等 ## 高级用法 ### 自定义命令 您可以通过以下方式扩展系统： 1. 将新函数添加到 MCP 服务器（`server.py`） 2. 在 FL Studio 控制器脚本（`device_flstudiocontroller.py`）中添加相应的处理程序 3. 为复杂命令实现 SysEx 解析/处理 ### 创建复杂的音乐进行 ```python # 创建一个诗- chorus 排列 # 诗：Am-F-C-G # Chorus：C-G-Am-F verse = ["Am", "F", "C", "G"] chorus = ["C", "G", "Am", "F"] # 创建诗节 create_chord_progression(verse, duration_beats=4, channel=0) # 创建合唱 select_pattern(1) # 移动到下一个模式（√ 工作中） create_chord_progression(chorus, duration_beats=4, channel=0) # 设置排列（注意：set_arrangement 目前不可用） # set_arrangement([0, 0, 1, 1, 0, 1, 1, 1], loop_start=0, loop_end=8) ``` ### 在和弦进行上生成主旋律 **（注意：`create_melody` 目前不可用）** ```python # 创建和弦进行 create_chord_progression(["C", "G", "Am", "F"], duration_beats=4, channel=0) # 在另一个通道上创建兼容的旋律（目前不可用） # create_melody(scale="C major", length=16, channel=1) ``` ## 故障排除 ### MIDI 连接问题 - 确保 IAC 驱动程序在 Audio MIDI Setup 中在线 - 确保在 FL Studio 的 MIDI 设置中选择了正确的 MIDI 端口 - 检查 MCP 服务器日志中是否有任何错误消息 ### FL Studio 对命令无响应 - 确保 FL Studio MCP 控制器已正确加载（您应该看到初始化日志） - 尝试重启 FL Studio 和 MCP 服务器 - 在控制器脚本中通过设置 `DEBUG = True` 启用调试模式 ### SysEx 消息错误 - 检查消息大小是否过大（某些 MIDI 实现有大小限制） - 验证服务器和控制器之间的命令 ID 是否匹配 - 确保复杂命令数据的 JSON 格式正确 ## 已知限制 - **功能状态**：几个核心功能目前不可用（参见“当前状态”部分和 API 表）。 - 可以播放音符和和弦，但设置 BPM 不起作用，加载乐器或音频效果也不起作用。 ## 未来增强 - **稳定核心功能**：优先修复不可用的命令。 - **插件扫描和验证**：实施一个系统来扫描用户安装的 VST/AU 生成器和效果。这将允许验证 `load_instrument` 和 `add_audio_effect` 调用与可用插件的匹配性，提高可靠性。 - **基于机器学习的旋律生成**：实施机器学习模型以生成更具音乐性的旋律（取决于修复 `create_melody`）。 - **音频分析反馈**：与音频分析集成以实现更智能的自动化（取决于修复 `automate_parameter` 和 `get_status`）。 - **模板支持**：保存和加载创作模板以进行快速作曲。 - **多设备支持**：与其他 MIDI 控制器协调。