Write the next chord with confidence.
A browser-based songwriting companion that suggests chord progressions using real music theory — and explains why each next chord works, then plays it back with General MIDI soundfonts.
- Ranked next-chord suggestions. Every suggestion is scored by root motion, harmonic function, and resolution of a pending dominant — then translated into a plain-language reason.
- Function-coloured progression board. Tonic, subdominant, and dominant chords are colour-coded so the shape of a phrase is visible at a glance.
- Roman-numeral first. Everything is displayed relative to the key (I, V, vi, IV), so what you learn in one key transfers to all twelve.
- Diatonic palette + chromatic colour. Add the seven chords of the key, plus secondary dominants, tritone substitutes, and modal-mixture borrowings.
- Melody-note guide. For the current chord, see which notes are chord tones, which are passing scale tones, and which sit outside the key as tension.
- The shape of a phrase. One tap adds the classic home → departure → tension → resolve backbone (I–IV–V–I, or i–iv–V–i in minor).
- Classic progressions. Load pop, doo-wop, rock, Pachelbel, jazz ii–V–I, Andalusian, minor ii–V–i, and 12-bar blues.
- Instant playback. Free FluidR3 General MIDI soundfonts, eight instruments, tempo control, looping, and a live playhead.
- Your work is remembered. Key, progression, tempo, and instrument are saved in
localStorage.
| Layer | Choice |
|---|---|
| UI | React 19 + TypeScript + Vite |
| Styling | Tailwind CSS v4 |
| Music theory | MusicTheoryJS |
| Audio | smplr with General MIDI soundfonts |
All theory work — Roman numerals, diatonic chords, suggestion scoring, modal mixture, chord spelling — is handled by musictheoryjs. Playback uses smplr's Soundfont instrument, which streams free FluidR3_GM samples from a CDN and caches them in the browser.
Want the full story? Read How Chord Compass was built — the research, API surprises, architecture, and trade-offs.
npm install
npm run devOpen the URL Vite prints (usually http://localhost:5173).
npm run build # type-check + production build into dist/
npm run preview # serve the production buildPushing to main triggers .github/workflows/deploy.yml, which builds the app and publishes dist/ to GitHub Pages. The Vite base is set to /chord-compass/ for project-site hosting.
src/
├── lib/
│ ├── theory.ts # key helpers, suggestions, explanations, presets, colour options
│ └── audio.ts # soundfont player, scheduling, audition
├── components/
│ ├── Header.tsx # key / mode / voicing controls
│ ├── ChordChip.tsx # progression chips
│ ├── Suggestions.tsx
│ ├── ColourOptions.tsx
│ ├── Backbone.tsx # tonic → subdominant → dominant → tonic
│ ├── MelodyGuide.tsx
│ ├── Presets.tsx
│ └── Transport.tsx
└── App.tsx
- Theory engine: MusicTheoryJS by Zach Moore (ISC).
- Soundfonts: Benjamin Gleitzman's MIDI.js soundfonts.
- Audio engine: smplr by danigb (MIT).
- Inspired by the songwriting-first approach of Hooktheory.
MIT