Keyboardia

Crear, coeditar, analizar, publicar y exportar sesiones colaborativas de secuenciador por pasos a través de MCP.

GitHub

Documentación

Keyboardia

Un secuenciador de pasos multijugador con patrones polirrítmicos, construido para la colaboración en tiempo real.

Características

Multijugador en tiempo real - Hasta 10 jugadores pueden tocar juntos en la misma sesión
Patrones polirrítmicos - Cada pista puede tener de 3 a 128 pasos (26 opciones, incluidos valores compatibles con tresillos)
70 generadores de sonido - 32 sintetizadores Web Audio, 11 sintetizadores FM/AM de Tone.js, 27 instrumentos muestreados
27 instrumentos muestreados - Piano de cola, kit 808, batería acústica, órgano Hammond, kalimba, tambores metálicos, cuerdas, guitarras, saxofón y más
Cadena de efectos - Reverberación, delay, chorus y distorsión con limitador (sincronización multijugador completa)
Bloqueos de parámetros - Automatización de tono, volumen y notas ligadas por paso
Cuadrícula cromática - Dos modos de vista: "Eventos" (intervalos de teclas + tonos usados) y "Todos" (49 tonos de -24 a +24)
Bloqueo de escala - Restringe la cuadrícula cromática a la escala musical seleccionada con advertencias de notas fuera de escala
Barra lateral de escala - Visualiza las notas de la escala con énfasis en la fundamental/quinta y resaltado de uso activo
Swing por pista - Ajustes de swing globales y por pista para controlar el groove
Compartir sesiones - Comparte enlaces, remezcla el trabajo de otros, publica sesiones inmutables
Compartir con código QR - Compartir sesiones compatible con dispositivos móviles
Edición rítmica con agente (Experimental) - Coedita, crea, remezcla, publica, exporta y analiza sesiones mediante MCP sin estado

Uso con un agente

Configura tu cliente MCP con:

https://keyboardia.dev/mcp

Para coeditar música que ya tienes, abre una sesión y dale al agente el UUID de su URL https://keyboardia.dev/s/{session_id}. Los agentes pueden leer el ritmo actual, añadir una pista, asignar pasos específicos y cambiar el tempo. Sus ediciones usan la misma sesión en vivo que los navegadores conectados, y las sesiones publicadas permanecen de solo lectura.

Los agentes también pueden empezar desde cero: crear una nueva sesión y devolver su enlace, remezclar una sesión publicada en una copia editable sin tocar la original, publicar el resultado actual como una instantánea inmutable cuando lo pidas, y exportar la sesión como archivo MIDI para un DAW.

También pueden explicar música: pregunta en qué tonalidad está una sesión, cómo se relacionan sus ritmos entre sí, o qué acorde forma un momento, y la respuesta proviene del mismo módulo de teoría musical que usa el Asistente de Tonalidad, con su incertidumbre declarada en lugar de oculta.

Consulta la especificación de segmentos rítmicos MCP sin estado para el contrato exacto de herramientas y las limitaciones actuales. Los mantenedores de directorios pueden usar el registro canónico de listados MCP, y el manejo de datos alojados se describe en el aviso de privacidad de MCP.

Pila tecnológica

Frontend: React 19, TypeScript, Vite
Audio: Web Audio API, Tone.js
Backend: Cloudflare Workers, Durable Objects, Almacenamiento KV
Tiempo real: WebSockets con Hibernation API

Primeros pasos

cd app

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm run test:all

# Build for production
npm run build

Desarrollo

Modo de depuración

Añade ?debug=1 a la URL para habilitar funciones de depuración:

Trazado de eventos
Depuración del estado de audio
Almacenamiento persistente de registros
Detección de patrones de errores

Consulta docs/DEVELOPMENT-TOOLS.md para documentación completa de depuración.

Estructura del proyecto

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

Archivos clave

Archivo	Descripción
`app/src/audio/engine.ts`	Motor de audio principal: coordina todos los subsistemas de audio
`app/src/audio/scheduler.ts`	Programación de anticipación sin deriva (temporizador de 25 ms, anticipación de 100 ms)
`app/src/audio/synth.ts`	Sintetizador polifónico de 16 voces con robo de voces
`app/src/audio/toneSynths.ts`	Gestor de sintetizadores Tone.js (FM, AM, Membrane, etc.)
`app/src/audio/toneEffects.ts`	Cadena de efectos (reverberación, delay, chorus, distorsión)
`app/src/sync/multiplayer.ts`	Cliente WebSocket para sincronización en tiempo real
`app/src/worker/live-session.ts`	Durable Object para el estado de la sesión

Pruebas

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

Arquitectura

Cadena de señal de audio

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

Motores de sintetizador

SynthEngine (synth.ts) - Osciladores Web Audio nativos, más de 40 preajustes
ToneSynthManager (toneSynths.ts) - Sintetizadores FM/AM/Membrane de Tone.js
AdvancedSynthEngine (advancedSynth.ts) - Doble oscilador con envolvente de filtro y LFO
SampledInstrument (sampled-instrument.ts) - Reproducción basada en muestras (piano)

Arquitectura multijugador

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

Cada sesión es una única instancia de Durable Object
Las conexiones WebSocket usan Hibernation API para eficiencia de costos
Los cambios de estado se transmiten a todos los clientes conectados
Persistencia híbrida: Las mutaciones se guardan inmediatamente en el almacenamiento de DO, KV se actualiza al desconectarse

Documentación

ROADMAP.md - Fases de implementación y estado
SYNTHESIS-ENGINE.md - Especificación de arquitectura de audio
SHARING-AND-PUBLISHING.md - Especificación de persistencia de sesiones
DEVELOPMENT-TOOLS.md - Referencia de herramientas de depuración
UI-PHILOSOPHY.md - Principios de diseño
LESSONS-LEARNED.md - Historias de depuración

Licencia

MIT

Las muestras de instrumentos incluidas son contenido de terceros con sus propias licencias (CC0, dominio público y términos de uso libre similares), documentadas en app/public/instruments/LICENSE.md.