Skip to Content
Tonal
Chord and scales

Scales

@tonaljs/scale on npm

Work with scales

Try it: Scale chords. Pick a tonic and any of 92 scales to see the chord on each degree: triads, sevenths, or chords stacked in fourths or seconds.

@tonaljs/scale is a collection of functions to create and manipulate musical scales

import { Scale } from "tonal";

Scale.get("c5 pentatonic").notes; // => ["C5", "D5", "E5", "G5", "A5"]

Scale properties

Scale.get

get(name: string) => Scale

Get a scale from a scale name. Scale.get accepts tonics in the scale name and returns a scale type with two more properties: tonic and notes:

Scale.get("c5 pentatonic");
// =>
// {
//   empty: false,
//   name: "C5 major pentatonic",
//   type: "major pentatonic",
//   tonic: "C5",
//   notes: ["C5", "D5", "E5", "G5", "A5"],
//   intervals: ["1P", "2M", "3M", "5P", "6M"],
//   aliases: ["pentatonic"],
//   setNum: 2708,
//   chroma: "101010010100",
//   normalized: "100101001010"
// }

Scale.tokenize

tokenize(name: string) => [string, string]

Split a scale name into its tonic and scale type. It doesn't check that the scale type exists:

Scale.tokenize("C mixolydian"); // => ["C", "mixolydian"]
Scale.tokenize("C4 major"); // => ["C4", "major"]
Scale.tokenize("anything is valid"); // => ["", "anything is valid"]

Scale notes

Scale.degrees

degrees(scaleName: string) => (degree: number | string) => string

Scale.degrees returns a function to get a note name from a scale degree:

const c4major = Scale.degrees("C4 major");
c4major(1); // => "C4"
c4major(2); // => "D4"
c4major(8); // => "C5"
c4major(-1); // => "B3"
c4major(-3); // => "G3"
c4major(-7); // => "C3"

Bear in mind that degree numbers starts with 1 and 0 returns an empty string:

c4major(0); // => ""

Because it returns a function, it's handy to be used with map (and similar functions):

[1, 2, 3].map(Scale.degrees("C major")); // => ["C", "D", "E"]
[1, 2, 3].map(Scale.degrees("C4 major")); // => ["C4", "D4", "E4"]
[-1, -2, -3].map(Scale.degrees("C major")); // => ["B", "A", "G"]

Notice that it uses octaves if the scale tonic has an octave or pitch classes (octaveless notes) otherwise.

A degree can also be a string with accidentals after the number, to get notes outside the scale. The note keeps the letter of the scale degree, so it's spelled by interval:

const cMajor = Scale.degrees("C major");
cMajor("7b"); // => "Bb"
cMajor("4#"); // => "F#"
cMajor("-2b"); // => "Ab" (the 2nd degree below the tonic, lowered)
Scale.degrees("A major")("7b"); // => "G" (not F##)

The number counts scale notes, so "7b" is the 7th note of the scale, lowered. In a scale that isn't major it's not a minor seventh: Scale.degrees("D dorian")("3#") is "F#", and in C major pentatonic the 7th note is D, so "7b" is "Db". The accidentals go after the number so that a scale step can't be mixed up with an interval name like "b7" (the minor seventh, as in Chord.noteOf): cMajor("b7") is "".

See Chord.degrees

See https://en.wikipedia.org/wiki/Degree_(music)

Scale.steps

steps(scaleName: string) => (step: number | string) => string

Same as Scale.degrees but 0 is tonic. It plays better with ranges:

import { Range, Scale } from "tonal";

Range.numeric([-3, 3]).map(Scale.steps("C4 major"));
// => ["G3", "A3", "B3", "C4", "D4", "E4", "F4"]

Steps take accidentals too: Scale.steps("C4 major")("6b") is "Bb4".

A melody written as scale steps can be played in any scale:

const melody = [0, 2, 4, "3#", 4, 7, 6, 4];
melody.map(Scale.steps("C4 major"));
// => ["C4", "E4", "G4", "F#4", "G4", "C5", "B4", "G4"]
melody.map(Scale.steps("D4 dorian"));
// => ["D4", "F4", "A4", "G#4", "A4", "D5", "C5", "A4"]

Scale.transposeBySteps

transposeBySteps(scaleName: string, note: string, steps: number) => string

Transpose a note of the scale by a number of scale steps (up, or down if negative):

Scale.transposeBySteps("C major", "E4", 2); // => "G4"
Scale.transposeBySteps("C major", "E4", -3); // => "B3"
Scale.transposeBySteps("C major", "E4", 7); // => "E5"
Scale.transposeBySteps("C major", "E", 2); // => "G" (pitch classes work too)

The note is compared by pitch, so an enharmonic spelling works, and the result is spelled as in the scale:

Scale.transposeBySteps("C major", "B#3", 1); // => "D4"

A note that isn't in the scale gives an empty string. Use Scale.nearest to move it into the scale first:

Scale.transposeBySteps("C major", "F#4", 1); // => ""
Scale.transposeBySteps("C major", Scale.nearest("C major", "F#4"), 1); // => "A4"

Scale.nearest

nearest(scaleName: string, note: string) => string

Find the scale note closest to a note, by pitch. A note halfway between two scale notes goes up, whatever its spelling, as in Midi.pcsetNearest:

Scale.nearest("C major", "F#4"); // => "G4"
Scale.nearest("C major", "Gb4"); // => "G4"
Scale.nearest("C minor pentatonic", "D4"); // => "Eb4"
Scale.nearest("C major", "Eb"); // => "E"

