Intervals
Calculate and manipulate intervals
Intervals module allow to do distance calculations between notes using intervals, obtain information and do calculations:
import { Interval } from "tonal";
Interval.distance("C4", "G4"); // => "5P"
Interval.invert("2M"); // => "7m"
Interval.simplify("9M"); // => "2M"
Interval.semitones("4P"); // => 5
Interval.add("4P", "2M"); // => "5P"Interval properties
Interval.get
get(name: string) => Interval
Get properties of an interval:
- name: the interval name (number + quality)
- type: "perfectable" | "majorable"
- dir: direction: 1 | -1
- num: the interval number
- q: quality (...| 'dd' | 'd' | 'm' | 'M' | 'A' | ...)
- alt: the quality number as a number
- oct: the number of octaves it spans
- semitones: the number of semitones it spans
- simple: the simplified number
Interval.get("5P"); // => { name: "5P", num: 5, ...}There are some shorthand functions (name, num, semitones, quality):
Interval.name("d4"); // => "4d"
Interval.num("5P"); // => 5
Interval.quality("5P"); // => "P"
Interval.semitones("P4"); // => 5Collections and conversion
Interval.names
names() => string[]
Return a list of (natural) interval names:
Interval.names(); // => ["1P", "2M", "3M", "4P", "5P", "6m", "7m"]Interval.fromSemitones
fromSemitones(semitones: number) => string
Given a number of semitones, returns the interval name:
Interval.fromSemitones(7); // => "5P"
Interval.fromSemitones(-7); // => "-5P"
[0, 1, 2, 3, 4].map(Interval.fromSemitones);Operations
Interval.simplify
simplify(interval: string) => string
Simplify an interval: keep its quality and direction, and reduce its number to an octave or less. An octave stays an octave, so only a unison simplifies to a unison:
Interval.simplify("9M"); // => "2M"
Interval.simplify("2M"); // => "2M"
Interval.simplify("-2M"); // => "-2M"
["8P", "9M", "10M", "11P", "12P", "13M", "14M", "15P"].map(Interval.simplify);
// => [ "8P", "2M", "3M", "4P", "5P", "6M", "7M", "8P" ]Interval.invert
invert(interval: string) => string
Get the interval inversion: the interval that completes the simplified interval to an octave. A unison and an octave invert to each other, compound intervals are simplified first, and the direction is kept:
Interval.invert("3m"); // => "6M"
Interval.invert("2M"); // => "7m"
Interval.invert("1P"); // => "8P"
Interval.invert("9M"); // => "7m"
Interval.invert("-3M"); // => "-6m"Interval.pitchClass
pitchClass(interval: string) => string
Get the pitch class of an interval: the interval within an octave, ascending by letter, that leads to the same pitch class. It ignores octaves and direction, like the distance between two pitch classes:
Interval.pitchClass("10M"); // => "3M"
Interval.pitchClass("-3M"); // => "6m"
Interval.pitchClass("8P"); // => "1P"Interval.negate
negate(interval: string) => string
Get the same interval in the opposite direction:
Interval.negate("3M"); // => "-3M"
Interval.negate("-5P"); // => "5P"Interval.abs
abs(interval: string) => string
Get the ascending version of an interval:
Interval.abs("-3M"); // => "3M"
Interval.abs("3M"); // => "3M"Interval.multiply
multiply(interval: string, times: number) => string
Stack an interval a number of times. A negative number stacks it downwards, and zero gives a unison:
Interval.multiply("5P", 3); // => "13M"
Interval.multiply("2M", 3); // => "4A"
Interval.multiply("3M", -2); // => "-5A"Interval.transposeFifths
transposeFifths(interval: string, fifths: number) => string
Add a number of perfect fifths to an interval. The fifths are stacked (the result is not reduced to an octave), and a negative number subtracts them:
Interval.transposeFifths("4P", 1); // => "8P"
[0, 1, 2, 3, 4].map((fifths) => Interval.transposeFifths("1P", fifths)); // => ["1P", "5P", "9M", "13M", "17M"]
[0, -1, -2].map((fifths) => Interval.transposeFifths("1P", fifths)); // => ["1P", "-5P", "-9M"]Interval.distance
distance(from: string, to: string) => string
Find the interval between two notes.
Interval.distance("C4", "G4"); // => "5P"Interval.add
add(a: string, b: string) => string
Add two intervals:
Interval.add("3m", "5P"); // => "7m"Interval.addTo
addTo(interval: string) => (other: string) => string
A curried version of Interval.add, handy with arrays:
["1P", "2M", "3M"].map(Interval.addTo("5P")); // => ["5P", "6M", "7M"]Interval.subtract
subtract(min: string, sub: string) => string
Subtract two intervals:
Interval.subtract("5P", "3M"); // => "3m"
Interval.subtract("3M", "5P"); // => "-3m"Consonance
Interval.consonance
consonance(interval: string, options?: { consonantFourth?: boolean }) => "perfect" | "imperfect" | "dissonant" | ""
Classify an interval as a perfect consonance, an imperfect consonance or a dissonance:
| Consonance | Intervals |
|---|---|
"perfect" | unison, fifth and octave (1P 5P 8P) |
"imperfect" | major and minor thirds and sixths (3m 3M 6m 6M) |
"dissonant" | seconds, sevenths, the perfect fourth, and every augmented or diminished interval |
Interval.consonance("5P"); // => "perfect"
Interval.consonance("6m"); // => "imperfect"
Interval.consonance("7m"); // => "dissonant"
Interval.consonance("blah"); // => ""Direction and octaves don't change the consonance:
Interval.consonance("-5P"); // => "perfect"
Interval.consonance("10m"); // => "imperfect"
Interval.consonance("-9M"); // => "dissonant"The spelling decides, not the sound. A diminished fourth sounds like a major third, and an augmented fifth like a minor sixth, but they're dissonances:
Interval.consonance("4d"); // => "dissonant"
Interval.consonance("3M"); // => "imperfect"
Interval.consonance("5A"); // => "dissonant"The perfect fourth is a dissonance by default, as it is against the bass in common practice harmony. Pass consonantFourth: true to count it as a perfect consonance, as between upper voices or in early counterpoint:
Interval.consonance("4P"); // => "dissonant"
Interval.consonance("4P", { consonantFourth: true }); // => "perfect"
Interval.consonance("4A", { consonantFourth: true }); // => "dissonant"Interval.isConsonant
isConsonant(interval: string, options?: { consonantFourth?: boolean }) => boolean
Is the interval a perfect or imperfect consonance? It takes the same options as Interval.consonance, and invalid intervals are false:
Interval.isConsonant("6M"); // => true
Interval.isConsonant("-12P"); // => true
Interval.isConsonant("2M"); // => false
Interval.isConsonant("4P"); // => false
Interval.isConsonant("4P", { consonantFourth: true }); // => true