music21.key¶
This module defines objects for representing key signatures as well as key
areas. The KeySignature
is used in
Measure
objects for defining notated key signatures.
The Key
object is a fuller representation not just of
a key signature but also of the key of a region.
Functions¶
-
music21.key.
convertKeyStringToMusic21KeyString
(textString)¶ Utility function to change strings in the form of “Eb” to “E-” (for E-flat major) and leaves alone proper music21 strings (like “E-” or “f#”). A little bit complex because of parsing bb as B-flat minor and Bb as B-flat major.
>>> key.convertKeyStringToMusic21KeyString('Eb') 'E-' >>> key.convertKeyStringToMusic21KeyString('f#') 'f#' >>> key.convertKeyStringToMusic21KeyString('bb') 'b-' >>> key.convertKeyStringToMusic21KeyString('Bb') 'B-' >>> key.convertKeyStringToMusic21KeyString('b#') 'b#' >>> key.convertKeyStringToMusic21KeyString('c') 'c'
-
music21.key.
pitchToSharps
(value, mode=None)¶ Given a pitch or
music21.pitch.Pitch
object, return the number of sharps found in that mode.The mode parameter can be ‘major’, ‘minor’, or most of the common church/jazz modes (‘dorian’, ‘mixolydian’, etc.) including Locrian.
If mode is omitted or not found, the default mode is major.
(extra points to anyone who can find the earliest reference to the Locrian mode in print. David Cohen and I (MSC) have been looking for this for years).
>>> key.pitchToSharps('c') 0 >>> key.pitchToSharps('c', 'minor') -3 >>> key.pitchToSharps('a', 'minor') 0 >>> key.pitchToSharps('d') 2 >>> key.pitchToSharps('e-') -3 >>> key.pitchToSharps('a') 3 >>> key.pitchToSharps('e', 'minor') 1 >>> key.pitchToSharps('f#', 'major') 6 >>> key.pitchToSharps('g-', 'major') -6 >>> key.pitchToSharps('c#') 7 >>> key.pitchToSharps('g#') 8 >>> key.pitchToSharps('e', 'dorian') 2 >>> key.pitchToSharps('d', 'dorian') 0 >>> key.pitchToSharps('g', 'mixolydian') 0 >>> key.pitchToSharps('e-', 'lydian') -2 >>> key.pitchToSharps('e-', 'lydian') -2 >>> key.pitchToSharps('a', 'phrygian') -1 >>> key.pitchToSharps('e', 'phrygian') 0 >>> key.pitchToSharps('f#') 6 >>> key.pitchToSharps('f-') -8 >>> key.pitchToSharps('f--') -15 >>> key.pitchToSharps('f--', 'locrian') -20
But quarter tones don’t work:
>>> key.pitchToSharps('C~') Traceback (most recent call last): KeyException: Cannot determine sharps for quarter-tone keys! silly!
-
music21.key.
sharpsToPitch
(sharpCount)¶ Given a number a positive/negative number of sharps, return a Pitch object set to the appropriate major key value.
>>> key.sharpsToPitch(1) <music21.pitch.Pitch G> >>> key.sharpsToPitch(2) <music21.pitch.Pitch D> >>> key.sharpsToPitch(-2) <music21.pitch.Pitch B-> >>> key.sharpsToPitch(-6) <music21.pitch.Pitch G->
Note that these are
music21.pitch.Pitch
objects not just names:>>> k1 = key.sharpsToPitch(6) >>> k1 <music21.pitch.Pitch F#> >>> k1.step 'F' >>> k1.accidental <accidental sharp>
KeySignature¶
-
class
music21.key.
KeySignature
(sharps=None, mode=None)¶ A KeySignature object specifies the signature to be used for a piece; it takes in zero, one, or two arguments. The first argument is an int giving the number of sharps, or if negative the number of flats. The second argument (deprecated Jan 2014 – do not use) specifies the mode of the piece (‘major’, ‘minor’, or None for unknown).
Mode will be deprecated fully once easier ways for MEI to store this information in a key are given.
If you are starting with the name of a key, see the
Key
object.>>> A = key.KeySignature(3) >>> A <music21.key.KeySignature of 3 sharps>
>>> Eflat = key.KeySignature(-3) >>> Eflat <music21.key.KeySignature of 3 flats>
Some specification of mode can go into the KeySignature object:
>>> Eflat.mode = 'phrygian' >>> Eflat <music21.key.KeySignature of 3 flats, mode phrygian>
But if you want to get a real Key, then use the
Key
object instead:>>> illegal = key.KeySignature('c#') Traceback (most recent call last): KeySignatureException: Cannot get a KeySignature from this "number" of sharps: "c#"; did you mean to use a key.Key() object instead?
>>> legal = key.Key('c#') >>> legal.sharps 4 >>> legal <music21.key.Key of c# minor>
KeySignature
bases
KeySignature
read-only properties
-
KeySignature.
alteredPitches
¶ Return a list of music21.pitch.Pitch objects that are altered by this KeySignature. That is, all Pitch objects that will receive an accidental.
>>> a = key.KeySignature(3) >>> a.alteredPitches [<music21.pitch.Pitch F#>, <music21.pitch.Pitch C#>, <music21.pitch.Pitch G#>] >>> b = key.KeySignature(1) >>> b.alteredPitches [<music21.pitch.Pitch F#>]
>>> c = key.KeySignature(9) >>> [str(p) for p in c.alteredPitches] ['F#', 'C#', 'G#', 'D#', 'A#', 'E#', 'B#', 'F##', 'C##']
>>> d = key.KeySignature(-3) >>> d.alteredPitches [<music21.pitch.Pitch B->, <music21.pitch.Pitch E->, <music21.pitch.Pitch A->]
>>> e = key.KeySignature(-1) >>> e.alteredPitches [<music21.pitch.Pitch B->]
>>> f = key.KeySignature(-6) >>> [str(p) for p in f.alteredPitches] ['B-', 'E-', 'A-', 'D-', 'G-', 'C-']
>>> g = key.KeySignature(-8) >>> [str(p) for p in g.alteredPitches] ['B-', 'E-', 'A-', 'D-', 'G-', 'C-', 'F-', 'B--']
-
KeySignature.
pitchAndMode
¶ DEPRECATED!
Returns a a two value list containing a
music21.pitch.Pitch
object that names this key and the value ofmode
.The only applicable modes are ‘minor’ and all others (=Major)
>>> key.KeySignature(-7).pitchAndMode (<music21.pitch.Pitch C->, None) >>> key.KeySignature(-6).pitchAndMode (<music21.pitch.Pitch G->, None) >>> key.KeySignature(-3).pitchAndMode (<music21.pitch.Pitch E->, None) >>> key.KeySignature(0).pitchAndMode (<music21.pitch.Pitch C>, None) >>> key.KeySignature(1).pitchAndMode (<music21.pitch.Pitch G>, None) >>> csharp = key.KeySignature(4) >>> csharp.mode = "minor" >>> csharp.pitchAndMode (<music21.pitch.Pitch C#>, 'minor') >>> csharpPitch = csharp.pitchAndMode[0] >>> csharpPitch.accidental <accidental sharp>
Read-only properties inherited from Music21Object
:
KeySignature
read/write properties
-
KeySignature.
mode
¶ Get or set the mode.
Mode is supported in a very rough manner for KeySignature objects, but for more sophisticated use of modes use the
Key
object.Mode may disappear in future releases so if you are counting on this for major or minor, consider supporting the
Key
object instead.
-
KeySignature.
sharps
¶ Get or set the number of sharps. If the number is negative then it sets the number of flats. Equivalent to musicxml’s ‘fifths’ attribute.
>>> ks1 = key.KeySignature(2) >>> ks1.sharps 2 >>> ks1.sharps = -4 >>> ks1 <music21.key.KeySignature of 4 flats>
Read/write properties inherited from Music21Object
:
KeySignature
methods
-
KeySignature.
accidentalByStep
(step)¶ Given a step (C, D, E, F, etc.) return the accidental for that note in this key (using the natural minor for minor) or None if there is none.
>>> g = key.KeySignature(1) >>> g.accidentalByStep("F") <accidental sharp> >>> g.accidentalByStep("G")
>>> f = key.KeySignature(-1) >>> bbNote = note.Note("B-5") >>> f.accidentalByStep(bbNote.step) <accidental flat>
Fix a wrong note in F-major:
>>> wrongBNote = note.Note("B#4") >>> if f.accidentalByStep(wrongBNote.step) != wrongBNote.pitch.accidental: ... wrongBNote.pitch.accidental = f.accidentalByStep(wrongBNote.step) >>> wrongBNote <music21.note.Note B->
Set all notes to the correct notes for a key using the note’s Key Context. Before:
>>> s1 = stream.Stream() >>> s1.append(key.KeySignature(4)) # E-major or C-sharp-minor >>> s1.append(note.Note('C', type='half')) >>> s1.append(note.Note('E-', type='half')) >>> s1.append(key.KeySignature(-4)) # A-flat-major or F-minor >>> s1.append(note.Note("A", type='whole')) >>> s1.append(note.Note("F#", type='whole')) >>> s1.show()
After:
>>> for n in s1.notes: ... n.pitch.accidental = n.getContextByClass(key.KeySignature).accidentalByStep(n.step) >>> s1.show()
-
KeySignature.
getScale
(mode=None)¶ Return a
music21.scale.Scale
object (or, actually, a subclass such asMajorScale
orMinorScale
) that is representative of this key signature and mode.Raises KeySignatureException if mode is not in [None, ‘major’, ‘minor’].
>>> ks = key.KeySignature(3) >>> ks <music21.key.KeySignature of 3 sharps> >>> ks.getScale('major') <music21.scale.MajorScale A major> >>> ks.mode = 'minor' >>> ks.getScale() <music21.scale.MinorScale F# minor>
-
KeySignature.
transpose
(value, inPlace=False)¶ Transpose the KeySignature 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.>>> a = key.KeySignature(2) >>> a <music21.key.KeySignature of 2 sharps> >>> a.pitchAndMode (<music21.pitch.Pitch D>, None)
>>> b = a.transpose('p5') >>> b <music21.key.KeySignature of 3 sharps> >>> b.pitchAndMode (<music21.pitch.Pitch A>, None) >>> b.sharps 3 >>> c = b.transpose('-m2') >>> c.pitchAndMode (<music21.pitch.Pitch G#>, None) >>> c.sharps 8
>>> d = c.transpose('-a3') >>> d.pitchAndMode (<music21.pitch.Pitch E->, None) >>> d.sharps -3
Methods inherited from Music21Object
:
KeySignature
instance variables
Instance variables inherited from Music21Object
:
Key¶
-
class
music21.key.
Key
(tonic=None, mode=None)¶ Note that a key is a sort of hypothetical/conceptual object. It probably has a scale (or scales) associated with it and a
KeySignature
, but not necessarily.A Key object has all the attributes of a KeySignature and all the attributes of a
DiatonicScale
.>>> cm = key.Key('c') # lowercase = c minor. >>> cm <music21.key.Key of c minor> >>> cm.mode 'minor' >>> cm.tonic <music21.pitch.Pitch C>
>>> cm.sharps -3 >>> cm.pitchFromDegree(3) <music21.pitch.Pitch E-4> >>> cm.pitchFromDegree(7) <music21.pitch.Pitch B-4>
>>> Csharpmaj = key.Key('C#') # uppercase = C# major >>> Csharpmaj <music21.key.Key of C# major> >>> Csharpmaj.sharps 7
>>> Fflatmaj = key.Key('F-') >>> Fflatmaj <music21.key.Key of F- major> >>> Fflatmaj.sharps -8 >>> Fflatmaj.accidentalByStep('B') <accidental double-flat>
Key
bases
Key
read-only properties
-
Key.
tonicPitchNameWithCase
¶ Return the pitch name as a string with the proper case (upper = major; lower = minor)
Useful, but simple:
>>> k = key.Key("c#") >>> k.tonicPitchNameWithCase 'c#' >>> k = key.Key("B") >>> k.tonicPitchNameWithCase 'B' >>> k.mode = 'minor' >>> k.tonicPitchNameWithCase 'b'
Read-only properties inherited from KeySignature
:
Read-only properties inherited from ConcreteScale
:
Read-only properties inherited from Music21Object
:
Key
read/write properties
Read/write properties inherited from KeySignature
:
Read/write properties inherited from Music21Object
:
Key
methods
-
Key.
tonalCertainty
(method='correlationCoefficient', *args, **keywords)¶ Provide a measure of tonal ambiguity for Key determined with one of many methods.
The correlationCoefficient assumes that the alternateInterpretations list has been filled from the use of a KeyWeightKeyAnalysis subclass.
>>> littlePiece = converter.parse('tinyNotation: 4/4 c4 d e f g a b cc ee gg ee cc') >>> k = littlePiece.analyze('key') >>> k <music21.key.Key of C major> >>> k.tonalCertainty() 1.1648...
Three most likely alternateInterpretations:
>>> k.alternateInterpretations[0:3] [<music21.key.Key of a minor>, <music21.key.Key of F major>, <music21.key.Key of d minor>] >>> k.correlationCoefficient 0.9068... >>> k.alternateInterpretations[0].correlationCoefficient 0.7778...
least likely interpretation:
>>> k.alternateInterpretations[-1] <music21.key.Key of F# major>
Note that this method only exists if the key has come from an analysis method. Otherwise it raises a KeySignatureException
>>> k2 = key.Key('b-') >>> k2.tonalCertainty() Traceback (most recent call last): KeySignatureException: cannot process ambiguity without a list of .alternateInterpretations >>> k2.alternateInterpretations is None True
-
Key.
transpose
(value, inPlace=False)¶ Transpose the Key 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.>>> dMajor = key.Key("D") >>> dMajor <music21.key.Key of D major>
>>> aMaj = dMajor.transpose('p5') >>> aMaj <music21.key.Key of A major> >>> aMaj.sharps 3 >>> aMaj.tonic <music21.pitch.Pitch A> >>> aMaj.mode 'major'
inPlace works here
>>> changingKey = key.Key('g') >>> changingKey <music21.key.Key of g minor> >>> changingKey.sharps -2 >>> changingKey.transpose('m-3', inPlace=True) >>> changingKey <music21.key.Key of e minor> >>> changingKey.sharps 1 >>> changingKey.transpose(1, inPlace=True) >>> changingKey <music21.key.Key of f minor> >>> changingKey.sharps -4
Methods inherited from KeySignature
:
Methods inherited from DiatonicScale
:
Methods inherited from ConcreteScale
:
Methods inherited from Scale
:
Methods inherited from Music21Object
:
Key
instance variables
Instance variables inherited from Music21Object
: