@gblp/music-theory

A pitch-class based music theory engine — scales, chords, chord-name parsing, and key detection. No framework dependency: plain TypeScript, works anywhere (Node, a browser, any UI framework).

Extracted from Soloin, which was the first package in The Chords ecosystem to need a real interval-based engine instead of a hardcoded per-key table.

npm install @gblp/music-theory

Usage

Every pitch is a plain number 0–11 (a pitch class, 0 = C). Scales and chords are both "a formula applied to a root" — no hardcoded per-key tables.

import { buildScale, buildChordTones, detectKey, isDiatonic, parseChordName, suggestChordName } from '@gblp/music-theory';

buildScale(0, 'ionian');                          // [0, 2, 4, 5, 7, 9, 11] — C major
buildScale(9, 'aeolian');                         // [9, 11, 0, 2, 4, 5, 7] — A natural minor
buildChordTones(2, 'm7');                         // [2, 5, 9, 0] — Dm7

parseChordName('Am');                             // { raw: 'Am', root: 9, quality: 'minor' }
suggestChordName('Dsu4');                         // 'Dsus4' — only suggests when confident, never guesses on a real ambiguity

detectKey(['Am', 'F', 'C', 'G']);                 // { root: 0, mode: 'major' }
isDiatonic({ root: 9, quality: 'dom7' }, { root: 0, mode: 'major' }); // false — A7 isn't in C major

What's included

• Pitch classes (pitch-class.ts) — parsing note names (naturals/sharps/flats/double-names) to pitch classes and back, with sensible sharp/flat spelling.
• Scales (scales.ts) — the 7 major-scale modes (generated by rotating one formula, not 7 transcribed arrays), major/minor pentatonic, blues. Degree labels (SCALE_DEGREE_LABELS) for every scale, correct per mode (e.g. Lydian's raised 4th is #4, not the enharmonic b5).
• Chords (chords.ts) — major/minor/dim/aug triads, 7th chords, sus chords, with degree labels (CHORD_DEGREE_LABELS).
• Chord parsing (chord-parser.ts) — parseChordName (root + accidental + quality suffix → structured chord), suggestChordName (Levenshtein-based "did you mean" — only suggests when exactly one candidate quality is a confident match, refuses to guess on real ambiguity).
• Key detection (key-detection.ts) — detectKey scores a chord list against all 24 keys' diatonic chords; isDiatonic checks whether one chord belongs to a given key; diatonicChords generates a key's 7 diatonic triads.

Building

npm run build   # tsc → dist/ (ESM + .d.ts)
npm test        # vitest

Part of The Chords ecosystem

Used by @gblp/soloin. Other packages in the family (@gblp/chord-finder, @gblp/circle-of-fifths, @gblp/bass-notes) each still use their own ad-hoc note model — migrating them to this shared engine is a deliberate future step, not assumed by this package's design.