The result is spelled as in the scale (Scale.nearest("C major", "Cb4") is "B3"), and a scale note gives itself back.

Scale.scaleNotes

scaleNotes(notes: string[]) => string[]

Given an array of notes, return an array of sorted note names starting from the first note name of the input array.

// Always start with the first note of the input array
Scale.scaleNotes(["D4", "c#5", "A5", "F#6"]); // => ["D", "F#", "A", "C#"]
// Remove duplicates
Scale.scaleNotes(["C4", "c3", "C5", "C4", "c4"]); // => ["C"]

Scale.rangeOf

rangeOf(scale: string | string[]) => (from: string, to: string) => string[]

Scale.rangeOf returns a function to create scale ranges:

const range = Scale.rangeOf("C pentatonic");
range("C4", "C5"); // => ["C4", "D4", "E4", "G4", "A4", "C5"]

Please note that the scale name must have tonic:

const range = Scale.rangeOf("pentatonic");
range("C4", "C5"); // => []

This function also works with a collection of notes:

const range = Scale.rangeOf(["C", "Db", "G"]);
range("C4", "C5"); // => ["C4", "Db4", "G4", "C5"]

Finding scales

Scale.names

names() => string[]

List all known scale names. Same as ScaleType.names()

See scale-type

Scale.detect

detect(notes: string[], options: { tonic?: string, match?: "fit" | "exact" }) => string[]

Find all scales that first a collection of notes with a given tonic:

Scale.detect(["C", "D", "E", "F", "G", "A", "B"]);
// => ["C major", "C bebop", "C bebop major",
//     "C ichikosucho",  "C chromatic"];

You can pass an optional tonic (otherwise first note will be used):

Scale.detect(["C", "D", "E", "F", "G", "A", "B"], { tonic: "A" });
// => [ 'A minor', 'A minor bebop', 'A chromatic' ]

You can ask just the exact match:

Scale.detect(["D", "E", "F#", "A", "B"], { match: "exact" });
// => ["D major pentatonic"]
Scale.detect(["D", "E", "F#", "A", "B"], { match: "exact", tonic: "B" });
// => ["B minor pentatonic"]

Relationships

Scale.chords

chords(scale: string, options?: { size?: number, step?: number }) => { degree: number, notes: string[], symbol: string }[]

Get the chord built on each degree of a scale, by stacking scale notes. size is the number of notes (3 by default: triads) and step the scale steps between them (2 by default: thirds; 3 for fourths, 1 for seconds). It works for any scale with a tonic:

Scale.chords("C major").map((c) => c.symbol);
// => ["C", "Dm", "Em", "F", "G", "Am", "Bdim"]
Scale.chords("C major", { size: 4 })[6];
// => { degree: 7, notes: ["B", "D", "F", "A"], symbol: "Bm7b5" }
Scale.chords("C melodic minor", { size: 4 }).map((c) => c.symbol);
// => ["CmMaj7", "Dm7", "Ebmaj7#5", "F7", "G7", "Am7b5", "Bm7b5"]

With an octave in the tonic, the notes have octaves:

Scale.chords("C4 major").map((c) => c.notes);
// => [["C4", "E4", "G4"], ["D4", "F4", "A4"], ["E4", "G4", "B4"], ["F4", "A4", "C5"],
//     ["G4", "B4", "D5"], ["A4", "C5", "E5"], ["B4", "D5", "F5"]]

The symbol is the chord type whose intervals spell the notes: Eb G B D is Ebmaj7#5, not EbM7b6. When no type spells them, it's a type with the same notes over the same root, which can spell a note differently (the diminished scale's Eb Gb A is Ebdim). When no chord type has those notes, the symbol is "" and the notes are still there:

Scale.chords("C major", { step: 3 }).map((c) => c.notes);
// => [["C", "F", "B"], ["D", "G", "C"], ...]   (symbols are "")
Scale.chords("C major", { size: 4, step: 3 })[1];
// => { degree: 2, notes: ["D", "G", "C", "F"], symbol: "Dquartal" }

A major triad is written without quality ("C"), as in Key. The chords of major and minor scales are the ones in Key and Mode, except the melodic minor tonic: Scale.chords stacks thirds (CmMaj7), while Key.minorKey("C").melodic.chords lists Cm6, as used in jazz.

Scales with more than seven notes (bebop, octatonic) or fewer (pentatonic) give stacks that may have no name. To get every chord type that fits a scale, see Scale.scaleChords.

Scale.scaleChords

scaleChords(scale: string) => string[]

Get all chords that fits a given scale:

Scale.scaleChords("pentatonic");
// => ["5", "M", "6", "sus2", "Madd9"]

Scale.extended

extended(scale: string) => string[]

Get all scales names that has the same notes and at least one more:

Scale.extended("major");
// => ["bebop", "bebop major", "ichikosucho", "chromatic"]

Scale.reduced

reduced(scale: string) => string[]

Find all scales names that are a subset of the given one (less notes but all from the given scale)

Scale.reduced("major");
// => ["major pentatonic", "ionian pentatonic", "ritusen"]

Scale.modeNames

modeNames(name: string) => [string, string][]

Find mode names (if any) of a given scale:

Scale.modeNames("C pentatonic"); // => [
//    ["C", "major pentatonic"],
//    ["D", "egyptian"],
//    ["E", "malkos raga"],
//    ["G", "ritusen"],
//    ["A", "minor pentatonic"]
//  ]

On this page