From 9768fc2865db72c0fe4b470c81872c7f5fd97cb4 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 12 Sep 2026 13:56:43 +0000 Subject: [PATCH] Fix root README's role, refresh Generator README for recent additions The root README's "Features" section claimed keyboard/guitar/staff views, WebMIDI, and print support were shared between both tools - verified against the Finder's actual code (no matches for guitar/staff/keyboard-view markup, no WebMIDI, no print CSS) and its own README: none of that is true, they're Generator-only. Replaced with an accurate "What They Share" section and gave each project blurb above it a more specific summary, so the page does its actual job of routing a visitor to the right tool instead of half-describing one of them under a shared banner. Also fixed "no frameworks, no dependencies" in Technology, which stopped being true the day JSZip and WebMidi got vendored into the repo. The Generator's README hadn't caught up with this session's work: no mention of the bulk-download pack anywhere, the MPC-naming bullet still described the pre-fix behavior, and Under the Hood didn't know its own dependencies were vendored or that the pack is CI-built rather than committed. Added a section for the pack, refreshed the naming and dependency bullets, noted the CI theory audit, and listed the two new modules and the tools/vendor directories that didn't exist when this file was last touched. While verifying the "173 progressions / 34 scales / 22 genres" claims against the actual source data (all confirmed accurate), found and fixed a pre-existing internal inconsistency unrelated to this session's work: the Quick Start section said 133 progressions and 4 variants where the rest of the document says 173 and five, and one bullet said 60+ genre-intelligent progressions against 100+ everywhere else (actual count is 99, confirmed from the palettePriorities data) - converged all of it on the verified numbers. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01EwQCigYZxdGBW3kPWnMMgF --- AkaiMPCChordProgressionGenerator/README.md | 30 ++++++++++--- README.md | 51 ++++++++-------------- 2 files changed, 43 insertions(+), 38 deletions(-) diff --git a/AkaiMPCChordProgressionGenerator/README.md b/AkaiMPCChordProgressionGenerator/README.md index b4dcc7b..c995c42 100644 --- a/AkaiMPCChordProgressionGenerator/README.md +++ b/AkaiMPCChordProgressionGenerator/README.md @@ -39,6 +39,15 @@ Generate a progression, switch to piano or guitar view, and **print chord sheets While the [MPC Chord Progression Finder](https://github.com/liotier/AkaiMPC/blob/main/AkaiMPCChordProgressionFinder/README.md) helps you identify and recreate chord progressions from existing music, this Generator takes the opposite approach: **it creates new progressions from scratch based on music theory principles**. +## Prefer a Pre-Built Library? + +Generating on demand is the point of this tool, but not everyone wants to click through it hundreds of times to build a collection. The entire catalogue - every progression this generator can produce, across every genre, scale, and voicing variant - is built by CI and sitting there as a straight download, no interaction required: + +- **`.progression` pack** - every progression, every style variant, as ready-to-load MPC files (key of C - Pad Perform transposes to any key on import) +- **MIDI pack** - the same catalogue as Standard MIDI Files, already rendered in all twelve keys + +Grab either from the download links under the generator. + ## For Crate Diggers and Beat Makers ### Chord Matcher: Bridge Your Samples to Theory @@ -99,6 +108,8 @@ The generator seamlessly incorporates: - **Neapolitan & Augmented Sixths** - Classical drama when you need it - **Tritone Substitutions** - Jazz reharmonization at the click of a button +Every one of these is checked against the full generated catalogue, not just spot-checked: secondary-dominant numerals, augmented-sixth spellings, and borrowed-chord roots are audited in CI so a plausible-looking chord that resolves to the wrong notes gets caught before it ships. + ### Battle-Tested Progression Palettes 173 progression palettes across 22 genres covering every style. **100+ progressions feature genre-specific palette intelligence** that prioritizes musically authentic chord voicings: - **Pop/Rock**: I-V-vi-IV (the "four chord song"), vi-IV-I-V (pop-punk anthem), classic rock patterns @@ -124,7 +135,7 @@ The fourth row isn't just filler—it's dynamically calculated based on sophisti - **Harmonic Function Analysis** - Identifies what your progression needs: missing tonic resolution? Need more tension? The algorithm knows. - **Voice Leading Optimization** - Selects chords that create the smoothest transitions with minimal finger movement - **Context-Aware Suggestions** - Adds borrowed chords, secondary dominants, and modal interchange based on your selected style -- **Genre Intelligence with Palette Priorities** - 60+ progressions use a sophisticated 3-tier weighting system (preferred, allowed, avoided) to prioritize genre-authentic chord voicings. Blues gets dom7, Folk gets simple triads, Gospel gets extended harmony—automatically. +- **Genre Intelligence with Palette Priorities** - 100+ progressions use a sophisticated 3-tier weighting system (preferred, allowed, avoided) to prioritize genre-authentic chord voicings. Blues gets dom7, Folk gets simple triads, Gospel gets extended harmony—automatically. ## Production-Ready Features @@ -133,7 +144,7 @@ The fourth row isn't just filler—it's dynamically calculated based on sophisti - MPC One, MPC Live, MPC X, MPC Key 61 - MPC Software, MPC Beats - Proper MIDI mapping with velocity sensitivity preserved -- Chord names follow Akai's exact naming conventions +- Names built specifically for Pad Perform's menu system - a clean category heading and a clean entry every time, regardless of how exotic the progression or scale name gets - Optimized pad layouts for finger drumming ### Multi-Instrument Visualization & Export @@ -155,13 +166,14 @@ The fourth row isn't just filler—it's dynamically calculated based on sophisti ### Zero Friction Workflow - **No Installation** - Works in any modern browser - **No Server Dependency** - Runs completely offline after first load +- **Reliable Exports** - JSZip and WebMIDI are bundled with the app rather than loaded from a CDN, so exporting works from your very first visit even behind a restrictive network - **Mobile Ready** - Use on your phone or tablet at rehearsal, on stage, or in the studio - **Privacy First** - All processing happens in your browser, nothing leaves your device ## Quick Start Guide 1. **Choose Your Workflow** - - **Progression Palette Mode** - Select a key and browse 133 progression palettes organized by genre. 60+ progressions feature smart palette priorities for genre-authentic voicings. Generate 4 voicing variants instantly. + - **Progression Palette Mode** - Select a key and browse 173 progression palettes organized by genre. 100+ progressions feature smart palette priorities for genre-authentic voicings. Generates up to five voicing variants instantly. - **Scale Mode** - Select a key + mode/scale to explore all available chords from that scale. Perfect for learning exotic scales and modal exploration. - **Chord Matcher** (optional) - Input chords from your sample to filter compatible keys and modes for both workflows. @@ -181,15 +193,16 @@ Together, they provide a complete harmonic toolkit for musicians and producers. ## Under the Hood -- Pure HTML5/CSS3/JavaScript ES6 modules - no frameworks, no bloat -- WebMIDI API (via webmidi.js) for cross-browser MIDI output support +- Pure HTML5/CSS3/JavaScript ES6 modules - no framework +- WebMIDI API (via vendored webmidi.js) for cross-browser MIDI output support - Web Audio API for low-latency chord playback fallback - Voice leading optimization using Hungarian algorithm for optimal note assignment - Custom harmonic analysis engine with parallel major Roman numeral analysis - Responsive CSS Grid that mirrors the MPC's 4×4 pad layout - SVG-based staff notation rendering with intelligent octave transposition - Viewport-aware keyboard event handling for seamless multi-progression browsing -- JSZip for seamless multi-file exports +- JSZip (vendored) for seamless multi-file exports, both libraries bundled with the app rather than loaded from a CDN +- The full `.progression` and MIDI packs are generated by CI (`tools/build-pack.mjs`), not committed to the repo or built in the browser - the download links just point at the static output ## Contributing @@ -206,6 +219,8 @@ This project was originally distributed as a single self-contained HTML file for - `styles.css` — extracted stylesheet - `app.js` — main application orchestration - `modules/musicTheory.js` — core music theory engine (scales, chords, voice leading) +- `modules/generation.js` — variant generation, shared by the app and `tools/build-pack.mjs` so both produce identical output +- `modules/mpcNaming.js` — the naming scheme that keeps Pad Perform's menu display correct - `modules/audio.js` — Web Audio synthesis and WebMIDI output - `modules/constants.js` — tuning, timing, layout and validation constants - `modules/guitarChords.js` — guitar chord library @@ -215,6 +230,9 @@ This project was originally distributed as a single self-contained HTML file for - `modules/i18n.js` — internationalization system - `locales/*.json` — translation files (en, fr, es, de, pt, it) - `service-worker.js` — offline caching +- `vendor/` — JSZip and WebMidi.js, vendored rather than CDN-loaded (see `vendor/NOTICE.md`) +- `tools/build-pack.mjs` — builds the bulk-download `.progression`/MIDI packs; runs in CI on every deploy, not committed to the repo +- `tools/audit-theory.mjs` — the CI theory audit described above Deployment remains the same: host these files on any static file host (GitHub Pages, Netlify, etc.). Modular structure improves readability, caching, and makes incremental development and testing easier. diff --git a/README.md b/README.md index bf35946..450ecec 100644 --- a/README.md +++ b/README.md @@ -9,26 +9,24 @@ This repository contains two complementary web applications for working with cho ## Projects ### 🎹 [Chord Progression Generator](https://liotier.github.io/AkaiMPC/AkaiMPCChordProgressionGenerator/) -Generate musically intelligent custom chord progressions in 4×4 pad layouts for Akai MPC Pad Perform. +Creates new chord progressions from music theory - 173 genre templates or 34 scales/modes, up to five voicing variants each, viewable as MPC pads, piano keyboard, guitar fretboard, or staff notation. **Key Features:** -- 173 progression templates across 22 genres -- 34 scales and modes from common to exotic, with chords derived from each scale +- 173 progression templates across 22 genres, or Scale Mode to explore any of 34 scales chord-by-chord - Five intelligent voicing variants (Smooth, Classic, Jazz, Modal, Experimental) - Voice leading optimization for smooth transitions - Chord Matcher for finding keys from specific chords -- Multi-view support: MPC pads, keyboard, guitar, and staff notation -- Export to .progression files for MPC hardware +- Multi-view support: MPC pads, keyboard, guitar, and staff notation, plus MIDI export +- Export to `.progression` files for MPC hardware, or grab the entire catalogue pre-built as a bulk download [View Documentation →](AkaiMPCChordProgressionGenerator/README.md) ### 🔍 [Chord Progression Finder](https://liotier.github.io/AkaiMPC/AkaiMPCChordProgressionFinder/) -Analyze and explore chord progressions from MPC .progression files. +Analyzes chord progressions from existing MPC `.progression` files - the opposite direction from the Generator: instead of creating new progressions, it identifies what you've already got. **Key Features:** -- Pure interval-based chord analysis -- Automatic key and scale detection -- Roman numeral analysis +- Pure interval-based chord analysis, including inversions - works from the actual notes, not the (possibly wrong) file name +- Automatic key and scale detection, with Roman numeral analysis - Playable progressions detection (ii-V-I, I-V-vi-IV, etc.) - Real-time filtering and export capabilities - Interactive 4×4 MPC pad layout with audio playback @@ -43,27 +41,16 @@ Pre-configured MIDI program files for Roland hardware: Download .xpm files directly from the [MIDI programs directory](https://github.com/liotier/AkaiMPC/tree/main/MIDI%20programs). -## Features +## What They Share -Both chord progression tools share these capabilities: +The Generator and the Finder are separate tools built for opposite directions (create vs. identify), each with its own feature set detailed above and in its own README. What they do share: -### Multi-View Visualization -- **MPC View**: 4x4 pad layout matching Akai MPC hardware -- **Keyboard View**: Piano diagrams showing which keys to press -- **Guitar View**: Chord diagrams with fret positions -- **Staff Notation**: Traditional treble clef notation +- **Zero installation** - runs entirely in the browser, no sign-up +- **Privacy-first** - all processing happens locally, nothing you load or generate leaves your device +- **MPC pad view with audio playback** - both render the familiar 4×4 layout and let you click a pad to hear it +- **Free and open source** - Unlicense, no strings attached -### Audio & Export -- **Web Audio Playback**: Browser-based chord playback -- **MIDI Support**: Connect external MIDI devices -- **Keyboard Control**: Trigger pads with computer keyboard -- **Export Options**: Download .progression files or print diagrams - -### Built for Musicians -- Zero installation required - runs entirely in browser -- Works offline after first load -- Privacy-first - all processing happens locally -- Mobile responsive design +Everything else - keyboard/guitar/staff views, WebMIDI hardware output, offline caching, MIDI export, bulk downloads - is Generator-specific; see its README for the full list. ## Quick Start @@ -74,11 +61,11 @@ Both chord progression tools share these capabilities: ## Technology -- Pure vanilla JavaScript (ES6 modules) -- Web Audio API for synthesis -- WebMIDI API for external devices -- SVG rendering for notation -- No frameworks, no dependencies +- Pure vanilla JavaScript (ES6 modules) - no framework in either tool +- Web Audio API for synthesis (both tools) +- WebMIDI API for external hardware output (Generator only) +- SVG rendering for notation (Generator only) +- The few third-party libraries used (JSZip for bulk exports, WebMidi.js for hardware MIDI) are vendored into the repo rather than loaded from a CDN, so a blocked or unreachable CDN never breaks a first-time visit ## Contributing