User’s Guide: Chapter 18: Intervals

Intervals, or distances in pitch space between two pitches, are fundamental concepts of music theory, dating back at least to Ancient Greece, and are thus fundamental concepts in music21 as well.

Different forms of music theory analysis, such as tonal theory, modal theory, and chromatic (atonal) theory use different kinds of intervals. Thus music21 has a collection of interval classes that can be used in different situations. They are all found in the interval module, which also contains some handy tools for creating and comparing intervals. This chapter of the User’s Guide explains how to create and use Interval objects.

The Interval Class

We’re going to break from the tradition of starting with the simplest objects and begin with the most flexible but also complex object, simply called Interval, since if you’re going to learn about even a single Interval, it might as well be the most useful one.

We can create an Interval object by giving an abbreviation for the interval as a string. For instance, if we want to model a perfect fifth, we’ll use the string "P5":

i = interval.Interval('P5')
 <music21.interval.Interval P5>

Now we can see some properties of Interval objects:

 'Perfect Fifth'

Here’s a rule that assumes a musical context from the late fourteenth century to the end of the nineteenth century:


What do we need to make this interval add up to an octave? That’s the complement:

 <music21.interval.Interval P4>

The .intervalClass of an Interval of the number of semitones of the smaller of the interval or its complement:


A cent is 1/100th of a semitone:


We can get a descending form of the Interval with the .reverse() method:

 <music21.interval.Interval P-5>

Let’s suppose that the interval is the distance between B4 and some other note, what note would that be?

i.noteStart = note.Note('B4')
 <music21.note.Note F#>

Or we can use this interval to transpose any given Note:

 <music21.note.Note G>

Or we can use intervals to transpose pitches:

 <music21.pitch.Pitch G5>

Note that Pitch, Note, Chord, and Stream objects all have a .transpose() method. These methods take Interval objects as arguments (or, if given something else such as a string, the methods try to automatically create an Interval):

 <music21.pitch.Pitch B3>
chord.Chord("F A C").transpose(i)
 <music21.chord.Chord C E G>
s = converter.parse('tinyNotation: 4/4 c4 d e8 f# g4')
s2 = s.transpose(i)

All intervals have properties called “simpleName” and “semiSimpleName” that become useful for reducing compound intervals (those over an octave) to smaller forms.

i2 = interval.Interval('P-12')

For most intervals, simple and semiSimple mean the same thing, but while simple will reduce an octave to a unison, semiSimple treats octaves as distinct intervals. There are certain theories where we want to consider, say, parallel octaves and parallel unisons differently (or at least display a different message to the user), but where we don’t care about the difference between a third and a tenth:

p8 = interval.Interval('P8')
m10 = interval.Interval('m10')
(p8.simpleNiceName, m10.simpleNiceName)
 ('Perfect Unison', 'Minor Third')
(p8.semiSimpleNiceName, m10.semiSimpleNiceName)
 ('Perfect Octave', 'Minor Third')

Note that capitalization makes a difference in determining Major and minor:

 'Minor Third'
 'Major Third'

Creating diminished and Augmented intervals is as simple as using “d” and “A” in the string:

 'Diminished Fifth'
 'Augmented Fourth'

And, yes, multiple letters can get certain obscure intervals:

for intName in ['d5', 'dd5', 'ddd5', 'A4', 'AA4', 'AAA4']:
    iTemp = interval.Interval(intName)
 Diminished Fifth
 Doubly-Diminished Fifth
 Triply-Diminished Fifth
 Augmented Fourth
 Doubly-Augmented Fourth
 Triply-Augmented Fourth

Up to a reasonable limit:

 'Quadruply-Diminished Fifth'
 <music21.pitch.Pitch G----4>
except TypeError:
    print("Can't do five ds!")
 Can't do five ds!

Other ways of constructing Interval objects

The method of creating an interval from a string such as “A4” or “d5” is great if you know the interval’s name in advance. But what if you don’t? Fortunately, there are some other great ways to create them.

First, if you have two Note or Pitch objects, pass them into the Interval constructor as the first and second elements:

e = note.Note('E4')
a = note.Note('A4')
p4 = interval.Interval(e, a)
 'Perfect Fourth'

Or, you can create intervals from an integer, representing the number of half-steps:

 <music21.interval.Interval P5>
for semitones in range(14):
    tempInt = interval.Interval(semitones)
    print(semitones, tempInt.niceName)
 0 Perfect Unison
 1 Minor Second
 2 Major Second
 3 Minor Third
 4 Major Third
 5 Perfect Fourth
 6 Diminished Fifth
 7 Perfect Fifth
 8 Minor Sixth
 9 Major Sixth
 10 Minor Seventh
 11 Major Seventh
 12 Perfect Octave
 13 Minor Ninth

Now, music theory geeks will wonder, how does music21 know that six semitones is a “Diminished Fifth” and not an Augmented Fourth? (Or for that matter, that three semitones is a Minor Third and not an Augmented Second or Triply-Augmented Unison?)

The answer is that it takes a good guess, but it records that the “diatonic interval” (that is “Diminished Fifth,” etc.) is just a guess, or is “implicit”:

sixSemis = interval.Interval(6)
d5 = interval.Interval('d5')
(sixSemis.implicitDiatonic, d5.implicitDiatonic)
 (True, False)

This distinction makes a difference if we use these two interval objects to transpose a pitch. Take the pitch “G flat”. A diminished fifth above it is “D double flat”, but if most of us were inclined to think about “a tritone above G flat” we’d probably think of C. The implicitDiatonic flag allows the six-semitone interval to make these sorts of intelligent decisions, while the interval that was explicitly specified to be a diminished fifth will do exactly what is asked (so long as it doesn’t go to more than quadruple flat or sharp):

 <music21.pitch.Pitch C>
 <music21.pitch.Pitch D-->

We can create new intervals by adding existing Intervals together:

i1 = interval.Interval('P5')
i2 = interval.Interval('M3')
i3 = interval.add([i1, i2])
 <music21.interval.Interval M7>

Here’s a nice way of making sure that a major scale actually does repeat at an octave (and a demo that “W” and “H” are synonyms for whole and half steps; and that interval.add() can automatically convert strings to Intervals:

interval.add(["W", "W", "H", "W", "W", "W", "H"])
 <music21.interval.Interval P8>

Or one can create new intervals by subtracting old ones:

interval.subtract([i1, i2])
 <music21.interval.Interval m3>

Subtraction, of course, is not commutative:

iDown = interval.subtract([i2, i1])
 'Descending Minor Third'

Intervals are returned by several analysis routines in music21. For instance, if you want to know the range from the lowest to the highest note in a piece:

s = converter.parse('4/4 c4 d e f# g# a# g f e1', format="tinyNotation")
 <music21.interval.Interval A6>
a6 = s.analyze('range')