A browser piano rhythm game — notes fall Guitar Hero-style and you catch them on your MIDI keyboard or computer keys. Drop in any MIDI file, paste a YouTube link to play along with the real recording, or import audio directly with built-in AI transcription.
git clone https://github.com/mathmati/keyfall.git
cd keyfall
npm install
npm run devOpen http://localhost:5173 in Chrome or Edge (these support Web MIDI).
To build for production:
npm run build
npm run previewDrop a MIDI file anywhere on the page — notes start falling immediately.
In Play mode, hit the notes as they cross the gold line at the bottom. Timing windows: Perfect (±140 ms) scores 100 points, Good (±320 ms) scores 50. Build combos for a multiplier (up to 4x at 40+ combo).
In Watch mode, the game auto-plays the notes so you can see and hear the chart before trying it.
- Plug in a USB MIDI keyboard
- Open Keyfall in Chrome or Edge (Firefox doesn't support Web MIDI)
- Allow MIDI access when prompted
- The status line at the bottom of the start screen shows connection state
That's it — your keyboard is automatically detected.
The home row maps to one octave of white keys starting from C:
| Key | Note | Key | Note | |
|---|---|---|---|---|
| A | C | K | C' | |
| S | D | L | E' | |
| D | E | ; | F' | |
| F | F | ' | G' | |
| G | G | |||
| H | A | |||
| J | B |
Black keys use the row above: W E T Y U O P
Z / X shifts the octave down / up. Adjust in Setup > "Computer-keys octave shift".
Keyfall can transcribe audio files directly into playable charts using Spotify's Basic Pitch ML model, running entirely in your browser — no server, no API keys.
Drop an audio file (.mp3, .wav, .m4a, .ogg) onto the page. After a few seconds of inference, you'll see controls to fine-tune the result:
- Sensitivity — onset detection threshold (lower = more notes detected)
- Note filter — minimum amplitude to keep a note
- Min note length — ignore very short detections
These sliders re-process instantly (inference only runs once).
- Solo piano recordings produce good charts
- Simple melodies with clear note separation work well
- Full band mixes will be noisy — the model detects all pitched instruments
- Vocals are partially detected but results vary
- The model runs client-side on WebGL (GPU) with CPU fallback
- Click Setup in the top-right
- Paste a YouTube link and click Load video
- Load a MIDI chart for that song
- Set the Chart offset — this is the video timestamp (in seconds) where the first note of your MIDI starts. Use the slider or nudge with [ and ] keys (±50 ms each)
- Press play on the video — notes fall in sync
The video plays behind the game with a dim overlay. Your MIDI provides the chart; the video provides the audio.
Keyfall does not bundle, fetch, or hotlink any copyrighted content. The "Find a MIDI" button opens BitMidi in a new tab for you to find files yourself. The built-in demo uses Für Elise by Beethoven (public domain).
Bring your own MIDI files and audio. Keyfall is a player, not a library.
- Vite + vanilla JavaScript (no framework)
- Canvas 2D rendering
- Web MIDI API for hardware keyboards
- YouTube IFrame API for video sync
- @spotify/basic-pitch + TensorFlow.js for audio transcription
- Deploys to GitHub Pages via Actions
npm run dev # Start dev server
npm test # Run vitest tests
npm run build # Production build to dist/The project has a single vitest test that validates the MIDI parser against a reference file.
- Fork the repo
- Create a feature branch
- Make your changes (keep it vanilla JS, no frameworks)
- Run
npm testto verify the MIDI parser - Submit a PR
Built with Claude Code.