Rhythm games are unforgiving about timing in a way most games aren't. A 40ms error is invisible in a platformer and ruins a rhythm game — which makes this the project that teaches you what audio timing really involves.

1. Never time against the frame loop

The fundamental rule. requestAnimationFrame fires roughly every 16ms and drifts. Audio playback has its own clock, and it's the accurate one.

Time everything against the audio context's current time. Notes have a position in the song; the display derives from where the audio actually is, not from a counter you increment.

rhythm-core.txt
Build a rhythm game core. Web Audio, canvas.

- Chart as data: a list of notes with a time in seconds and a lane.
- All timing from the audio context's clock, never from the frame
  loop. Explain how the display position is derived.
- Judge input against the note's time with windows — perfect, good,
  miss. Say what windows you chose in milliseconds.
- Handle the audio output latency offset, and let the player calibrate
  it, because it varies by device by tens of milliseconds.
- Notes scrolling into view with enough lead time to react.

2. Calibration is mandatory

Between the browser, the operating system and the output device — especially Bluetooth headphones — audio comes out anywhere from 20ms to 300ms after you asked for it. Without a calibration step, the game feels wrong on most setups and correct on yours.

A short calibration where the player taps along to a beat, and you average the offset, fixes it entirely.

3. Judgement windows

Roughly: ±25ms perfect, ±60ms good, ±100ms okay, beyond that a miss. Tune them, but state them explicitly so the difficulty is a design decision rather than an accident.

Show the timing error — early or late — so players can learn. That feedback is what makes people improve rather than plateau.

4. Charting is the content problem

Placing notes by hand against a waveform is slow. Build the simplest possible editor — play the song, tap keys, record timestamps — and then let yourself nudge them afterwards. Automated beat detection is a research project; tapping is an afternoon.

Test on Bluetooth headphones early. The latency there is large enough that a game built and tested on wired audio feels completely broken.