PartyKeys MIDI 键盘控制

通过 MCP 控制 PartyKeys MIDI 键盘（音乐密码）的 LED 灯光和监听弹奏。

统一架构

手机 App 和浏览器页面使用同一套通信协议，都连接 WebSocket 端口 18790：

MCP Server (端口 18790)
/ \
/ \
WebSocket / \ WebSocket
↓ ↓
┌──────────┐ ┌──────────┐
│ 手机 App │ │ 浏览器页面 │
│ │ │ │
│ BLE │ │ Web BT │
└────┬─────┘ └────┬─────┘
│ │
└──────┬──────┘
↓
MIDI 键盘

单一服务：调用 music_connect() 时，MCP 只启动 WebSocket 服务（端口 18790）。

安装

首次使用前运行安装脚本：

bash
bash {baseDir}/scripts/setup.sh

连接设备

连接键盘前，先询问用户选择连接方式：

请选择 MIDI 键盘的连接方式：

• - 🌐 浏览器连接 — 在 Chrome/Edge 浏览器中连接设备（推荐本机使用）
• 📱 手机 App — 通过手机 App 桥接蓝牙（推荐云端/远程使用）

两种连接方式使用同一套协议，可任选其一。

方式 1：浏览器连接（web）

使用流程：

1. 1. 用户打开 partykeys-bridge-web/standalone.html 网页
2. 输入 WebSocket 地址：ws://<本机 IP>:18790/ws
3. 点击「连接服务器」，然后点击「连接设备」
4. 选择并连接 MIDI 键盘

适用系统：所有系统（Windows、Linux、macOS）

安全上下文（必读）：Web Bluetooth 只在浏览器的「安全上下文」里可用，即 https:// 或本机的 http://localhost / http://127.0.0.1。远程 http://IP 无法使用 Web Bluetooth，需改用 手机 App。

方式 2：手机 App（mobile）

使用流程：

1. 1. 用户在手机下载 PartyKeys Bridge App（Android/iOS）
2. 打开 App，输入服务器地址 ws://<服务器 IP>:18790/ws
3. 在 App 中扫描并连接 MIDI 键盘
4. 保持 App 在前台

适用系统：所有系统（Windows、Linux、macOS、云端服务器）

可用工具

music_connect

连接 MIDI 键盘设备。

• - mode: mobile 或 web（可选，不传时让用户选择）

music_disconnect

断开设备连接。

musiclightkeys

点亮指定按键的 LED 灯。

• - keys: 音符列表（必填），如 [C4, E4, G4] 或 [3c, 40, 43] 或 3c,40,43
• colors: 颜色数组，每个键对应一个颜色（可选），如 [1, 3, 5]
• color: 单个颜色值，所有键共用（可选，已废弃，推荐使用 colors）

12 种颜色

值	颜色	值	颜色
0	关闭（熄灭）	7	绿色
1

红色 | 8 | 青绿 | | 2 | 橙红 | 9 | 青色 | | 3 | 橙色 | 10 | 蓝色 | | 4 | 黄橙 | 11 | 蓝紫 | | 5 | 黄色 | 12 | 紫色 | | 6 | 黄绿 | | |

music_listen

监听用户弹奏输入。

• - timeout: 超时时间，毫秒（默认 5000）
• mode: single 或 continuous

musicplaysequence

播放音符序列。

• - sequence: 音符序列数组，每个元素含 keys 和 delay（毫秒）

musicfollowmode

跟弹模式。

• - notes: 音符序列
• timeout: 每个音符超时，毫秒（默认 30000）

music_status

获取硬件连接状态。

musicsetmode

切换键盘/设备工作模式。

• - mode: skin / free / game / skinconfig / drum / freelight / singing / singingadvanced / appconnect

musicsetoctave

设置键盘音区（8度偏移）。

• - octave: 整数，-3~3，0 为默认音区

musicsetbpm

设置节拍速度。

• - bpm: 整数，20~300

musicsetbeat_type

设置节拍类型（拍号）。

• - beat: 4/4 / 4/3 / 8/6

musicchordlight

根据和弦名称点亮键盘对应按键（教学用）。

• - chord: 和弦名称，格式：根音+和弦类型，如 C、Dm、G7、FMaj7、Am7
• position: 把位偏移，0 为默认，正数升高，负数降低

musicsetskin

设置键盘/设备皮肤（色盘）。

• - skin_id: 色盘编号，0~127
• query: 若为 true 则仅查询已有皮肤列表

musicquerydevice

查询设备在线状态，获取当前已连接的设备列表。

musicqueryversion

查询设备固件版本信息。

• - target: all / box / keyboard

示例

浏览器连接模式:

music_connect(mode=web)
musiclightkeys(keys=[3c, 40, 43], colors=[1, 3, 5])
music_disconnect()

手机中转模式:

music_connect(mode=mobile)
musiclightkeys(keys=[C4, E4, G4], color=blue)
music_disconnect()

12 色渐变:

点亮 12 个键，每个键不同颜色

musiclightkeys( keys=[30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 3a, 3b], colors=[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] )

关闭所有灯光:

musiclightkeys(keys=[])