@hum2music/harmony 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,20 @@
 {
   "name": "@hum2music/harmony",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Tempo, key, chord-progression, and song-structure estimation for Hum2Music.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/hum2music/hum2music",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hum2music/hum2music.git",
+    "directory": "packages/harmony"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": ["src"],
+  "dependencies": {
+    "@hum2music/core": "0.1.0",
+    "@hum2music/music-theory": "0.1.0"
+  }
+}

package/src/analyze.ts

@@ -0,0 +1,38 @@
+import type { ChordEvent, KeyCandidate, NoteEvent, SongSection, TempoCandidate } from "@hum2music/core";
+import { groupNotesIntoBars } from "./bars";
+import { estimateKey } from "./key-estimation";
+import { quantizeToBeats } from "./quantize";
+import { searchChordProgression, type ProgressionSearchWeights } from "./progression-search";
+import { estimateSongStructure } from "./song-structure";
+import { estimateTempo } from "./tempo";
+import type { TimedNote } from "./timed-note";
+
+export interface HarmonyAnalysis {
+  tempoCandidates: TempoCandidate[];
+  selectedBpm: number;
+  keyCandidates: KeyCandidate[];
+  melody: NoteEvent[];
+  chords: ChordEvent[];
+  songSections: SongSection[];
+}
+
+export interface AnalyzeHarmonyOptions {
+  overrideBpm?: number;
+  progressionWeights?: ProgressionSearchWeights;
+}
+
+/** Harmony analysis pipeline: timed notes -> tempo/key candidates -> quantized melody -> chord progression -> song structure. */
+export function analyzeHarmony(notes: TimedNote[], options: AnalyzeHarmonyOptions | number = {}): HarmonyAnalysis {
+  const resolvedOptions: AnalyzeHarmonyOptions = typeof options === "number" ? { overrideBpm: options } : options;
+
+  const tempoCandidates = estimateTempo(notes);
+  const selectedBpm = resolvedOptions.overrideBpm ?? tempoCandidates[0]?.bpm ?? 120;
+
+  const melody = quantizeToBeats(notes, selectedBpm);
+  const keyCandidates = estimateKey(notes);
+  const bars = groupNotesIntoBars(melody);
+  const chords = searchChordProgression(bars, keyCandidates[0], resolvedOptions.progressionWeights);
+  const songSections = estimateSongStructure(chords);
+
+  return { tempoCandidates, selectedBpm, keyCandidates, melody, chords, songSections };
+}

package/src/bars.ts

@@ -0,0 +1,28 @@
+import type { NoteEvent } from "@hum2music/core";
+import type { BarSegment } from "./chord-candidates";
+
+/** Splits quantized notes into fixed-size bars, per PRD §7.2's 4/4-only MVP scope. */
+export function groupNotesIntoBars(notes: NoteEvent[], beatsPerBar = 4): BarSegment[] {
+  if (notes.length === 0) return [];
+
+  const lastEndBeat = Math.max(...notes.map((note) => note.startBeat + note.durationBeats));
+  const barCount = Math.ceil(lastEndBeat / beatsPerBar);
+
+  const bars: BarSegment[] = Array.from({ length: barCount }, (_, index) => ({
+    startBeat: index * beatsPerBar,
+    endBeat: (index + 1) * beatsPerBar,
+    notes: [],
+  }));
+
+  for (const note of notes) {
+    const noteEndBeat = note.startBeat + note.durationBeats;
+    for (const bar of bars) {
+      const overlapStart = Math.max(note.startBeat, bar.startBeat);
+      const overlapEnd = Math.min(noteEndBeat, bar.endBeat);
+      const overlapBeats = overlapEnd - overlapStart;
+      if (overlapBeats > 0) bar.notes.push({ pitch: note.pitch, weight: overlapBeats });
+    }
+  }
+
+  return bars;
+}

package/src/chord-candidates.ts

