Hybrid Piano Interface - Chord-Intuitive Musical Thinking Made Physical

Version 2.0.0 - Now built with TypeScript for enhanced type safety and maintainability

Overview

This project develops a hybrid piano interface that solves a fundamental problem in music: traditional piano keyboards force musicians to memorize 12 different physical patterns for every chord, scale, and progression due to a geometric mismatch between uniform musical space (12 equal semitones) and the asymmetric piano keyboard layout (7 white + 5 black keys).

Rather than replacing the piano with an isomorphic keyboard (which faces insurmountable adoption barriers), we augment the standard keyboard with intelligent controls that let musicians think in functional harmony (root + quality + extensions) instead of specific note names.

The Problem

Geometric Mismatch

The piano keyboard attempts an impossible mapping: fitting 12 equal chromatic semitones onto a 7+5 diatonic-chromatic hybrid layout with asymmetric spacing. This creates transpositional non-invariance:

• C major scale: all white keys in a horizontal line
• F# major scale: five black keys and two white keys at different depths
• C major 7th chord (C-E-G-B): four white keys at uniform depth
• C# major 7th (C#-F-G#-C): alternating between elevated black keys and recessed white keys

Cognitive Cost

• 6-12 months of daily practice needed for basic fluency across all major scales
• 1-2 years for solid technique in all keys
• Learning C major provides zero motor pattern transfer to F# major
• Professional pianists still process complex keys measurably slower than simple keys
• Musicians must memorize 12 distinct physical patterns for every chord type

The Solution

Core Principle

Preserve everything pianists know while eliminating what they must memorize.

The system maintains the standard 88-key piano keyboard completely unchanged while adding auxiliary controls that provide isomorphic logic for chord selection. Musicians can:

1. Play traditionally (ignoring all augmentations)
2. Use simplified chord selection (auxiliary controls)
3. Mix both approaches seamlessly

How Musicians Actually Think

Contemporary musicians don't think in note names - they think in:

• Functional relationships: I-IV-V, ii-V-I progressions
• Interval patterns: major thirds, perfect fifths
• Chord structures: root + quality + extensions
• Scale degrees: 1-2-3-4-5-6-7 relative to tonic

Our interface matches these mental models.

---

What's New in v2.0

Complete TypeScript Migration

• ~6,000 lines of JavaScript migrated to TypeScript across 23 files
• Zero compilation errors - fully type-safe codebase
• Comprehensive type system with music theory types (Note, Chord, Scale, etc.)
• Path aliases for clean imports (@voicing/, @input/, @audio/, @utils/, @ui/)
• Full JSDoc documentation throughout

New Features

🎵 Chord Progression Player

Play entire chord progressions from text input:

• Simple syntax: C Am F G or Dm7 G7 Cmaj7
• Octave specification: (4) C Am F G (centers voicing on octave 4)
• Slash chords: Cm7/A (custom bass note)
• Double slash notation: Cm7/A//F (custom bass AND top note)
• Supports: Major, Minor, 7th, Maj7, Min7, 9ths, Sus2/Sus4, Diminished, Half-diminished

🌀 Jazz Wormhole Mode (Experimental)

An experimental feature for adventurous musicians that applies non-diatonic chord substitutions using:

• Chromatic mediants
• Parallel chords
• Tritone substitutions
• Modal interchange
• Cluster voicings for smooth voice leading

🔄 Chord Inversions

• Press , (comma) to rotate chord notes downward
• Press . (period) to rotate chord notes upward
• Explore different voicings of the same chord instantly

🎨 Enhanced Visual Feedback

• Color-coded chord tones now include extensions:
  • Root (red), Third (blue), Fifth (green), Seventh (yellow)
  • Ninth, Eleventh, Thirteenth (purple/pink tones)

Modern Development Stack

• Vite for lightning-fast development with HMR
• Vitest for testing
• ESLint + Prettier for code quality
• Node 18+ required

---

Seven Design Principles

1. Maintain Keyboard Primacy with Auxiliary Controls

• Standard 88-key piano keyboard remains fully functional
• Auxiliary controls positioned above/beside keyboard
• Musicians can ignore augmentations entirely
• Preserves compatibility with existing technique, repertoire, pedagogy

2. Think in Root + Quality + Extensions, Not Specific Notes

Interface lets musicians specify:

