Partykeys Midi

Control PartyKeys MIDI keyboard via WebSocket - connect device, light up keys with 12 colors, listen to playing, play sequences, and follow mode for music teaching.

PartyKeys MIDI 键盘控制

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

统一架构

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

text

                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. 用户打开 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. 用户在手机下载 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

断开设备连接。

music_light_keys

点亮指定按键的 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"

music_play_sequence

播放音符序列。

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

music_follow_mode

跟弹模式。

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

music_status

获取硬件连接状态。

music_set_mode

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

• mode: skin / free / game / skin_config / drum / free_light / singing / singing_advanced / app_connect

music_set_octave

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

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

music_set_bpm

设置节拍速度。

• bpm: 整数，20~300

music_set_beat_type

设置节拍类型（拍号）。

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

music_chord_light

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

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

music_set_skin

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

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

music_query_device

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

music_query_version

查询设备固件版本信息。

• target: "all" / "box" / "keyboard"

示例

浏览器连接模式:

text

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

手机中转模式:

text

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

12 色渐变:

text

# 点亮 12 个键，每个键不同颜色
music_light_keys(
  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]
)

关闭所有灯光:

text

music_light_keys(keys=[])