MACCA Technical Audit

What MACCA Is

MACCA (Make All Composers Compliant Again) is a browser-based chord progression tool built with Next.js 16 and React 19. It enables musicians to:

• Explore diatonic chords across all seven modes
• Build custom chord progressions with a visual timeline
• Hear voice-led voicings via Web Audio API synthesis
• Export progressions to MIDI files
• Learn music theory through pedagogical tooltips

The application uniquely focuses on guitar voicings across three-string sets, making it particularly valuable for guitarists exploring partial chord voicings and voice leading.

Current State Assessment

Overall Grade: B- (Solid foundation, significant room for improvement)

Key Strengths

1. Voice Leading Algorithm: The bestVoicingForChord() function implements intelligent voice leading by minimizing movement between chord changes—a genuinely useful feature missing from many competitors.
2. Three-String Voicing Focus: Unique niche targeting partial guitar voicings (E-A-D, A-D-G, D-G-B, G-B-e), valuable for rhythm guitarists and fingerstyle players.
3. Pedagogical Mode: The collapsible panels explaining harmonic functions and interval roles show educational intent—a strong differentiator.
4. Modern Stack: React 19, Next.js 16, Tailwind 4, and proper TypeScript usage provide a solid foundation.
5. Zero Dependencies for Core Features: Music theory and audio are implemented without external libraries, ensuring small bundle size and full control.

Key Weaknesses

1. Monolithic Architecture: 1,500+ lines in a single page.tsx file creates maintainability challenges.
2. Limited Audio Quality: Basic oscillator synthesis sounds artificial compared to sampled instruments.
3. MIDI Export is Minimal: No track names, no velocity variation, no sustain pedal, no time signature metadata.
4. No State Persistence: Refreshing the page loses all work. No URL sharing, no cloud save.
5. Guitar-Centric Limitation: Piano voicings, bass lines, and other instruments are unsupported.

Strategic Recommendations

1. Immediate Priority: Refactor to component architecture and add browser localStorage persistence.
2. Short-term: Integrate Tone.js for production-quality audio and enhance MIDI export.
3. Medium-term: Add piano roll visualization, URL-shareable progressions, and user accounts.
4. Long-term: AI-powered chord suggestions, collaborative editing, and DAW plugin export.

Code Structure Evaluation

The entire application lives in a single 1,500-line app/page.tsx file containing:

• Music theory utilities (scales, chords, voicings)
• Audio engine (Web Audio API synthesis)
• MIDI export functionality
• UI components (timeline, chord cards, controls)
• State management (useState/useMemo)
• Drag-and-drop logic

macca/
├── app/
│   ├── page.tsx        # 1,500 lines - EVERYTHING
│   ├── layout.tsx      # Metadata + fonts
│   └── globals.css     # Tailwind config
├── components/
│   └── ui/             # 57 shadcn/ui components (mostly unused)
└── hooks/
    ├── use-toast.ts
    └── use-mobile.ts

Assessment: The codebase violates separation of concerns. While acceptable for a prototype, this structure inhibits testing, reusability, and team collaboration.

Recommended Decomposition

macca/
├── lib/
│   ├── music-theory/
│   │   ├── scales.ts           # Scale definitions & utilities
│   │   ├── chords.ts           # Chord building & naming
│   │   ├── voicings.ts         # Voice leading algorithms
│   │   └── intervals.ts        # PC math, enharmonics
│   ├── audio/
│   │   ├── engine.ts           # AudioContext management
│   │   ├── synth.ts            # Oscillator synthesis
│   │   └── presets.ts          # Sound configurations
│   └── midi/
│       ├── export.ts           # MIDI file generation
│       └── constants.ts        # MIDI spec values
├── components/
│   ├── chord-card.tsx
│   ├── timeline.tsx
│   ├── timeline-item.tsx
│   ├── progression-bank.tsx
│   ├── controls-panel.tsx
│   └── pedagogy-panels.tsx
├── hooks/
│   ├── use-audio.ts
│   ├── use-timeline.ts
│   └── use-scale.ts
└── app/
    └── page.tsx                 # ~100 lines, composition only

Scale System Accuracy

The seven modes are correctly implemented:

const SCALES: Record<string, number[]> = {
  "Major (Ionian)": [0, 2, 4, 5, 7, 9, 11],
  "Natural Minor (Aeolian)": [0, 2, 3, 5, 7, 8, 10],
  Dorian: [0, 2, 3, 5, 7, 9, 10],
  Phrygian: [0, 1, 3, 5, 7, 8, 10],
  Lydian: [0, 2, 4, 6, 7, 9, 11],
  Mixolydian: [0, 2, 4, 5, 7, 9, 10],
  Locrian: [0, 1, 3, 5, 6, 8, 10],
}

Verdict: ✅ Correct. All semitone patterns match standard music theory.

Missing Scales (Recommended Additions)

Voice Leading Algorithm Assessment

The voice leading implementation is genuinely well-designed:

function bestVoicingForChord(full, type, openPcs, prev?) {
  const shell = selectVoicingPcs(full, type)
  const candidates = [0, 1, 2].map(inv => 
    findVoicingOnTop3Strings(shell, inv, openPcs)
  )
  if (!prev) return candidates[0]
  
  const cost = (f) => {
    const dist = /* sum of fret movements from prev */
    const spread = /* range of frets in voicing */
    return dist + spread * 0.2
  }
  return candidates.sort((a, b) => cost(a) - cost(b))[0]
}

Verdict: ✅ This is solid. The algorithm minimizes finger movement while penalizing wide spreads. The 0.2 spread weight is reasonable.

Current Implementation Review

The MIDI export function generates a basic Type 0 (single-track) MIDI file. Current features:

• ✅ Correct tempo meta event
• ✅ Note on/off events
• ✅ Variable-length quantity encoding
• ✅ End of track marker

Missing Features vs MIDI 1.0 Spec

Recommended Library Migration

Consider replacing the DIY implementation with @tonejs/midi:

import { Midi } from '@tonejs/midi'

function exportProgression(timeline, bpm) {
  const midi = new Midi()
  const track = midi.addTrack()
  
  track.name = "MACCA Progression"
  midi.header.setTempo(bpm)
  midi.header.timeSignatures.push({ ticks: 0, timeSignature: [4, 4] })
  
  let time = 0
  for (const chord of timeline) {
    for (const note of chord.notes) {
      track.addNote({
        midi: note,
        time,
        duration: 60 / bpm,
        velocity: 0.7 + Math.random() * 0.2  // Humanization
      })
    }
    time += 60 / bpm
  }
  
  return midi.toArray()
}

Current Implementation

The audio system uses raw Web Audio API with basic oscillators:

• Waveforms: triangle, sine, sawtooth, square
• Simple ADSR envelope (attack → sustain → release)
• High-pass filter at 120Hz
• No reverb, no effects, no samples

Recommended: Tone.js + Salamander Piano

import * as Tone from 'tone'

const sampler = new Tone.Sampler({
  urls: {
    C4: "C4.mp3",
    "D#4": "Ds4.mp3",
    "F#4": "Fs4.mp3",
    A4: "A4.mp3",
  },
  baseUrl: "https://tonejs.github.io/audio/salamander/",
}).toDestination()

const reverb = new Tone.Reverb({ decay: 1.5, wet: 0.3 })
sampler.connect(reverb)

Benefits: Real piano samples, automatic polyphony management, built-in effects.

Accessibility Assessment

Competitor Comparison (UX)

Missing Features vs Industry Standard

Essential (expected by all users):

Important (expected by serious users):

User Journey Gap

The current workflow is one-way. Users can't:

• Save work and return later
• Share a progression link with a collaborator
• Import MIDI back into MACCA for editing

Priority 1: Critical Improvements (4-6 weeks)

• P1.1 Architecture Refactor: Decompose page.tsx into modular components, extract music theory into /lib/
• P1.2 State Persistence: LocalStorage autosave, URL hash state for sharing
• P1.3 MIDI Export Enhancement: Track names, time signature, velocity humanization
• P1.4 Audio Quality Boost: Replace oscillators with Tone.js + Salamander Piano samples

Priority 2: Major Features (8-12 weeks)

• P2.1 Piano Roll Visualization: Horizontal piano roll showing current timeline
• P2.2 Extended Scale Library: Harmonic minor, melodic minor, pentatonic, blues
• P2.3 Chord Symbol Display: Proper symbols (Cmaj7, Dm7), slash chords, Nashville numbers
• P2.4 User Accounts: Cloud save/load, project sharing
• P2.5 Internationalization: English (primary), Swedish, Spanish

Priority 3: Polish and Extras (12+ weeks)

• P3.1 AI-Powered Features: "Suggest next chord" using markov chains
• P3.2 Collaborative Editing: Real-time multiplayer (Yjs/Liveblocks)
• P3.3 DAW Integration: Ableton Link, plugin wrapper (VST/AU)
• P3.4 Advanced Audio: Multiple tracks, drum patterns, bass auto-generation

Suggested Tech Stack Changes

Hookpad (Hooktheory)

Price: $5/month or $150 lifetime

Strengths: Industry-leading theory integration, pop song database with chord analysis, beautiful UI

Weaknesses: No MIDI export without paid tier, web-only

MACCA Opportunity: Free + open-source positioning, guitar-specific voicings

ChordChord

Price: Free with ads, $48/year premium

Strengths: AI chord suggestions, large progression library

Weaknesses: Generic voicings, intrusive ads

MACCA Opportunity: Ad-free, guitar-first design

Scaler 2 (Plugin Boutique)

Price: $69 one-time

Strengths: DAW plugin, massive chord/scale library, detect chords from audio

Weaknesses: Desktop-only, paid software

MACCA Opportunity: Free, web-based, beginner-friendly

MACCA's Unique Positioning

"The free, open-source chord progression tool built specifically for guitarists. Voice-led voicings, guitar tab notation, and music theory education—all in your browser."

Differentiation pillars:

1. Guitar-first: Three-string voicings, tab notation, string set selection
2. Educational: Harmonic function labels, interval role colors, theory explanations
3. Free & open: No ads, no subscription, MIT license
4. Focused: Does one thing well (chords), doesn't try to be a DAW
5. Modern: Responsive, fast, clean UI