@@ -0,0 +1,69 @@
+import { CHORD_QUALITIES, type ChordQuality, chordPitchClasses, chordSymbol, pitchClassOf } from "@hum2music/music-theory";
+
+export interface ChordCandidate {
+  root: number;
+  quality: ChordQuality;
+  symbol: string;
+  /** Fraction (0-1) of the bar's duration-weighted pitch-class mass that are chord tones. */
+  melodyFit: number;
+}
+
+export interface WeightedPitch {
+  pitch: number;
+  /** Duration (in beats) this pitch occupies within the bar. */
+  weight: number;
+}
+
+export interface BarSegment {
+  startBeat: number;
+  endBeat: number;
+  notes: WeightedPitch[];
+}
+
+/** Generates every (root, quality) chord as a scored candidate for one bar. */
+export function generateChordCandidates(segment: BarSegment): ChordCandidate[] {
+  const histogram = buildWeightedPitchClassHistogram(segment.notes);
+  const candidates: ChordCandidate[] = [];
+
+  for (let root = 0; root < 12; root++) {
+    for (const quality of CHORD_QUALITIES) {
+      const chordTones = new Set(chordPitchClasses(root, quality));
+      candidates.push({
+        root,
+        quality,
+        symbol: chordSymbol(root, quality),
+        melodyFit: scoreMelodyFit(histogram, chordTones),
+      });
+    }
+  }
+
+  return candidates;
+}
+
+function buildWeightedPitchClassHistogram(notes: WeightedPitch[]): number[] {
+  const histogram = new Array(12).fill(0);
+  for (const note of notes) histogram[pitchClassOf(note.pitch)] += note.weight;
+  const total = histogram.reduce((sum, value) => sum + value, 0);
+  return total === 0 ? histogram : histogram.map((value) => value / total);
+}
+
+/**
+ * Fraction of the bar's pitch-class mass covered by this chord's tones,
+ * scaled down by how many of the chord's own tones go unconfirmed by the
+ * melody. Without this scaling, a 7th/6th chord whose extra tone simply
+ * never sounds would always tie a plain triad that covers the same notes,
+ * since an absent tone costs nothing — this way the smallest chord that
+ * fully explains the melody wins, rather than an assumed, unheard tension.
+ */
+function scoreMelodyFit(histogram: number[], chordTones: Set<number>): number {
+  let matchedMass = 0;
+  let confirmedToneCount = 0;
+  for (const pitchClass of chordTones) {
+    if (histogram[pitchClass] > 0) {
+      matchedMass += histogram[pitchClass];
+      confirmedToneCount++;
+    }
+  }
+  const confirmedCoverage = confirmedToneCount / chordTones.size;
+  return matchedMass * confirmedCoverage;
+}

package/src/harmonic-naturalness.ts

