An interactive browser-based tool for real-time chord detection, circle-of-fifths visualization, and music notation rendering.
- 🎹 Piano & MIDI Keyboard Input — Play chords by clicking keys, using standard computer keyboard mappings, or connecting physical MIDI devices (Web MIDI API)
- 🔴 Circle of Fifths Visualization — Notes are displayed in a dynamic circular layout; active notes light up and connect with lines to show chord shapes at a glance
- 📝 Real-time Chord Detection — Automatically identifies chord names (including complex extensions like
M7#5sus4) as you play, with multiple enharmonic candidates listed - 🎼 Music Notation Rendering — Renders played chords as proper staff notation (treble + bass clef) using Verovio
- 🎵 Multi-Instrument Audio Playback — Plays realistic sounds (Piano, Guitars, Organ, Strings, Accordion, etc.) via Soundfont Player with Web Audio API
- 🔀 Multiple Chord Replay Modes — Audition chords in 8 playback patterns (Simultaneous, Ascending, Descending, Strumming, Bass & Chord / Oom-Pah, Up & Down, Alberti Bass, Random Harp)
- 🎸 Guitar Voicings — Calculates and displays guitar chord voicings and barre shapes (E-shape, A-shape)
- 🗝️ Key Signature Selection — Choose any key signature (C major through 7 sharps/flats) to contextualize chord display
- 📌 Sustain Pedal Mode — Hold notes beyond key release to build up extended chords (supports physical MIDI pedal CC 64)
- 🔁 Chord History & Candidates — Keeps a history of recently played chords; hover to preview, click to lock and re-examine or pick alternative chord names
- ⌨️ Extended Keyboard Mapping — Expand standard computer keyboard mappings to cover more octaves
- 🎨 Theme & Accent Customization — Light/Dark theme toggle with customizable accent color palette
- Node.js v18 or higher
- npm v9 or higher
git clone https://github.com/manh9011/ChordVisualizer.git
cd ChordVisualizer
npm installnpm run devOpen your browser at http://localhost:5173 (or the port shown in your terminal).
npm run buildThe compiled output will be in the dist/ directory — ready to deploy as a static site.
npm run previewThe computer keyboard is mapped logically to resemble a real piano, using rows for white and black keys:
Standard Mapping (Octaves 4 & 5):
- White Keys:
↹QWERTYUIOP[]\ - Black Keys:
1245689-=⌫
Extended Mapping (Octaves 3 & 6): (Enable in the panel to reach additional octaves)
-
White Keys:
⇧ZXCVBNM,./⇧ -
Black Keys:
⇪ADFGJK;'↵ -
Hold multiple keys simultaneously to build a chord.
-
Enable Sustain Pedal to keep notes ringing after key release (also compatible with hardware MIDI sustain pedals).
Click any key on the on-screen piano keyboard or connect a hardware USB/MIDI keyboard to trigger notes.
Detected chords are logged in the History panel. Hover over a history entry to preview the chord; click to lock it for detailed inspection. Press the × button to remove individual entries or Clear to reset.
| Library | Purpose |
|---|---|
| Vue 3 | Reactive UI framework |
| TypeScript | Type safety |
| Vite | Build tooling & dev server |
| @tonaljs/tonal | Music theory (chord detection, note utilities) |
| Verovio | MusicXML → SVG staff notation rendering |
| Soundfont Player | Web Audio API piano synthesis |
chord-visualizer/
├── src/
│ ├── App.vue # Main application component & state management
│ ├── main.ts # Vue app entry point
│ ├── style.css # Global styles
│ ├── keys.ts # Keyboard mapping definitions
│ ├── components/ # Reusable UI components
│ │ ├── AccentColorPicker.vue
│ │ ├── ChooseChordPanel.vue
│ │ ├── ChordCandidates.vue
│ │ ├── ChordHistoryList.vue
│ │ ├── ChordHistoryStrip.vue
│ │ ├── CopyToast.vue
│ │ ├── KeySignaturePicker.vue
│ │ ├── MiniCircleOfFifths.vue
│ │ ├── MobileKeySignatureList.vue
│ │ ├── ReplayModeControl.vue
│ │ ├── ScorePanel.vue
│ │ └── SustainIndicator.vue
│ ├── layouts/ # Responsive layout containers
│ │ ├── DesktopLayout.vue
│ │ └── MobileLayout.vue
│ ├── utils/ # Core logic & helpers
│ │ ├── CanvasRenderer.ts # Canvas-based circle-of-fifths visualization
│ │ ├── GuitarVoicings.ts # Guitar chord voicing calculations
│ │ ├── MusicLogic.ts # Chord detection, MIDI mapping, key utilities
│ │ └── MusicXml.ts # MusicXML generation for Verovio rendering
│ └── types/ # TypeScript type declarations
│ ├── soundfont-player.d.ts
│ └── verovio.d.ts
├── public/ # Static assets
├── index.html # HTML entry point
├── vite.config.ts # Vite configuration
└── tsconfig.json # TypeScript configuration
Contributions are welcome! Here's how to get involved:
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature-name - Commit your changes:
git commit -m 'feat: add some feature' - Push to your branch:
git push origin feature/your-feature-name - Open a Pull Request
Please follow Conventional Commits for commit messages.
- MIDI input device support
- Dark/light theme toggle
- More instrument soundfonts
- Export chord sheet as PDF/image
- Chord progression sequencer
- Mobile touch gesture improvements
This project is licensed under the MIT License — see the LICENSE file for details.
- Tonal.js — The backbone of all music theory computations
- Verovio — Beautiful open-source music notation engraver
- Soundfont Player — Simple Web Audio soundfont library
- The open-source music & web community 🎶
Made with ❤️ and music theory