@musodojo/music-theory-data 29.0.0 → 30.0.0

package/README.md

@@ -211,6 +211,21 @@ console.log(
 );
 // ["CM", "FM", "GM"]
 
+// Chord-change references return one item each time the chord changes in
+// progression.chords. Durations are not expanded here.
+console.log(
+  music_theory_data.getChordProgressionChordChangeReferences(
+    "C",
+    "oneOneFiveFive",
+  ),
+);
+// [
+//   { rootNote: "C", chordName: "CM", noteCollectionKey: "major" },
+//   { rootNote: "G", chordName: "GM", noteCollectionKey: "major" },
+// ]
+
+// Unique chord references return each distinct chord once, preserving the
+// first-seen order from the chord-change list.
 console.log(
   music_theory_data.getChordProgressionUniqueChordReferences(
     "C",
@@ -219,15 +234,76 @@ console.log(
 );
 // [
 //   { rootNote: "C", chordName: "CM", noteCollectionKey: "major" },
-//   { rootNote: "C", chordName: "FM", noteCollectionKey: "major" },
-//   { rootNote: "C", chordName: "GM", noteCollectionKey: "major" },
+//   { rootNote: "F", chordName: "FM", noteCollectionKey: "major" },
+//   { rootNote: "G", chordName: "GM", noteCollectionKey: "major" },
 // ]
 
+// Chord references by bar return the song/practice order grouped by bar. A
+// 2-bar chord appears in two bars, and split bars contain multiple references.
+console.log(
+  music_theory_data.getChordProgressionChordReferencesByBar(
+    "C",
+    "oneOneFiveFive",
+  ),
+);
+// [
+//   [{ rootNote: "C", chordName: "CM", noteCollectionKey: "major" }],
+//   [{ rootNote: "C", chordName: "CM", noteCollectionKey: "major" }],
+//   [{ rootNote: "G", chordName: "GM", noteCollectionKey: "major" }],
+//   [{ rootNote: "G", chordName: "GM", noteCollectionKey: "major" }],
+// ]
+
+console.log(
+  music_theory_data.getChordProgressionChordReferencesByBar(
+    "C",
+    "oneFourOneFiveSplitReturn",
+  )[6],
+);
+// [
+//   { rootNote: "C", chordName: "CM", noteCollectionKey: "major" },
+//   { rootNote: "G", chordName: "GM", noteCollectionKey: "major" },
+// ]
+
+// Song chord references flatten the bar-structured references into one ordered
+// list for apps that want one diagram/card per chord occurrence.
+console.log(
+  music_theory_data.getChordProgressionSongChordReferences(
+    "C",
+    "oneOneFiveFive",
+  ).map((reference) => reference.chordName),
+);
+// ["CM", "CM", "GM", "GM"]
+
+// In Muso Dojo, "Each Chord Once" should import
+// getChordProgressionUniqueChordReferences. "Full Song Order" should import
+// getChordProgressionSongChordReferences, or flatten
+// getChordProgressionChordReferencesByBar locally when bar grouping is needed.
+
 console.log(
   music_theory_data.getChordProgressionTotalDurationInBars("twelveBarBlues"),
 );
 // 12
 
+console.log(
+  music_theory_data.getChordProgressionChordReferencesByBar(
+    "C",
+    "twelveBarBlues",
+  ).length,
+);
+// 12
+
+console.log(
+  music_theory_data.getChordProgressionUniqueChordReferences(
+    "C",
+    "twelveBarBlues",
+  ),
+);
+// [
+//   { rootNote: "C", chordName: "C7", noteCollectionKey: "dominant7" },
+//   { rootNote: "F", chordName: "F7", noteCollectionKey: "dominant7" },
+//   { rootNote: "G", chordName: "G7", noteCollectionKey: "dominant7" },
+// ]
+
 console.log(music_theory_data.chordProgressionBarGroups);
 // [
 //   { totalBars: 4, progressionKeys: ["oneOneFiveFive", ...] },

package/esm/src/utils/chord-progressions.d.ts

@@ -12,7 +12,32 @@ export declare function getChordProgressionChordNames(rootNote: RootNote, progre
 export declare function getChordProgressionRomanSymbols(progressionOrKey: ChordProgression | ChordProgressionKey): string[];
 export declare function getChordProgressionKeysForTotalBars(totalBars: number): ChordProgressionKey[];
 export declare function getChordProgressionUniqueChordNames(rootNote: RootNote, progressionOrKey: ChordProgression | ChordProgressionKey): string[];
-export declare function getChordProgressionChordReferences(rootNote: RootNote, progressionOrKey: ChordProgression | ChordProgressionKey): ChordProgressionChordReference[];
+/**
+ * Returns one chord reference for each authored chord entry in
+ * `progression.chords`.
+ *
+ * This is the "chord changes" view: a chord lasting 2 bars is returned once,
+ * because it is one chord entry/change, while repeated entries are preserved.
+ */
+export declare function getChordProgressionChordChangeReferences(rootNote: RootNote, progressionOrKey: ChordProgression | ChordProgressionKey): ChordProgressionChordReference[];
+/**
+ * Returns each distinct chord reference once, preserving first-seen order from
+ * the chord-change list.
+ */
 export declare function getChordProgressionUniqueChordReferences(rootNote: RootNote, progressionOrKey: ChordProgression | ChordProgressionKey): ChordProgressionChordReference[];
+/**
+ * Returns duration-aware chord references grouped by bar.
+ *
+ * Each outer array item is one bar. A 2-bar chord appears in two bar entries,
+ * and a split bar can contain multiple chord references in order.
+ */
+export declare function getChordProgressionChordReferencesByBar(rootNote: RootNote, progressionOrKey: ChordProgression | ChordProgressionKey): ChordProgressionChordReference[][];
+/**
+ * Returns duration-aware chord references in song/practice order.
+ *
+ * This flattens `getChordProgressionChordReferencesByBar`, so a 2-bar chord
+ * appears twice and split bars preserve their left-to-right order.
+ */
+export declare function getChordProgressionSongChordReferences(rootNote: RootNote, progressionOrKey: ChordProgression | ChordProgressionKey): ChordProgressionChordReference[];
 export declare function getChordProgressionTotalDurationInBars(progressionOrKey: ChordProgression | ChordProgressionKey): number;
 //# sourceMappingURL=chord-progressions.d.ts.map

package/esm/src/utils/chord-progressions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chord-progressions.d.ts","sourceRoot":"","sources":["../../../src/src/utils/chord-progressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAMzE,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;CAC/C;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,GACV,GAAG,IAAI,mBAAmB,CAE5B;AASD,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,EAAE,CAYV;AAED,wBAAgB,+BAA+B,CAC7C,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,EAAE,CAKV;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,MAAM,GAChB,mBAAmB,EAAE,CAKvB;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,EAAE,CAIV;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,8BAA8B,EAAE,CAmBlC;AAED,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,8BAA8B,EAAE,CAkBlC;AAED,wBAAgB,sCAAsC,CACpD,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,CAQR"}
+{"version":3,"file":"chord-progressions.d.ts","sourceRoot":"","sources":["../../../src/src/utils/chord-progressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAMzE,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;CAC/C;AASD,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,GACV,GAAG,IAAI,mBAAmB,CAE5B;AA2CD,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,EAAE,CAYV;AAED,wBAAgB,+BAA+B,CAC7C,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,EAAE,CAKV;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,MAAM,GAChB,mBAAmB,EAAE,CAKvB;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,EAAE,CAIV;AAED;;;;;;GAMG;AACH,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,8BAA8B,EAAE,CAKlC;AAED;;;GAGG;AACH,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,8BAA8B,EAAE,CAkBlC;AAED;;;;;GAKG;AACH,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,8BAA8B,EAAE,EAAE,CAiDpC;AAED;;;;;GAKG;AACH,wBAAgB,sCAAsC,CACpD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,8BAA8B,EAAE,CAKlC;AAED,wBAAgB,sCAAsC,CACpD,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,CAQR"}

package/esm/src/utils/chord-progressions.js

@@ -1,6 +1,7 @@
 import { chordProgressionBarGroups, chordProgressions, } from "../data/chord-progressions/mod.js";
 import { getChordQualityNoteCollectionKey } from "../data/chords/mod.js";
 import { getNoteNamesForRootAndIntervals, normalizeRootNoteString, } from "./note-names.js";
+const BAR_DURATION_EPSILON = 0.000000001;
 export function isValidChordProgressionKey(key) {
     return Object.prototype.hasOwnProperty.call(chordProgressions, key);
 }
@@ -9,6 +10,28 @@ function resolveProgression(progressionOrKey) {
         return progressionOrKey;
     return chordProgressions[progressionOrKey];
 }
+function createChordProgressionChordReference(chord, chordRootNote) {
+    return {
+        rootNote: chordRootNote,
+        chordName: chordRootNote + chord.quality,
+        noteCollectionKey: getChordQualityNoteCollectionKey(chord.quality),
+    };
+}
+function getResolvedChordProgressionChordReferences(rootNote, progressionOrKey) {
+    const progression = resolveProgression(progressionOrKey);
+    if (!progression)
+        return [];
+    const chordRootNotes = getNoteNamesForRootAndIntervals(rootNote, progression.chords.map((chord) => chord.degree)).map((noteName) => normalizeRootNoteString(noteName));
+    return progression.chords.flatMap((chord, index) => {
+        const chordRootNote = chordRootNotes[index];
+        if (!chordRootNote)
+            return [];
+        return [{
+                chord,
+                reference: createChordProgressionChordReference(chord, chordRootNote),
+            }];
+    });
+}
 export function getChordProgressionChordNames(rootNote, progressionOrKey) {
     const progression = resolveProgression(progressionOrKey);
     if (!progression)
@@ -29,26 +52,24 @@ export function getChordProgressionKeysForTotalBars(totalBars) {
 export function getChordProgressionUniqueChordNames(rootNote, progressionOrKey) {
     return Array.from(new Set(getChordProgressionChordNames(rootNote, progressionOrKey)));
 }
-export function getChordProgressionChordReferences(rootNote, progressionOrKey) {
-    const progression = resolveProgression(progressionOrKey);
-    if (!progression)
-        return [];
-    const chordRootNotes = getNoteNamesForRootAndIntervals(rootNote, progression.chords.map((chord) => chord.degree)).map((noteName) => normalizeRootNoteString(noteName));
-    return progression.chords.flatMap((chord, index) => {
-        const chordRootNote = chordRootNotes[index];
-        if (!chordRootNote)
-            return [];
-        return [{
-                rootNote: chordRootNote,
-                chordName: chordRootNote + chord.quality,
-                noteCollectionKey: getChordQualityNoteCollectionKey(chord.quality),
-            }];
-    });
+/**
+ * Returns one chord reference for each authored chord entry in
+ * `progression.chords`.
+ *
+ * This is the "chord changes" view: a chord lasting 2 bars is returned once,
+ * because it is one chord entry/change, while repeated entries are preserved.
+ */
+export function getChordProgressionChordChangeReferences(rootNote, progressionOrKey) {
+    return getResolvedChordProgressionChordReferences(rootNote, progressionOrKey).map(({ reference }) => reference);
 }
+/**
+ * Returns each distinct chord reference once, preserving first-seen order from
+ * the chord-change list.
+ */
 export function getChordProgressionUniqueChordReferences(rootNote, progressionOrKey) {
     const uniqueReferences = [];
     const seen = new Set();
-    for (const reference of getChordProgressionChordReferences(rootNote, progressionOrKey)) {
+    for (const reference of getChordProgressionChordChangeReferences(rootNote, progressionOrKey)) {
         const key = `${reference.rootNote}:${reference.noteCollectionKey}:${reference.chordName}`;
         if (seen.has(key))
             continue;
@@ -57,6 +78,51 @@ export function getChordProgressionUniqueChordReferences(rootNote, progressionOr
     }
     return uniqueReferences;
 }
+/**
+ * Returns duration-aware chord references grouped by bar.
+ *
+ * Each outer array item is one bar. A 2-bar chord appears in two bar entries,
+ * and a split bar can contain multiple chord references in order.
+ */
+export function getChordProgressionChordReferencesByBar(rootNote, progressionOrKey) {
+    const bars = [];
+    let currentBar = [];
+    let remainingBarDuration = 1;
+    const pushCurrentBar = () => {
+        if (currentBar.length > 0) {
+            bars.push(currentBar);
+        }
+        currentBar = [];
+        remainingBarDuration = 1;
+    };
+    for (const { chord, reference } of getResolvedChordProgressionChordReferences(rootNote, progressionOrKey)) {
+        let remainingChordDuration = chord.durationInBars;
+        if (!Number.isFinite(remainingChordDuration) ||
+            remainingChordDuration <= BAR_DURATION_EPSILON) {
+            continue;
+        }
+        while (remainingChordDuration > BAR_DURATION_EPSILON) {
+            currentBar.push(reference);
+            const filledDuration = Math.min(remainingChordDuration, remainingBarDuration);
+            remainingChordDuration -= filledDuration;
+            remainingBarDuration -= filledDuration;
+            if (remainingBarDuration <= BAR_DURATION_EPSILON) {
+                pushCurrentBar();
+            }
+        }
+    }
+    pushCurrentBar();
+    return bars;
+}
+/**
+ * Returns duration-aware chord references in song/practice order.
+ *
+ * This flattens `getChordProgressionChordReferencesByBar`, so a 2-bar chord
+ * appears twice and split bars preserve their left-to-right order.
+ */
+export function getChordProgressionSongChordReferences(rootNote, progressionOrKey) {
+    return getChordProgressionChordReferencesByBar(rootNote, progressionOrKey).flat();
+}
 export function getChordProgressionTotalDurationInBars(progressionOrKey) {
     const progression = resolveProgression(progressionOrKey);
     if (!progression)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@musodojo/music-theory-data",
-  "version": "29.0.0",
+  "version": "30.0.0",
   "description": "The musician-friendly TypeScript library for scales, modes, chords, and arpeggios.",
   "keywords": [
     "music",

package/script/src/utils/chord-progressions.d.ts

@@ -12,7 +12,32 @@ export declare function getChordProgressionChordNames(rootNote: RootNote, progre
 export declare function getChordProgressionRomanSymbols(progressionOrKey: ChordProgression | ChordProgressionKey): string[];
 export declare function getChordProgressionKeysForTotalBars(totalBars: number): ChordProgressionKey[];
 export declare function getChordProgressionUniqueChordNames(rootNote: RootNote, progressionOrKey: ChordProgression | ChordProgressionKey): string[];
-export declare function getChordProgressionChordReferences(rootNote: RootNote, progressionOrKey: ChordProgression | ChordProgressionKey): ChordProgressionChordReference[];
+/**
+ * Returns one chord reference for each authored chord entry in
+ * `progression.chords`.
+ *
+ * This is the "chord changes" view: a chord lasting 2 bars is returned once,
+ * because it is one chord entry/change, while repeated entries are preserved.
+ */
+export declare function getChordProgressionChordChangeReferences(rootNote: RootNote, progressionOrKey: ChordProgression | ChordProgressionKey): ChordProgressionChordReference[];
+/**
+ * Returns each distinct chord reference once, preserving first-seen order from
+ * the chord-change list.
+ */
 export declare function getChordProgressionUniqueChordReferences(rootNote: RootNote, progressionOrKey: ChordProgression | ChordProgressionKey): ChordProgressionChordReference[];
+/**
+ * Returns duration-aware chord references grouped by bar.
+ *
+ * Each outer array item is one bar. A 2-bar chord appears in two bar entries,
+ * and a split bar can contain multiple chord references in order.
+ */
+export declare function getChordProgressionChordReferencesByBar(rootNote: RootNote, progressionOrKey: ChordProgression | ChordProgressionKey): ChordProgressionChordReference[][];
+/**
+ * Returns duration-aware chord references in song/practice order.
+ *
+ * This flattens `getChordProgressionChordReferencesByBar`, so a 2-bar chord
+ * appears twice and split bars preserve their left-to-right order.
+ */
+export declare function getChordProgressionSongChordReferences(rootNote: RootNote, progressionOrKey: ChordProgression | ChordProgressionKey): ChordProgressionChordReference[];
 export declare function getChordProgressionTotalDurationInBars(progressionOrKey: ChordProgression | ChordProgressionKey): number;
 //# sourceMappingURL=chord-progressions.d.ts.map

package/script/src/utils/chord-progressions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chord-progressions.d.ts","sourceRoot":"","sources":["../../../src/src/utils/chord-progressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAMzE,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;CAC/C;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,GACV,GAAG,IAAI,mBAAmB,CAE5B;AASD,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,EAAE,CAYV;AAED,wBAAgB,+BAA+B,CAC7C,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,EAAE,CAKV;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,MAAM,GAChB,mBAAmB,EAAE,CAKvB;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,EAAE,CAIV;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,8BAA8B,EAAE,CAmBlC;AAED,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,8BAA8B,EAAE,CAkBlC;AAED,wBAAgB,sCAAsC,CACpD,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,CAQR"}
+{"version":3,"file":"chord-progressions.d.ts","sourceRoot":"","sources":["../../../src/src/utils/chord-progressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAMzE,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;CAC/C;AASD,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,GACV,GAAG,IAAI,mBAAmB,CAE5B;AA2CD,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,EAAE,CAYV;AAED,wBAAgB,+BAA+B,CAC7C,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,EAAE,CAKV;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,MAAM,GAChB,mBAAmB,EAAE,CAKvB;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,EAAE,CAIV;AAED;;;;;;GAMG;AACH,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,8BAA8B,EAAE,CAKlC;AAED;;;GAGG;AACH,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,8BAA8B,EAAE,CAkBlC;AAED;;;;;GAKG;AACH,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,8BAA8B,EAAE,EAAE,CAiDpC;AAED;;;;;GAKG;AACH,wBAAgB,sCAAsC,CACpD,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,8BAA8B,EAAE,CAKlC;AAED,wBAAgB,sCAAsC,CACpD,gBAAgB,EAAE,gBAAgB,GAAG,mBAAmB,GACvD,MAAM,CAQR"}

package/script/src/utils/chord-progressions.js

@@ -5,12 +5,15 @@ exports.getChordProgressionChordNames = getChordProgressionChordNames;
 exports.getChordProgressionRomanSymbols = getChordProgressionRomanSymbols;
 exports.getChordProgressionKeysForTotalBars = getChordProgressionKeysForTotalBars;
 exports.getChordProgressionUniqueChordNames = getChordProgressionUniqueChordNames;
-exports.getChordProgressionChordReferences = getChordProgressionChordReferences;
+exports.getChordProgressionChordChangeReferences = getChordProgressionChordChangeReferences;
 exports.getChordProgressionUniqueChordReferences = getChordProgressionUniqueChordReferences;
+exports.getChordProgressionChordReferencesByBar = getChordProgressionChordReferencesByBar;
+exports.getChordProgressionSongChordReferences = getChordProgressionSongChordReferences;
 exports.getChordProgressionTotalDurationInBars = getChordProgressionTotalDurationInBars;
 const mod_js_1 = require("../data/chord-progressions/mod.js");
 const mod_js_2 = require("../data/chords/mod.js");
 const note_names_js_1 = require("./note-names.js");
+const BAR_DURATION_EPSILON = 0.000000001;
 function isValidChordProgressionKey(key) {
     return Object.prototype.hasOwnProperty.call(mod_js_1.chordProgressions, key);
 }
@@ -19,6 +22,28 @@ function resolveProgression(progressionOrKey) {
         return progressionOrKey;
     return mod_js_1.chordProgressions[progressionOrKey];
 }
+function createChordProgressionChordReference(chord, chordRootNote) {
+    return {
+        rootNote: chordRootNote,
+        chordName: chordRootNote + chord.quality,
+        noteCollectionKey: (0, mod_js_2.getChordQualityNoteCollectionKey)(chord.quality),
+    };
+}
+function getResolvedChordProgressionChordReferences(rootNote, progressionOrKey) {
+    const progression = resolveProgression(progressionOrKey);
+    if (!progression)
+        return [];
+    const chordRootNotes = (0, note_names_js_1.getNoteNamesForRootAndIntervals)(rootNote, progression.chords.map((chord) => chord.degree)).map((noteName) => (0, note_names_js_1.normalizeRootNoteString)(noteName));
+    return progression.chords.flatMap((chord, index) => {
+        const chordRootNote = chordRootNotes[index];
+        if (!chordRootNote)
+            return [];
+        return [{
+                chord,
+                reference: createChordProgressionChordReference(chord, chordRootNote),
+            }];
+    });
+}
 function getChordProgressionChordNames(rootNote, progressionOrKey) {
     const progression = resolveProgression(progressionOrKey);
     if (!progression)
@@ -39,26 +64,24 @@ function getChordProgressionKeysForTotalBars(totalBars) {
 function getChordProgressionUniqueChordNames(rootNote, progressionOrKey) {
     return Array.from(new Set(getChordProgressionChordNames(rootNote, progressionOrKey)));
 }
-function getChordProgressionChordReferences(rootNote, progressionOrKey) {
-    const progression = resolveProgression(progressionOrKey);
-    if (!progression)
-        return [];
-    const chordRootNotes = (0, note_names_js_1.getNoteNamesForRootAndIntervals)(rootNote, progression.chords.map((chord) => chord.degree)).map((noteName) => (0, note_names_js_1.normalizeRootNoteString)(noteName));
-    return progression.chords.flatMap((chord, index) => {
-        const chordRootNote = chordRootNotes[index];
-        if (!chordRootNote)
-            return [];
-        return [{
-                rootNote: chordRootNote,
-                chordName: chordRootNote + chord.quality,
-                noteCollectionKey: (0, mod_js_2.getChordQualityNoteCollectionKey)(chord.quality),
-            }];
-    });
+/**
+ * Returns one chord reference for each authored chord entry in
+ * `progression.chords`.
+ *
+ * This is the "chord changes" view: a chord lasting 2 bars is returned once,
+ * because it is one chord entry/change, while repeated entries are preserved.
+ */
+function getChordProgressionChordChangeReferences(rootNote, progressionOrKey) {
+    return getResolvedChordProgressionChordReferences(rootNote, progressionOrKey).map(({ reference }) => reference);
 }
+/**
+ * Returns each distinct chord reference once, preserving first-seen order from
+ * the chord-change list.
+ */
 function getChordProgressionUniqueChordReferences(rootNote, progressionOrKey) {
     const uniqueReferences = [];
     const seen = new Set();
-    for (const reference of getChordProgressionChordReferences(rootNote, progressionOrKey)) {
+    for (const reference of getChordProgressionChordChangeReferences(rootNote, progressionOrKey)) {
         const key = `${reference.rootNote}:${reference.noteCollectionKey}:${reference.chordName}`;
         if (seen.has(key))
             continue;
@@ -67,6 +90,51 @@ function getChordProgressionUniqueChordReferences(rootNote, progressionOrKey) {
     }
     return uniqueReferences;
 }
+/**
+ * Returns duration-aware chord references grouped by bar.
+ *
+ * Each outer array item is one bar. A 2-bar chord appears in two bar entries,
+ * and a split bar can contain multiple chord references in order.
+ */
+function getChordProgressionChordReferencesByBar(rootNote, progressionOrKey) {
+    const bars = [];
+    let currentBar = [];
+    let remainingBarDuration = 1;
+    const pushCurrentBar = () => {
+        if (currentBar.length > 0) {
+            bars.push(currentBar);
+        }
+        currentBar = [];
+        remainingBarDuration = 1;
+    };
+    for (const { chord, reference } of getResolvedChordProgressionChordReferences(rootNote, progressionOrKey)) {
+        let remainingChordDuration = chord.durationInBars;
+        if (!Number.isFinite(remainingChordDuration) ||
+            remainingChordDuration <= BAR_DURATION_EPSILON) {
+            continue;
+        }
+        while (remainingChordDuration > BAR_DURATION_EPSILON) {
+            currentBar.push(reference);
+            const filledDuration = Math.min(remainingChordDuration, remainingBarDuration);
+            remainingChordDuration -= filledDuration;
+            remainingBarDuration -= filledDuration;
+            if (remainingBarDuration <= BAR_DURATION_EPSILON) {
+                pushCurrentBar();
+            }
+        }
+    }
+    pushCurrentBar();
+    return bars;
+}
+/**
+ * Returns duration-aware chord references in song/practice order.
+ *
+ * This flattens `getChordProgressionChordReferencesByBar`, so a 2-bar chord
+ * appears twice and split bars preserve their left-to-right order.
+ */
+function getChordProgressionSongChordReferences(rootNote, progressionOrKey) {
+    return getChordProgressionChordReferencesByBar(rootNote, progressionOrKey).flat();
+}
 function getChordProgressionTotalDurationInBars(progressionOrKey) {
     const progression = resolveProgression(progressionOrKey);
     if (!progression)