@musodojo/music-theory-data 26.5.0 → 28.0.0

package/README.md

@@ -26,12 +26,11 @@ Have a question, a suggestion, or want to report a bug? Get in touch!
 - ✅ Augmented Variants
 - ✅ Other Note Collections, including notes and dyads
 
-## Available Chord Progression Templates
+## Available Chord Progressions
 
-- ✅ Basic Progressions
-- ✅ Pop Progressions
-- ✅ Blues Progressions
-- ✅ Jazz Progressions
+- ✅ 4-bar foundational loops
+- ✅ 8-bar loops
+- ✅ 12-bar blues
 
 ## Features
 
@@ -177,23 +176,106 @@ console.log(Object.keys(music_theory_data.noteCollections));
 console.log(Object.keys(music_theory_data.groupedNoteCollections));
 // ["diatonicModes", "pentatonicVariants", ...]
 
-// Get a beginner-friendly chord progression template
-const oneFourFive = music_theory_data.chordProgressionTemplates.oneFourFive;
+// Get a chord progression
+const oneSixFourFive = music_theory_data.chordProgressions.oneSixFourFive;
 
-console.log(oneFourFive.primaryName);
-// "One Four Five"
+console.log(oneSixFourFive.primaryName);
+// "I | vi | IV | V"
+
+console.log(oneSixFourFive.chords);
+// [
+//   { degree: "1", quality: "M", durationInBars: 1 },
+//   { degree: "6", quality: "m", durationInBars: 1 },
+//   { degree: "4", quality: "M", durationInBars: 1 },
+//   { degree: "5", quality: "M", durationInBars: 1 },
+// ]
 
 console.log(
-  music_theory_data.getChordProgressionTemplateRomanNames("oneFourFive"),
+  music_theory_data.getChordProgressionChordNames(
+    "C",
+    "oneSixFourFive",
+  ),
 );
-// ["I", "IV", "V"]
+// ["CM", "Am", "FM", "GM"]
 
 console.log(
-  music_theory_data.getChordProgressionTemplateChordNames("C", "oneFourFive"),
+  music_theory_data.getChordProgressionUniqueChordNames(
+    "C",
+    "oneFourOneFiveSplitReturn",
+  ),
 );
 // ["CM", "FM", "GM"]
