#API Reference: Scoring

The scoring system aligns detected notes to expected notes and produces per-note pitch and rhythm accuracy scores.

Source: src/lib/scoring/

---

#alignment.ts

Dynamic Time Warping (DTW) alignment of detected notes to expected notes.

#alignNotes(expected, detected, tempo, swing?): AlignmentPair[]

Find the minimum-cost alignment between two note sequences.

Returns: AlignmentPair[] where each pair is one of:

• { expectedIndex, detectedIndex, cost } — matched pair
• { expectedIndex, detectedIndex: null, cost } — missed note
• { expectedIndex: null, detectedIndex, cost } — extra note

Cost function:

---

#pitch-scoring.ts

Per-note pitch accuracy scoring.

#scorePitch(expected, detected): number

Intonation bonus: 0.1 * max(0, 1 - |cents| / 50)

• 0 cents: +0.10 (total 1.10)
• 25 cents: +0.05 (total 1.05)
• 50 cents: +0.00 (total 1.00)

The bonus is clamped to 1.0 at the composite score level.

---

#rhythm-scoring.ts

Per-note rhythm accuracy scoring.

#scoreRhythm(expected, detected, tempo, swing?): number

timingError = |detectedOnset - expectedOnset| / beatDuration
penalty     = min(1.0, 0.5 + tempo / 300)
rhythmScore = max(0, 1.0 - timingError * penalty)

The penalty is tempo-scaled: gentler at slow tempos (where a given absolute timing error is a smaller fraction of a beat) and tighter at fast tempos.

Swing awareness: When swing > 0.5 and the expected note falls on an off-beat eighth, the expected onset is adjusted to match swing playback timing.

Rests: If expected.pitch is null, the score is 1.0.

---

#scorer.ts

Orchestrates the full scoring pipeline.

#scoreAttempt(phrase, detected, tempo, transportSeconds?, swing?): Score

Pipeline:

1. Grid anchoring — Snap detected onsets to the nearest bar downbeat using Transport position
2. DTW alignment — alignNotes() matches detected to expected
3. Latency correction — Compute median timing offset of matched pairs and subtract from all detected onsets (absorbs ~100–300ms constant delay)
4. Per-note scoring — scorePitch() and scoreRhythm() for each matched pair
5. Composite score — overall = pitchAccuracy * 0.6 + rhythmAccuracy * 0.4
6. Grade assignment — scoreToGrade(overall)

Returns: Score object:

{
  pitchAccuracy: number;       // 0-1, average of pitch scores
  rhythmAccuracy: number;      // 0-1, average of rhythm scores
  overall: number;             // 0-1, weighted composite
  grade: Grade;                // 'perfect' | 'great' | 'good' | 'fair' | 'try-again'
  noteResults: NoteResult[];   // Per-note breakdown
  notesHit: number;            // Count of correct pitches
  notesTotal: number;          // Total expected notes
  timing: TimingDiagnostics;   // Offset statistics after latency correction
}

TimingDiagnostics:

interface TimingDiagnostics {
  meanOffsetMs: number;                // Average signed offset after correction
  medianOffsetMs: number;
  stdDevMs: number;                    // Rhythmic consistency
  latencyCorrectionMs: number;         // Median offset that was subtracted
  perNoteOffsetMs: (number | null)[];  // null = missed / extra
}

---

#grades.ts

Score-to-grade mapping and display constants.

#scoreToGrade(overall): Grade

#GRADE_LABELS: Record

Display labels: 'Perfect', 'Great', 'Good', 'Fair', 'Try Again'.

#GRADE_COLORS: Record

CSS color variables: perfect/great → --color-success, good → --color-accent, fair → --color-warning, try-again → --color-error.