Intervals

An IntervalId names one of the 14 intervals in the catalog, from half steps through the octave. Use resolveIntervalEndpoints to find the exact from/to notes for any interval anchored at a root, or look up semitone distances directly from INTERVAL_DEFINITIONS.

Scale motion vs named intervals

The catalog distinguishes two ways of describing the same semitone distances:

Scale motion: half_step and whole_step resolve between adjacent scale degrees within the major scale (e.g. in C major: E→F is a half step, D→E is a whole step). These are pedagogical step names for diatonic motion.

Named intervals from root: minor_2nd and major_2nd resolve from degree 1 at the given root. A minor 2nd is one semitone above the root (chromatic); a major 2nd is the diatonic 2nd scale degree (two semitones). Same distances as a half step and whole step, but anchored at the tonic rather than mid-scale.

All other catalog entries (minor_3rd through octave) are named intervals from the root using diatonic degree targets, except minor_7th which uses a chromatic upper note like minor_2nd.

import { resolveIntervalEndpoints, Intervals, Notes } from '@playbykey/theory';

// Scale motion: E → F in C major (not from the tonic)
resolveIntervalEndpoints({ root: Notes.C, interval: Intervals.HalfStep });
// { from: 'E', to: 'F', semitones: 1, label: 'Half step (scale motion)' }

// Named interval from root: C → C#
resolveIntervalEndpoints({ root: Notes.C, interval: Intervals.Minor2nd });
// { from: 'C', to: 'C#', semitones: 1, label: 'Minor 2nd (from root)' }

Live Playground

getIntervalSemitones

getIntervalSemitones(interval: IntervalId): number

Returns the semitone distance for a named interval from the catalog.

Result7

resolveIntervalEndpoints

resolveIntervalEndpoints(context: IntervalContext): ResolvedInterval

Resolves the from/to notes for an interval anchored at a root. Scale-motion entries (half_step, whole_step) use adjacent degrees; named intervals (minor_2nd, major_2nd, etc.) anchor from the root.

Result

{
  "from": "C",
  "to": "E",
  "semitones": 4,
  "label": "Major 3rd"
}

Interval Types

IntervalContext: { root: Note; interval: IntervalId }. Passed to resolveIntervalEndpoints to resolve the two notes bounding the interval.

ResolvedInterval: { from: Note; to: Note; semitones: number; label: string }. The resolved endpoints plus the catalog label for the interval.

IntervalDefinition: { label: string; intervalSpec: IntervalSpec }. Describes how an interval is defined relative to scale degrees. See the Constants page for the full INTERVAL_DEFINITIONS catalog.