JamBuddy

Hear the jam, learn the jam. JamBuddy listens through your microphone, figures out the key and chords you're playing in real time, then shows you how to play over them — and helps you level up while you do it.

It started as a live key/chord detector (you may know it as WhatTheFlat). It's growing into an open, contributable learning platform for the player who can already survive a jam and wants to make it better.

---

The idea: detect → guide → level up

1. Detect. Point your mic at a guitar, piano, or a whole band. JamBuddy identifies the key and the chords as you play, finds the repeating loop, and reads it back in Roman numerals (ii–V–I, I–V–vi–IV).

2. Guide. Once it knows your loop, the Roadmap Jam Guide lays it out as an improv highway synced to what you're playing: guide tones (the 3rds and 7ths that carry the harmony), voice-leading rails showing how each chord resolves into the next, the solo scale to blow over each station, and the chord voicings to grab — all in your detected key, with a playhead tracking where the loop is.

3. Level up. Style packs turn the same ii–V–I into jazz vs bossa vs funk — genuinely different voicings, rhythms, and improv advice — so you don't just play the changes, you learn the language. This is the on-ramp to the wider Learn direction (drills and detection-powered feedback) described in GOAL.md.

---

What works today vs. what's in progress

This is an honest snapshot — it's an active project.

Working today

• Real-time key detection with top-3 candidate chips (click to lock) — works for guitar and piano.
• Real-time chord detection from live audio, with chord history and repeating-progression detection.
• Roadmap Jam Guide panel: matches your detected loop to a style progression and renders guide tones, voice-leading rails, solo-scale labels, and chord-voicing thumbnails synced to the loop position.
• 8 guitar style packs in the knowledgebase — jazz, blues, rock, bossa nova, funk, reggae, country, and R&B (gospel landing next).
• Fretboard and piano visualisers that colour chord tones, pentatonic, and scale notes.
• Chromatic tuner and a loop station for capturing and replaying phrases.
• Fully offline — all audio and detection run locally in the desktop window; no server, no network calls.

In progress

• Piano and bass style packs (guitar is the first instrument rolled out).
• The Progression Builder — lay out and rearrange your own progression by hand (GOAL §G3).
• Detection-powered drills — practice exercises and feedback that use the fact that the app can actually hear you (GOAL Part 2).

---

What it looks like

(Screenshot coming — the Roadmap panel mid-jam.)

---

Quickstart

You'll need Node.js (18+) and a microphone.

git clone https://github.com/whattheflat/whattheflat.git
cd whattheflat
npm install

# Desktop app (Vite dev server + Electron window, hot reload)
npm run electron:dev

Prefer the browser? Run the renderer on its own (no Electron shell):

npm run dev    # then open http://localhost:5173

To see the magic: grant microphone permission when prompted, then play a recognized loop — a ii–V–I or a 12-bar blues are the easiest ways to light up the Roadmap Jam Guide. JamBuddy needs to hear the loop repeat a couple of times to lock the key and match the progression.

Building installers

npm run electron:build:win     # Windows NSIS installer  → release/
npm run electron:build:mac     # macOS DMG               → release/
npm run electron:build:linux   # Linux AppImage          → release/

---

Contributing — add a style without deep coding

The style packs are data, not code. If you're a musician who knows how a style is voiced and played, you can add one by filling in a structured data file — no audio or detection internals required.

• The data contract lives in src/data/kb/SCHEMA.md: progressions as key-agnostic scale degrees, plus 2+ idiomatic "ways to play" each (voicings, comping, improv). One entry renders in all 12 keys.
• An assisted path is available: the /kb-expand workflow researches, drafts, and validates one style cell at a time, so you can start from a scaffold rather than a blank file.
• Every contribution passes a validator quality gate (node scripts/validate-kb.mjs) that mechanically checks each voicing actually contains the chord's tones — that's the bar that keeps the knowledgebase trustworthy.

A full step-by-step CONTRIBUTING.md guide is coming (tracked as task H-02). Until then, SCHEMA.md is the source of truth, and the jazz pack is the gold-standard example to imitate.

---

How it's built — the ensemble

JamBuddy is built by a six-agent team (Maestro, Professor, Luthier, Muse, Critic, Herald) that collaborates entirely through files — a shared ledger and the repo — conducted by one scheduled loop. If you want to understand how the project plans and ships work, start in docs/agents/:

• ROSTER.md — the six agents and their domains.
• PROTOCOL.md — how they collaborate (task locking, review gate, scheduling).
• LEDGER.md — the live task board.

The product north star and full roadmap are in GOAL.md.

---

Tech & how detection works

App shell	Electron (window host only — all logic runs in the renderer)
UI	React, Tailwind CSS, Vite
Audio	Web Audio API, Pitchy (McLeod pitch detection)
Music theory	Custom JS — Krumhansl-Schmuckler key detection, harmonic-summation chroma chord matching

Two audio pipelines run in parallel: a fast pitch path (4096-sample FFT, McLeod autocorrelation) feeds Krumhansl-Schmuckler key detection over a voting window; a higher-resolution chord path (16384-sample FFT, ~2.7 Hz/bin) extracts a harmonic-summation chroma and matches it against chord templates. Architecture details are in CLAUDE.md.

Note on modes: Krumhansl-Schmuckler distinguishes major vs. minor but not modes — Dorian and natural minor look the same to it. JamBuddy detects the tonal centre, and you pick the mode (the dropdown offers Dorian, Mixolydian, etc.). By design.

---

License

No license file is set yet. Until one is added, all rights are reserved by the authors — please open an issue before reusing the code.