harmonic analysis engine

Author: upfusion

CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to `@jmove/generator` will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.3.0] - 2026-07-17
+
+### Added
+
+- **Harmonic analysis engine** (`harmonicAnalysis.ts`) - analyzes chord progressions for key centers, Roman numeral degrees, harmonic function (tonic/predominant/dominant), ii-V-I patterns, cadences, secondary dominants, modulations, and per-chord tension values
+- New types: `ChordAnalysis`, `HarmonicFunction`, `CadenceType`, `HarmonicAnalysisResult`
+- `ChordEvent.analysis` - optional per-chord harmonic annotation populated by `analyzeHarmony()`
+- `BandContext.harmonicAnalysis` - full analysis result available to all generators
+- `analyzeHarmony()` exported from package for standalone use
+- 61 new tests covering key detection, degree assignment, ii-V-I detection, secondary dominants, cadences, tension values, modulation detection, real jazz progressions, key transposition accuracy, and voicing deduplication across styles
+
+### Fixed
+
+- **Key transposition bug** - `detectTemplateKey()` used last-chord heuristic, causing wrong key for templates ending on non-tonic chords (e.g. "Blues in Bb" produced chords in Ab). Replaced with explicit `TEMPLATE_KEY` map covering all ~60 template variants
+- **Duplicate MIDI notes in voicings** - cluster, inversion, open, and root-position voicing builders lacked pitch deduplication after octave clamping. Added `[...new Set()]` to 4 fallback paths
+- **Harsh minor-2nd clusters in Alfa Mist** - minor cluster intervals `[2,3,5,10]` always placed 9th and b3rd one semitone apart. Changed to `[3,5,7,10]` (b3-4-5-b7)
+
+### Changed
+
+- **Ensemble** runs harmonic analysis once before generation; all three generators receive annotated chords with per-chord function, tension, and cadence data
+- **Piano comping** uses `chord.analysis` for ii-V-I awareness instead of ad-hoc `isDominantQuality`/`isResolvingDominant`; altered voicings now trigger on secondary dominants and authentic cadence dominants, not just V-I root motion; anticipation probability modulated by per-chord tension (high-tension dominants anticipate more)
+- **Walking bass** beat 1 selection is harmonic-aware: 85% root on tonic resolution (strong arrival), 55% root on dominant chords (more variety for tension); leading-tone approach on beat 4 of V-I cadences (45% probability) creates strongest resolution motion
+- **Drum fills** placed before authentic cadence resolutions using harmonic analysis, not just form/phrase markers
+- `planMusicalIntents` uses average phrase tension to modulate anticipation and passing chord probabilities per phrase
+
 ## [1.2.9] - 2026-07-16
 
 ### Added

README.md

@@ -38,6 +38,7 @@ Deep technical articles about how JMove and the generator work:
 - **Drum Patterns** - 19 styles with humanization, ghost notes, groove templates based on GrooVAE research. Holdsworth preset features Chad Wackerman-inspired drumming: cross-stick interjections, ghost cascades, linear fills, 11/8-specific patterns
 
 **Intelligence**
+- **Harmonic Analysis Engine** - `analyzeHarmony()` detects key centers, assigns Roman numeral degrees, identifies ii-V-I patterns, cadences, secondary dominants, and modulations. Per-chord tension values drive musical decisions across all generators
 - **Musicality Engine** - phrase-level intelligence: dynamic drops, air gaps, harmonic anticipation, passing chords, conversation dynamics, motif memory. Four parameters (creativity, conversation, airGaps, harmonicFreedom) control musical character
 - **Per-Instrument Complexity** - 3 general sliders drive 13 granular sub-controls via piecewise linear mapping. Manual overrides take precedence over derived values
 - **Full Song Form** - multi-section arrangements with dynamic shaping and section-driven dynamics (intro sparse, shout dense)

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmove/generator",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "description": "Jazz backing track generator — walking bass, piano comping, drum patterns, and style presets for practice sessions",
   "license": "MIT",
   "author": "JMove",

package.json

@@ -3024,11 +3024,23 @@ export function generateDrumPattern(options: DrumPatternOptions = {}): DrumHit[]
     // BandContext: fill probability scales with energy — sparse sections rarely fill
     // In streaming (measures=1), fillHint from ensemble.ts provides lookahead info
     // since the single-measure loop can't look at m+1/m+2.
