#API Reference: Music Theory

Modules for scales, chords, keys, intervals, notation, and transposition.

Source: src/lib/music/

---

#intervals.ts

MIDI and pitch math utilities. All MIDI note numbers are concert pitch.

#Note conversion

noteNameToMidi handles sharps by converting to flat equivalents (e.g. C# → Db).

#Frequency conversion

#Interval measurement

#Fraction arithmetic

Fractions [numerator, denominator] represent note durations and offsets without floating-point error.

---

#scales.ts

Complete scale catalog — 35 scales across 7 families.

#SCALE_CATALOG: ScaleDefinition[]

Each ScaleDefinition contains:

• id — Unique identifier (e.g. 'major.dorian')
• intervals — Semitone steps between consecutive degrees (must sum to 12)
• degrees — Degree labels relative to major scale
• chordApplications — Applicable chord qualities
• targetNotes / avoidNotes — Improvisation guidance

#Query functions

#MVP_SCALE_IDS: string[]

20 scale IDs selected for the MVP — 12 must-have + 8 should-have.

---

#chords.ts

Chord definitions and utilities.

#CHORD_DEFINITIONS: Record

18 chord qualities with intervals and display symbols:

#chordTones(rootMidi, quality): number[]

Get chord tones as MIDI notes from a root MIDI note.

#chordSymbol(root, quality): string

Get display symbol (e.g. chordSymbol('D', 'min7') → 'Dm7').

---

#keys.ts

Key signatures, circle of fifths, and scale realization.

#keySignatureAccidentals(key): number

Sharps (positive) or flats (negative) for a major key. E.g. 'Bb' → -2, 'D' → 2.

#circleOfFifths(): PitchClass[]

Returns ['C', 'G', 'D', 'A', 'E', 'B', 'Gb', 'Db', 'Ab', 'Eb', 'Bb', 'F'].

#circleOfFourths(): PitchClass[]

Reverse of circleOfFifths() (without duplicating the starting note).

#getNextKeyInCircle(current, direction?): PitchClass

Return the next key around the circle of fourths. direction is 1 (fourths, default) or -1 (fifths).

#getKeyAtIndex(index: number): PitchClass

Return the key at the given position in the circle of fourths. The index wraps around (negative values and values ≥ 12 are normalized via modulo).

#relativeMajor(minorKey): PitchClass

#relativeMinor(majorKey): PitchClass

#realizeScale(root, intervals): number[]

Returns pitch class indices (0–11) for a scale.

#realizeScaleMidi(root, intervals, lowMidi, highMidi): number[]

Returns all MIDI notes in a scale within a range.

#scalePitchClasses(root, intervals): PitchClass[]

Returns all pitch classes in a scale.

---

#notation.ts

ABC notation generation from Phrase data. Used by NotationDisplay.svelte to render sheet music via abcjs.

#phraseToAbc(phrase, instrument?, defaultLength?): string

Generate an ABC notation string.

Output includes:

• ABC header: X:, T:, M:, L:, K: fields
• Notes with proper ABC octave conventions (uppercase C4, lowercase c5, apostrophes/commas)
• Key-signature-aware accidentals: Notes matching the key signature (e.g., F# in D major) omit the accidental symbol. Natural signs (=) are emitted when a note cancels a key signature accidental. Chromatic alterations outside the key signature display as before.
• Duration modifiers relative to L: value
• Final barline |]

Uses KEY_SIG_ACCIDENTALS lookup table (maps each key to its altered pitch classes) to determine which accidentals are implicit vs. explicit.

#displayPitchClass(pc, keyContext): string

Return a pitch class name spelled for a given key context. Only special-cases F# → Gb when keyContext is a flat key; all other pitch classes pass through unchanged. Used by UI chips that show the current scale's notes.

#midiToDisplayName(midi, useFlats?): string

Convert MIDI to display name (e.g. 60 → 'C4', 58 → 'Bb3'). Defaults to flats.

---

#transposition.ts

Concert/written pitch conversion for transposing instruments.

#concertToWritten(concertMidi, instrument): number

Concert pitch → written pitch. written = concert + transpositionSemitones.

#writtenToConcert(writtenMidi, instrument): number

Written pitch → concert pitch. concert = written - transpositionSemitones.

#concertKeyToWritten(concertKey, instrument): PitchClass

Transpose a key name (e.g. C concert → D for Bb instruments).

#writtenKeyToConcert(writtenKey, instrument): PitchClass

Reverse key transposition.

#transpose(midi, semitones): number

Simple MIDI transposition.

#transposePitchClass(pc, semitones): PitchClass

Transpose a pitch class by semitones.

#pitchClassInterval(from, to): number

Ascending interval in semitones between two pitch classes.

#isInRange(midi, instrument): boolean

Check if a MIDI note is within an instrument's concert range.

---

#key-ordering.ts

Staged 12-key orderings for lick practice. The order a lick cycles through the 12 keys is chosen from a pool of "stages" unlocked at the current tempo.

#Ordering generators

#KeyOrderingStage type

export type KeyOrderingStage = 0 | 1 | 2 | 3 | 4;

#unlockedStages(tempo, minBpm): KeyOrderingStage[]

Return the stages unlocked at tempo:

• Stage 0 always unlocked — circle of fifths from the player's written C.
• Stages 1 and 2 unlock linearly between minBpm and 150 BPM — circle of fifths / chromatic from a random root.
• Stages 3 and 4 unlock together at 150 BPM — whole-tone pair and full shuffle.

#PlanLickKeysArgs interface

interface PlanLickKeysArgs {
  tempo: number;
  minBpm: number;
  instrument: InstrumentConfig;   // resolves "written C" for Stage 0
  rng?: () => number;
}

#planLickKeys(args): PitchClass[]

Pick a stage uniformly at random from unlockedStages(tempo, minBpm), then draw that stage's 12-key ordering. The returned array is always a permutation of all 12 pitch classes.