+
+console.log(
+  music_theory_data.getChordProgressionUniqueChordReferences(
+    "C",
+    "oneFourOneFiveSplitReturn",
+  ),
+);
+// [
+//   { rootNote: "C", chordName: "CM", noteCollectionKey: "major" },
+//   { rootNote: "C", chordName: "FM", noteCollectionKey: "major" },
+//   { rootNote: "C", chordName: "GM", noteCollectionKey: "major" },
+// ]
+
+console.log(
+  music_theory_data.getChordProgressionTotalDurationInBars("twelveBarBlues"),
+);
+// 12
+```
+
+## Note Colors And Chromatic Indexes
+
+Note color collections use 12 chromatic slots. In absolute mode, each index is a
+pitch class where index `0` is C and index `7` is G. In relative mode, each
+index is measured from a musical root where index `0` is the root and index `7`
+is the fifth.
+
+`noteLabelCollections.noteNamesFlat` is the default label set for absolute note
+colors, and `noteLabelCollections.intervalsFlat` is the default label set for
+relative note colors. `ChromaticIndex` is the shared `0`-to-`11` pitch-class
+shape used by chromatic tuples, note labels, root-note integers, and filled
+chromatic interval helpers. `ChromaticMode` is the shared `"absolute"` or
+`"relative"` mode used by note colors and label collections.
+
+Chromatic indexes must be integers. Helpers such as `normalizeChromaticIndex`
+wrap negative or large semitone values into the `0`-to-`11` range, but reject
+fractional or non-finite values.
+
+```ts
+import {
+  colorCollections,
+  getNoteColorIndex,
+  getNoteColorLabels,
+} from "jsr:@musodojo/music-theory-data";
+
+const absoluteIndex = getNoteColorIndex({
+  midi: 67,
+  mode: "absolute",
+});
+console.log(absoluteIndex);
+// 7, the pitch class G
+
+const relativeIndex = getNoteColorIndex({
+  midi: 69,
+  mode: "relative",
+  rootPitchClass: 2,
+});
+console.log(relativeIndex);
+// 7, A as the fifth above D
+
+console.log(getNoteColorLabels(colorCollections.musoDojoRootAndFifth));
+// ["1", "♭2", "2", "♭3", "3", "4", "♭5", "5", "♭6", "6", "♭7", "7"]
 ```
 
+Color values may be hex strings or `null`. A `null` value means there is
+intentionally no semantic color for that pitch or degree; consuming apps should
+choose their own visual fallback through theme or UI settings.
+
+Regular note collection interval arrays remain variable length because chords,
+dyads, arpeggios, and scales have different natural sizes. Helpers that opt into
+`fillChromatic: true` return a fixed 12-slot chromatic tuple.
+
 ## API Documentation
 
 For a full list of all available data, types, and utility functions, please see

package/esm/src/data/chord-progressions/mod.d.ts

@@ -1,66 +1,21 @@
-import type { ChordProgressionTemplateCategory, ChordProgressionTemplateType } from "../../types/chord-progressions";
-import type { ChordQuality } from "../../types/chords";
-import type { NoteCollectionKey } from "../note-collections/mod.js";
-export { basicChordProgressionTemplates } from "./basic.js";
-export { bluesChordProgressionTemplates } from "./blues.js";
-export { jazzChordProgressionTemplates } from "./jazz.js";
-export { popChordProgressionTemplates } from "./pop.js";
-export declare const chordProgressionTemplates: {
-    readonly twoFiveOneMajor: import("../../mod.js").ChordProgressionTemplate;
-    readonly minorTwoFiveOne: import("../../mod.js").ChordProgressionTemplate;
-    readonly rhythmChanges: import("../../mod.js").ChordProgressionTemplate;
-    readonly jazzBluesBasic: import("../../mod.js").ChordProgressionTemplate;
-    readonly twelveBarBlues: import("../../mod.js").ChordProgressionTemplate;
-    readonly dooWop: import("../../mod.js").ChordProgressionTemplate;
-    readonly axisProgression: import("../../mod.js").ChordProgressionTemplate;
-    readonly oneFourFive: import("../../mod.js").ChordProgressionTemplate;
-    readonly oneFive: import("../../mod.js").ChordProgressionTemplate;
-    readonly oneFour: import("../../mod.js").ChordProgressionTemplate;
-    readonly oneOneFiveFive: import("../../mod.js").ChordProgressionTemplate;
-    readonly oneOneFiveFiveSeven: import("../../mod.js").ChordProgressionTemplate;
-    readonly oneFourOneFive: import("../../mod.js").ChordProgressionTemplate;
+import type { ChordProgression } from "../../types/chord-progressions";
+declare const _chordProgressions: {
+    readonly oneOneFiveFive: ChordProgression;
+    readonly oneOneFiveFiveDominant7: ChordProgression;
+    readonly oneOneFourFour: ChordProgression;
+    readonly oneOneFourFive: ChordProgression;
+    readonly oneFourOneFive: ChordProgression;
+    readonly oneSixFourFive: ChordProgression;
+    readonly oneFiveSixFour: ChordProgression;
+    readonly oneSixTwoFive: ChordProgression;
+    readonly sixTwoFiveOne: ChordProgression;
+    readonly majorTwoFiveOne: ChordProgression;
+    readonly minorTwoFiveOne: ChordProgression;
+    readonly oneFourOneFiveSplitReturn: ChordProgression;
+    readonly twelveBarBlues: ChordProgression;
+    readonly twelveBarBluesQuickChange: ChordProgression;
 };
-export type ChordProgressionTemplateKey = keyof typeof chordProgressionTemplates;
-export type ChordProgressionStepNoteCollectionKeyMap = Partial<Record<ChordQuality, NoteCollectionKey>>;
-/** Canonical chord/arpeggio collection keys for chord qualities used by progression steps. */
-export declare const chordProgressionStepNoteCollectionKeys: ChordProgressionStepNoteCollectionKeyMap;
-export declare const groupedChordProgressionTemplates: {
-    readonly basicChordProgressionTemplates: {
-        readonly oneFourFive: import("../../mod.js").ChordProgressionTemplate;
-        readonly oneFive: import("../../mod.js").ChordProgressionTemplate;
-        readonly oneFour: import("../../mod.js").ChordProgressionTemplate;
-        readonly oneOneFiveFive: import("../../mod.js").ChordProgressionTemplate;
-        readonly oneOneFiveFiveSeven: import("../../mod.js").ChordProgressionTemplate;
-        readonly oneFourOneFive: import("../../mod.js").ChordProgressionTemplate;
-    };
-    readonly popChordProgressionTemplates: {
-        readonly dooWop: import("../../mod.js").ChordProgressionTemplate;
-        readonly axisProgression: import("../../mod.js").ChordProgressionTemplate;
-    };
-    readonly bluesChordProgressionTemplates: {
-        readonly twelveBarBlues: import("../../mod.js").ChordProgressionTemplate;
-    };
-    readonly jazzChordProgressionTemplates: {
-        readonly twoFiveOneMajor: import("../../mod.js").ChordProgressionTemplate;
-        readonly minorTwoFiveOne: import("../../mod.js").ChordProgressionTemplate;
-        readonly rhythmChanges: import("../../mod.js").ChordProgressionTemplate;
-        readonly jazzBluesBasic: import("../../mod.js").ChordProgressionTemplate;
-    };
-};
-export type ChordProgressionTemplateGroupKey = keyof typeof groupedChordProgressionTemplates;
-/** Human-readable DisplayName and Description metadata for top-level chord progression groups. */
-export declare const chordProgressionTemplateGroupsMetadata: Record<ChordProgressionTemplateGroupKey, {
-    displayName: string;
-    description: string;
-}>;
-/** Human-readable DisplayName and Description metadata for chord progression categories. */
-export declare const chordProgressionTemplateCategoryMetadata: Record<ChordProgressionTemplateCategory, {
-    displayName: string;
-    description: string;
-}>;
-/** Human-readable DisplayName and Description metadata for chord progression template types. */
-export declare const chordProgressionTemplateTypeMetadata: Record<ChordProgressionTemplateType, {
-    displayName: string;
-    description: string;
-}>;
+export type ChordProgressionKey = keyof typeof _chordProgressions;
+export declare const chordProgressions: Record<ChordProgressionKey, ChordProgression>;
+export {};
 //# sourceMappingURL=mod.d.ts.map

package/esm/src/data/chord-progressions/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../src/src/data/chord-progressions/mod.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,gCAAgC,EAChC,4BAA4B,EAC7B,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,OAAO,EAAE,8BAA8B,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,8BAA8B,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,6BAA6B,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC;AAExD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;CAK5B,CAAC;AAEX,MAAM,MAAM,2BAA2B,GACrC,MAAM,OAAO,yBAAyB,CAAC;AAEzC,MAAM,MAAM,wCAAwC,GAAG,OAAO,CAC5D,MAAM,CAAC,YAAY,EAAE,iBAAiB,CAAC,CACxC,CAAC;AAEF,8FAA8F;AAC9F,eAAO,MAAM,sCAAsC,EACjD,wCAQU,CAAC;AAEb,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;CAKnC,CAAC;AAEX,MAAM,MAAM,gCAAgC,GAC1C,MAAM,OAAO,gCAAgC,CAAC;AAEhD,kGAAkG;AAClG,eAAO,MAAM,sCAAsC,EAAE,MAAM,CACzD,gCAAgC,EAChC;IACE,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB,CAsBO,CAAC;AAEX,4FAA4F;AAC5F,eAAO,MAAM,wCAAwC,EAAE,MAAM,CAC3D,gCAAgC,EAChC;IACE,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB,CAMO,CAAC;AAEX,gGAAgG;AAChG,eAAO,MAAM,oCAAoC,EAAE,MAAM,CACvD,4BAA4B,EAC5B;IACE,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB,CAgBO,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../src/src/data/chord-progressions/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,gCAAgC,CAAC;AA+JxC,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;CAed,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAElE,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,mBAAmB,EAAE,gBAAgB,CACxD,CAAC"}

package/esm/src/data/chord-progressions/mod.js

@@ -1,71 +1,155 @@
-import { basicChordProgressionTemplates } from "./basic.js";
-import { bluesChordProgressionTemplates } from "./blues.js";
-import { jazzChordProgressionTemplates } from "./jazz.js";
-import { popChordProgressionTemplates } from "./pop.js";
-export { basicChordProgressionTemplates } from "./basic.js";
-export { bluesChordProgressionTemplates } from "./blues.js";
-export { jazzChordProgressionTemplates } from "./jazz.js";
-export { popChordProgressionTemplates } from "./pop.js";
-export const chordProgressionTemplates = {
-    ...basicChordProgressionTemplates,
-    ...popChordProgressionTemplates,
-    ...bluesChordProgressionTemplates,
-    ...jazzChordProgressionTemplates,
+function chord(degree, quality, durationInBars) {
+    return {
+        degree,
+        quality,
+        durationInBars,
+    };
+}
+const oneOneFiveFive = {
+    primaryName: "I | I | V | V",
+    chords: [
+        chord("1", "M", 2),
+        chord("5", "M", 2),
+    ],
 };
-/** Canonical chord/arpeggio collection keys for chord qualities used by progression steps. */
-export const chordProgressionStepNoteCollectionKeys = {
-    M: "major",
-    m: "minor",
-    "7": "dominant7",
-    M7: "major7",
-    m7: "minor7",
-    "ø7": "halfDiminished7",
-    "°7": "diminished7",
+const oneOneFiveFiveDominant7 = {
+    primaryName: "I | I | V | V7",
+    chords: [
+        chord("1", "M", 2),
+        chord("5", "M", 1),
+        chord("5", "7", 1),
+    ],
 };
-export const groupedChordProgressionTemplates = {
-    basicChordProgressionTemplates,
-    popChordProgressionTemplates,
-    bluesChordProgressionTemplates,
-    jazzChordProgressionTemplates,
+const oneOneFourFour = {
+    primaryName: "I | I | IV | IV",
+    chords: [
+        chord("1", "M", 2),
+        chord("4", "M", 2),
+    ],
 };
-/** Human-readable DisplayName and Description metadata for top-level chord progression groups. */
-export const chordProgressionTemplateGroupsMetadata = {
-    basicChordProgressionTemplates: {
-        displayName: "Basic",
-        description: "Simple beginner-friendly formulas and playable loops built from foundational harmonic movement.",
-    },
-    popChordProgressionTemplates: {
-        displayName: "Pop",
-        description: "Common songwriting loops used across pop, rock, folk, and related styles.",
-    },
-    bluesChordProgressionTemplates: {
-        displayName: "Blues",
-        description: "Blues forms and dominant-chord progressions, including twelve-bar templates.",
-    },
-    jazzChordProgressionTemplates: {
-        displayName: "Jazz",
-        description: "Functional harmony templates, turnarounds, cadences, and standard jazz forms.",
-    },
+const oneOneFourFive = {
+    primaryName: "I | I | IV | V",
+    chords: [
+        chord("1", "M", 2),
+        chord("4", "M", 1),
+        chord("5", "M", 1),
+    ],
 };
-/** Human-readable DisplayName and Description metadata for chord progression categories. */
-export const chordProgressionTemplateCategoryMetadata = {
-    basic: chordProgressionTemplateGroupsMetadata.basicChordProgressionTemplates,
-    pop: chordProgressionTemplateGroupsMetadata.popChordProgressionTemplates,
-    blues: chordProgressionTemplateGroupsMetadata.bluesChordProgressionTemplates,
-    jazz: chordProgressionTemplateGroupsMetadata.jazzChordProgressionTemplates,
+const oneFourOneFive = {
+    primaryName: "I | IV | I | V",
+    chords: [
+        chord("1", "M", 1),
+        chord("4", "M", 1),
+        chord("1", "M", 1),
+        chord("5", "M", 1),
+    ],
 };
-/** Human-readable DisplayName and Description metadata for chord progression template types. */
-export const chordProgressionTemplateTypeMetadata = {
-    formula: {
-        displayName: "Formula",
-        description: "A reusable harmonic relationship, not necessarily a complete playable loop or song form.",
-    },
-    loop: {
-        displayName: "Loop",
-        description: "A short playable chord progression intended to repeat.",
-    },
-    form: {
-        displayName: "Form",
-        description: "A longer structured progression with named sections or a conventional song form.",
-    },
+const oneSixFourFive = {
+    primaryName: "I | vi | IV | V",
+    chords: [
+        chord("1", "M", 1),
+        chord("6", "m", 1),
+        chord("4", "M", 1),
+        chord("5", "M", 1),
+    ],
 };
+const oneFiveSixFour = {
+    primaryName: "I | V | vi | IV",
+    chords: [
+        chord("1", "M", 1),
+        chord("5", "M", 1),
+        chord("6", "m", 1),
+        chord("4", "M", 1),
+    ],
+};
+const oneSixTwoFive = {
+    primaryName: "I | vi | ii | V",
+    chords: [
+        chord("1", "M", 1),
+        chord("6", "m", 1),
+        chord("2", "m", 1),
+        chord("5", "M", 1),
+    ],
+};
+const sixTwoFiveOne = {
+    primaryName: "vi | ii | V | I",
+    chords: [
+        chord("6", "m", 1),
+        chord("2", "m", 1),
+        chord("5", "M", 1),
+        chord("1", "M", 1),
+    ],
+};
+const majorTwoFiveOne = {
+    primaryName: "iim7 | V7 | Imaj7 | Imaj7",
+    chords: [
+        chord("2", "m7", 1),
+        chord("5", "7", 1),
+        chord("1", "M7", 2),
+    ],
+};
+const minorTwoFiveOne = {
+    primaryName: "iiø7 | V7 | i | i",
+    chords: [
+        chord("2", "ø7", 1),
+        chord("5", "7", 1),
+        chord("1", "m", 2),
+    ],
+};
+const oneFourOneFiveSplitReturn = {
+    primaryName: "I | IV | I | V | I | IV | I V | I",
+    chords: [
+        chord("1", "M", 1),
+        chord("4", "M", 1),
+        chord("1", "M", 1),
+        chord("5", "M", 1),
+        chord("1", "M", 1),
+        chord("4", "M", 1),
+        chord("1", "M", 0.5),
+        chord("5", "M", 0.5),
+        chord("1", "M", 1),
+    ],
+};
+const twelveBarBlues = {
+    primaryName: "12 Bar Blues",
+    chords: [
+        chord("1", "7", 4),
+        chord("4", "7", 2),
+        chord("1", "7", 2),
+        chord("5", "7", 1),
+        chord("4", "7", 1),
+        chord("1", "7", 1),
+        chord("5", "7", 1),
+    ],
+};
+const twelveBarBluesQuickChange = {
+    primaryName: "12 Bar Blues Quick Change",
+    chords: [
+        chord("1", "7", 1),
+        chord("4", "7", 1),
+        chord("1", "7", 2),
+        chord("4", "7", 2),
+        chord("1", "7", 2),
+        chord("5", "7", 1),
+        chord("4", "7", 1),
+        chord("1", "7", 1),
+        chord("5", "7", 1),
+    ],
+};
+const _chordProgressions = {
+    oneOneFiveFive,
+    oneOneFiveFiveDominant7,
+    oneOneFourFour,
+    oneOneFourFive,
+    oneFourOneFive,
+    oneSixFourFive,
+    oneFiveSixFour,
+    oneSixTwoFive,
+    sixTwoFiveOne,
+    majorTwoFiveOne,
+    minorTwoFiveOne,
+    oneFourOneFiveSplitReturn,
+    twelveBarBlues,
+    twelveBarBluesQuickChange,
+};
+export const chordProgressions = _chordProgressions;

package/esm/src/data/chords/mod.d.ts

@@ -1,3 +1,4 @@
+import type { NoteCollectionKey } from "../note-collections/mod.js";
 declare const _triadChordQualities: readonly ["M", "m", "°", "+"];
 declare const _seventhChordQualities: readonly ["M7", "m7", "7", "ø7", "m7♭5", "°7", "m(M7)", "+M7", "M7♯5"];
 declare const _upperCaseRomanNumerals: readonly ["I", "II", "III", "IV", "V", "VI", "VII"];
@@ -21,6 +22,9 @@ export declare const triadChordQualities: readonly Triad[];
 export declare const seventhChordQualities: readonly SeventhChord[];
 /** The complete set of supported chord suffix qualities. */
 export declare const chordQualities: readonly ChordQuality[];
+export type ChordQualityNoteCollectionKeyMap = Record<ChordQuality, NoteCollectionKey>;
+/** Note-collection keys for every supported chord quality. */
+export declare const chordQualityNoteCollectionKeys: ChordQualityNoteCollectionKeyMap;
 /** Roman numeral rendering metadata for each supported chord quality. */
 export declare const chordQualityRomanRenderings: ReadonlyMap<ChordQuality, ChordQualityRomanRendering>;
 /** An ordered array containing the fundamental triad qualities of the diatonic major scale. */
@@ -39,5 +43,6 @@ export declare const melodicMinorSeventhChords: SeventhChord[];
 export declare const upperCaseRomanNumerals: readonly UpperCaseRomanNumeral[];
 /** An array mapping 7 index scale degrees to their corresponding lower-case Roman numerals. */
 export declare const lowerCaseRomanNumerals: readonly LowerCaseRomanNumeral[];
+export declare function getChordQualityNoteCollectionKey(quality: ChordQuality): NoteCollectionKey;
 export {};
 //# sourceMappingURL=mod.d.ts.map

package/esm/src/data/chords/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../src/src/data/chords/mod.ts"],"names":[],"mappings":"AAAA,QAAA,MAAM,oBAAoB,+BAAgC,CAAC;AAE3D,QAAA,MAAM,sBAAsB,wEAUlB,CAAC;AAEX,QAAA,MAAM,uBAAuB,qDAQnB,CAAC;AAEX,QAAA,MAAM,uBAAuB,qDAQnB,CAAC;AAEX,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AACnE,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,YAAY,CAAC;AAEhD,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7E,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7E,MAAM,MAAM,YAAY,GAAG,qBAAqB,GAAG,qBAAqB,CAAC;AAEzE,MAAM,MAAM,UAAU,GAAG,GAAG,YAAY,EAAE,GAAG,GAAG,YAAY,GAAG,KAAK,EAAE,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,GAAG,YAAY,GAAG,YAAY,EAAE,CAAC;AACjE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,EAAE,SAAS,KAAK,EAAyB,CAAC;AAE1E,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB,EAAE,SAAS,YAAY,EACjC,CAAC;AAEzB,4DAA4D;AAC5D,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAGjD,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,2BAA2B,EAAE,WAAW,CACnD,YAAY,EACZ,0BAA0B,CAe1B,CAAC;AAEH,+FAA+F;AAC/F,eAAO,MAAM,cAAc,EAAE,KAAK,EAQxB,CAAC;AAEX,uGAAuG;AACvG,eAAO,MAAM,qBAAqB,EAAE,YAAY,EAQtC,CAAC;AAEX,+FAA+F;AAC/F,eAAO,MAAM,mBAAmB,EAAE,KAAK,EAQ7B,CAAC;AAEX,uGAAuG;AACvG,eAAO,MAAM,0BAA0B,EAAE,YAAY,EAQ3C,CAAC;AAEX,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,EAAE,KAAK,EAQ5B,CAAC;AAEX,sGAAsG;AACtG,eAAO,MAAM,yBAAyB,EAAE,YAAY,EAQ1C,CAAC;AAEX,+FAA+F;AAC/F,eAAO,MAAM,sBAAsB,EAAE,SAAS,qBAAqB,EAC1C,CAAC;AAE1B,+FAA+F;AAC/F,eAAO,MAAM,sBAAsB,EAAE,SAAS,qBAAqB,EAC1C,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../src/src/data/chords/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,QAAA,MAAM,oBAAoB,+BAAgC,CAAC;AAE3D,QAAA,MAAM,sBAAsB,wEAUlB,CAAC;AAEX,QAAA,MAAM,uBAAuB,qDAQnB,CAAC;AAEX,QAAA,MAAM,uBAAuB,qDAQnB,CAAC;AAEX,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AACnE,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,YAAY,CAAC;AAEhD,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7E,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7E,MAAM,MAAM,YAAY,GAAG,qBAAqB,GAAG,qBAAqB,CAAC;AAEzE,MAAM,MAAM,UAAU,GAAG,GAAG,YAAY,EAAE,GAAG,GAAG,YAAY,GAAG,KAAK,EAAE,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,GAAG,YAAY,GAAG,YAAY,EAAE,CAAC;AACjE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAkBD,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,EAAE,SAAS,KAAK,EAAyB,CAAC;AAE1E,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB,EAAE,SAAS,YAAY,EACjC,CAAC;AAEzB,4DAA4D;AAC5D,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAGjD,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG,MAAM,CACnD,YAAY,EACZ,iBAAiB,CAClB,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,8BAA8B,EAAE,gCACZ,CAAC;AAElC,yEAAyE;AACzE,eAAO,MAAM,2BAA2B,EAAE,WAAW,CACnD,YAAY,EACZ,0BAA0B,CAe1B,CAAC;AAEH,+FAA+F;AAC/F,eAAO,MAAM,cAAc,EAAE,KAAK,EAQxB,CAAC;AAEX,uGAAuG;AACvG,eAAO,MAAM,qBAAqB,EAAE,YAAY,EAQtC,CAAC;AAEX,+FAA+F;AAC/F,eAAO,MAAM,mBAAmB,EAAE,KAAK,EAQ7B,CAAC;AAEX,uGAAuG;AACvG,eAAO,MAAM,0BAA0B,EAAE,YAAY,EAQ3C,CAAC;AAEX,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,EAAE,KAAK,EAQ5B,CAAC;AAEX,sGAAsG;AACtG,eAAO,MAAM,yBAAyB,EAAE,YAAY,EAQ1C,CAAC;AAEX,+FAA+F;AAC/F,eAAO,MAAM,sBAAsB,EAAE,SAAS,qBAAqB,EAC1C,CAAC;AAE1B,+FAA+F;AAC/F,eAAO,MAAM,sBAAsB,EAAE,SAAS,qBAAqB,EAC1C,CAAC;AAE1B,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,YAAY,GACpB,iBAAiB,CAEnB"}

package/esm/src/data/chords/mod.js

@@ -28,6 +28,21 @@ const _lowerCaseRomanNumerals = [
     "vi",
     "vii",
 ];
+const _chordQualityNoteCollectionKeys = {
+    M: "major",
+    m: "minor",
+    "°": "diminishedTriad",
+    "+": "augmentedTriad",
+    M7: "major7",
+    m7: "minor7",
+    "7": "dominant7",
+    "ø7": "halfDiminished7",
+    "m7♭5": "halfDiminished7",
+    "°7": "diminished7",
+    "m(M7)": "minorMajor7",
+    "+M7": "augmentedMajor7",
+    "M7♯5": "augmentedMajor7",
+};
 /** The complete set of supported triad chord qualities. */
 export const triadChordQualities = _triadChordQualities;
 /** The complete set of supported seventh chord qualities. */
@@ -37,6 +52,8 @@ export const chordQualities = [
     ...triadChordQualities,
     ...seventhChordQualities,
 ];
+/** Note-collection keys for every supported chord quality. */
+export const chordQualityNoteCollectionKeys = _chordQualityNoteCollectionKeys;
 /** Roman numeral rendering metadata for each supported chord quality. */
 export const chordQualityRomanRenderings = new Map([
     ["M", { numeralCase: "upper", suffix: "" }],
@@ -117,3 +134,6 @@ export const melodicMinorSeventhChords = [
 export const upperCaseRomanNumerals = _upperCaseRomanNumerals;
 /** An array mapping 7 index scale degrees to their corresponding lower-case Roman numerals. */
 export const lowerCaseRomanNumerals = _lowerCaseRomanNumerals;
+export function getChordQualityNoteCollectionKey(quality) {
+    return chordQualityNoteCollectionKeys[quality];
+}

package/esm/src/data/chromatic.d.ts

@@ -0,0 +1,24 @@
+export declare const CHROMATIC_NOTE_COUNT: 12;
+/** A zero-indexed chromatic pitch-class or relative degree slot. */
+export type ChromaticIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11;
+/** How a chromatic index should be interpreted. */
+export type ChromaticMode = "absolute" | "relative";
+/** A fixed 12-slot tuple indexed by chromatic pitch class or relative degree. */
+export type ChromaticTuple<T> = readonly [
+    T,
+    T,
+    T,
+    T,
+    T,
+    T,
+    T,
+    T,
+    T,
+    T,
+    T,
+    T
+];
+export declare const CHROMATIC_INDEXES: ChromaticTuple<ChromaticIndex>;
+/** A variable-length set of chromatic indexes, such as the pitch classes in a scale or dyad. */
+export type ChromaticIndexSet = readonly ChromaticIndex[];
+//# sourceMappingURL=chromatic.d.ts.map

package/esm/src/data/chromatic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chromatic.d.ts","sourceRoot":"","sources":["../../../src/src/data/chromatic.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,EAAG,EAAW,CAAC;AAEhD,oEAAoE;AACpE,MAAM,MAAM,cAAc,GACtB,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,EAAE,GACF,EAAE,CAAC;AAEP,mDAAmD;AACnD,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,UAAU,CAAC;AAEpD,iFAAiF;AACjF,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,SAAS;IACvC,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;CACF,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,cAAc,CAanD,CAAC;AAEX,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,GAAG,SAAS,cAAc,EAAE,CAAC"}

package/esm/src/data/chromatic.js

@@ -0,0 +1,15 @@
+export const CHROMATIC_NOTE_COUNT = 12;
+export const CHROMATIC_INDEXES = [
+    0,
+    1,
+    2,
+    3,
+    4,
+    5,
+    6,
+    7,
+    8,
+    9,
+    10,
+    11,
+];

package/esm/src/data/colors/mod.d.ts

@@ -1,51 +1,62 @@
-export type Color = string | null;
-export type ColorGroup = readonly [
-    Color,
-    Color,
-    Color,
-    Color,
-    Color,
-    Color,
-    Color,
-    Color,
-    Color,
-    Color,
-    Color,
-    Color
-];
-export interface ColorCollection {
-    name: string;
-    description: string;
-    relative: boolean;
-    colors: ColorGroup;
+import { type NoteLabelCollectionKey, type NoteLabelGroup } from "../labels/note-label-collections.js";
+import type { ChromaticMode, ChromaticTuple } from "../chromatic.js";
+export type NoteColorMode = ChromaticMode;
+export type NoteColorValue = string | null;
+export type NoteColorTuple = ChromaticTuple<NoteColorValue>;
+export interface NoteColorCollection {
+    readonly name: string;
+    readonly shortName?: string;
+    readonly description: string;
+    readonly mode: NoteColorMode;
+    readonly labelCollectionKey?: NoteLabelCollectionKey;
+    readonly colors: NoteColorTuple;
 }
+export type Color = NoteColorValue;
+export type ColorGroup = NoteColorTuple;
+export type ColorCollection = NoteColorCollection;
+export type DefaultNoteColorLabelCollectionKeys = Readonly<Record<NoteColorMode, NoteLabelCollectionKey>> & Readonly<{
+    absolute: "noteNamesFlat";
+    relative: "intervalsFlat";
+}>;
+export declare const defaultNoteColorLabelCollectionKeys: DefaultNoteColorLabelCollectionKeys;
+export declare function getDefaultNoteColorLabelCollectionKey(mode: NoteColorMode): NoteLabelCollectionKey;
+export declare function getNoteColorLabelCollectionKey(collection: NoteColorCollection): NoteLabelCollectionKey;
+export declare function getNoteColorLabels(collection: NoteColorCollection): NoteLabelGroup;
 declare const _colorCollections: {
     readonly musoDojo: {
         readonly name: "Muso Dojo Colors";
-        readonly description: "A custom set of colors, designed by Muso Dojo.";
-        readonly relative: false;
+        readonly shortName: "Muso Dojo";
+        readonly description: "A custom absolute chromatic palette designed by Muso Dojo.";
+        readonly mode: "absolute";
+        readonly labelCollectionKey: "noteNamesFlat";
         readonly colors: readonly ["#ED2929", "#9F000F", "#78C7C7", "#00008B", "#FF9933", "#EBEB19", "#286704", "#99CC33", "#660099", "#CC00FF", "#BF6A1F", "#FF9EE6"];
     };
     readonly musoDojoRoot: {
         readonly name: "Muso Dojo Root";
+        readonly shortName: "Root";
         readonly description: "Use the red color from Muso Dojo's colors on just the root note.";
-        readonly relative: true;
+        readonly mode: "relative";
+        readonly labelCollectionKey: "intervalsFlat";
         readonly colors: readonly ["#ED2929", null, null, null, null, null, null, null, null, null, null, null];
     };
     readonly musoDojoRootAndFifth: {
         readonly name: "Muso Dojo Root and Fifth";
+        readonly shortName: "Root and Fifth";
         readonly description: "Use the red-and-green colors from Muso Dojo's colors on the root-and-fifth notes.";
-        readonly relative: true;
+        readonly mode: "relative";
+        readonly labelCollectionKey: "intervalsFlat";
         readonly colors: readonly ["#ED2929", null, null, null, null, null, null, "#99CC33", null, null, null, null];
     };
     readonly boomwhackers: {
         readonly name: "Boomwhackers";
+        readonly shortName: "Boomwhackers";
         readonly description: "The colors used by Boomwhackers.";
-        readonly relative: false;
+        readonly mode: "absolute";
+        readonly labelCollectionKey: "noteNamesFlat";
         readonly colors: readonly ["#E21C48", "#F26622", "#F99D1C", "#FFCC33", "#FFF32B", "#BCD85F", "#62BC47", "#009C95", "#0071BB", "#5E50A1", "#8D5BA6", "#CF3E96"];
     };
 };
 export type ColorCollectionKey = keyof typeof _colorCollections;
-export declare const colorCollections: Record<ColorCollectionKey, ColorCollection>;
+export declare const colorCollections: Record<ColorCollectionKey, NoteColorCollection>;
 export {};
 //# sourceMappingURL=mod.d.ts.map