Table Of Contents

Previous topic

music21.noteworthy.translate

Next topic

music21.roman

music21.pitch

Classes and functions for creating and manipulating pitches, pitch-space, and accidentals. Used extensively by note.py

music21.pitch.convertCentsToAlterAndCents(shift)

Given any floating point value, split into accidental and microtone components.

>>> from music21 import *
>>> pitch.convertCentsToAlterAndCents(125)
(1, 25.0)
>>> pitch.convertCentsToAlterAndCents(-75)
(-0.5, -25.0)
>>> pitch.convertCentsToAlterAndCents(-125)
(-1, -25.0)
>>> pitch.convertCentsToAlterAndCents(-200)
(-2, 0.0)
>>> pitch.convertCentsToAlterAndCents(235)
(2.5, -15.0)
music21.pitch.convertFqToPs(fq)

Utility conversion; does not process internals. Converts a frequency in Hz into a midiNote number. Assumes A4 = 440 Hz

>>> convertFqToPs(440)
69.0
>>> convertFqToPs(261.62556530059862)
60.0
music21.pitch.convertHarmonicToCents(value)

Given a harmonic number, return the total number shift in cents assuming 12 tone equal temperament.

>>> convertHarmonicToCents(8)
3600
>>> [convertHarmonicToCents(x) for x in [5, 6, 7, 8]]
[2786, 3102, 3369, 3600]
>>> [convertHarmonicToCents(x) for x in [16, 17, 18, 19]]
[4800, 4905, 5004, 5098]
>>> [convertHarmonicToCents(x) for x in range(1, 32)]
[0, 1200, 1902, 2400, 2786, 3102, 3369, 3600, 3804, 3986, 4151, 4302, 4441, 4569, 4688, 4800, 4905, 5004, 5098, 5186, 5271, 5351, 5428, 5502, 5573, 5641, 5706, 5769, 5830, 5888, 5945]
music21.pitch.convertNameToPitchClass(pitchName)

Utility conversion: from a pitch name to a pitch class integer between 0 and 11.

>>> convertNameToPitchClass('c4')
0
>>> convertNameToPitchClass('c#')
1
>>> convertNameToPitchClass('d-')
1
>>> convertNameToPitchClass('e--')
2
>>> convertNameToPitchClass('b2##')
1
music21.pitch.convertNameToPs(pitchName)

Utility conversion: from a pitch name to a pitch space number (floating point MIDI pitch values).

>>> from music21 import *
>>> pitch.convertNameToPs('c4')
60.0
>>> pitch.convertNameToPs('c2#')
37.0
>>> pitch.convertNameToPs('d7-')
97.0
>>> pitch.convertNameToPs('e1--')
26.0
>>> pitch.convertNameToPs('b2##')
49.0
>>> pitch.convertNameToPs('c~4')
60.5
music21.pitch.convertPitchClassToNumber(ps)

Given a pitch class or pitch class value, look for strings. If a string is found, replace it with the default pitch class representation.

>>> from music21 import *
>>> pitch.convertPitchClassToNumber(3)
3
>>> pitch.convertPitchClassToNumber('a')
10
>>> pitch.convertPitchClassToNumber('B')
11
>>> pitch.convertPitchClassToNumber('3')
3
music21.pitch.convertPitchClassToStr(pc)

Given a pitch class number, return a string.

>>> convertPitchClassToStr(3)
'3'
>>> convertPitchClassToStr(10)
'A'
music21.pitch.convertPsToFq(ps)

Utility conversion; does not process internals. Converts a midiNote number to a frequency in Hz. Assumes A4 = 440 Hz

>>> from music21 import *
>>> pitch.convertPsToFq(69)
440.0
>>> str(pitch.convertPsToFq(60))
'261.625565301'
>>> str(pitch.convertPsToFq(2))
'9.17702399742'
>>> str(pitch.convertPsToFq(135))
'19912.1269582'
music21.pitch.convertPsToOct(ps)

Utility conversion; does not process internals. Converts a midiNote number to an octave number. Assume C4 middle C, so 60 returns 4

>>> [convertPsToOct(59), convertPsToOct(60), convertPsToOct(61)]
[3, 4, 4]
>>> [convertPsToOct(12), convertPsToOct(0), convertPsToOct(-12)]
[0, -1, -2]
>>> convertPsToOct(135)
10
music21.pitch.convertPsToStep(ps)

Utility conversion; does not process internal representations. Takes in a pitch space floating-point value or a MIDI note number (Assume C4 middle C, so 60 returns 4). Returns a tuple of Step, an Accidental object, and a Microtone object or None.

>>> convertPsToStep(60)
('C', <accidental natural>, (+0c), 0)
>>> convertPsToStep(66)
('F', <accidental sharp>, (+0c), 0)
>>> convertPsToStep(67)
('G', <accidental natural>, (+0c), 0)
>>> convertPsToStep(68)
('G', <accidental sharp>, (+0c), 0)
>>> convertPsToStep(-2)
('B', <accidental flat>, (+0c), 0)
>>> convertPsToStep(60.5)
('C', <accidental half-sharp>, (+0c), 0)
>>> convertPsToStep(61.5)
('C', <accidental one-and-a-half-sharp>, (+0c), 0)
>>> convertPsToStep(62)
('D', <accidental natural>, (+0c), 0)
>>> convertPsToStep(62.5)
('D', <accidental half-sharp>, (+0c), 0)
>>> convertPsToStep(135)
('E', <accidental flat>, (+0c), 0)
>>> convertPsToStep(70)
('B', <accidental flat>, (+0c), 0)
>>> convertPsToStep(70.5)
('B', <accidental half-flat>, (+0c), 0)
music21.pitch.convertStepToPs(step, oct, acc=None, microtone=None)

Utility conversion; does not process internals. Takes in a note name string, octave number, and optional Accidental object. Returns a pitch space value as a floating point MIDI note number.

>>> from music21 import *
>>> pitch.convertStepToPs('c', 4, pitch.Accidental('sharp'))
61.0
>>> pitch.convertStepToPs('d', 2, pitch.Accidental(-2))
36.0
>>> pitch.convertStepToPs('b', 3, pitch.Accidental(3))
62.0
>>> pitch.convertStepToPs('c', 4, pitch.Accidental('half-flat'))
59.5

Pitch

Inherits from: Music21Object, JSONSerializer

class music21.pitch.Pitch(name=None, **keywords)

An object for storing pitch values. All values are represented internally as a scale step (self.step), and octave and an accidental object. In addition, pitches know their pitch space representation (self.ps); altering any of the first three changes the pitch space (ps) representation. Similarly, altering the .ps representation alters the first three.

Two Pitches are equal if they represent the same pitch and are spelled the same. A Pitch is greater than another Pitch if its pitchSpace is greater than the other. Thus C##4 > D-4.

Create a Pitch. Optional parameter name should include a step and accidental character(s) it can also include an octave number (“C#4”, “B–3”, etc.) so long as it’s 0 or higher.

>>> from music21 import *
>>> p1 = pitch.Pitch('a#')
>>> p1
A#
>>> p2 = pitch.Pitch(3)
>>> p2
E-

This is B-double flat in octave 3, not B- in octave -3.

>>> p3 = pitch.Pitch("B--3")
>>> p3.accidental
<accidental double-flat>
>>> p3.octave
3

Just about everything can be specified in keywords too:

>>> p4 = pitch.Pitch(name = 'C', accidental = '#', octave = 7, microtone = -30)
>>> p4.fullName
'C7-sharp (-30c)'

Pitch attributes

Attributes without Documentation: fundamental, implicitAccidental, defaultOctave

Attributes inherited from Music21Object: classSortOrder, hideObjectOnPrint, id, isSpanner, isStream, isWrapper, groups

Pitch properties

name

Gets or sets the name (pitch name with accidental but without octave) of the Pitch.

>>> from music21 import *
>>> p = pitch.Pitch()
>>> p.name = 'C#'
>>> p.implicitAccidental
False
>>> p.ps = 61
>>> p.implicitAccidental
True
>>> p.name
'C#'
>>> p.ps = 58
>>> p.name
'B-'
>>> p.name = 'C#'
>>> p.implicitAccidental
False
nameWithOctave

The pitch name with an octave designation. If no octave as been set, no octave value is returned.

Read only attribute. Set name and octave separately (TODO: Change).

>>> from music21 import *
>>> a = pitch.Pitch('G#4')
>>> a.nameWithOctave
'G#4'
>>> a.name = 'A-'
>>> a.octave = -1
>>> a.nameWithOctave
'A--1'
step

The diatonic name of the note; i.e. does not give the accidental or octave. Is case insensitive.

>>> from music21 import *
>>> a = pitch.Pitch('B-3')
>>> a.step
'B'
>>> a.step = "c"
>>> a.nameWithOctave
'C-3'

Giving a name with an accidental raises a PitchException. Use .name instead. >>> from music21 import * >>> b = pitch.Pitch(‘E4’) >>> b.step = “E-” Traceback (most recent call last): PitchException: Cannot make a step out of ‘E-‘

pitchClass

Returns or sets the integer value for the pitch, 0-11, where C=0, C#=1, D=2...B=11. Can be set using integers (0-11) or ‘A’ or ‘B’ for 10 or 11.

>>> from music21 import *
>>> a = pitch.Pitch('a3')
>>> a.pitchClass
9
>>> dis = pitch.Pitch('d3')
>>> dis.pitchClass
2
>>> dis.accidental = pitch.Accidental("#")
>>> dis.pitchClass
3
>>> dis.pitchClass = 11
>>> dis.pitchClass
11
>>> dis.name
'B'
octave

Returns or sets the octave of the note. Setting the octave updates the pitchSpace attribute.

>>> from music21 import *
>>> a = pitch.Pitch('g')
>>> a.octave is None
True
>>> a.implicitOctave
4
>>> a.ps  ## will use implicitOctave
67.0
>>> a.name
'G'
>>> a.octave = 14
>>> a.octave
14
>>> a.implicitOctave
14
>>> a.name
'G'
>>> a.ps
187.0
midi

Get or set a pitch value in MIDI. MIDI pitch values are like ps values (pitchSpace) rounded to the nearest integer; while the ps attribute will accommodate floats.

>>> from music21 import *
>>> c = pitch.Pitch('C4')
>>> c.midi
60
>>> c.midi =  23.5
>>> c.midi
24

Note that like ps (pitchSpace), MIDI notes do not distinguish between sharps and flats, etc.

>>> dSharp = pitch.Pitch('D#4')
>>> dSharp.midi
63
>>> eFlat = pitch.Pitch('E-4')
>>> eFlat.midi
63

Midi values are constrained to the space 0-127. Higher or lower values will be transposed octaves to fit in this space.

>>> veryHighFHalfFlat = pitch.Pitch("F")
>>> veryHighFHalfFlat.octave = 12
>>> veryHighFHalfFlat.accidental = pitch.Accidental('half-flat')
>>> veryHighFHalfFlat
F`12
>>> veryHighFHalfFlat.ps
160.5
>>> veryHighFHalfFlat.midi
125
>>> notAsHighNote = pitch.Pitch()
>>> notAsHighNote.ps = veryHighFHalfFlat.midi
>>> notAsHighNote
F9

Note that the conversion of improper midi values to proper midi values is done before assigning .ps:

>>> a = pitch.Pitch()
>>> a.midi = -10
>>> a.midi
2
>>> a.ps
2.0
>>> a.implicitAccidental
True
accidental

Stores an optional accidental object contained within the Pitch object. This might return None.

>>> from music21 import *
>>> a = pitch.Pitch('E-')
>>> a.accidental.alter
-1.0
>>> a.accidental.modifier
'-'
>>> b = pitch.Pitch('C4')
>>> b.accidental is None
True
>>> b.accidental = pitch.Accidental('natural')
>>> b.accidental is None
False
>>> b.accidental
<accidental natural>
>>> b = pitch.Pitch('C4')
>>> b.accidental = 1.5
>>> b
C#4(+50c)
>>> b.accidental = 1.65
>>> b
C#~4(+15c)
>>> b.accidental = 1.95
>>> b
C##4(-5c)
alter

Return the pitch alteration as a numeric value, where 1 is the space of one half step and all base pitch values are given by step alone. Thus, the alter value combines the pitch change suggested by the Accidental and the Microtone combined.

>>> from music21 import *
>>> p = pitch.Pitch('g#4')
>>> p.alter
1.0
>>> p.microtone = -25 # in cents
>>> p.alter
0.75
diatonicNoteNum

Returns (or takes) an integer that uniquely identifies the diatonic version of a note, that is ignoring accidentals. The number returned is the diatonic interval above C0 (the lowest C on a Boesendorfer Imperial Grand), so G0 = 5, C1 = 8, etc. Numbers can be negative for very low notes. C4 (middleC) = 29, C#4 = 29, C##4 = 29, D-4 = 30, D4 = 30, etc.

>>> from music21 import *
>>> c = pitch.Pitch('c4')
>>> c.diatonicNoteNum
29
>>> c = pitch.Pitch('c#4')
>>> c.diatonicNoteNum
29
>>> d = pitch.Pitch('d--4')
>>> d.accidental.name
'double-flat'
>>> d.diatonicNoteNum
30
>>> lowc = pitch.Pitch('c1')
>>> lowc.diatonicNoteNum
8
>>> b = pitch.Pitch()
>>> b.step = "B"
>>> b.octave = -1
>>> b.diatonicNoteNum
0
>>> c = pitch.Pitch("C")
>>> c.diatonicNoteNum  #implicitOctave
29
>>> lowDSharp = pitch.Pitch("C#7") # start high !!!
>>> lowDSharp.diatonicNoteNum = 9  # move low
>>> lowDSharp.octave
1
>>> lowDSharp.name
'D#'
freq440

Gets the frequency of the note as if it’s in an equal temperment context where A4 = 440hz. The same as .frequency so long as no other temperments are currently being used.

Since we don’t have any other temperament objects as of alpha 7, this is the same as .frequency always.

frequency

The frequency property gets or sets the frequency of the pitch in hertz. If the frequency has not been overridden, then it is computed based on A440Hz and equal temperament

>>> from music21 import *
>>> a = pitch.Pitch()
>>> a.frequency = 440.0
>>> a.frequency
440.0
>>> a.name
'A'
>>> a.octave
4
>>> a.frequency = 450.0 # microtones are captured
>>> a
A~4(-11c)
fullName

Return the most complete representation of this Pitch, providing name, octave, accidental, and any microtonal adjustments.

>>> from music21 import *
>>> p = pitch.Pitch('A-3')
>>> p.microtone = 33.33
>>> p.fullName
'A3-flat (+33c)'
>>> p = pitch.Pitch('A`7')
>>> p.fullName
'A7-half-flat'
german

Read-only attribute. Returns the name of a Pitch in the German system (where B-flat = B, B = H, etc.) (Microtones raise an error). Note that Ases is used instead of the also acceptable Asas.

>>> from music21 import *
>>> print pitch.Pitch('B-').german
B
>>> print pitch.Pitch('B').german
H
>>> print pitch.Pitch('E-').german
Es
>>> print pitch.Pitch('C#').german
Cis
>>> print pitch.Pitch('A--').german
Ases
>>> p1 = pitch.Pitch('C')
>>> p1.accidental = pitch.Accidental('half-sharp')
>>> p1.german
Traceback (most recent call last):
PitchException: Es geht nicht "german" zu benutzen mit Microtoenen.  Schade!

Note these rarely used pitches:

>>> print pitch.Pitch('B--').german
Heses
>>> print pitch.Pitch('B#').german
His
implicitOctave
Returns the octave of the Pitch, or defaultOctave if octave was never set. To set an octave, use .octave. Default octave is usually 4.
microtone

Sets the microtone object contained within the Pitch object. Microtones must be supplied in cents.

>>> from music21 import *
>>> p = pitch.Pitch('E4-')
>>> p.microtone.cents == 0
True
>>> p.ps
63.0
>>> p.microtone = 33 # adjustment in cents
>>> p
E-4(+33c)
>>> (p.name, p.nameWithOctave) # these representations are unchanged
('E-', 'E-4')
>>> p.microtone = '(-12c' # adjustment in cents
>>> p
E-4(-12c)
>>> p.microtone = pitch.Microtone(-30)
>>> p
E-4(-30c)
musicxml
Provide a complete MusicXML representation. Presently, this is based on
mx
No documentation.
pitchClassString

Returns or sets a string representation of the pitch class, where integers greater than 10 are replaced by A and B, respectively. Can be used to set pitch class by a string representation as well (though this is also possible with pitchClass.

>>> from music21 import *
>>> a = pitch.Pitch('a3')
>>> a.pitchClassString = 'B'
>>> a.pitchClass
11
>>> a.pitchClassString
'B'
ps

The ps property permits getting and setting a pitch space value, a floating point number representing pitch space, where 60.0 is C4, middle C, 61.0 is C#4 or D-4, and floating point values are microtonal tunings (.01 is equal to one cent), so a quarter-tone sharp above C5 is 72.5. Note that the choice of 60.0 for C4 makes it identical to the integer value of 60 for .midi, but .midi does not allow for microtones and is limited to 0-127 while .ps allows for notes before midi 0 or above midi 127.

>>> from music21 import *
>>> a = pitch.Pitch("C4")
>>> a.ps
60.0

Changing the ps value for A will change the step and octave:

>>> a.ps = 45
>>> a
A2
>>> a.ps
45.0

Notice that ps 61 represents both C# and D-flat. Thus “implicitAccidental” will be true after setting our pitch to 61:

>>> a.ps = 61
>>> a
C#4
>>> a.ps
61.0
>>> a.implicitAccidental
True

Microtones are allowed, as are extreme ranges:

>>> b = pitch.Pitch('B9')
>>> b.accidental = pitch.Accidental('half-flat')
>>> b
B`9
>>> b.ps
130.5
stepWithOctave

Returns the pitch step (F, G, etc) with octave designation. If no octave has been set, no octave value is returned.

>>> from music21 import *
>>> a = pitch.Pitch('G#4')
>>> a.stepWithOctave
'G4'
>>> a = pitch.Pitch('A#')
>>> a.stepWithOctave
'A'
unicodeName
Return the pitch name in a unicode encoding.
unicodeNameWithOctave
Return the pitch name with octave with unicode accidental symbols, if available.

Properties inherited from Music21Object: activeSite, beat, beatDuration, beatStr, beatStrength, classes, derivationHierarchy, duration, measureNumber, offset, priority

Properties inherited from JSONSerializer: json

Pitch methods

convertMicrotonesToQuarterTones(inPlace=True)

Convert any Microtones available to quarter tones, if possible.

>>> from music21 import *
>>> p = pitch.Pitch('g3')
>>> p.microtone = 78
>>> p
G3(+78c)
>>> p.convertMicrotonesToQuarterTones(inPlace=True)
>>> p
G#3(-22c)
>>> p = pitch.Pitch('d#3')
>>> p.microtone = 46
>>> p
D#3(+46c)
>>> p.convertMicrotonesToQuarterTones(inPlace=True)
>>> p
D#~3(-4c)
>>> p = pitch.Pitch('f#2')
>>> p.microtone = -38
>>> p.convertMicrotonesToQuarterTones(inPlace=True)
>>> p
F~2(+12c)
convertQuarterTonesToMicrotones(inPlace=True)

Convert any quarter tone Accidentals to Microtones.

>>> from music21 import *
>>> p = pitch.Pitch('G#~')
>>> p, p.microtone
(G#~, (+0c))
>>> p.convertQuarterTonesToMicrotones(inPlace=True)
>>> p.ps
68.5
>>> p, p.microtone
(G#(+50c), (+50c))
>>> p = pitch.Pitch('A`')
>>> p, p.microtone
(A`, (+0c))
>>> x = p.convertQuarterTonesToMicrotones(inPlace=False)
>>> x, x.microtone
(A(-50c), (-50c))
>>> p, p.microtone
(A`, (+0c))
getAllCommmonEnharmonics(alterLimit=2)

Return all common unique enharmonics for a pitch, or those that do not involve more than two accidentals.

>>> from music21 import *
>>> p = pitch.Pitch('c#3')
>>> p.getAllCommmonEnharmonics()
[D-3, B##2]
>>> p = pitch.Pitch('g-6')
>>> p.getAllCommmonEnharmonics()
[F#6, E##6]
>>> p.getAllCommmonEnharmonics(alterLimit=3)
[A---6, F#6, E##6]
getCentShiftFromMidi()

Get cent deviation of this pitch from MIDI pitch.

>>> from music21 import *
>>> p = pitch.Pitch('c~4')
>>> p.midi # midi values automatically round up
61
>>> p.getCentShiftFromMidi()
50
>>> p = pitch.Pitch('c#4')
>>> p.microtone = -25
>>> p.getCentShiftFromMidi()
-25
>>> p = pitch.Pitch('c#~4')
>>> p.getCentShiftFromMidi()
50
>>> p.microtone = 3
>>> p.getCentShiftFromMidi()
53
>>> p = pitch.Pitch('c`4') # quarter tone flat
>>> p.getCentShiftFromMidi()
-50
>>> p.microtone = 3
>>> p.getCentShiftFromMidi()
-47
getEnharmonic(inPlace=False)

Returns a new Pitch that is the(/an) enharmonic equivalent of this Pitch.

N.B.: n1.name == getEnharmonic(getEnharmonic(n1)).name is not necessarily true. For instance: getEnharmonic(E##) => F#; getEnharmonic(F#) => G- getEnharmonic(A–) => G; getEnharmonic(G) => F##

However, for all cases not involving double sharps or flats (and even many that do), getEnharmonic(getEnharmonic(n)) = n

For the most ambiguous cases, it’s good to know that these are the enharmonics: C <-> B#, D <-> C##, E <-> F-; F <-> E#, G <-> F##, A <-> B–, B <-> C-

However, isEnharmonic() for A## and B certainly returns true.

>>> from music21 import *
>>> p = pitch.Pitch('d#')
>>> p.getEnharmonic()
E-
>>> p = pitch.Pitch('e-8')
>>> p.getEnharmonic()
D#8

Other tests:

>>> pitch.Pitch('c-3').getEnharmonic()
B2
>>> pitch.Pitch('e#2').getEnharmonic()
F2
>>> pitch.Pitch('f#2').getEnharmonic()
G-2
>>> pitch.Pitch('c##5').getEnharmonic()
D5
>>> pitch.Pitch('g3').getEnharmonic()
F##3
>>> pitch.Pitch('B7').getEnharmonic()
C-8

Octaveless Pitches remain octaveless:

>>> p = pitch.Pitch('a-')
>>> p.getEnharmonic()
G#
>>> p = pitch.Pitch('B#')
>>> p.getEnharmonic()
C
getHarmonic(number)

Return a Pitch object representing the harmonic found above this Pitch.

>>> from music21 import *
>>> p = pitch.Pitch('a4')
>>> p.getHarmonic(2)
A5
>>> p.getHarmonic(3)
E6(+2c)
>>> p.getHarmonic(4)
A6
>>> p.getHarmonic(5)
C#7(-14c)
>>> p.getHarmonic(6)
E7(+2c)
>>> p.getHarmonic(7)
F#~7(+19c)
>>> p.getHarmonic(8)
A7
>>> p2 = p.getHarmonic(2)
>>> p2
A5
>>> p2.fundamental
A4
>>> p2.transpose('p5', inPlace=True)
>>> p2
E6
>>> p2.fundamental
E5

Or we can iterate over a list of the next 8 odd harmonics:

>>> for i in [9,11,13,15,17,19,21,23]:
...     print p.getHarmonic(i),
B7(+4c) D~8(+1c) F~8(-9c) G#8(-12c) B-8(+5c) C9(-2c) C#~9(+21c) E`9(-22c)

Microtonally adjusted notes also generate harmonics:

>>> q = pitch.Pitch('C4')
>>> q.microtone = 10
>>> q.getHarmonic(2)
C5(+10c)
>>> q.getHarmonic(3)
G5(+12c)

The fundamental is stored with the harmonic.

>>> h7 = pitch.Pitch("A4").getHarmonic(7)
>>> h7
F#~7(+19c)
>>> h7.fundamental
A4
>>> h7.harmonicString()
'7thH/A4'
>>> h7.harmonicString('A3')
'14thH/A3'
>>> h2 = h7.getHarmonic(2)
>>> h2
F#~8(+19c)
>>> h2.fundamental
F#~7(+19c)
>>> h2.fundamental.fundamental
A4
>>> h2.transpose(-24, inPlace=True)
>>> h2
F#~6(+19c)
>>> h2.fundamental.fundamental
A2
getHigherEnharmonic(inPlace=False)

Returns a Pitch enharmonic note that a dim-second above the current note.

>>> from music21 import *
>>> p1 = pitch.Pitch('C#3')
>>> p2 = p1.getHigherEnharmonic()
>>> p2
D-3
>>> p1 = pitch.Pitch('C#3')
>>> p1.getHigherEnharmonic(inPlace=True)
>>> p1
D-3

The method even works for certain CRAZY enharmonics

>>> p3 = pitch.Pitch('D--3')
>>> p4 = p3.getHigherEnharmonic()
>>> p4
E----3

But not for things that are just utterly insane:

>>> p4.getHigherEnharmonic()
Traceback (most recent call last):
AccidentalException: -5 is not a supported accidental type
getLowerEnharmonic(inPlace=False)

returns a Pitch enharmonic note that is a diminished second below the current note If inPlace is set to true, changes the current Pitch.

>>> from music21 import *
>>> p1 = pitch.Pitch('C-3')
>>> p2 = p1.getLowerEnharmonic()
>>> p2
B2
>>> p1 = pitch.Pitch('C#3')
>>> p1.getLowerEnharmonic(inPlace=True)
>>> p1
B##2
getMidiPreCentShift()

If pitch bend will be used to adjust MIDI values, the given pitch values for microtones should go to the nearest non-microtonal pitch value, not rounded up or down. This method is used in MIDI output generation.

>>> from music21 import *
>>> p = pitch.Pitch('c~4')
>>> p.getMidiPreCentShift()
60
>>> p = pitch.Pitch('c#4')
>>> p.getMidiPreCentShift()
61
>>> p.microtone = 65
>>> p.getMidiPreCentShift()
61
>>> p.getCentShiftFromMidi()
65
harmonicAndFundamentalFromPitch(target)

Given a Pitch that is a plausible target for a fundamental, return the harmonic number and a potentially shifted fundamental that describes this Pitch.

>>> from music21 import *
>>> pitch.Pitch('g4').harmonicAndFundamentalFromPitch('c3')
(3, C3(-2c))
harmonicAndFundamentalStringFromPitch(fundamental)

Given a Pitch that is a plausible target for a fundamental, return the harmonic number and a potentially shifted fundamental that describes this Pitch. Return a string representation.

>>> from music21 import *
>>> pitch.Pitch('g4').harmonicAndFundamentalStringFromPitch('c3')
'3rdH/C3(-2c)'
>>> pitch.Pitch('c4').harmonicAndFundamentalStringFromPitch('c3')
'2ndH/C3'
>>> p = pitch.Pitch('c4')
>>> p.microtone = 20 # raise 20
>>> p.harmonicAndFundamentalStringFromPitch('c3')
'2ndH/C3(+20c)'
>>> p.microtone = -20 # lower 20
>>> p.harmonicAndFundamentalStringFromPitch('c3')
'2ndH/C3(-20c)'
>>> p = pitch.Pitch('c4')
>>> f = pitch.Pitch('c3')
>>> f.microtone = -20
>>> p.harmonicAndFundamentalStringFromPitch(f)
'2ndH/C3'
>>> f.microtone = +20
>>> p.harmonicAndFundamentalStringFromPitch(f)
'2ndH/C3'
>>> p = pitch.Pitch('A4')
>>> p.microtone = 69
>>> p.harmonicAndFundamentalStringFromPitch('c2')
'7thH/C2'
>>> p = pitch.Pitch('A4')
>>> p.harmonicAndFundamentalStringFromPitch('c2')
'7thH/C2(-69c)'
harmonicFromFundamental(fundamental)

Given another Pitch as a fundamental, find the harmonic of that pitch that is equal to this Pitch.

Returns a tuple of harmonic number and the number of cents that the first Pitch object would have to be shifted to be the exact harmonic of this fundamental.

Microtones applied to the fundamental are irrelevant, as the fundamental may be microtonally shifted to find a match to this Pitch.

Example: G4 is the third harmonic of C3, albeit 2 cents flatter than the true 3rd harmonic.

>>> from music21 import *
>>> p = pitch.Pitch('g4')
>>> f = pitch.Pitch('c3')
>>> p.harmonicFromFundamental(f)
(3, 2.0)
>>> p.microtone = p.harmonicFromFundamental(f)[1] # adjust microtone
>>> int(f.getHarmonic(3).frequency) == int(p.frequency)
True

The shift from B-5 to the 7th harmonic of C3 is more substantial and likely to be noticed by the audience. To make p the 7th harmonic it’d have to be lowered by 31 cents. Note that the second argument is a float, but because the default rounding of music21 is to the nearest cent, the .0 is not a significant digit. I.e. it might be more like 31.3 cents.

>>> p = pitch.Pitch('B-5')
>>> f = pitch.Pitch('C3')
>>> p.harmonicFromFundamental(f)
(7, -31.0)
harmonicString(fundamental=None)

Return a string representation of a harmonic equivalence.

N.B. this has nothing to do with what string a string player would use to play the harmonic on. (Perhaps should be renamed).

>>> from music21 import *
>>> pitch.Pitch('g4').harmonicString('c3')
'3rdH(-2c)/C3'
>>> pitch.Pitch('c4').harmonicString('c3')
'2ndH/C3'
>>> p = pitch.Pitch('c4')
>>> p.microtone = 20 # raise 20
>>> p.harmonicString('c3')
'2ndH(+20c)/C3'
>>> p.microtone = -20 # lower 20
>>> p.harmonicString('c3')
'2ndH(-20c)/C3'
>>> p = pitch.Pitch('c4')
>>> f = pitch.Pitch('c3')
>>> f.microtone = -20
>>> p.harmonicString(f)
'2ndH(+20c)/C3(-20c)'
>>> f.microtone = +20
>>> p.harmonicString(f)
'2ndH(-20c)/C3(+20c)'
>>> p = pitch.Pitch('A4')
>>> p.microtone = 69
>>> p.harmonicString('c2')
'7thH/C2'
>>> p = pitch.Pitch('A4')
>>> p.harmonicString('c2')
'7thH(-69c)/C2'
inheritDisplay(other)

Inherit display properties from another Pitch, including those found on the Accidental object.

>>> from music21 import *
>>> a = pitch.Pitch('c#')
>>> a.accidental.displayType = 'always'
>>> b = pitch.Pitch('c-')
>>> b.inheritDisplay(a)
>>> b.accidental.displayType
'always'
isEnharmonic(other)

Return True if other is an enharmonic equivalent of self.

>>> from music21 import *
>>> p1 = pitch.Pitch('C#3')
>>> p2 = pitch.Pitch('D-3')
>>> p3 = pitch.Pitch('D#3')
>>> p1.isEnharmonic(p2)
True
>>> p2.isEnharmonic(p1)
True
>>> p3.isEnharmonic(p1)
False
isTwelveTone()

Return True if this Pitch is one of the twelve tones available on a piano keyboard. Returns False if it instead has a non-zero microtonal adjustment or has a quarter tone accidental.

>>> from music21 import *
>>> p = pitch.Pitch('g4')
>>> p.isTwelveTone()
True
>>> p.microtone = -20
>>> p.isTwelveTone()
False
>>> p2 = pitch.Pitch('g~4')
>>> p2.isTwelveTone()
False
lilyNoOctave()
returns the lilypond representation of the pitch (with accidentals) but without octave.
setAccidentalDisplay(value=None)

If this Pitch has an accidental, set its displayStatus, which can be True, False, or None.

>>> from music21 import *
>>> a = pitch.Pitch('a')
>>> past = [pitch.Pitch('a#'), pitch.Pitch('c#'), pitch.Pitch('c')]
>>> a.updateAccidentalDisplay(past, cautionaryAll=True)
>>> a.accidental, a.accidental.displayStatus
(<accidental natural>, True)
>>> a.setAccidentalDisplay(None)
>>> a.accidental, a.accidental.displayStatus
(<accidental natural>, None)
simplifyEnharmonic(inPlace=False)

Returns a new Pitch (or sets the current one if inPlace is True) that is either the same as the current pitch or has fewer sharps or flats if possible. For instance, E# returns F, while A# remains A# (i.e., does not take into account that B- is more common than A#). Useful to call if you ever have an algorithm that might take your piece far into the realm of double or triple flats or sharps. TODO: should be called automatically after ChromaticInterval transpositions.

>>> from music21 import *
>>> p1 = pitch.Pitch("B#5")
>>> p1.simplifyEnharmonic().nameWithOctave
'C6'
>>> p2 = pitch.Pitch("A#2")
>>> p2.simplifyEnharmonic(inPlace = True)
>>> p2
A#2
>>> p3 = pitch.Pitch("E--3")
>>> p4 = p3.transpose(interval.Interval('-A5'))
>>> p4.simplifyEnharmonic()
F#2

Note that pitches with implicit octaves retain their implicit octaves. This might change the pitch space for B#s and C-s.

>>> pList = [pitch.Pitch("B"), pitch.Pitch("C#"), pitch.Pitch("G"), pitch.Pitch("A--")]
>>> [p.simplifyEnharmonic() for p in pList]
[B, C#, G, G]
>>> pList = [pitch.Pitch("C-"), pitch.Pitch("B#")]
>>> [p.ps for p in pList]
[59.0, 72.0]
>>> [p.simplifyEnharmonic().ps for p in pList]
[71.0, 60.0]
transpose(value, inPlace=False)

Transpose the pitch by the user-provided value. If the value is an integer, the transposition is treated in half steps. If the value is a string, any Interval string specification can be provided. Alternatively, a music21.interval.Interval object can be supplied.

>>> from music21 import *
>>> aPitch = pitch.Pitch('g4')
>>> bPitch = aPitch.transpose('m3')
>>> bPitch
B-4
>>> aInterval = interval.Interval(-6)
>>> bPitch = aPitch.transpose(aInterval)
>>> bPitch
C#4
>>> aPitch
G4
>>> aPitch.transpose(aInterval, inPlace=True)
>>> aPitch
C#4
transposeAboveTarget(target, minimize=False)

Given a source Pitch, shift it up octaves until it is above the target. Note: this manipulates src inPlace. If minimize is True, a pitch above the the target will move down to the nearest octave.

>>> from music21 import *
>>> pitch.Pitch('d2').transposeAboveTarget(pitch.Pitch('e4'))
D5
>>> # if already above the target, make no change
>>> pitch.Pitch('d7').transposeAboveTarget(pitch.Pitch('e2'))
D7
>>> # accept the same pitch
>>> pitch.Pitch('d2').transposeAboveTarget(pitch.Pitch('d8'))
D8
>>> # if minimize is True, we go the closest position
>>> pitch.Pitch('d#8').transposeAboveTarget(pitch.Pitch('d2'), minimize=True)
D#2
>>> pitch.Pitch('d7').transposeAboveTarget(pitch.Pitch('e2'), minimize=True)
D3
>>> pitch.Pitch('d0').transposeAboveTarget(pitch.Pitch('e2'), minimize=True)
D3
transposeBelowTarget(target, minimize=False)

Given a source Pitch, shift it down octaves until it is below the target. Note: this manipulates src inPlace. If minimize is True, a pitch below the the target will move up to the nearest octave.

>>> from music21 import *
>>> pitch.Pitch('g5').transposeBelowTarget(pitch.Pitch('c#4'))
G3
>>> # if already below the target, make no change
>>> pitch.Pitch('g#3').transposeBelowTarget(pitch.Pitch('c#6'))
G#3
>>> # accept the same pitch
>>> pitch.Pitch('g#8').transposeBelowTarget(pitch.Pitch('g#1'))
G#1
>>> pitch.Pitch('g#2').transposeBelowTarget(pitch.Pitch('f#8'))
G#2
>>> pitch.Pitch('g#2').transposeBelowTarget(pitch.Pitch('f#8'), minimize=True)
G#7
>>> pitch.Pitch('f#2').transposeBelowTarget(pitch.Pitch('f#8'), minimize=True)
F#8
updateAccidentalDisplay(pitchPast=[], alteredPitches=[], cautionaryPitchClass=True, cautionaryAll=False, overrideStatus=False, cautionaryNotImmediateRepeat=True, isFirstOfMeasure=False)

Given a list of Pitch objects in pitchPast, determine if this pitch’s Accidental object needs to be created or updated with a natural or other cautionary accidental.

Changes to this Pitch object’s Accidental object are made in-place.

The alteredPitches list supplies pitches from a KeySignature object using the alteredPitches property.

If cautionaryPitchClass is True, comparisons to past accidentals are made regardless of register. That is, if a past sharp is found two octaves above a present natural, a natural sign is still displayed.

If overrideStatus is True, this method will ignore any current displayStatus stetting found on the Accidental. By default this does not happen. If displayStatus is set to None, the Accidental’s displayStatus is set.

If cautionaryNotImmediateRepeat is True, cautionary accidentals will be displayed for an altered pitch even if that pitch had already been displayed as altered.

If this Pitch is the first of a Measure, set isFirstOfMeasure to True. The first altered accidental of new Measure will generally always need to be displayed.

>>> from music21 import *
>>> a = pitch.Pitch('a')
>>> past = [pitch.Pitch('a#'), pitch.Pitch('c#'), pitch.Pitch('c')]
>>> a.updateAccidentalDisplay(past, cautionaryAll=True)
>>> a.accidental, a.accidental.displayStatus
(<accidental natural>, True)
>>> b = pitch.Pitch('a')
>>> past = [pitch.Pitch('a#'), pitch.Pitch('c#'), pitch.Pitch('c')]
>>> b.updateAccidentalDisplay(past) # should add a natural
>>> b.accidental, b.accidental.displayStatus
(<accidental natural>, True)
>>> c = pitch.Pitch('a4')
>>> past = [pitch.Pitch('a#3'), pitch.Pitch('c#'), pitch.Pitch('c')]
>>> # will not add a natural because match is pitchSpace
>>> c.updateAccidentalDisplay(past, cautionaryPitchClass=False)
>>> c.accidental == None
True

Methods inherited from Music21Object: addContext(), addLocation(), addLocationAndActiveSite(), freezeIds(), getAllContextsByClass(), getCommonSiteIds(), getCommonSites(), getContextAttr(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSpannerSite(), isClassOrSubclass(), mergeAttributes(), purgeLocations(), removeLocationBySite(), removeLocationBySiteId(), removeNonContainedLocations(), searchParentByAttr(), setContextAttr(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), unfreezeIds(), unwrapWeakref(), wrapWeakref(), write()

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

Accidental

Inherits from: Music21Object, JSONSerializer

class music21.pitch.Accidental(specifier=natural)

Accidental class, representing the symbolic and numerical representation of pitch deviation from a pitch name (e.g., G, B). Two accidentals are considered equal if their names are equal. Accidentals have three defining attributes: a name, a modifier, and an alter. For microtonal specifications, the name and modifier are the same’

>>> from music21 import pitch
>>> a = pitch.Accidental('sharp')
>>> a.name, a.alter, a.modifier
('sharp', 1.0, '#')

Accidental attributes

name
A string name of the Accidental, such as “sharp” or “double-flat”.
modifier
A string symbol used to modify the pitch name, such as “#” or “-” for sharp and flat, respectively.
alter
A signed decimal representing the number of half-steps shifted by this Accidental, such as 1.0 for a sharp and -.5 for a quarter tone flat.
displayLocation
Location of accidental: “normal”, “above”, “below”.
displaySize
Size in display: “cue”, “large”, or a percentage.
displayStyle
Style of display: “parentheses”, “bracket”, “both”.

Attributes inherited from Music21Object: classSortOrder, hideObjectOnPrint, id, isSpanner, isStream, isWrapper

Accidental properties

displayStatus
Determines if this Accidental is to be displayed; can be None (for not set), True, or False.
displayType
Display if first in measure; other valid terms: “always”, “never”, “unless-repeated” (show always unless the immediately preceding note is the same), “even-tied” (stronger than always: shows even if it is tied to the previous note)
fullName

Return the most complete representation of this Accidental.

>>> from music21 import *
>>> a = pitch.Accidental('double-flat')
>>> a.fullName
'double-flat'
lily
From music21 to Lilypond notation.
mx

From music21 to MusicXML

>>> from music21 import *
>>> a = pitch.Accidental()
>>> a.set('half-sharp')
>>> a.alter == .5
True
>>> mxAccidental = a.mx
>>> mxAccidental.get('content')
'quarter-sharp'
unicode
Return a unicode representation of this accidental.

Properties inherited from Music21Object: activeSite, beat, beatDuration, beatStr, beatStrength, classes, derivationHierarchy, duration, measureNumber, offset, priority

Properties inherited from JSONSerializer: json

Accidental methods

set(name)

Provide a value to the Accidental. Strings values, numbers, and Lilypond Abbreviations are all accepted.

>>> from music21 import *
>>> a = pitch.Accidental()
>>> a.set('sharp')
>>> a.alter == 1
True
>>> a = pitch.Accidental()
>>> a.set(2)
>>> a.modifier == "##"
True
>>> a = pitch.Accidental()
>>> a.set(2.0)
>>> a.modifier == "##"
True
>>> a = pitch.Accidental('--')
>>> a.alter
-2.0
inheritDisplay(other)

Given another Accidental object, inherit all the display properites of that object. This is needed when transposing Pitches: we need to retain accidental display properties.

>>> from music21 import *
>>> a = pitch.Accidental('double-flat')
>>> a.displayType = 'always'
>>> b = pitch.Accidental('sharp')
>>> b.inheritDisplay(a)
>>> b.displayType
'always'
isTwelveTone()

Return a boolean if this Accidental describes a twelve-tone pitch.

>>> from music21 import *
>>> a = pitch.Accidental('~')
>>> a.isTwelveTone()
False
>>> a = pitch.Accidental('###')
>>> a.isTwelveTone()
True
lilyDisplayType()
No documentation.

Methods inherited from Music21Object: addContext(), addLocation(), addLocationAndActiveSite(), freezeIds(), getAllContextsByClass(), getCommonSiteIds(), getCommonSites(), getContextAttr(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSpannerSite(), isClassOrSubclass(), mergeAttributes(), purgeLocations(), removeLocationBySite(), removeLocationBySiteId(), removeNonContainedLocations(), searchParentByAttr(), setContextAttr(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), unfreezeIds(), unwrapWeakref(), wrapWeakref(), write()

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

Microtone

class music21.pitch.Microtone(centsOrString=0)

The Microtone object defines a pitch transformation above or below a standard Pitch and its Accidental.

>>> from music21 import *
>>> m = pitch.Microtone(20)
>>> m.cents
20
>>> m.alter
0.2...
>>> m
(+20c)
>>> m.harmonicShift = 3
>>> m
(+20c+3rdH)
>>> m.cents
1922
>>> m.alter
19.2...
>>> m = pitch.Microtone('(-33.333333)')
>>> m
(-33c)
>>> m = pitch.Microtone('33.333333')
>>> m
(+33c)
>>> m.alter
0.3333...

Microtone properties

alter
Return the microtone value in accidental alter values.
cents
Return the microtone value in cents. This is not a settable property. To set the value in cents, simply use that value as a creation argument.
harmonicShift
Set or get the harmonic shift.