Skip to content

README.md

Latest commit

 

History

History
129 lines (86 loc) · 4.33 KB

README.md

File metadata and controls

129 lines (86 loc) · 4.33 KB
Raw

Keyfall

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.

Keyfall screenshot placeholder

Quick Start

git clone https://github.com/mathmati/keyfall.git
cd keyfall
npm install
npm run dev

Open http://localhost:5173 in Chrome or Edge (these support Web MIDI).

To build for production:

npm run build
npm run preview

How to Play

Drop 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.

MIDI Keyboard Setup

  1. Plug in a USB MIDI keyboard
  2. Open Keyfall in Chrome or Edge (Firefox doesn't support Web MIDI)
  3. Allow MIDI access when prompted
  4. The status line at the bottom of the start screen shows connection state

That's it — your keyboard is automatically detected.

Computer Key Map

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".

Audio Import (AI Transcription)

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).

Quality Notes

  • 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

YouTube Play-Along

  1. Click Setup in the top-right
  2. Paste a YouTube link and click Load video
  3. Load a MIDI chart for that song
  4. 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)
  5. 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.

Legal

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.

Tech Stack

  • 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

Development

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.

Contributing

  1. Fork the repo
  2. Create a feature branch
  3. Make your changes (keep it vanilla JS, no frameworks)
  4. Run npm test to verify the MIDI parser
  5. Submit a PR

License

MIT

Transparency

Built with Claude Code.