Skip to content
PlayByKeyPlayByKeyMusic Theory Engine

@playbykey/theory

@playbykey/theory is a zero-dependency npm package for computing scales, modes, chords, progressions, transposition, MIDI/frequency conversions, key relationships, and note display maps.

The music theory engine powering PlayByKey, a free interactive music theory learning tool.

Music theory relationships, resolved deterministically through fixed interval and scale-degree relationships.

Note notation

Section titled “Note notation”

The package represents notes with one canonical sharp spelling (C#, not Db) to keep the Note type safe and unambiguous. Flats are fully supported:

  • Input: parseNote/parseNoteToken accept flat-spelled note names (Db, Eb, Gb, Ab, Bb), normalized to the canonical sharp spelling.
  • Output: getFlats/getEnharmonicLabels respell computed output as flats or combined enharmonic labels.

Installation

Section titled “Installation”
Terminal window
npm install @playbykey/theory

Quickstart

Section titled “Quickstart”

Written in TypeScript with strict mode - every export is fully typed, no any. Import types directly: import type { Note, ModeName } from '@playbykey/theory';

import { getModeNotes, getParentScaleModes } from '@playbykey/theory';


// Get all notes in D Dorian
const notes = getModeNotes('D', 'dorian');
console.log(notes); // ['D', 'E', 'F', 'G', 'A', 'B', 'C']


// Find the parent major key
const parentModes = getParentScaleModes('D', 'dorian');
const parent = parentModes.find((m) => m.mode === 'ionian');
console.log(parent?.root); // 'C'
import {
  getModeNotes,
  getFlats,
  getEnharmonicLabels,
  getSharps,
} from '@playbykey/theory';


// Sharp-spelled by default
const notes = getModeNotes('C#', 'aeolian');
console.log(notes); // ['C#', 'D#', 'E', 'F#', 'G#', 'A', 'B']


// Respell as flats or combined enharmonic labels
console.log(getFlats(notes)); // ['Db', 'Eb', 'E', 'Gb', 'Ab', 'A', 'B']
console.log(getEnharmonicLabels(notes)); // ['Db/C#', 'Eb/D#', 'E', 'Gb/F#', 'Ab/G#', 'A', 'B']


// getSharps normalizes flat-spelled notes back to canonical sharps
console.log(getSharps(['Db', 'Eb', 'Gb'])); // ['C#', 'D#', 'F#']

What’s in the package

Section titled “What’s in the package”
Category What it covers Page
Keys & Modes Scales, modes, key relationships, note utilities Keys & Modes
Intervals Interval catalog, semitone lookup, endpoint resolution Intervals
Scales Blues, harmonic minor, melodic minor, pentatonic, bebop, derived scales Scales
Chords Chord notes, diatonic triads, inversions, chord detection (22 chord types) Chords
Progressions 7 catalog progressions, roman numeral labeling Progressions
Transposition Shift a set of notes between keys Transposition
MIDI & Frequency Convert between notes, MIDI numbers, and Hz frequencies MIDI & Frequency
Constants All exported constants and their values Constants