• Root note (12 chromatic options via circle of fifths)
• Quality (Major 7, Dominant 7, Minor 7, Half-diminished, Diminished)
• Extensions (11th and 13th via keyboard modifiers with automatic compatibility logic)
  • Cmd adds 13th (major/dominant chords only)
  • Ctrl adds 11th (#11 for major/dominant, natural 11 for minor)

The system knows tertian harmony patterns and handles geometric mapping automatically.

3. Enable Functional Progression Building

Scale step progression builders: I, ii, iii, IV, V, vi, vii° buttons that:

• Trigger appropriate chord qualities automatically (I = major 7, ii = minor 7, V = dominant 7)
• Work identically in all 12 keys
• Support mode selection (Ionian, Dorian, Phrygian, Lydian, Mixolydian, Aeolian, Locrian)

Think "I want a ii-V-I in Bb" and press three buttons - the system handles note selection.

4. Voice Leading Optimization

When moving between chords, the system calculates optimal voice leading:

• Retain common tones
• Move other voices minimally
• Prefer contrary motion between bass and upper voices

Supports four voicing styles:

• Close voicing: all notes within octave
• Drop-2 voicing: drop second voice from top
• Drop-2-4 voicing: drop both second and fourth voices from top (wider jazz voicing)
• Jazz/Guide voicing: rootless voicings emphasizing 3rd and 7th

5. Visual Feedback and Learning Reinforcement

LED-capable keyboard provides visual feedback:

• Root notes (red)
• Thirds (blue)
• Fifths (green)
• Sevenths (yellow)
• Extensions (11th/13th) (purple)

Multiple display modes:

1. Show only chord tones
2. Show full scale
3. Show available tensions
4. Show voice leading arrows between chords

6. Chromatic Escape Hatch Always Available

Despite all simplifications, musicians retain unrestricted chromatic access:

• Secondary dominants
• Modal interchange borrowing
• Chromatic passing tones
• Unexpected color notes

The system never prevents playing any pitch. Essential for sophisticated harmony in jazz and contemporary music.

7. Transposition and Key-Independent Operation

All patterns work identically in all keys:

• Program a ii-V-I in C major
• Change key selector to G♭
• Same button presses work instantly
• Transposition reduces to single-button key change

Implementation Architecture

Minimum Viable Interface

Physical Buttons:

• 12 root buttons (circle of fifths arrangement)
• 7 scale mode buttons (Major, Minor, Dorian, Mixolydian, etc.)
• 7 scale step buttons (I, ii, iii, IV, V, vi, vii°)
• 4 voicing style buttons (Close, Drop-2, Drop-2-4, Jazz/Guide)

Keyboard Modifiers:

• Shift: Octave shift (+8va)
• Cmd: Add 13th extension
• Ctrl: Add 11th extension (#11 for major, natural 11 for minor)
• Space: Chord mode (trigger contextual chords from scale degrees)

Physical form factor: 12" x 4" x 2" console mountable above any piano.

Voice Leading System

The system automatically calculates optimal voice leading between chords:

• Retains common tones when possible
• Moves other voices with minimal finger movement
• Prefers contrary motion between bass and upper voices
• Supports multiple voicing styles for different musical contexts

Tertian Harmony Patterns (System Knowledge)

Five Main Seventh Chord Types

1. Major 7th: M3+m3+M3 (intervals: 0, 4, 7, 11)
2. Dominant 7th: M3+m3+m3 (intervals: 0, 4, 7, 10)
3. Minor 7th: m3+M3+m3 (intervals: 0, 3, 7, 10)
4. Half-diminished 7th: m3+m3+M3 (intervals: 0, 3, 6, 10)
5. Fully diminished 7th: m3+m3+m3 (intervals: 0, 3, 6, 9)

Extension Compatibility Rules

The system automatically enforces music theory compatibility:

• Major & Dominant chords: Can take 11th (#11) and 13th
• Minor chords: Can take 11th (natural) only
• Diminished chords: Extensions not typically used

These patterns are identical in all 12 keys - piano's physical layout obscures this invariance.

Learning from Commercial Products

Successes

• Expressive E Osmose ($1,799): Maintains traditional keys, adds 3D control. Pre-orders sold out. Lesson: evolutionary beats revolutionary.
• LinnStrument: 5,300+ units since 2014, sustained profitability. Lesson: sustainable niche beats hypergrowth.
• Launchpad Pro MK3: Only mainstream grid controller with chord mode. Lesson: simple features users want beat complex features designers think are cool.
• Scaler 2 ($59): Strong professional adoption by augmenting workflow. Lesson: suggest and facilitate, don't automate and restrict.

Failures

• ROLI: £101M raised, £34.1M losses, bankruptcy 2021. Revolutionary continuous surface intimidated keyboard players. Over-invested in hypergrowth.
• Continuous surfaces: Require complete retraining, alienate existing pianists.
• Scale-lock modes: Remove control that advanced players need.

Key Insights

1. Preserve existing skills: Musicians have years invested in piano technique
2. Provide escape hatches: Never remove chromatic access or full control
3. Use open standards: MIDI compatibility ensures longevity
4. Target realistic markets: Educators, jazz pianists, church musicians, composition students
5. Build sustainably: $500-$800 prosumer price point, not venture-backed hypergrowth

Implementation Roadmap

Phase 1 - MIDI Controller

• Physical control console with 27+ buttons
• Circle of fifths layout for key selection
• Color-coded button groups for intuitive operation
• Small display for chord/voicing information
• MIDI output for maximum compatibility

Phase 2 - LED Integration

• LED lighting for piano keyboard
• Color-coded chord tone highlighting
• Multiple display modes (chord tones, full scale, tensions)
• Real-time visual feedback

Phase 3 - Preset System

• Common progression storage (I-V-vi-IV, ii-V-I, 12-bar blues)
• User-programmable custom progressions
• Quick recall for frequently used patterns

Phase 4 - Advanced Features

• Voice leading arrow visualization
• Mode selection (Ionian, Dorian, Phrygian, etc.)
• Chromatic overlay mode indicator
• Transpose function
• Computer software for configuration

Targeted Use Cases

Jazz Pianists

• Quick ii-V-I progression practice in all keys
• Optimal voice leading for comping
• Exploration of chord extensions (11th, 13th) with automatic compatibility
• Transposition of standards

Music Educators

• Visual demonstration of harmonic theory
• Teaching voice leading principles
• Key-independent pattern learning
• Immediate feedback for students

Church Musicians

• Quick chord progression building for hymns
• Transposition for different vocalists
• Professional-sounding voicings instantly
• Minimal practice time required

Composition Students

• Exploration of harmonic possibilities
• Voice leading experimentation
• Progression prototyping
• Theory made tangible

Research Foundation

This project synthesizes research from:

• Music theory: Tertian harmony, voice leading, functional harmony
• Cognitive science: Expert vs. novice processing, chunking, motor learning
• Pedagogy: Scale degree vs. interval thinking, pattern recognition
• Alternative instruments: Isomorphic keyboards, Jankó, Wicki-Hayden, Harmonic Table
• Commercial products: Osmose, LinnStrument, ROLI, Launchpad Pro, Scaler 2
• Piano design: 300-year-old layout, path dependency, network effects

Why This Approach Works

Addresses Root Cause

The cognitive problem isn't memorization capacity - it's geometric mapping. Musicians understand that all major 7th chords have the same structure; the challenge is that this structure maps to different physical patterns depending on root note.

Provides Abstraction Layer

Instead of changing the physical layout (isomorphic keyboards), we add an abstraction layer that thinks isomorphically while maintaining the familiar interface.

Enables Progressive Learning

• Day 1: Play traditional repertoire normally
• Week 1: Try simple I-IV-V progressions with scale steps
• Month 1: Explore voice leading optimization
• Year 1: Master transposition and extensions
• Year 5+: Use chromatic overlay for sophisticated harmony

Grows with the Player

Beginners benefit from simplified chord selection. Experts benefit from voice leading optimization and visual feedback. Advanced players use chromatic escape hatch for color notes and modal interchange.

Target Specifications

Price Point

$500-$800: Prosumer sweet spot

• Less than Osmose ($1,799)
• More than Launchpad Pro ($449)
• Justified by piano-specific integration and sophistication

Form Factor Options

1. Console unit above keyboard (like organ stops)
2. Side panel to left of keyboard
3. Touch strip along fallboard/music desk
4. iPad/tablet app mounted on music desk

Console provides most physical buttons and best visibility for initial version.

Market Size

• Music educators: 10,000s potential
• Jazz pianists: 100,000s potential
• Church musicians: 100,000s potential
• Composition students: 10,000s potential

Aggregate: viable niche market without requiring mainstream piano replacement.

Anti-Patterns to Avoid

Based on commercial failures:

• ❌ Never remove chromatic access (auto-accompaniment keyboard limitation)
• ❌ Never require complete retraining (continuous surface failure)
• ❌ Never build proprietary lock-in (ROLI abandonware concerns)
• ❌ Never design for hypergrowth (venture capital incompatibility)
• ❌ Never sacrifice build quality (cheap MIDI controller complaints)
• ❌ Never ignore user feedback (Push chord mode requests ignored 6+ years)

Instead:

• ✅ Maintain backward compatibility
• ✅ Support incremental adoption
• ✅ Use open standards (MIDI)
• ✅ Build sustainably
• ✅ Prioritize reliability
• ✅ Listen to musicians' actual needs

Project Philosophy

Make theory visible and memorization obsolete.

Musicians don't need a new keyboard - they need an intelligent co-pilot that knows music theory so they can focus on music making. The tertian harmony patterns are systematic and key-independent; the voice leading principles are mathematical and predictable; the functional progressions are universal across styles.

All of this knowledge can be encoded in 27 buttons and supporting logic, turning the piano from a difficult-to-master mechanical device into an intuitive musical thought interface that grows with the player from beginner to expert.

Getting Started

Installation

# Clone the repository
git clone <repository-url>
cd best-instrument

# Install dependencies (requires Node 18+)
npm install

Running the Development Server

# Start the development server with hot module reloading
npm run dev

# Server will start at http://localhost:3001
# Open in your browser and start playing!

What to Try

Basic Chord Selection

1. Select a key: Click root buttons (C, G, D, etc.)
2. Choose quality: Click chord quality buttons (Maj7, Min7, Dom7)
3. Add extensions: Hold Cmd for 13th, Ctrl for 11th
4. Watch the keyboard: See chord tones highlighted in color

Scale Degree Progressions

1. Set your key: Click a root note (e.g., C)
2. Choose scale: Select Ionian (Major) or other modes
3. Build progressions: Click I → IV → V → I or ii → V → I
4. Observe voice leading: Watch how the system minimizes hand movement

Voicing Styles

1. Try different voicings: Close, Drop-2, Drop-2-4, Guide
2. Notice how voice leading changes with each style
3. Enable Smart Voicing for automatic optimization

Chord Progression Player

1. Enter a progression: (4) C Am F G or Dm7 G7 Cmaj7
2. Press Play or hit Enter
3. Watch and listen as the system plays through your progression
4. Try slash chords: Cm7/A or double slash: Cm7/A//F

Experimental Features

1. Jazz Wormhole Mode: Click the JAZZ button for harmonic surprises
2. Inversions: Use , and . to rotate chord notes
3. Pedal Points: Click Pedal button, then press a key to set sustain

Keyboard Shortcuts

Scale Degrees & Notes

• 1-7: Play diatonic scale degrees
• 8-9-0-=: Upper octave scale degrees (8-14)
• Space + 1-7: Trigger contextual chords (I, ii, iii, IV, V, vi, vii°)
• Piano keys work as expected for direct note playing

Modifiers

• Shift: Octave shift (+8va)
• Cmd: Add 13th extension
• Ctrl: Add 11th extension
• , (comma): Rotate chord downward
• . (period): Rotate chord upward

Development Commands

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Run tests
npm test

# Run tests with UI
npm run test:ui

# Run tests with coverage
npm run test:coverage

# Type check without emitting
npm run typecheck

# Format code
npm run format

# Lint code
npm run lint

Development

Project Structure

src/
├── types/           # TypeScript type definitions
│   ├── music.ts     # Music theory types (Note, Chord, Scale, etc.)
│   ├── state.ts     # Application state types
│   └── index.ts     # Type exports
├── audio/           # Web Audio API integration
│   ├── audioContext.ts
│   └── playback.ts
├── input/           # Keyboard and user input handling
│   ├── constants.ts
│   ├── keyboardInput.ts
│   ├── keyboardMap.ts
│   ├── scaleDegreePlayer.ts
│   ├── chordTrigger.ts
│   └── notePlayback.ts
├── voicing/         # Chord voicing and voice leading
│   ├── constants.ts
│   ├── state.ts
│   ├── generators.ts
│   ├── optimizer.ts
│   ├── updater.ts
│   └── wormhole.ts  # Experimental chord substitution
├── ui/              # User interface components
│   ├── display.ts
│   ├── eventHandlers.ts
│   ├── keyboard.ts
│   ├── scaleStepCarousel.ts
│   └── chordProgressionPlayer.ts
├── utils/           # Utility functions
│   └── helpers.ts
├── analysis/        # Key detection
│   └── keyDetection.js
├── looper/          # Looping functionality
│   └── looper.js
└── init.ts          # Application entry point

TypeScript Features

• Strict type checking for all music theory operations
• Path aliases for clean imports (configured in tsconfig.json)
• Full IDE support with autocomplete and inline documentation
• Compile-time error detection prevents runtime bugs
• JSDoc comments provide context-aware help

Testing

The project uses Vitest for testing. Tests will be added incrementally as features stabilize.

# Run tests in watch mode
npm test

# Run tests once
npm run test:run

# View test UI
npm run test:ui

Code Quality

The project uses ESLint and Prettier to maintain code quality:

# Check for linting errors
npm run lint

# Auto-format all code
npm run format

Next Steps

See implementation phases above for hardware development roadmap.

---

This project exists at the intersection of music theory, cognitive science, interface design, and sustainable innovation. It proves that you don't need to reinvent the piano - you need to augment it intelligently.