@@ -0,0 +1,19 @@
+import { pitchClassOf } from "@hum2music/music-theory";
+
+/** Pitch classes ordered by stacking perfect fifths from C, for circle-of-fifths distance. */
+const CIRCLE_OF_FIFTHS_ORDER = [0, 7, 2, 9, 4, 11, 6, 1, 8, 3, 10, 5];
+const FIFTHS_POSITION = new Map(CIRCLE_OF_FIFTHS_ORDER.map((pitchClass, position) => [pitchClass, position]));
+
+/**
+ * Scores how "natural" a chord-root transition is: root motion by a fifth
+ * (dominant/subdominant motion) scores highest, a tritone-apart move lowest.
+ * A simplified stand-in for a full functional-harmony transition table
+ * (PRD §8.3's H term).
+ */
+export function harmonicNaturalnessScore(prevRoot: number, curRoot: number): number {
+  const prevPosition = FIFTHS_POSITION.get(pitchClassOf(prevRoot))!;
+  const curPosition = FIFTHS_POSITION.get(pitchClassOf(curRoot))!;
+  const rawDistance = Math.abs(prevPosition - curPosition) % 12;
+  const fifthsDistance = Math.min(rawDistance, 12 - rawDistance);
+  return 1 - fifthsDistance / 6;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./timed-note";
+export * from "./tempo";
+export * from "./quantize";
+export * from "./key-estimation";
+export * from "./chord-candidates";
+export * from "./bars";
+export * from "./harmonic-naturalness";
+export * from "./voice-leading";
+export * from "./progression-search";
+export * from "./song-structure";
+export * from "./analyze";

package/src/key-estimation.ts

@@ -0,0 +1,61 @@
+import type { KeyCandidate } from "@hum2music/core";
+import { KEY_PROFILES, NOTE_NAMES, pitchClassOf, type ScaleMode } from "@hum2music/music-theory";
+import type { TimedNote } from "./timed-note";
+
+/**
+ * Correlates a duration-weighted pitch-class histogram against all 24
+ * Krumhansl-Kessler key profiles (12 tonics x major/minor) and returns the
+ * best-matching keys, ranked, rather than committing to a single guess
+ * (PRD §8.1).
+ */
+export function estimateKey(notes: TimedNote[], maxCandidates = 5): KeyCandidate[] {
+  const histogram = buildPitchClassHistogram(notes);
+
+  const candidates: KeyCandidate[] = [];
+  for (let tonic = 0; tonic < 12; tonic++) {
+    for (const mode of ["major", "minor"] as ScaleMode[]) {
+      const rotatedProfile = rotateProfileToTonic(KEY_PROFILES[mode], tonic);
+      const correlation = pearsonCorrelation(histogram, rotatedProfile);
+      candidates.push({ tonic: NOTE_NAMES[tonic], mode, confidence: clamp01((correlation + 1) / 2) });
+    }
+  }
+
+  candidates.sort((a, b) => b.confidence - a.confidence);
+  return candidates.slice(0, maxCandidates);
+}
+
+function buildPitchClassHistogram(notes: TimedNote[]): number[] {
+  const histogram = new Array(12).fill(0);
+  for (const note of notes) histogram[pitchClassOf(note.pitch)] += note.durationMs;
+  const total = histogram.reduce((sum, value) => sum + value, 0);
+  return total === 0 ? histogram : histogram.map((value) => value / total);
+}
+
+/** `profile[i]` is defined relative to the tonic; this aligns it to absolute pitch classes. */
+function rotateProfileToTonic(profile: number[], tonic: number): number[] {
+  return Array.from({ length: 12 }, (_, pitchClass) => profile[(((pitchClass - tonic) % 12) + 12) % 12]);
+}
+
+function pearsonCorrelation(a: number[], b: number[]): number {
+  const n = a.length;
+  const meanA = a.reduce((sum, value) => sum + value, 0) / n;
+  const meanB = b.reduce((sum, value) => sum + value, 0) / n;
+
+  let numerator = 0;
+  let varianceA = 0;
+  let varianceB = 0;
+  for (let i = 0; i < n; i++) {
+    const deviationA = a[i] - meanA;
+    const deviationB = b[i] - meanB;
+    numerator += deviationA * deviationB;
+    varianceA += deviationA * deviationA;
+    varianceB += deviationB * deviationB;
+  }
+
+  const denominator = Math.sqrt(varianceA * varianceB);
+  return denominator === 0 ? 0 : numerator / denominator;
+}
+
+function clamp01(value: number): number {
+  return Math.min(1, Math.max(0, value));
+}

package/src/progression-search.ts

@@ -0,0 +1,97 @@
+import type { ChordEvent, KeyCandidate } from "@hum2music/core";
+import { NOTE_NAMES, isDiatonic, type ScaleMode } from "@hum2music/music-theory";
+import { generateChordCandidates, type BarSegment, type ChordCandidate } from "./chord-candidates";
+import { harmonicNaturalnessScore } from "./harmonic-naturalness";
+import { voiceLeadingScore } from "./voice-leading";
+
+export interface ProgressionSearchWeights {
+  melodyFit: number;
+  harmonicNaturalness: number;
+  voiceLeading: number;
+}
+
+const DEFAULT_WEIGHTS: ProgressionSearchWeights = {
+  melodyFit: 0.5,
+  harmonicNaturalness: 0.3,
+  voiceLeading: 0.2,
+};
+
+/**
+ * Dynamic-programming search over bar-by-bar chord candidates, maximizing
+ * S(c) = wM*M + wH*H + wV*V across the whole progression rather than
+ * picking each bar's locally-best chord (PRD §8.3). The style term (S) is
+ * left out of the MVP weighting (see docs/specs/style-profiles.md).
+ */
+export function searchChordProgression(
+  bars: BarSegment[],
+  topKey?: KeyCandidate,
+  weights: ProgressionSearchWeights = DEFAULT_WEIGHTS,
+): ChordEvent[] {
+  if (bars.length === 0) return [];
+
+  const candidatesPerBar = bars.map((bar) => generateChordCandidates(bar));
+  const candidateCount = candidatesPerBar[0].length;
+
+  const barScore = (candidate: ChordCandidate) =>
+    weights.melodyFit * candidate.melodyFit * diatonicBonus(candidate.root, topKey);
+
+  const dp: number[][] = candidatesPerBar.map(() => new Array(candidateCount).fill(-Infinity));
+  const parent: number[][] = candidatesPerBar.map(() => new Array(candidateCount).fill(-1));
+
+  for (let c = 0; c < candidateCount; c++) {
+    dp[0][c] = barScore(candidatesPerBar[0][c]);
+  }
+
+  for (let i = 1; i < bars.length; i++) {
+    for (let c = 0; c < candidateCount; c++) {
+      const candidate = candidatesPerBar[i][c];
+      let best = -Infinity;
+      let bestPrev = -1;
+
+      for (let p = 0; p < candidateCount; p++) {
+        const prevCandidate = candidatesPerBar[i - 1][p];
+        const transitionScore =
+          weights.harmonicNaturalness * harmonicNaturalnessScore(prevCandidate.root, candidate.root) +
+          weights.voiceLeading *
+            voiceLeadingScore(prevCandidate.root, prevCandidate.quality, candidate.root, candidate.quality);
+        const score = dp[i - 1][p] + transitionScore;
+        if (score > best) {
+          best = score;
+          bestPrev = p;
+        }
+      }
+
+      dp[i][c] = best + barScore(candidate);
+      parent[i][c] = bestPrev;
+    }
+  }
+
+  const lastBarIndex = bars.length - 1;
+  let bestLastCandidate = 0;
+  for (let c = 1; c < candidateCount; c++) {
+    if (dp[lastBarIndex][c] > dp[lastBarIndex][bestLastCandidate]) bestLastCandidate = c;
+  }
+
+  const chosenIndexPerBar = new Array<number>(bars.length);
+  chosenIndexPerBar[lastBarIndex] = bestLastCandidate;
+  for (let i = lastBarIndex; i > 0; i--) {
+    chosenIndexPerBar[i - 1] = parent[i][chosenIndexPerBar[i]];
+  }
+
+  return bars.map((bar, i) => {
+    const candidate = candidatesPerBar[i][chosenIndexPerBar[i]];
+    return {
+      symbol: candidate.symbol,
+      startBeat: bar.startBeat,
+      durationBeats: bar.endBeat - bar.startBeat,
+      confidence: candidate.melodyFit,
+    };
+  });
+}
+
+function diatonicBonus(root: number, topKey?: KeyCandidate): number {
+  if (!topKey) return 1;
+  const tonicPitchClass = (NOTE_NAMES as readonly string[]).indexOf(topKey.tonic);
+  if (tonicPitchClass === -1) return 1;
+  return isDiatonic(root, tonicPitchClass, topKey.mode as ScaleMode) ? 1 : 0.85;
+}

package/src/quantize.ts

@@ -0,0 +1,35 @@
+import type { NoteEvent } from "@hum2music/core";
+import type { TimedNote } from "./timed-note";
+
+/** Sixteenth-note grid: fine enough that quarter/eighth/dotted values fall exactly on it. */
+const GRID_STEP_BEATS = 1 / 4;
+
+/**
+ * Converts absolute-time notes to beat-relative notes for a given tempo
+ * hypothesis, snapping to the nearest sixteenth-note grid position. The
+ * pre-quantization timing is preserved in `expression.timingOffsetMs`
+ * (PRD §7.3) rather than discarded.
+ */
+export function quantizeToBeats(notes: TimedNote[], bpm: number): NoteEvent[] {
+  const msPerBeat = 60000 / bpm;
+
+  return notes.map((note) => {
+    const rawStartBeat = note.startMs / msPerBeat;
+    const startBeat = roundToGrid(rawStartBeat);
+    const durationBeats = Math.max(GRID_STEP_BEATS, roundToGrid(note.durationMs / msPerBeat));
+
+    return {
+      pitch: note.pitch,
+      startBeat,
+      durationBeats,
+      velocity: note.velocity,
+      expression: {
+        timingOffsetMs: (rawStartBeat - startBeat) * msPerBeat,
+      },
+    };
+  });
+}
+
+function roundToGrid(valueInBeats: number): number {
+  return Math.round(valueInBeats / GRID_STEP_BEATS) * GRID_STEP_BEATS;
+}

package/src/song-structure.ts

@@ -0,0 +1,37 @@
+import type { ChordEvent, SongSection } from "@hum2music/core";
+
+const DEFAULT_CYCLE_LENGTH_BARS = 4;
+
+/**
+ * Detects repeating cycles in the bar-level chord sequence and labels them
+ * A, B, C, ... reusing a label whenever an earlier cycle's chord sequence
+ * repeats exactly. A simple, defensible stand-in for full song-structure
+ * estimation — detecting verse/chorus boundaries from audio/lyrics is out
+ * of scope for a rule-based system working from chords alone.
+ */
+export function estimateSongStructure(chords: ChordEvent[], cycleLengthBars = DEFAULT_CYCLE_LENGTH_BARS): SongSection[] {
+  if (chords.length === 0) return [];
+
+  const symbols = chords.map((chord) => chord.symbol);
+  const sections: SongSection[] = [];
+  const seenCycles: string[] = [];
+
+  for (let start = 0; start < symbols.length; start += cycleLengthBars) {
+    const cycle = symbols.slice(start, start + cycleLengthBars);
+    const key = cycle.join(",");
+
+    let labelIndex = seenCycles.indexOf(key);
+    if (labelIndex === -1) {
+      seenCycles.push(key);
+      labelIndex = seenCycles.length - 1;
+    }
+
+    sections.push({ label: indexToLabel(labelIndex), startBarIndex: start, barCount: cycle.length });
+  }
+
+  return sections;
+}
+
+function indexToLabel(index: number): string {
+  return String.fromCharCode(65 + (index % 26));
+}

package/src/tempo.ts

@@ -0,0 +1,61 @@
+import type { TempoCandidate } from "@hum2music/core";
+import type { TimedNote } from "./timed-note";
+
+export interface TempoEstimationOptions {
+  minIntervalMs?: number;
+  maxIntervalMs?: number;
+  maxCandidates?: number;
+}
+
+/**
+ * Builds a histogram of inter-onset intervals (read as implied quarter-note
+ * BPM) and returns the most frequent values as ranked candidates. Half/double
+ * tempo relationships are flagged rather than collapsed, per PRD §7.1.
+ */
+export function estimateTempo(notes: TimedNote[], options: TempoEstimationOptions = {}): TempoCandidate[] {
+  const minIntervalMs = options.minIntervalMs ?? 100;
+  const maxIntervalMs = options.maxIntervalMs ?? 2000;
+  const maxCandidates = options.maxCandidates ?? 5;
+
+  const onsets = notes.map((note) => note.startMs).sort((a, b) => a - b);
+  const intervals: number[] = [];
+  for (let i = 1; i < onsets.length; i++) {
+    const interval = onsets[i] - onsets[i - 1];
+    if (interval >= minIntervalMs && interval <= maxIntervalMs) intervals.push(interval);
+  }
+  if (intervals.length === 0) return [];
+
+  const bpmCounts = new Map<number, number>();
+  for (const interval of intervals) {
+    const bpm = Math.round(60000 / interval);
+    bpmCounts.set(bpm, (bpmCounts.get(bpm) ?? 0) + 1);
+  }
+
+  const total = intervals.length;
+  const candidates: TempoCandidate[] = [];
+  for (const [bpm, count] of [...bpmCounts.entries()].sort((a, b) => b[1] - a[1])) {
+    if (candidates.some((candidate) => isCloseBpm(candidate.bpm, bpm, 4))) continue;
+    candidates.push({ bpm, confidence: count / total });
+    if (candidates.length >= maxCandidates) break;
+  }
+
+  linkHalfAndDoubleTempoCandidates(candidates);
+  return candidates;
+}
+
+function isCloseBpm(a: number, b: number, toleranceBpm: number): boolean {
+  return Math.abs(a - b) <= toleranceBpm;
+}
+
+function linkHalfAndDoubleTempoCandidates(candidates: TempoCandidate[]): void {
+  for (const candidate of candidates) {
+    const strongerRelated = candidates.find(
+      (other) =>
+        other !== candidate &&
+        other.confidence >= candidate.confidence &&
+        (isCloseBpm(other.bpm, candidate.bpm * 2, other.bpm * 0.05) ||
+          isCloseBpm(other.bpm, candidate.bpm / 2, other.bpm * 0.05)),
+    );
+    if (strongerRelated) candidate.isHalfOrDoubleOf = strongerRelated.bpm;
+  }
+}

package/src/timed-note.ts

@@ -0,0 +1,7 @@
+/** A transcribed note in absolute time, independent of any tempo hypothesis. */
+export interface TimedNote {
+  pitch: number;
+  startMs: number;
+  durationMs: number;
+  velocity: number;
+}

package/src/voice-leading.ts

@@ -0,0 +1,24 @@
+import { type ChordQuality, chordPitchClasses, pitchClassDistance } from "@hum2music/music-theory";
+
+/**
+ * Scores voice-leading smoothness between two chords as the inverse of the
+ * average nearest-tone movement (in semitones) from the previous chord's
+ * tones to the current chord's tones (PRD §8.3's V term).
+ */
+export function voiceLeadingScore(
+  prevRoot: number,
+  prevQuality: ChordQuality,
+  curRoot: number,
+  curQuality: ChordQuality,
+): number {
+  const prevTones = chordPitchClasses(prevRoot, prevQuality);
+  const curTones = chordPitchClasses(curRoot, curQuality);
+
+  const totalMovement = prevTones.reduce((sum, prevTone) => {
+    const nearestDistance = Math.min(...curTones.map((curTone) => Math.abs(pitchClassDistance(prevTone, curTone))));
+    return sum + nearestDistance;
+  }, 0);
+
+  const averageMovement = totalMovement / prevTones.length;
+  return 1 - averageMovement / 6;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.