Documentation
Complete guide for using and developing with KeysBattle
📖 KeysBattle Overview
KeysBattle is a web-based piano learning application that combines the fun of gaming with music education. Play with your MIDI keyboard or computer keyboard, track your progress, and compete on global leaderboards.
Key Features
- ✓ Full MIDI keyboard support via Web MIDI API
- ✓ 4 game modes: Listening, Learn, Practice, and Arcade
- ✓ Presentation modes: Falling Notes (available), Sheet Music (coming soon)
- ✓ Advanced scoring system with accuracy, combos, and timing
- ✓ AI-powered smart hand separation (in development - accuracy improvements coming)
- ✓ Optimal fingering suggestions (coming soon)
- ✓ Detailed progress tracking and statistics
- ✓ Global and per-song leaderboards
- ✓ Extensive music library
Tech Stack
Frontend: SvelteKit 2.0, Svelte 5 (Runes), TypeScript, Tailwind CSS
Rendering: Pixi.js 7.3 (WebGL), OpenSheetMusicDisplay
Audio/MIDI: Web MIDI API, @tonejs/midi, Tone.js
Backend: Supabase (PostgreSQL, Auth, Storage)
Deployment: Vite, Vercel/Netlify compatible
📚 Resources
Internal Documentation
- • README.md: Project overview
- • CLAUDE.md: Guide for AI assistants
- • Setup guides: Supabase, Google OAuth, Admin
- • AUDIO_SYSTEM.md: Detailed audio system
- • NOTESEPARATION.MD: Hand separation
- • SHEET_MUSIC_MODE.md: Sheet music mode
External Links
- • SvelteKit: kit.svelte.dev
- • Pixi.js: pixijs.com
- • Supabase: supabase.com/docs
- • Web MIDI: developer.mozilla.org/en-US/docs/Web/API/Web_MIDI_API
- • OpenSheetMusicDisplay: opensheetmusicdisplay.github.io