친 음을 어떻게 채점하나 — 실시간 MIDI 판정 엔진

The problem: "is this key, right now, correct?"

Like a rhythm game, LevelUp Piano flows notes down the screen and the player presses keys to hit them. But a piano isn't a few buttons — it's chords across 88 keys. And people don't play perfectly on the beat; they play a little early or late. That subtle drift has to be judged not as "right/wrong" but as a degree — Perfect, Good, Bad, or Miss.

The timeline and four verdicts

The basis for judgment is elapsed time. On an axis of milliseconds since the song started, each note has "when it should sound" and each input has "when it was pressed." The absolute value of the difference (the error) is the grade.

"Early/late" isn't a separate grade — it's shown on screen as the sign of the error. So the grade is symmetric and the direction is just informational. This window width governs the feel of difficulty: too narrow and it's frustrating, too wide and it's trivial. 300ms is a deliberately forgiving edge — "not exactly on, but you got the beat."

Two-stage judgment — attack and hold

A note's score doesn't end at the instant you press it. Let go of a note you were supposed to sustain and, even with a perfect press, it's only half right. So judgment splits in two:

1. Attack — how close the NoteOn is to the expected time (the Perfect/Good/Bad/Miss above).
2. Duration — how well the actual hold length matches the chart note. Short notes (≤200ms) finalize immediately on attack; long notes wait until you release (NoteOff) to be scored.

# Final score for a long note (>200ms)
final = attack_score × 0.7 + duration_score × 0.3
 
# Duration grade — actual hold ÷ chart length
0.8 – 1.2 → 1.0     0.5 – 1.5 → 0.7     0.3 – 2.0 → 0.3     else → 0.0

The attack grade is just as literal in code — compare the absolute error against three windows.

JudgmentResult _classifyAttack(int absOffsetMs) {
  if (absOffsetMs <= perfectWindowMs) return JudgmentResult.perfect; // ≤ 50ms
  if (absOffsetMs <= goodWindowMs)    return JudgmentResult.good;    // ≤ 150ms
  if (absOffsetMs <= badWindowMs)     return JudgmentResult.bad;     // ≤ 300ms
  return JudgmentResult.miss;
}

The whole-song score is scaled to 100 for an S (≥90) · A (≥80) · B (≥70) grade, and a measure drill counts as passed at 80% accuracy or higher.

Input buffering — holding onto notes played early

The trickiest part was ordering. What if the user presses slightly before a note becomes "active"? Just throwing that input away would wrong an honest player.

So a key press that fails to match is held in a buffer for up to 300ms. Each frame (tick) promotes notes into the active window and re-tries the buffered inputs. If 300ms passes with no note to bind to, the input is dropped (to stop a stale press from later attaching to the wrong note). In other words, judgment is bidirectional: "a note can wait for input, and input can wait for a note."

Chords and hands — which note does a press bind to?

Pianos play multiple notes at once. When several keys go down together, the question is which note each input binds to. The rule is best-fit — among unmatched active notes with the same pitch, bind to the one whose expected time is closest, and immediately lock that note as "matched."

// Among active, unmatched notes of the same pitch, bind to the closest in time.
_PendingNote? best;
var bestOffset = badWindowMs + 1;
for (final p in _active) {
  if (p.matched || p.note.noteNumber != noteNumber) continue;
  final offset = (inputTimeMs - p.note.startTimeMs).round().abs();
  if (offset < bestOffset) { bestOffset = offset; best = p; }
}
if (best == null) return null;   // nothing to bind yet → the caller buffers it
best.matched = true;             // lock: one input never binds to two notes

That "matched" lock means one input never binds to several notes within the same chord. The note chart also carries which hand each note belongs to (left/right), the foundation for practicing one hand or diagnosing weaknesses per hand.

Surviving a dropped connection

Real-world problems found in device testing:

• Ambiguous endpoints — the same piano can show up as several MIDI endpoints. Auto-connecting to any of them risks grabbing one that receives no input, so with two or more, it doesn't auto-connect — the user picks via a picker.
• Dropping mid-performance — a loose cable, power saving; USB-MIDI can stop suddenly. Connection state is kept separate from game state, so when the signal drops the app signals the drop and guides reconnection instead of plowing ahead with scoring — so "the engine is running but there's no input" isn't mistaken for "user error."

The alternative not chosen — Bluetooth-MIDI. Wireless is convenient, but Bluetooth MIDI has too much latency and too many micro-dropouts for millisecond-level judgment. So the real-time path is USB only.

Deterministic, therefore testable

A nice property of this engine is that it's deterministic. Input is just a list of (time, note number) events, and all timing math is integer milliseconds. So feed it a fixed NoteChart and a pre-recorded input event log, and it always produces the same judgments.

That means regressions can be caught with replay tests — no piano required. Pin down "this input sequence should yield Perfect ×3 + Good ×1" as a unit test, and any change to a window value or the buffer logic makes the divergence show up immediately. The more real-time and hardware-dependent a feature is, the more writing it as a pure function — so it can be table-tested — becomes the biggest safety net.

Closing

The judgment engine looks simple on the surface — "did you press the right note at the right time?" But once you account for symmetric windows, buffering early presses, best-fit chord matching, splitting attack from hold, and hardware uncertainty, a judgment that's both fair and satisfying takes a lot of decisions. And because every one of them lives as a number (±50/150/300ms, 0.7·0.3, 300ms) and a pure function, changing a single value means its effect can be confirmed by a test.