Keyboardia

Crie, co-edite, analise, publique e exporte sessões colaborativas de step-sequencer através do MCP.

GitHub

Documentação

Keyboardia

Um sequenciador de passos multiplayer com padrões polirrítmicos, construído para colaboração em tempo real.

Recursos

Multijogador em Tempo Real - Até 10 jogadores podem tocar juntos na mesma sessão
Padrões Polirrítmicos - Cada faixa pode ter de 3 a 128 contagens de passos (26 opções, incluindo valores compatíveis com tercinas)
70 Geradores de Som - 32 sintetizadores Web Audio, 11 sintetizadores FM/AM do Tone.js, 27 instrumentos sampleados
27 Instrumentos Sampleados - Piano de cauda, kit 808, bateria acústica, órgão Hammond, kalimba, steel drums, cordas, guitarras, sax e muito mais
Cadeia de Efeitos - Reverb, delay, chorus e distorção com limitador (sincronização total em multiplayer)
Travas de Parâmetros - Automação de pitch, volume e notas ligadas por passo
Grade Cromática - Dois modos de visualização: "Eventos" (intervalos de teclas + pitches usados) e "Todos" (49 pitches de -24 a +24)
Trava de Escala - Restringe a grade cromática à escala musical selecionada, com avisos de notas fora da escala
Barra Lateral de Escala - Visualize as notas da escala com ênfase em tônica e quinta e destaque de uso ativo
Swing por Faixa - Configurações de swing globais e por faixa para controle do groove
Compartilhamento de Sessão - Compartilhe links, remixe o trabalho de outros, publique sessões imutáveis
Compartilhamento por QR Code - Compartilhamento de sessão compatível com dispositivos móveis
Edição Rítmica por Agente (Experimental) - Coedite, crie, remixe, publique, exporte e analise sessões por meio de MCP sem estado

Uso com um agente

Configure seu cliente MCP com:

https://keyboardia.dev/mcp

Para coeditar músicas que você já possui, abra uma sessão e forneça ao agente o UUID da URL https://keyboardia.dev/s/{session_id}. Os agentes podem ler o ritmo atual, adicionar uma faixa, atribuir passos específicos e alterar o tempo. As edições deles usam a mesma sessão ao vivo dos navegadores conectados, e as sessões publicadas permanecem somente leitura.

Os agentes também podem começar do zero: criar uma nova sessão e devolver o link, remixar uma sessão publicada em uma cópia editável sem tocar no original, publicar o resultado atual como um snapshot imutável quando você pedir, e exportar a sessão como um arquivo MIDI para uma DAW.

Eles também podem explicar música — pergunte em qual tonalidade uma sessão está, como os ritmos se relacionam entre si, ou que acorde um momento forma, e a resposta vem do mesmo módulo de teoria musical usado pelo Key Assistant, com sua incerteza declarada em vez de oculta.

Consulte a especificação de fatias rítmicas MCP sem estado para o contrato exato das ferramentas e as limitações atuais. Mantenedores de diretórios podem usar o registro canônico de listagem MCP, e o tratamento de dados hospedados é descrito no aviso de privacidade do MCP.

Pilha Tecnológica

Frontend: React 19, TypeScript, Vite
Áudio: Web Audio API, Tone.js
Backend: Cloudflare Workers, Durable Objects, Armazenamento KV
Tempo Real: WebSockets com Hibernation API

Primeiros Passos

cd app

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm run test:all

# Build for production
npm run build

Desenvolvimento

Modo de Depuração

Adicione ?debug=1 à URL para ativar os recursos de depuração:

Rastreamento de eventos
Depuração do estado de áudio
Armazenamento persistente de logs
Detecção de padrões de bugs

Consulte docs/DEVELOPMENT-TOOLS.md para documentação abrangente de depuração.

Estrutura do Projeto

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

Arquivos Principais

Arquivo	Descrição
`app/src/audio/engine.ts`	Motor de áudio principal - coordena todos os subsistemas de áudio
`app/src/audio/scheduler.ts`	Agendamento lookahead sem deriva (timer de 25ms, lookahead de 100ms)
`app/src/audio/synth.ts`	Sintetizador polifônico de 16 vozes com roubo de voz
`app/src/audio/toneSynths.ts`	Gerenciador de sintetizadores Tone.js (FM, AM, Membrane, etc.)
`app/src/audio/toneEffects.ts`	Cadeia de efeitos (reverb, delay, chorus, distorção)
`app/src/sync/multiplayer.ts`	Cliente WebSocket para sincronização em tempo real
`app/src/worker/live-session.ts`	Durable Object para estado da sessão

Testes

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

Arquitetura

Cadeia de Sinal de Áudio

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 nativos de Web Audio, mais de 40 presets
ToneSynthManager (toneSynths.ts) - Sintetizadores FM/AM/Membrane do Tone.js
AdvancedSynthEngine (advancedSynth.ts) - Oscilador duplo com envelope de filtro e LFO
SampledInstrument (sampled-instrument.ts) - Reprodução baseada em amostras (piano)

Arquitetura Multijogador

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

Cada sessão é uma única instância de Durable Object
Conexões WebSocket usam a Hibernation API para eficiência de custo
Mudanças de estado são transmitidas a todos os clientes conectados
Persistência híbrida: Mutações salvas imediatamente no armazenamento do DO, KV atualizado na desconexão

Documentação

ROADMAP.md - Fases de implementação e status
SYNTHESIS-ENGINE.md - Especificação da arquitetura de áudio
SHARING-AND-PUBLISHING.md - Especificação de persistência de sessão
DEVELOPMENT-TOOLS.md - Referência de ferramentas de depuração
UI-PHILOSOPHY.md - Princípios de design
LESSONS-LEARNED.md - Histórias de guerra de depuração

Licença

MIT

As amostras de instrumentos incluídas são conteúdo de terceiros com suas próprias licenças (CC0, domínio público e termos de uso livre semelhantes), documentadas em app/public/instruments/LICENSE.md.