+    //
+    // Harmonic-aware: boost fill probability before cadence resolutions.
+    // Real drummers set up cadences with fills to mark the arrival.
     let fillPattern: Pattern | null = null;
     const fillHint = options.fillHint;
+    const isBeforeCadence = (() => {
+      const ha = bandCtx?.harmonicAnalysis;
+      if (!ha) return false;
+      // Check if next measure's chord is a cadence resolution (V-I arrival)
+      const nextMeasureIdx = absoluteM + 1;
+      return nextMeasureIdx < ha.chordAnalyses.length
+        && ha.chordAnalyses[nextMeasureIdx].cadenceRole === "resolution"
+        && ha.chordAnalyses[nextMeasureIdx].cadenceType === "authentic";
+    })();
     if (FILL_STYLES.has(style) && (m > 0 || fillHint)) {
       const isBeforeSectionMarker = fillHint === "section" || sectionMarkers.includes(m + 1);
-      const isBeforeFormMarker = fillHint === "phrase" || formMarkers.includes(m + 1);
+      const isBeforeFormMarker = fillHint === "phrase" || formMarkers.includes(m + 1) || isBeforeCadence;
       const isSetupBar = fillHint === "setup" || sectionMarkers.includes(m + 2);
 
       // Energy multiplier: at energy 0.3 fills are 40% as likely, at 1.0 fully likely

src/drumPatterns.ts

@@ -17,9 +17,12 @@
 import { generateDrumPattern } from "./drumPatterns";
 import { generateWalkingBass } from "./walkingBass";
 import { generatePianoComping } from "./pianoComping";
+import { analyzeHarmony } from "./harmonicAnalysis";
 import { createPRNG, randomSeed, deriveStream, STREAM_DRUMS, STREAM_BASS, STREAM_PIANO } from "./prng";
 import type {
   BandContext,
+  ChordEvent,
+  HarmonicAnalysisResult,
   PhraseMap,
   PhraseIntent,
   PhraseArc,
@@ -33,6 +36,25 @@ import type {
   CompNote,
 } from "./types";
 
+// ── Harmonic Analysis Annotation ──
+
+/**
+ * Run harmonic analysis on chord events and return annotated copies.
+ * Each returned ChordEvent has its `analysis` field populated.
+ */
+function annotateChords(
+  chords: ChordEvent[],
+  keyHint: string | undefined,
+  measureDuration: number,
+): { annotated: ChordEvent[]; analysis: HarmonicAnalysisResult } {
+  const analysis = analyzeHarmony(chords, keyHint, measureDuration);
+  const annotated = chords.map((c, i) => ({
+    ...c,
+    analysis: analysis.chordAnalyses[i],
+  }));
+  return { annotated, analysis };
+}
+
 // ── Phrase Map Computation ──
 
 function computePhraseMap(options: EnsembleOptions): PhraseMap {
@@ -86,6 +108,7 @@ function planMusicalIntents(
   phraseMap: PhraseMap,
   options: EnsembleOptions,
   rng: () => number,
+  harmonic?: HarmonicAnalysisResult,
 ): PhraseIntent[] {
   const creativity = (options.creativity ?? 35) / 100;       // 0-1
   const conversation = (options.conversation ?? 30) / 100;
@@ -180,9 +203,25 @@ function planMusicalIntents(
     }
 
     // ── Harmonic Anticipation ──
-    // Higher harmonicFreedom → more likely piano plays next chord early
-    const anticipationChance = harmonicFreedom * 0.35; // max 35%
-    const passingChordChance = harmonicFreedom * 0.25; // max 25%
+    // Higher harmonicFreedom → more likely piano plays next chord early.
+    // Boost on predominant phrases (lots of ii chords setting up V),
+    // reduce on tonic-heavy phrases (already resolved, no need to rush).
+    let anticipationChance = harmonicFreedom * 0.35; // max 35%
+    let passingChordChance = harmonicFreedom * 0.25; // max 25%
+    if (harmonic && harmonic.chordAnalyses.length > 0) {
+      // Average tension across chords in this phrase
+      const phraseChordsStart = phraseStart;
+      const phraseChordsEnd = phraseEnd;
+      const phraseAnalyses = harmonic.chordAnalyses.filter((_, idx) =>
+        idx >= phraseChordsStart && idx < phraseChordsEnd);
+      if (phraseAnalyses.length > 0) {
+        const avgTension = phraseAnalyses.reduce((s, a) => s + a.tension, 0) / phraseAnalyses.length;
+        // High-tension phrases: boost anticipation (forward motion)
+        // Low-tension phrases: reduce passing chords (let resolution breathe)
+        anticipationChance *= 0.7 + avgTension * 0.6; // range: 0.7x to 1.3x
+        passingChordChance *= 0.6 + avgTension * 0.8; // range: 0.6x to 1.4x
+      }
+    }
 
     // ── Motif Lock Duration ──
     // How many bars piano/bass hold their pattern before changing.
@@ -412,10 +451,15 @@ export function generateEnsemble(options: EnsembleOptions): EnsembleResult {
   const density = options.density ?? 50;
   const swingAmount = options.swingAmount ?? 100;
 
+  // ── Harmonic Analysis (run once, before any generation) ──
+  const { annotated: annotatedChords, analysis: harmonicAnalysis } =
+    annotateChords(options.chordEvents, undefined, measureDuration);
+
   // Compute phrase structure and musical intent
   const phraseMap = computePhraseMap(options);
-  phraseMap.intents = planMusicalIntents(phraseMap, options, masterRng);
+  phraseMap.intents = planMusicalIntents(phraseMap, options, masterRng, harmonicAnalysis);
   const context = initContext(phraseMap, options);
+  context.harmonicAnalysis = harmonicAnalysis;
 
   // Determine section energy for density scaling.
   // Batch path: compute weighted average energy across all measures so that
@@ -482,7 +526,7 @@ export function generateEnsemble(options: EnsembleOptions): EnsembleResult {
 
   // ── Step 2: Generate Bass (informed by kick pattern) ──
   const scaledBassDensity = scaleDensity(density, energy);
-  const bassNotes = generateWalkingBass(options.chordEvents, {
+  const bassNotes = generateWalkingBass(annotatedChords, {
     style: bassStyle,
     tempo,
     swingAmount,
@@ -508,7 +552,7 @@ export function generateEnsemble(options: EnsembleOptions): EnsembleResult {
     ? Math.round(scaledPianoDensity * 0.8)
     : scaledPianoDensity;
 
-  const pianoNotes = generatePianoComping(options.chordEvents, {
+  const pianoNotes = generatePianoComping(annotatedChords, {
     style: pianoStyle,
     tempo,
     swingAmount,
@@ -557,9 +601,14 @@ export function* generateEnsembleMeasures(options: EnsembleOptions): Generator<M
   const density = options.density ?? 50;
   const swingAmount = options.swingAmount ?? 100;
 
+  // ── Harmonic Analysis (run once, before any generation) ──
+  const { annotated: annotatedChords, analysis: harmonicAnalysis } =
+    annotateChords(options.chordEvents, undefined, measureDuration);
+
   const phraseMap = computePhraseMap(options);
-  phraseMap.intents = planMusicalIntents(phraseMap, options, masterRng);
+  phraseMap.intents = planMusicalIntents(phraseMap, options, masterRng, harmonicAnalysis);
   const context = initContext(phraseMap, options);
+  context.harmonicAnalysis = harmonicAnalysis;
 
   const drumStyle = options.instrumentStyles?.drums ?? options.style;
   const bassStyle = options.instrumentStyles?.bass ?? options.style;
@@ -642,8 +691,8 @@ export function* generateEnsembleMeasures(options: EnsembleOptions): Generator<M
     const hitsPerMeasure = totalDrumHits / measuresGenerated;
     context.drumDensity = Math.min(1, Math.max(0, (hitsPerMeasure - 5) / 40));
 
-    // Generate bass for this measure's chords
-    const measureChords = options.chordEvents.filter(
+    // Generate bass for this measure's chords (use annotated chords with analysis)
+    const measureChords = annotatedChords.filter(
       c => c.time >= measureStart - 0.001 && c.time < measureEnd,
     );
     const bassSlice = measureChords.length > 0