Constants

Every constant below is exported from @playbykey/theory. The catalog covers the 12 chromatic CHROMATIC_NOTES, the 7 diatonic MODES, the full INTERVAL_DEFINITIONS map, SCALE_DEFINITIONS for derived scale types, and Notations for display mapping. Select inputs to see live values and the exact function call.

Notes

NOTES is the ordered list of all 12 chromatic notes. ENHARMONIC_LABELS maps each accidental note to its flat/sharp display string.

Enharmonic label

Natural - no enharmonic equivalent

ENHARMONIC_LABELS[Notes.C]

Note spelling

getFlats, getEnharmonicLabels, and getSharps respell already-computed sharp Note[] output. parseNote and parseNoteToken accept flat-spelled input (Db, Eb, Gb, Ab, Bb) too; see the Keys & Modes page.

Flat (getFlats)

Db

Enharmonic label (getEnharmonicLabels)

Db/C#

Back to sharp (getSharps)

C#

getFlats([Notes.CSharp])[0] // 'Db'getEnharmonicLabels([Notes.CSharp])[0] // 'Db/C#'getSharps(['Db'])[0] // 'C#'

Diatonic scale spelling

A written scale should use each letter A-G exactly once. For most keys that’s automatic, but a few need a spelling Note alone can’t express - B#, E#, Cb, Fb, or a double sharp/flat.

spellDiatonicScale fixes the spelling of a 7-note scale (major, minor, or any mode) so every letter is used once, correctly. getRootLetter tells it which letter to start from. formatSpelledNote turns a result into a plain string, like F##.

getSpelledAccidentalCount counts the sharps or flats in that corrected spelling, including doubles - the real key signature for keys getKeySignatureCount alone can’t represent correctly.

const notes = getModeNotes(Notes.CSharp, Modes.Ionian)const rootLetter = getRootLetter(Notes.CSharp, 'sharp') // 'C'spellDiatonicScale(notes, rootLetter).map(formatSpelledNote)getSpelledAccidentalCount(notes, rootLetter)

Letter-correct spellingC#, D#, E#, F#, G#, A#, B#

Key signature7 sharps

Modes

MODES describes each of the 7 diatonic modes - name, scale degree, and character. MODE_INTERVALS and MODE_SEMITONE_OFFSETS give the step sizes and absolute offsets from the root.

Ionian

Degree 1

Bright and resolved - the familiar major sound

Step intervals[2, 2, 1, 2, 2, 2, 1]

Semitone offsets[0, 2, 4, 5, 7, 9, 11]

NotesC, D, E, F, G, A, B

MODE_INTERVALS[Modes.Ionian]MODE_SEMITONE_OFFSETS[Modes.Ionian]getModeNotes(Notes.C, Modes.Ionian)

Intervals

INTERVAL_DEFINITIONS maps each of the 14 interval IDs to a label and semitone count. half_step and whole_step describe scale motion between adjacent degrees; minor_2nd and major_2nd are named intervals from the root with the same semitone distances. resolveIntervalEndpoints uses this data to find the actual notes that bound an interval at a given root. See the Intervals page for the full distinction and live resolution.

INTERVAL_DEFINITIONS[Intervals.Perfect5th]  // { label: 'Perfect 5th', semitones: 7 }resolveIntervalEndpoints({ root: Notes.C, interval: Intervals.Perfect5th })

resolveIntervalEndpoints result

{
  "from": "C",
  "to": "G",
  "semitones": 7,
  "label": "Perfect 5th"
}

Scales

SCALE_DEFINITIONS maps each scale kind to a label and how its notes are computed - ScaleTypes now includes MelodicMinor alongside the original 6 types. getScaleNotes uses this to return the correct note set for any root and scale type.

MelodicMinorModes names the 7 melodic minor modes, HarmonicMinorModes names harmonic minor’s supported modes, and BebopScaleTypes names the 3 bebop scale variants - getMelodicMinorModeNotes, getHarmonicMinorModeNotes, and getBebopScaleNotes use these. See the Scales page for the live playground covering all of them.

SCALE_DEFINITIONS[ScaleTypes.Major]getScaleNotes(Notes.C, ScaleTypes.Major)

getScaleNotes resultC, D, E, F, G, A, B

Chords

ChordTypes names the 22 supported chord types (triads, 7ths, 6ths, suspended, 9ths, 11ths, 13ths). CHORD_DEFINITIONS maps each to a label and its semitone-offset shape - getChordNotes uses this to return a chord’s notes for any root. See the Chords page for the live playground.

Progressions

ProgressionIds names the 7 catalog progressions. PROGRESSION_DEFINITIONS maps each to a label and its scale-degree sequence - getProgressionInKey uses this to render a progression’s chords in any key. See the Progressions page for the live playground.

Notation and display

buildNoteMap(root, scaleType) returns one entry per in-scale note with note, scaleDegree (1-based), and semitoneOffset (0–11, distance from root). Notation is left to the consumer - use entry.note for letter labels or String(entry.scaleDegree) for numeric labels.

buildNoteMap(Notes.C, ScaleTypes.Major)

buildNoteMap result

[
  {
    "note": "C",
    "scaleDegree": 1,
    "semitoneOffset": 0
  },
  {
    "note": "D",
    "scaleDegree": 2,
    "semitoneOffset": 2
  },
  {
    "note": "E",
    "scaleDegree": 3,
    "semitoneOffset": 4
  },
  {
    "note": "F",
    "scaleDegree": 4,
    "semitoneOffset": 5
  },
  {
    "note": "G",
    "scaleDegree": 5,
    "semitoneOffset": 7
  },
  {
    "note": "A",
    "scaleDegree": 6,
    "semitoneOffset": 9
  },
  {
    "note": "B",
    "scaleDegree": 7,
    "semitoneOffset": 11
  }
]