{
  "markdown": "# Keyboardia\n\nA multiplayer step sequencer with polyrhythmic patterns, built for real-time collaboration.\n\n## Features\n\n- **Real-time Multiplayer** - Up to 10 players can jam together on the same session\n- **Polyrhythmic Patterns** - Each track can have 3-128 step counts (26 options including triplet-friendly values)\n- **70 Sound Generators** - 32 Web Audio synths, 11 Tone.js FM/AM synths, 27 sampled instruments\n- **27 Sampled Instruments** - Grand piano, 808 kit, acoustic drums, Hammond organ, kalimba, steel drums, strings, guitars, sax, and more\n- **Effects Chain** - Reverb, delay, chorus, and distortion with limiter (full multiplayer sync)\n- **Parameter Locks** - Per-step pitch, volume, and tied notes automation\n- **Chromatic Grid** - Two view modes: \"Events\" (key intervals + used pitches) and \"All\" (49 pitches from -24 to +24)\n- **Scale Lock** - Constrain chromatic grid to selected musical scale with out-of-scale warnings\n- **Scale Sidebar** - Visualize scale notes with root/fifth emphasis and active usage highlighting\n- **Per-track Swing** - Global and per-track swing settings for groove control\n- **Session Sharing** - Share links, remix others' work, publish immutable sessions\n- **QR Code Sharing** - Mobile-friendly session sharing\n- **Agent Rhythm Editing (Experimental)** - Co-edit, create, remix, publish, export, and analyze sessions through stateless MCP\n\n## Use with an agent\n\nConfigure your MCP client with:\n\n```text\nhttps://keyboardia.dev/mcp\n```\n\nTo co-edit music you already have, open a session and give the agent the UUID\nfrom its `https://keyboardia.dev/s/{session_id}` URL. Agents can read the\ncurrent rhythm, add a track, assign specific steps, and change tempo. Their\nedits use the same live session as connected browsers, and published sessions\nstay read-only.\n\nAgents can also start from nothing: create a new session and hand back its link,\nremix a published session into an editable copy without touching the original,\npublish the current result as an immutable snapshot when you ask, and export the\nsession as a MIDI file for a DAW.\n\nThey can explain music too — ask what key a session is in, how its rhythms sit\nagainst each other, or what chord a moment forms, and the answer comes from the\nsame music-theory module the Key Assistant uses, with its uncertainty stated\nrather than hidden.\n\nSee the [stateless MCP rhythm-slice specification](specs/STATELESS-MCP.md) for\nthe exact tool contract and current limitations. Directory maintainers can use\nthe canonical [MCP listing record](docs/MCP-DIRECTORY-LISTINGS.md), and hosted\ndata handling is described in the [MCP privacy notice](docs/MCP-PRIVACY.md).\n\n## Tech Stack\n\n- **Frontend**: React 19, TypeScript, Vite\n- **Audio**: Web Audio API, Tone.js\n- **Backend**: Cloudflare Workers, Durable Objects, KV Storage\n- **Real-time**: WebSockets with Hibernation API\n\n## Getting Started\n\n```bash\ncd app\n\n# Install dependencies\nnpm install\n\n# Start development server\nnpm run dev\n\n# Run tests\nnpm run test:all\n\n# Build for production\nnpm run build\n```\n\n## Development\n\n### Debug Mode\n\nAdd `?debug=1` to the URL to enable debug features:\n- Event tracing\n- Audio state debugging\n- Persistent log storage\n- Bug pattern detection\n\nSee [docs/DEVELOPMENT-TOOLS.md](docs/DEVELOPMENT-TOOLS.md) for comprehensive debugging documentation.\n\n### Project Structure\n\n```\napp/\n├── src/\n│   ├── audio/           # Audio engine, synths, effects, scheduling\n│   ├── components/      # React UI components\n│   ├── hooks/           # React hooks (useSession, useMultiplayer, etc.)\n│   ├── state/           # State management (grid reducer)\n│   ├── sync/            # Multiplayer synchronization\n│   ├── worker/          # Cloudflare Worker (Durable Objects, API routes)\n│   ├── utils/           # Logging, debugging, utilities\n│   └── debug/           # Debug overlay and context\n├── e2e/                 # End-to-end tests (Playwright)\n├── test/                # Integration tests\n└── scripts/             # Development and debugging scripts\n```\n\n### Key Files\n\n| File | Description |\n|------|-------------|\n| `app/src/audio/engine.ts` | Main audio engine - coordinates all audio subsystems |\n| `app/src/audio/scheduler.ts` | Drift-free lookahead scheduling (25ms timer, 100ms lookahead) |\n| `app/src/audio/synth.ts` | 16-voice polyphonic synthesizer with voice stealing |\n| `app/src/audio/toneSynths.ts` | Tone.js synth manager (FM, AM, Membrane, etc.) |\n| `app/src/audio/toneEffects.ts` | Effects chain (reverb, delay, chorus, distortion) |\n| `app/src/sync/multiplayer.ts` | WebSocket client for real-time sync |\n| `app/src/worker/live-session.ts` | Durable Object for session state |\n\n### Testing\n\n```bash\ncd app\nnpm run test:unit          # Unit tests (vitest)\nnpm run test:integration   # Integration tests (Cloudflare Workers)\nnpm run test:all           # All tests\nnpm run analyze:bugs       # Static bug pattern analysis\n```\n\n## Architecture\n\n### Audio Signal Chain\n\n```\nSource (Oscillator/Sample)\n    → Track Gain (per-track volume)\n    → Master Gain\n    → Effects Chain (Tone.js: reverb → delay → chorus → distortion)\n    → Limiter\n    → Compressor\n    → Destination\n```\n\n### Synth Engines\n\n1. **SynthEngine** (`synth.ts`) - Native Web Audio oscillators, 40+ presets\n2. **ToneSynthManager** (`toneSynths.ts`) - Tone.js FM/AM/Membrane synths\n3. **AdvancedSynthEngine** (`advancedSynth.ts`) - Dual-oscillator with filter envelope and LFO\n4. **SampledInstrument** (`sampled-instrument.ts`) - Sample-based playback (piano)\n\n### Multiplayer Architecture\n\n```\nClient A ←→ Durable Object ←→ Client B\n              ↓\n        DO Storage (immediate)\n              ↓\n        KV Storage (on disconnect)\n```\n\n- Each session is a single Durable Object instance\n- WebSocket connections use Hibernation API for cost efficiency\n- State changes broadcast to all connected clients\n- **Hybrid persistence:** Mutations saved immediately to DO storage, KV updated on disconnect\n\n## Documentation\n\n- [ROADMAP.md](specs/ROADMAP.md) - Implementation phases and status\n- [SYNTHESIS-ENGINE.md](specs/SYNTHESIS-ENGINE.md) - Audio architecture spec\n- [SHARING-AND-PUBLISHING.md](specs/SHARING-AND-PUBLISHING.md) - Session persistence spec\n- [DEVELOPMENT-TOOLS.md](docs/DEVELOPMENT-TOOLS.md) - Debug tools reference\n- [UI-PHILOSOPHY.md](specs/UI-PHILOSOPHY.md) - Design principles\n- [LESSONS-LEARNED.md](docs/LESSONS-LEARNED.md) - Debugging war stories\n\n## License\n\n[MIT](LICENSE)\n\nBundled instrument samples are third-party content with their own licenses\n(CC0, public domain, and similar free-use terms), documented in\n[app/public/instruments/LICENSE.md](app/public/instruments/LICENSE.md).\n",
  "bytes": 6645,
  "sha": "11fda42275ea986bea4232cdc65a4cd2902f0c37c8983aea0a87c794017c23da",
  "repo_slug": "adewale/keyboardia",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_adewale_keyboardia_8b90b885/readme"
}