Melody Masters
A guitar and piano academy for absolute beginners through to advanced players. It has structured lessons, playable instruments, a real microphone tuner, a practice toolkit, a song lab and an honest listening coach.
It works with no setup. Clone it, install, run. The first screen asks for your name and saves your progress under it — no password. Add a free Supabase database (optional) and you can pick your name on any device to continue where you left off.
The product name is set in one place, src/config/brand.ts. Change it there to rename the app.
Quick start
npm install
npm run dev # http://localhost:3000
Requirements: Node.js 20.9 or newer (tested on Node 26) and a modern browser. Chrome or Edge is recommended for MIDI.
| Command | What it does |
|---|
npm run dev | Development server |
npm run build && npm start | Production build and server |
npm test | Unit tests (Vitest) |
npm run test:e2e | End-to-end tests (Playwright; run npm run build first) |
npm run typecheck | TypeScript check |
npm run lint | ESLint |
To run the Playwright browsers for the first time: npx playwright install chromium.
What's inside
| Route | Feature |
|---|
/ | Landing page |
/onboarding | Short questionnaire that builds a beginner plan |
/dashboard | Guitar / Piano mode switch, today's plan, streak, weekly chart, next lesson, achievements |
/learn, /learn/guitar, /learn/piano, /learn/diagnostic | Curriculum map (levels 0–7) and placement quiz |
/lesson/[id] | Lesson player: explain → listen → see → try (auto-checked) → quiz |
/piano-lab | 49/61/88-key playable piano with mouse, touch, computer keyboard and MIDI; guided exercises |
/guitar-lab | Fretboard, chord and scale explorers, capo simulator, Easy Chord Transposer, exercises |
/tuner | Microphone guitar tuner with cents needle and adjustable A4 |
/practice/* | Metronome, chord trainer, scale trainer, rhythm trainer, ear training, note detector, practice timer, 1-Minute Chord Change drill |
/songs/sheet | Song sheets: paste any song's lyrics with chords, then sing along. Chords appear above the words, the sheet follows your voice (or auto-scrolls), and the song's YouTube video plays alongside |
/songs | Bollywood chord charts (29 songs), a searchable list of 165 Hindi songs, Hindi-style practice pieces, your own charts, and a small English classics tab |
/videos | Curated, verified YouTube lessons with search, filters, favourites and watched state |
/ai-coach | Listening teacher (explain → demo → listen → feedback → adapt) and chat |
/progress | Completion vs mastery, per-track progress, drill history, quiz history, weekly report |
/settings | Your profile & sync, theme, Western/Sargam labels and Sa, keyboard size, goals, backup/import |
Music conventions
- Scientific pitch notation: MIDI 60 = C4 = middle C and A4 = 440 Hz (adjustable from 430 to 450 Hz). Some keyboard brands call middle C "C3". It is the same physical key.
- Guitar standard tuning, low to high: E2 A2 D3 G3 B3 E4. In code, string index 0 is the low E string (string number 6).
- Sargam uses a movable Sa. You choose the tonic and every label is worked out from it, using the equal-tempered approximation. Komal swaras are underlined and tivra Ma is shown as Ma′.
All theory logic is pure TypeScript in src/lib/music/, with tests in music.test.ts: notes, keyboard ranges, fretboard, chords and guitar shapes, scales, transposition and capo, and sargam. Every lesson, lab and song uses these same utilities.
Architecture
src/
app/ Next.js routes ((app)/ group shares the sidebar shell; api/ = server routes)
components/
ui/ Design-system primitives (Button, Card, Segmented, Slider, …)
instruments/ PianoKeyboard, Fretboard, ChordDiagram, Staff, MicButton, note labels
layout/ App shell, instrument toggle, theme toggle, global audio/mic indicator
dashboard/ progress/ settings/ piano/ guitar/ practice/ tuner/ lesson/ learn/
onboarding/ songs/ videos/ coach/ learner/
content/ Curriculum (levels 0–7), songs, curated videos — pure data
hooks/ usePrefs, useData, useMic, useMidi, useNoteInput, useMetronome, usePracticeLog
lib/
music/ Theory core (tested)
audio/ Tone.js output, drift-free beat scheduler, mic pitch/chroma analysis, Web MIDI
exercises/ Pure exercise checkers
progress/ Completion/mastery rules, unlocking, streaks, practice plans
storage/ Storage adapters, zod schemas, repositories, export/import
coach/ Rule-based coach + listening-session state machine
server/ Server-only code (auth, database)
supabase/schema.sql Table for learner profiles (optional cross-device sync)
e2e/ Playwright tests (microphone mocked with a synthetic oscillator)
Persistence (local-first)
UI components never touch storage directly. They call repositories (src/lib/storage/repositories.ts). The repositories use a StorageAdapter interface with get, set, update, remove, list and clear.
- IndexedDB stores progress, history and saved items. It is chosen automatically, falls back to localStorage, and then to memory if storage is blocked.
- localStorage stores small preferences: instrument, theme, label mode, Sa, keyboard size and so on. These are read synchronously so the first paint is correct.
- Supabase (optional) stores one row per learner name with their full progress. The browser talks only to the app's own
/api/learners routes; the Supabase secret key stays on the server. See Profiles & Supabase.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
