| name | kaaro-percussion |
| description | Build, enhance, and maintain the KaaroPercussion web-based percussion training game. Covers curriculum content, interactive tools (metronome, tap pads, rhythm visualizations), gamification, SEO, and deployment. |
KaaroPercussion Project Skill
Project Overview
KaaroPercussion is a free, self-paced, gamified percussion training web app. It teaches drumming/percussion through 8 structured phases — from foundational rhythm to advanced temporal architecture — with interactive exercises, a Web Audio metronome, virtual tap pads, and curated YouTube lessons.
Architecture
- Single-page app — vanilla HTML/CSS/JS, no frameworks, no build step
- 4 source files:
index.html (shell), style.css (dark theme), data.js (course content), app.js (all logic)
- Reference:
seed.md contains the full pedagogical framework (8 phases, 65 cited works). Always consult it for curriculum accuracy.
File Roles
| File | Purpose |
|---|
seed.md | Source pedagogical content — 8 phases, works cited, YouTube URLs. Read-only reference. |
data.js | COURSE_DATA.phases[], LEVELS[], PHASE_ICONS. 8 phases, 18 lessons, ~48 exercises. |
style.css | Dark theme design system. CSS variables for colors. Responsive breakpoints at 640px / 1024px. |
index.html | SPA shell with SEO head, header (XP bar), phase nav, main content area, metronome panel. |
app.js | IIFE with modules: State, Storage, Gamification, Metro, TapPads, AccuracyTracker, LiveGrid, PolyrhythmPlayer, Timer, RhythmDisplay, UI, Router. |
og-image.svg | 1200x630 branded OG image. Must use XML-safe entities only (no •, no HTML emoji entities). |
favicon.svg | 32x32 SVG favicon with orange-gold gradient. |
site.webmanifest | PWA manifest for installability. |
Key Technical Details
Metronome (Web Audio API)
- Lookahead scheduling:
setInterval at 25ms schedules audio 100ms ahead via audioContext.currentTime
- OscillatorNode clicks: accent=1000Hz, normal=800Hz, subdivision=600Hz
- 6 ghost beat modes:
all, 2-4, 1-3, synco-e, synco-and, silent-bars
Metro.beatTimestamps[] stores scheduled beat times for accuracy tracking
Tap Pads
- 6 pads: hihat, snare, crash, tom1, kick, tom2
- Sounds synthesized via Web Audio (oscillators + noise buffers + filters)
- Keyboard: Q/W/E (top row), A/S/D (bottom row)
- Touch:
touchstart with passive: false for zero-latency mobile
Accuracy Tracking
- Measures ms offset from nearest metronome grid position
- Grades: perfect (<=10ms), good (<=25ms), ok (<=50ms), miss (>50ms)
Gamification
- XP: 50-100 per exercise, ~4500 total
- 10 levels: Novice -> Temporal Wizard
- Phase unlocking via cumulative XP thresholds
- Streak tracking (consecutive days)
- All progress in
localStorage
Design System
- Background:
#0a0a0f, Accent: #ff6b35 (orange), Gold: #ffc857, Teal: #4ecdc4
- Fonts: Inter (body), JetBrains Mono (code/numbers)
- Mobile-first, touch-friendly (44px min targets)
Deployment
- Hosted at:
https://karx.github.io/kaaroPercussion/
- GitHub Pages — push to main branch deploys automatically
- All URLs in meta tags, JSON-LD, and manifest must use this base URL
Guidelines When Modifying
- No build tools — everything runs directly in the browser
- Consult
seed.md for any curriculum or pedagogical changes
- SVG files — use only XML-valid entities (
• not •, hex escapes not HTML emoji names)
- Metronome changes — preserve the lookahead scheduling pattern; never use
setTimeout for audio timing
- New exercises — add to
data.js with proper type, update rendering in app.js renderExercise()
- SEO changes — update both JSON-LD schemas, OG tags, Twitter cards, and manifest consistently
- Test on mobile — tap pads and metronome are core mobile experiences
