Keyboardia

Keyboardia

一款支持多人协作的步进音序器，可实时协作创作复节奏模式。

功能特性

• 实时多人协作 - 最多 10 位玩家可在同一场会话中共同即兴演奏
• 复节奏模式 - 每条音轨可设置 3-128 个步数（共 26 种选项，包括适合三连音的数值）
• 70 种声音生成器 - 32 种 Web Audio 合成器、11 种 Tone.js FM/AM 合成器、27 种采样乐器
• 27 种采样乐器 - 三角钢琴、808 鼓组、原声鼓、哈蒙德风琴、卡林巴琴、钢鼓、弦乐、吉他、萨克斯等
• 效果链 - 混响、延迟、合唱和失真，并带有限制器（完整支持多人同步）
• 参数锁定 - 自动控制每一步的音高、音量和延音
• 半音网格 - 两种视图模式：“Events”（调性间隔 + 已使用音高）和“All”（从 -24 到 +24 的 49 个音高）
• 音阶锁定 - 将半音网格限制在所选音阶内，并对不属于该音阶的音符发出警告
• 音阶侧边栏 - 可视化音阶音符，突出显示根音/五度音，并标出当前使用情况
• 每条音轨的摇摆设置 - 提供全局和每条音轨的摇摆设置，以控制律动
• 会话分享 - 分享链接、混编他人作品、发布不可变会话
• 二维码分享 - 便于在移动设备上分享会话
• Agent 节奏编辑（实验性） - 通过无状态 MCP 共同编辑、创建、混编、发布、导出和分析会话

与 Agent 搭配使用

使用以下内容配置你的 MCP 客户端：

https://keyboardia.dev/mcp

若要共同编辑已有音乐，请打开一个会话，并将其 https://keyboardia.dev/s/{session_id} URL 中的 UUID 提供给 Agent。Agent 可以读取当前节奏、添加音轨、指定具体步骤并更改速度。其编辑会与已连接的浏览器共享同一实时会话，而已发布的会话则保持只读。

Agent 也可以从零开始：创建新会话并返回其链接；将已发布的会话混编为可编辑副本，而不改动原始会话；在你提出要求时，将当前结果发布为不可变快照；以及将会话导出为供 DAW 使用的 MIDI 文件。

Agent 还可以解释音乐——你可以询问会话所处的调性、不同节奏之间的关系，或某个时刻形成的和弦。答案来自 Key Assistant 使用的同一音乐理论模块，并会说明其不确定性，而非将其隐藏。

有关确切的工具契约和当前限制，请参阅无状态 MCP 节奏切片规范。目录维护者可使用规范的 MCP 目录条目，托管数据的处理方式详见 MCP 隐私声明。

技术栈

• 前端：React 19、TypeScript、Vite
• 音频：Web Audio API、Tone.js
• 后端：Cloudflare Workers、Durable Objects、KV Storage
• 实时通信：基于 WebSockets，并使用 Hibernation API

快速开始

cd app

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm run test:all

# Build for production
npm run build

开发

调试模式

在 URL 中添加 ?debug=1 以启用调试功能：

• 事件跟踪
• 音频状态调试
• 持久化日志存储
• Bug 模式检测

有关完整的调试文档，请参阅 docs/DEVELOPMENT-TOOLS.md。

项目结构

app/
├── src/
│   ├── audio/           # Audio engine, synths, effects, scheduling
│   ├── components/      # React UI components
│   ├── hooks/           # React hooks (useSession, useMultiplayer, etc.)
│   ├── state/           # State management (grid reducer)
│   ├── sync/            # Multiplayer synchronization
│   ├── worker/          # Cloudflare Worker (Durable Objects, API routes)
│   ├── utils/           # Logging, debugging, utilities
│   └── debug/           # Debug overlay and context
├── e2e/                 # End-to-end tests (Playwright)
├── test/                # Integration tests
└── scripts/             # Development and debugging scripts

关键文件

文件	描述
app/src/audio/engine.ts	主音频引擎——协调所有音频子系统
app/src/audio/scheduler.ts	无漂移的前瞻式调度（25ms 定时器，100ms 前瞻时间）
app/src/audio/synth.ts	16 声部复音合成器，支持声部剥夺
app/src/audio/toneSynths.ts	Tone.js 合成器管理器（FM、AM、Membrane 等）
app/src/audio/toneEffects.ts	效果链（混响、延迟、合唱、失真）
app/src/sync/multiplayer.ts	用于实时同步的 WebSocket 客户端
app/src/worker/live-session.ts	用于管理会话状态的 Durable Object

测试

cd app
npm run test:unit          # Unit tests (vitest, fast product lane)
npm run test:audio-render  # Offline audio renders (native Web Audio)
npm run test:verification-tooling  # Tests of the verification tooling itself
npm run test:integration   # Integration tests (Cloudflare Workers)
npm run test:all           # All of the above
npm run analyze:bugs       # Static bug pattern analysis

架构

音频信号链

Source (Oscillator/Sample)
    → Track Gain (per-track volume)
    → Master Gain
    → Effects Chain (Tone.js: reverb → delay → chorus → distortion)
    → Limiter
    → Compressor
    → Destination

合成器引擎

1. SynthEngine（synth.ts）- 原生 Web Audio 振荡器，40 多种预设
2. ToneSynthManager（toneSynths.ts）- Tone.js FM/AM/膜合成器
3. AdvancedSynthEngine（advancedSynth.ts）- 双振荡器，带滤波器包络和 LFO
4. SampledInstrument（sampled-instrument.ts）- 基于采样的播放（钢琴）

多人游戏架构

Client A ←→ Durable Object ←→ Client B
              ↓
        DO Storage (immediate)
              ↓
        KV Storage (on disconnect)

• 每个会话都是一个独立的 Durable Object 实例
• WebSocket 连接使用 Hibernation API，以提高成本效益
• 状态变更会广播给所有已连接的客户端
• **混合持久化：**变更会立即保存到 DO 存储中，断开连接时更新 KV

文档

• ROADMAP.md - 实施阶段和状态
• SYNTHESIS-ENGINE.md - 音频架构规范
• SHARING-AND-PUBLISHING.md - 会话持久化规范
• DEVELOPMENT-TOOLS.md - 调试工具参考
• UI-PHILOSOPHY.md - 设计原则
• LESSONS-LEARNED.md - 调试实战经验

许可证

MIT

捆绑的乐器采样是第三方内容，各自遵循其许可证 （CC0、公有领域及类似的自由使用条款），详见 app/public/instruments/LICENSE.md。