PartyKeys Development Foundation

音乐密码新 Web / iOS 音乐产品的统一技术底座。它把已经验证的 MIDI、音色与硬件灯光能力整理成可直接复用的文档、代码、音频资源和发布验收标准。

官网：https://foundation.partykeys.ai

GitHub：https://github.com/PartyBohan/PartyKeysDevFoundation（公开仓库，无需申请访问权限）

核心能力

1. MidiBrowser / Web MIDI transport — 统一 USB、BLE MIDI、热插拔、多消息 packet、running status、CC64 与时间戳。
2. Four-layer piano engine — Salamander Grand Piano V3 的 13 个音高锚点 × 4 个力度层，共 52 个采样，并提供合成音色降级。
3. Light controller — 音乐密码 36 的 CMD 0x15 RGB 与 CMD 0x71 palette profile、256-byte frame 限制及约 200 ms 灯光同步。
4. Device profiles — 音乐密码 36 与 PopuPiano 29 分离编码，避免 key index、MIDI note 与 palette slot 混用。

品牌命名规则

• 中文品牌名统一使用 音乐密码。
• 英文品牌名统一使用 PartyKeys。
• 仓库名、域名、代码类名、MIDI port 名称与 /partykey/i 设备匹配等机器标识继续保留 PartyKeys，不得为了文案本地化而破坏兼容性。

仓库结构

PartyKeysDevFoundation/
├── index.html                              # foundation.partykeys.ai 单文件官网
├── PARTYKEYS_DEVELOPMENT_FOUNDATION.md     # 完整固化文档
├── src/partykeys-foundation.js             # 零依赖 ES module
├── tests/foundation.test.mjs               # 协议与解析回归测试
├── samples/                                # 52 个四级力度钢琴 MP3
├── assets/partykeys-logo.png               # 音乐密码 / PartyKeys 企业 Logo 原文件
├── assets/products/                        # 11 张音乐密码官方产品透明 PNG
├── AUDIO_CREDITS.md                        # Salamander 署名与许可证
├── ASSET_NOTICE.md                         # 品牌与官方产品资产权利边界
├── LICENSE                                 # 代码与协议文档的 MIT License
└── vercel.json                             # 官网安全与缓存配置

快速接入

import {
  connectMidi,
  FourLayerPiano,
  PartyKeysLights
} from './src/partykeys-foundation.js';

const piano = new FourLayerPiano({ baseURL: './samples/' });
const inputs = await connectMidi(event => {
  if (event.type === 'on') piano.noteOn(event.note, event.velocity);
  if (event.type === 'off') piano.noteOff(event.note);
  if (event.type === 'pedal') piano.setPedal(event.on);
});

首次连接必须从用户手势同步调用 piano.ensureAudio()；音乐密码设备的 MIDI output 连接或重连后必须重新发送相应协议的 init()。

验证

npm run check

完整接入流程、协议字节、参数与发布矩阵见 PARTYKEYS_DEVELOPMENT_FOUNDATION.md。音频资源使用时必须保留 AUDIO_CREDITS.md。

官方产品渲染

assets/products/ 保存用户提供的原始透明 PNG，网页和后续音乐密码产品应直接复用这些官方实物渲染，不再自行绘制通用键盘。

仓库文件	内容
keyboard-white-front.png	音乐密码 36 键白色正面
keyboard-white-angle.png	音乐密码 36 键白色斜视角
keyboard-black-front.png	音乐密码 36 键黑色正面
keyboard-black-angle.png	音乐密码 36 键黑色斜视角
keyboard-speaker-white.png	白色键盘 + 音响
keyboard-speaker-black.png	黑色键盘 + 音响
keyboard-speaker-sticks-white.png	白色键盘 + 音响 + 鼓棒
keyboard-speaker-sticks-black.png	黑色键盘 + 音响 + 鼓棒
keyboard-sticks-speaker-black-angle.png	黑色全套斜视角组合
keyboard-speaker-sticks-black-wide.png	黑色全套横向组合
dual-keyboard-speaker-sticks-white.png	双白色键盘 + 音响 + 鼓棒

开源许可

• MIDI 传输、钢琴引擎、灯光协议实现、测试与基础文档采用 MIT License，任何个人或组织均可无需申请地使用、复制、修改、分发与集成。
• samples/ 中的 Salamander Grand Piano V3 采样遵循 CC BY 3.0，使用时必须保留 AUDIO_CREDITS.md 中的署名。
• 音乐密码、PartyKeys 名称及 Logo 属于品牌标识；assets/products/ 官方产品渲染不包含在 MIT License 授权范围内，详见 ASSET_NOTICE.md。
• 任何目标固件都应分别真机验证 0x15 与 0x71，未验证前默认使用已兼容的 0x71 profile。