Previous topic

music21.graph

Next topic

music21.humdrum

Table Of Contents

Table Of Contents

music21.harmony

An object representation of harmony, a subclass of chord, as encountered as chord symbols or roman numerals, or other chord representations with a defined root.

music21.harmony.realizeChordSymbolDurations(piece)

Returns music21 stream with duration attribute of chord symbols correctly set. Duration of chord symbols is based on the surrounding chord symbols; The chord symbol continues duration until another chord symbol is located or the piece ends. Useful for

>>> from music21 import *
>>> s = stream.Score()
>>> s.append(harmony.ChordSymbol('C'))
>>> s.repeatAppend(note.Note('C'), 4)
>>> s.append(harmony.ChordSymbol('C'))
>>> s.repeatAppend(note.Note('C'), 4)
>>> s = s.makeMeasures()

>>> harmony.realizeChordSymbolDurations(s).show('text')
{0.0} <music21.clef.BassClef>
{0.0} <music21.meter.TimeSignature 4/4>
{0.0} <music21.harmony.ChordSymbol C>
{0.0} <music21.note.Note C>
{1.0} <music21.note.Note C>
{2.0} <music21.note.Note C>
{3.0} <music21.note.Note C>
{4.0} <music21.harmony.ChordSymbol C>
{4.0} <music21.note.Note C>
{5.0} <music21.note.Note C>
{6.0} <music21.note.Note C>
{7.0} <music21.note.Note C>
{8.0} <music21.bar.Barline style=final>

If only one chord symbol object is present:

>>> s = stream.Score()
>>> s.append(harmony.ChordSymbol('C'))
>>> s.repeatAppend(note.Note('C'), 4)
>>> s = s.makeMeasures()
>>> harmony.realizeChordSymbolDurations(s).show('text')
{0.0} <music21.clef.BassClef>
{0.0} <music21.meter.TimeSignature 4/4>
{0.0} <music21.harmony.ChordSymbol C>
{0.0} <music21.note.Note C>
{1.0} <music21.note.Note C>
{2.0} <music21.note.Note C>
{3.0} <music21.note.Note C>
{4.0} <music21.bar.Barline style=final>

If a ChordSymbol object exists followed by many notes, duration represents all those notes (how else can the computer know to end the chord? if there’s not chord following it other than end the chord at the end of the piece?)

>>> s = stream.Score()
>>> s.repeatAppend(note.Note('C'), 4)
>>> s.append(harmony.ChordSymbol('C'))
>>> s.repeatAppend(note.Note('C'), 8)
>>> s = s.makeMeasures()
>>> harmony.realizeChordSymbolDurations(s).show('text')
{0.0} <music21.clef.BassClef>
{0.0} <music21.meter.TimeSignature 4/4>
{0.0} <music21.note.Note C>
{1.0} <music21.note.Note C>
{2.0} <music21.note.Note C>
{3.0} <music21.note.Note C>
{4.0} <music21.harmony.ChordSymbol C>
{4.0} <music21.note.Note C>
{5.0} <music21.note.Note C>
{6.0} <music21.note.Note C>
{7.0} <music21.note.Note C>
{8.0} <music21.note.Note C>
{9.0} <music21.note.Note C>
{10.0} <music21.note.Note C>
{11.0} <music21.note.Note C>
{12.0} <music21.bar.Barline style=final>

Harmony

Inherits from: Chord, NotRest, GeneralNote, Music21Object, JSONSerializer

class music21.harmony.Harmony(figure=None, **keywords)
>>> from music21 import *
>>> h = harmony.ChordSymbol()
>>> h.XMLroot = 'b-'
>>> h.XMLbass = 'd'
>>> h.XMLinversion = 1
>>> h.addChordStepModification(harmony.ChordStepModification('add', 4))
>>> h
<music21.harmony.ChordSymbol B-/D add 4>
>>> p = harmony.ChordSymbol(root='C', bass='E', kind = 'major')
>>> p
<music21.harmony.ChordSymbol C/E>

Harmony objects in music21 are a special type of chord - they retain all the same functionality as a chord (and inherit from chord directly), although they have special representations symbolically. They contain a figure representation, a shorthand, for the actual pitches they contain. This shorthand is commonly used on musical scores rather than writing out the chord pitches. Thus, each harmony object has an attribute, self.writeAsChord that dictates whether the object will be written to a score as a chord (with pitches realized) or with just the figure (as in Chord Symbols).

>>> from music21 import *
>>> h = harmony.ChordSymbol('C7/E')
>>> h.root()
C4
>>> h.bass()
E3
>>> h.inversion()
1
>>> h.isSeventh()
True
>>> h.pitches
[E3, G3, B-3, C4]

Harmony attributes

Attributes without Documentation: chordStepModifications

Attributes inherited from Chord: isChord, isNote, isRest, beams

Attributes inherited from GeneralNote: lyrics, expressions, articulations, editorial

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

Harmony properties

XMLbass

Get or set the XMLbass of the Harmony as a Pitch object. String representations accepted by Pitch are also accepted. Also updates the associated chord object’s bass. If the bass is ‘None’ (commonly read in from music xml) then it returns the root pitch.

>>> from music21 import *
>>> h = harmony.ChordSymbol()
>>> h.XMLbass = 'a#'
>>> h.XMLbass
A#
>>> h.XMLbass = pitch.Pitch('d-')
>>> h.XMLbass
D-
>>> h.XMLbass = 'juicy'
Traceback (most recent call last):
HarmonyException: not a valid pitch specification: juicy
XMLinversion

Get or set the inversion of this Harmony as a positive integer. Also updates the associated chord object’s bass.

>>> from music21 import *
>>> h = harmony.ChordSymbol()
>>> h.XMLinversion = 2
>>> h.XMLinversion
2
XMLroot

Get or set the XMLroot attribute of the Harmony as a Pitch object. String representations accepted by Pitch are also accepted. Also updates the associated chord object’s root

>>> from music21 import *
>>> h = harmony.ChordSymbol()
>>> h.XMLroot= 'a#'
>>> h.XMLroot
A#
>>> h.XMLroot= pitch.Pitch('c#')
>>> h.XMLroot
C#
>>> h.XMLroot= 'juicy'
Traceback (most recent call last):
HarmonyException: not a valid pitch specification: juicy
figure

Get or set the figure of the harmony object. The figure is the character (string) representation of the object. For example, ‘I’, ‘CM’, ‘3#’

when you instantiate a harmony object, if you pass in a figure it is stored internally and returned when you access the figure property. if you don’t instantiate the object with a figure, this property calls music21.harmony.findFigure() method which deduces the figure provided other information about the object, especially the chord

if the pitches of the harmony object have been modified after being instantiated, call music21.harmony.findFigure() to deduce the new figure

>>> from music21 import *
>>> h = harmony.ChordSymbol('CM')
>>> h.figure
'CM'
>>> harmony.ChordSymbol(root = 'C', bass = 'A', kind = 'minor').figure
'Cm/A'
>>> h.bass(note.Note('E'))
>>> h.figure
'CM'
romanNumeral

Get or set the romanNumeral numeral function of the Harmony as a RomanNumeral object. String representations accepted by RomanNumeral are also accepted.

>>> from music21 import *
>>> h = harmony.ChordSymbol()
>>> h.romanNumeral = 'III'
>>> h.romanNumeral
<music21.roman.RomanNumeral III>
>>> h.romanNumeral = roman.RomanNumeral('vii')
>>> h.romanNumeral
<music21.roman.RomanNumeral vii>
writeAsChord

No documentation.

Properties inherited from Chord: pitches, chordTablesAddress, color, commonName, duration, fifth, forteClass, forteClassNumber, forteClassTn, forteClassTnI, fullName, hasZRelation, intervalVector, intervalVectorString, isPrimeFormInversion, midiEvents, midiFile, multisetCardinality, mx, normalForm, normalFormString, orderedPitchClasses, orderedPitchClassesString, pitchClassCardinality, pitchClasses, pitchNames, pitchedCommonName, primeForm, primeFormString, quality, scaleDegrees, seventh, third, tie, volume

Properties inherited from NotRest: notehead, noteheadFill, noteheadParen, stemDirection

Properties inherited from GeneralNote: lyric, musicxml, quarterLength

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

Properties inherited from JSONSerializer: json

Harmony methods

addChordStepModification(degree)

Add a harmony degree specification to this Harmony as a ChordStepModification object.

>>> from music21 import *
>>> hd = harmony.ChordStepModification('add', 4)
>>> h = harmony.ChordSymbol()
>>> h.addChordStepModification(hd)
>>> h.addChordStepModification('juicy')
Traceback (most recent call last):
HarmonyException: cannot add this object as a degree: juicy
findFigure()

No documentation.

getChordStepModifications()

Return all harmony degrees as a list.

Methods inherited from Chord: annotateIntervals(), areZRelations(), bass(), canBeDominantV(), canBeTonic(), closedPosition(), containsSeventh(), containsTriad(), findRoot(), getChordStep(), getColor(), getNotehead(), getStemDirection(), getTie(), getVolume(), getZRelation(), hasAnyRepeatedDiatonicNote(), hasComponentVolumes(), hasRepeatedChordStep(), intervalFromChordStep(), inversion(), inversionName(), isAugmentedSixth(), isAugmentedTriad(), isConsonant(), isDiminishedSeventh(), isDiminishedTriad(), isDominantSeventh(), isFalseDiminishedSeventh(), isFrenchAugmentedSixth(), isGermanAugmentedSixth(), isHalfDiminishedSeventh(), isIncompleteMajorTriad(), isIncompleteMinorTriad(), isItalianAugmentedSixth(), isMajorTriad(), isMinorTriad(), isSeventh(), isSwissAugmentedSixth(), isTriad(), removeRedundantPitchClasses(), removeRedundantPitchNames(), removeRedundantPitches(), root(), seekChordTablesAddress(), semiClosedPosition(), semitonesFromChordStep(), setColor(), setNotehead(), setStemDirection(), setTie(), setVolume(), sortAscending(), sortChromaticAscending(), sortDiatonicAscending(), sortFrequencyAscending(), transpose()

Methods inherited from NotRest: jsonAttributes()

Methods inherited from GeneralNote: addLyric(), augmentOrDiminish(), compactNoteInfo(), getGrace(), hasLyrics(), insertLyric()

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

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

ChordSymbol

Inherits from: Harmony, Chord, NotRest, GeneralNote, Music21Object, JSONSerializer

class music21.harmony.ChordSymbol(figure=None, **keywords)

Class representing the Chord Symbols commonly found on lead sheets. Chord Symbol objects can be instantiated one of two main ways: 1) when music xml is parsed by the music21 converter, xml Chord Symbol tags are interpreted as Chord Symbol objects with a root and kind attribute. If bass is not specified, the bass is assumed to be the root

2) by creating a chord symbol object with music21 by passing in the expression commonly found on leadsheets. Due to the relative diversity of lead sheet chord syntax, not all expressions are supported. Consult the examples for the supported syntax, or email us for help.

All ChordSymbol inherit from Chord so you can consider these objects as chords, although they have a unique representation in a score. ChordSymbols, unlike chords, by default appear as chord symbols in a score and have duration of 0. To obtain the chord representation of the in the score, change the music21.harmony.ChordSymbol.writeAsChord to True. Unless otherwise specified, the duration of this chord object will become 1.0. If you have a leadsheet, run music21.harmony.realizeChordSymbolDurations() on the stream to assign the correct (according to offsets) duration to each harmony object.)

The music xml-based approach to instantiating Chord Symbol objects:

>>> from music21 import *
>>> cs = harmony.ChordSymbol(kind='minor',kindStr = 'm', root='C', bass = 'E-')
>>> cs
<music21.harmony.ChordSymbol Cm/E->
>>> cs.XMLkind
'minor'
>>> cs.XMLroot
C
>>> cs.XMLbass
E-

The second approach to creating a Chord Symbol object, by passing a regular expression:

>>> harmony.ChordSymbol('C').pitches
[C3, E3, G3]
>>> harmony.ChordSymbol('Cm').pitches
[C3, E-3, G3]
>>> harmony.ChordSymbol('C+').pitches
[C3, E3, G#3]
>>> harmony.ChordSymbol('Cdim').pitches
[C3, E-3, G-3]
>>> harmony.ChordSymbol('C7').pitches
[C3, E3, G3, B-3]
>>> harmony.ChordSymbol('CM7').pitches
[C3, E3, G3, B3]
>>> harmony.ChordSymbol('Cm7').pitches
[C3, E-3, G3, B-3]
>>> harmony.ChordSymbol('Cdim7').pitches
[C3, E-3, G-3, B--3]
>>> harmony.ChordSymbol('C7+').pitches
[C3, E3, G#3, B-3]
>>> harmony.ChordSymbol('Cm7b5').pitches #half-diminished
[C3, E-3, G-3, B-3]
>>> harmony.ChordSymbol('CmMaj7').pitches
[C3, E-3, G3, B3]
>>> harmony.ChordSymbol('C6').pitches
[C3, E3, G3, A3]
>>> harmony.ChordSymbol('Cm6').pitches
[C3, E-3, G3, A3]
>>> harmony.ChordSymbol('C9').pitches
[C3, E3, G3, B-3, D4]
>>> harmony.ChordSymbol('CMaj9').pitches
[C3, E3, G3, B3, D4]
>>> harmony.ChordSymbol('Cm9').pitches
[C3, E-3, G3, B-3, D4]
>>> harmony.ChordSymbol('C11').pitches
[C2, E2, G2, B-2, D3, F3]
>>> harmony.ChordSymbol('CMaj11').pitches
[C2, E2, G2, B2, D3, F3]
>>> harmony.ChordSymbol('Cm11').pitches
[C2, E-2, G2, B-2, D3, F3]
>>> harmony.ChordSymbol('C13').pitches
[C2, E2, G2, B-2, D3, F3, A3]
>>> harmony.ChordSymbol('CMaj13').pitches
[C2, E2, G2, B2, D3, F3, A3]
>>> harmony.ChordSymbol('Cm13').pitches
[C2, E-2, G2, B-2, D3, F3, A3]
>>> harmony.ChordSymbol('Csus2').pitches
[C3, D3, G3]
>>> harmony.ChordSymbol('Csus4').pitches
[C3, F3, G3]
>>> harmony.ChordSymbol('CN6').pitches
[C3, D-3, E3, G-3]
>>> harmony.ChordSymbol('CIt+6').pitches
[C3, F#3, A-3]
>>> harmony.ChordSymbol('CFr+6').pitches
[C3, D3, F#3, A-3]
>>> harmony.ChordSymbol('CGr+6').pitches
[C3, E-3, F#3, A-3]
>>> harmony.ChordSymbol('Cpedal').pitches
[C3]
>>> harmony.ChordSymbol('Cpower').pitches
[C3, G3]
>>> harmony.ChordSymbol('Ftristan').pitches
[F3, G#3, B3, D#4]
>>> harmony.ChordSymbol('C/E').pitches
[E3, G3, C4]
>>> harmony.ChordSymbol('Dm7/F').pitches
[F3, A3, C4, D4]
>>> harmony.ChordSymbol('Cadd2').pitches
[C3, D3, E3, G3]
>>> harmony.ChordSymbol('C7omit3').pitches
[C3, G3, B-3]

You can also create a Chord Symbol by writing out each degree, and any alterations to that degree: You must explicitly indicate EACH degree (a triad is NOT necessarily implied)

>>> harmony.ChordSymbol('C35b7b9#11b13').pitches
[C3, D-3, E3, F#3, G3, A-3, B-3]

>>> harmony.ChordSymbol('C35911').pitches
[C3, D3, E3, F3, G3]

Ambiguity in notation: if the expression is ambiguous, for example ‘Db35’ (is this the key of Db with a third and a fifth, or is this key of D with a flat 3 and normal fifth?) To prevent ambiguity, insert a comma after the root.

>>> harmony.ChordSymbol('Db,35').pitches
[D-3, F3, A-3]
>>> harmony.ChordSymbol('D,b35').pitches
[D3, F3, A3]
>>> harmony.ChordSymbol('D,35b7b9#11b13').pitches
[D3, E-3, F#3, G#3, A3, B-3, C4]

The ‘-‘ symbol and the ‘b’ symbol are interchangeable, they correspond to flat, not minor.

>>> harmony.ChordSymbol('Am').pitches
[A2, C3, E3]
>>> harmony.ChordSymbol('Abm').pitches
[A-2, C-3, E-3]
>>> harmony.ChordSymbol('A-m').pitches
[A-2, C-3, E-3]
>>> harmony.ChordSymbol('F-dim7').pitches
[F-2, A--2, C--3, E---3]

ChordSymbol attributes

Attributes without Documentation: XMLkindStr, XMLkind

Attributes inherited from Harmony: chordStepModifications

Attributes inherited from Chord: isChord, isNote, isRest, beams

Attributes inherited from GeneralNote: lyrics, expressions, articulations, editorial

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

ChordSymbol properties

Properties inherited from Harmony: XMLbass, XMLinversion, XMLroot, figure, romanNumeral, writeAsChord

Properties inherited from Chord: pitches, chordTablesAddress, color, commonName, duration, fifth, forteClass, forteClassNumber, forteClassTn, forteClassTnI, fullName, hasZRelation, intervalVector, intervalVectorString, isPrimeFormInversion, midiEvents, midiFile, multisetCardinality, mx, normalForm, normalFormString, orderedPitchClasses, orderedPitchClassesString, pitchClassCardinality, pitchClasses, pitchNames, pitchedCommonName, primeForm, primeFormString, quality, scaleDegrees, seventh, third, tie, volume

Properties inherited from NotRest: notehead, noteheadFill, noteheadParen, stemDirection

Properties inherited from GeneralNote: lyric, musicxml, quarterLength

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

Properties inherited from JSONSerializer: json

ChordSymbol methods

findFigure()

return the chord symbol figure associated with this chord. the XMLroot, XMLbass and XMLkind attributes must be specified

Needs development - TODO: chord step modifications need actual pitches rather than numeric degrees

>>> from music21 import *
>>> h = harmony.ChordSymbol(root = 'F', bass = 'D-', kind = 'Neapolitan')
>>> h.figure
'FN6/D-'
inversionIsValid(inversion)

returns true if the provided inversion is exists for the given pitches of the chord. If not, it returns false and the getPitches method then appends the bass pitch to the chord.

Methods inherited from Harmony: addChordStepModification(), getChordStepModifications()

Methods inherited from Chord: annotateIntervals(), areZRelations(), bass(), canBeDominantV(), canBeTonic(), closedPosition(), containsSeventh(), containsTriad(), findRoot(), getChordStep(), getColor(), getNotehead(), getStemDirection(), getTie(), getVolume(), getZRelation(), hasAnyRepeatedDiatonicNote(), hasComponentVolumes(), hasRepeatedChordStep(), intervalFromChordStep(), inversion(), inversionName(), isAugmentedSixth(), isAugmentedTriad(), isConsonant(), isDiminishedSeventh(), isDiminishedTriad(), isDominantSeventh(), isFalseDiminishedSeventh(), isFrenchAugmentedSixth(), isGermanAugmentedSixth(), isHalfDiminishedSeventh(), isIncompleteMajorTriad(), isIncompleteMinorTriad(), isItalianAugmentedSixth(), isMajorTriad(), isMinorTriad(), isSeventh(), isSwissAugmentedSixth(), isTriad(), removeRedundantPitchClasses(), removeRedundantPitchNames(), removeRedundantPitches(), root(), seekChordTablesAddress(), semiClosedPosition(), semitonesFromChordStep(), setColor(), setNotehead(), setStemDirection(), setTie(), setVolume(), sortAscending(), sortChromaticAscending(), sortDiatonicAscending(), sortFrequencyAscending(), transpose()

Methods inherited from NotRest: jsonAttributes()

Methods inherited from GeneralNote: addLyric(), augmentOrDiminish(), compactNoteInfo(), getGrace(), hasLyrics(), insertLyric()

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

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

ChordStepModification

class music21.harmony.ChordStepModification(modType=None, degree=None, interval=None)

ChordStepModification objects define the specification of harmony degree alterations, subtractions, or additions, used in Harmony objects, which includes harmony.ChordSymbol objects (and will include harmony.RomanNumeral objects)

degree-value element: indicates degree in chord, positive integers only degree-alter: indicates semitone alteration of degree, positive and negative integers only degree-type: add, alter, or subtract

if add: degree-alter is relative to a dominant chord (major and perfect intervals except for a minor seventh)

if alter or subtract: degree-alter is relative to degree already in the chord based on its kind element

>>> from music21 import *
>>> hd = harmony.ChordStepModification('add', 4)
>>> hd
<music21.harmony.ChordStepModification modType=add degree=4 interval=None>
>>> hd = harmony.ChordStepModification('alter', 3, 1)
>>> hd
<music21.harmony.ChordStepModification modType=alter degree=3 interval=<music21.interval.Interval A1>>

ChordStepModification properties

degree
>>> from music21 import *
>>> hd = harmony.ChordStepModification()
>>> hd.degree = 3
>>> hd.degree
3
>>> hd.degree = 'juicy'
Traceback (most recent call last):
ChordStepModificationException: not a valid degree: juicy
interval

Get or set the alteration of this degree as a Interval object.

>>> from music21 import *
>>> hd = harmony.ChordStepModification()
>>> hd.interval = 1
>>> hd.interval
<music21.interval.Interval A1>
>>> hd.interval = -2
>>> hd.interval
<music21.interval.Interval AA-1>
modType

Get or set the ChordStepModification modification type, where permitted types are the strings add, subtract, or alter.

>>> from music21 import *
>>> hd = harmony.ChordStepModification()
>>> hd.modType = 'add'
>>> hd.modType
'add'
>>> hd.modType = 'juicy'
Traceback (most recent call last):
ChordStepModificationException: not a valid degree modification type: juicy