# 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.chordSymbolFigureFromChord(inChord, includeChordType=False)

method to analyze the given chord, and attempt to describe its pitches using a standard chord symbol figure. The pitches of the chord are analyzed based on intervals, and compared to standard triads, sevenths, ninths, elevenths, and thirteenth chords. The type of chord therefore is determined if it matches (given certain guidelines documented below) and the figure is returned. There is no standard “chord symbol” notation, so a typical notation is used that can be easily modified if desired by changing a dictionary in the source code.

set includeChordType to true (default is False) to return a tuple, the first element being the figure and the second element the identified chord type

```>>> from music21 import *
>>> harmony.chordSymbolFigureFromChord(chord.Chord(['C3','E3','G3'])) #standard example
'C'
```

THIRDS

```>>> c = chord.Chord(['C3', 'E3', 'G3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('C', 'major')
>>> c = chord.Chord(['B-3', 'D-4', 'F4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('B-m', 'minor')
>>> c = chord.Chord(['F#3', 'A#3', 'C##4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('F#+', 'augmented')
>>> c = chord.Chord(['C3', 'E-3', 'G-3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('Cdim', 'diminished')
```

SEVENTHS

```>>> c = chord.Chord(['E-3', 'G3', 'B-3', 'D-4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('E-7', 'dominant-seventh')
>>> c = chord.Chord(['C3', 'E3', 'G3', 'B3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('Cmaj7', 'major-seventh')
>>> c = chord.Chord(['F#3', 'A3', 'C#4', 'E#4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('F#mM7', 'minor-major-seventh')
>>> c = chord.Chord(['F3', 'A-3', 'C4', 'E-4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('Fm7', 'minor-seventh')
>>> c = chord.Chord(['F3', 'A3', 'C#4', 'E4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('F+M7', 'augmented-major seventh')
>>> c = chord.Chord(['C3', 'E3', 'G#3', 'B-3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('C7+', 'augmented-seventh')
>>> c = chord.Chord(['G3', 'B-3', 'D-4', 'F4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('G/o7', 'half-diminished')
>>> c = chord.Chord(['C3', 'E-3', 'G-3', 'B--3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('Co7', 'diminished-seventh')
>>> c = chord.Chord(['B-3', 'D4', 'F-4', 'A-4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('B-dom7dim5', 'seventh-flat-five')
```

NINTHS

```>>> c = chord.Chord(['C3', 'E3', 'G3', 'B3', 'D3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('CM9', 'major-ninth')
>>> c = chord.Chord(['B-3', 'D4', 'F4', 'A-4', 'C4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('B-9', 'dominant-ninth')
>>> c = chord.Chord(['E-3', 'G-3', 'B-3', 'D4', 'F3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('E-mM9', 'minor-major-ninth')
>>> c = chord.Chord(['C3', 'E-3', 'G3', 'B-3', 'D3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('Cm9', 'minor-ninth')
>>> c = chord.Chord(['F#3', 'A#3', 'C##4', 'E#4', 'G#3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('F#+M9', 'augmented-major-ninth')
>>> c = chord.Chord(['G3', 'B3', 'D#4', 'F4', 'A3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('G9#5', 'augmented-dominant-ninth')
>>> c = chord.Chord(['C3', 'E-3', 'G-3', 'B-3', 'D3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('C/o9', 'half-diminished-ninth')
>>> c = chord.Chord(['B-3', 'D-4', 'F-4', 'A-4', 'C-4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('B-/ob9', 'half-diminished-minor-ninth')
>>> c = chord.Chord(['C3', 'E-3', 'G-3', 'B--3', 'D3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('Co9', 'diminished-ninth')
>>> c = chord.Chord(['F3', 'A-3', 'C-4', 'E--4', 'G-3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('Fob9', 'diminished-minor-ninth')
```

ELEVENTHS

```>>> c = chord.Chord(['E-3', 'G3', 'B-3', 'D-4', 'F3', 'A-3'] )
>>> harmony.chordSymbolFigureFromChord(c, True)
('E-11', 'dominant-11th')
>>> c = chord.Chord(['G3', 'B3', 'D4', 'F#4', 'A3', 'C4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('GM11', 'major-11th')
>>> c = chord.Chord(['C3', 'E-3', 'G3', 'B3', 'D3', 'F3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('CmM11', 'minor-major-11th')
>>> c = chord.Chord(['F#3', 'A3', 'C#4', 'E4', 'G#3', 'B3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('F#m11', 'minor-11th')
>>> c = chord.Chord(['B-3', 'D4', 'F#4', 'A4', 'C4', 'E-4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('B-+M11', 'augmented-major-11th')
>>> c = chord.Chord(['F3', 'A3', 'C#4', 'E-4', 'G3', 'B-3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('F+11', 'augmented-11th')
>>> c = chord.Chord(['G3', 'B-3', 'D-4', 'F4', 'A-3', 'C4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('G/o11', 'half-diminished-11th')
>>> c = chord.Chord(['E-3', 'G-3', 'B--3', 'D--4', 'F-3', 'A--3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('E-o11', 'diminished-11th')
```

THIRTEENTHS these are so tricky...music21 needs to be told what the root is in these cases all tests here are ‘C’ chords, but any root will work

```>>> c = chord.Chord(['C3', 'E3', 'G3', 'B3', 'D4', 'F4', 'A4'])
>>> c.root('C3')
>>> harmony.chordSymbolFigureFromChord(c, True)
('CM13', 'major-13th')
>>> c = chord.Chord(['C3', 'E3', 'G3', 'B-3', 'D4', 'F4', 'A4'])
>>> c.root('C3')
>>> harmony.chordSymbolFigureFromChord(c, True)
('C13', 'dominant-13th')
>>> c = chord.Chord(['C3', 'E-3', 'G3', 'B3', 'D4', 'F4', 'A4'])
>>> c.root('C3')
>>> harmony.chordSymbolFigureFromChord(c, True)
('CmM13', 'minor-major-13th')
>>> c = chord.Chord(['C3', 'E-3', 'G3', 'B-3', 'D4', 'F4', 'A4'])
>>> c.root('C3')
>>> harmony.chordSymbolFigureFromChord(c, True)
('Cm13', 'minor-13th')
>>> c = chord.Chord(['C3', 'E3', 'G#3', 'B3', 'D4', 'F4', 'A4'])
>>> c.root('C3')
>>> harmony.chordSymbolFigureFromChord(c, True)
('C+M13', 'augmented-major-13th')
>>> c = chord.Chord(['C3', 'E3', 'G#3', 'B-3', 'D4', 'F4', 'A4'])
>>> c.root('C3')
>>> harmony.chordSymbolFigureFromChord(c, True)
('C+13', 'augmented-dominant-13th')
>>> c = chord.Chord(['C3', 'E-3', 'G-3', 'B-3', 'D4', 'F4', 'A4'])
>>> c.root('C3')
>>> harmony.chordSymbolFigureFromChord(c, True)
('C/o13', 'half-diminished-13th')
```

Pop chords are typically not always “strictly” spelled and often certain degrees are omitted. Therefore, the following common chord omissions are permitted and the chord will still be identified correctly:

• seventh chords: none
• ninth chords: fifth
• eleventh chords: third and/or fifth
• thirteenth chords: fifth, eleventh, ninth
```>>> c = chord.Chord(['F3', 'A-3', 'E-4'])
>>> harmony.chordSymbolFigureFromChord(c)  # could be minor 7th with a C4, but because this 5th isn't present, not identified
'Chord Symbol Cannot Be Identified'
>>> c = chord.Chord(['C3', 'E3',  'B3', 'D3']) #G3 removed (fifth of chord)
>>> harmony.chordSymbolFigureFromChord(c, True)
('CM9', 'major-ninth')
>>> c = chord.Chord(['E-3', 'D-4', 'F3', 'A-3'] ) # G3 and B-3 removed (3rd & 5th of chord)
>>> c.root('E-3') #but without the 3rd and 5th, findRoot() algorithm can't locate the root, so we must tell it the root (or write an algorithm that assume's the root is the lowest note if the root can't be found)
>>> harmony.chordSymbolFigureFromChord(c, True)
('E-11', 'dominant-11th')
```

Inversions are supported, and indicated with a ‘/’ between the root, typestring, and bass

```>>> c = chord.Chord([ 'G#3', 'B-3','C4', 'E4',])
>>> harmony.chordSymbolFigureFromChord(c, True)
('C7+/G#', 'augmented-seventh')
>>> c = chord.Chord(['G#2', 'B2','F#3', 'A3', 'C#4', 'E4'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('F#m11/G#', 'minor-11th')
```

if the algorithm matches the chord, but omitions or subtractions are present, the chord symbol attempts to indicate this (although there is no standard way of doing this so the notation might be different than what you’re familiar with.

An example of using this algorithm for identifying chords “in the wild”:

```>>> score = corpus.parse('bach/bwv380')
>>> excerpt = score.measures(2, 3)
>>> cs = []
>>> for c in excerpt.chordify().flat.getElementsByClass(chord.Chord):
...   print harmony.chordSymbolFigureFromChord(c)
B-7
E-maj7/B-
B-7
Chord Symbol Cannot Be Identified
B-7
E-
B-
Chord Symbol Cannot Be Identified
B-/D
B-7
Cm/D
E-+M7/D
Cm/E-
F7
```

Notice, however, that this excerpt contains many embellishment and non-harmonic tones, so an algorithm to truly identify the chord symbols must be as complex as any harmonic analysis algorithm, which this is not, so innately this method is flawed.

And for the sake of completeness, unique chords supported by musicxml that this method can still successfully identify. Notice that the root must often be specified for this method to work.

```>>> c = chord.Chord(['C3', 'D3', 'G3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('Csus2', 'suspended-second')
>>> c = chord.Chord(['C3', 'F3', 'G3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('Csus', 'suspended-fourth')
>>> c = chord.Chord(['C3', 'D-3', 'E3', 'G-3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('CN6', 'Neapolitan')
>>> c = chord.Chord(['C3', 'F#3', 'A-3'])
>>> c.root('C3')
>>> harmony.chordSymbolFigureFromChord(c, True)
('CIt+6', 'Italian')
>>> c = chord.Chord(['C3', 'D3', 'F#3', 'A-3'])
>>> c.root('C3')
>>> harmony.chordSymbolFigureFromChord(c, True)
('CFr+6', 'French')
>>> c = chord.Chord(['C3', 'E-3', 'F#3', 'A-3'])
>>> c.root('C3')
>>> harmony.chordSymbolFigureFromChord(c, True)
('CGr+6', 'German')
>>> c = chord.Chord(['C3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('Cpedal', 'pedal')
>>> c = chord.Chord(['C3', 'G3'])
>>> harmony.chordSymbolFigureFromChord(c, True)
('Cpower', 'power')
>>> c = chord.Chord(['F3', 'G#3', 'B3', 'D#4'] )
>>> c.root('F3')
>>> harmony.chordSymbolFigureFromChord(c, True)
('Ftristan', 'Tristan')
```

This algorithm works as follows:

1. chord is analyzed for root (using chord’s findRoot() )

if the root cannot be determined, error is raised be aware that the findRoot() method determines the root based on which note has the most thirds above it this is not a consistent way to determine the root of 13th chords, for example

2. a chord vector is extracted from the chord using music21.chord.semitonesFromChordStep()

this vector extracts the following degrees: (2,3,4,5,6,7,9,11,and13)

3. this vector is converted to fbNotationString (in the form of chord step, and a ‘-‘ or ‘#’ to indicate semitone distance)

4. the fbNotationString is matched against the CHORD_TYPES dictionary in this harmony module,

although certain subtractions are permitted for example a 9th chord will still be identified correctly even if it is missing the 5th

5. the type with the most identical matches is used, and if no type matches, “Chord Type Cannot Be Identified” is returned

6. the output format for the chord symbol figure is the chord’s root (with ‘b’ instead of ‘-‘),

the chord type’s Abbreviation (saved in CHORD_TYPES dictionary), a ‘/’ if the chord is in an inversion, and the chord’s bass

The chord symbol nomenclature is not entirely standardized. There are several different ways to write each Abbreviation For example, an augmented triad might be symbolized with ‘+’ or ‘aug’ Thus, by default the returned symbol is the first (element 0) in the CHORD_TYPES list For example (Eb minor eleventh chord, second inversion) root + chordtypestr + ‘/’ + bass = ‘Ebmin11/Bb’

Users who wish to change these defaults can simply change that entry in the CHORD_TYPES dictionary.

```>>> harmony.chordSymbolFigureFromChord(chord.Chord(['C2','E2','G2']))
'C'
>>> harmony.changeAbbreviationFor('major', 'maj')
>>> harmony.chordSymbolFigureFromChord(chord.Chord(['C2','E2','G2']))
'Cmaj'
```
```>>> from music21 import *
>>> harmony.addNewChordSymbol('BethChord', '1,3,-6,#9', ['MH','beth'])
>>> [str(p) for p in harmony.ChordSymbol('BMH').pitches]
['B2', 'C##3', 'D#3', 'G3']
⁠
>>> harmony.ChordSymbol('Cbeth').pitches
[<music21.pitch.Pitch C3>, <music21.pitch.Pitch D#3>, <music21.pitch.Pitch E3>, <music21.pitch.Pitch A-3>]
>>> harmony.ChordSymbol('C-beth').pitches
[<music21.pitch.Pitch C-3>, <music21.pitch.Pitch D3>, <music21.pitch.Pitch E-3>, <music21.pitch.Pitch A--3>]
```
music21.harmony.changeAbbreviationFor(chordType, changeTo)

change the current Abbreviation used for a certain music21.harmony.ChordSymbol chord type

```>>> from music21 import *
>>> harmony.getCurrentAbbreviationFor('minor')
'm'
>>> harmony.changeAbbreviationFor('minor', 'min')
>>> harmony.getCurrentAbbreviationFor('minor')
'min'
```
music21.harmony.chordSymbolFromChord(inChord)

get the chordSymbol object from the chord, using music21.harmony.chordSymbolFigureFromChord()

```>>> from music21 import *
>>> chordSymbolFromChord(chord.Chord(['D3','F3','A3','B-3']))
<music21.harmony.ChordSymbol B-maj7/D>
```
music21.harmony.getAbbreviationListGivenChordType(chordType)

get the Abbreviation list (all allowed Abbreviations that map to this music21.harmony.ChordSymbol object)

```>>> from music21 import *
>>> harmony.getAbbreviationListGivenChordType('minor-major-13th')
['mM13', 'minmaj13']
```
music21.harmony.getCurrentAbbreviationFor(chordType)

return the current Abbreviation for a given music21.harmony.ChordSymbol chordType

```>>> from music21 import *
>>> harmony.getCurrentAbbreviationFor('dominant-seventh')
'7'
```
music21.harmony.getNotationStringGivenChordType(chordType)

get the notation string (fbnotation style) associated with this music21.harmony.ChordSymbol chordType

```>>> from music21 import *
>>> harmony.getNotationStringGivenChordType('German')
'1,-3,#4,-6'
```
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>
```
music21.harmony.removeChordSymbols(chordType)

remove the given chord type from the CHORD_TYPES dictionary, so it can no longer be identified or parsed by harmony methods

## Harmony¶

Inherits from: Chord, NotRest, GeneralNote, Music21Object

class music21.harmony.Harmony(figure=None, **keywords)
```>>> from music21 import *
>>> h = harmony.ChordSymbol()
>>> h.root('B-3')
>>> h.bass('D')
>>> h.inversion(1)
>>> 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()
<music21.pitch.Pitch C4>
>>> h.bass()
<music21.pitch.Pitch E3>
>>> h.inversion()
1
>>> h.isSeventh()
True
>>> [str(p) for p in 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, xPosition, id, sites, groups, hideObjectOnPrint

Harmony properties

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'
```
key

Gets or Sets the current Key (or Scale object) associated with this Harmony object. for a given RomanNumeral object. Each sub-classed harmony object may treat this property differently, for example Roman Numeral objects update the pitches when the key is changed, but chord symbol objects do not and the key provides more information about the musical context from where the harmony object was extracted.

```>>> from music21 import *
>>> r1 = roman.RomanNumeral('V')
>>> r1.pitches
[<music21.pitch.Pitch G4>, <music21.pitch.Pitch B4>, <music21.pitch.Pitch D5>]
>>> r1.key = key.Key('A')
>>> r1.pitches
[<music21.pitch.Pitch E5>, <music21.pitch.Pitch G#5>, <music21.pitch.Pitch B5>]
```

Changing the key for a ChordSymbol object does nothing, since it’s not dependent on key.

```>>> h1 = harmony.ChordSymbol('D-m11')
>>> [str(p) for p in h1.pitches]
['D-2', 'F-2', 'A-2', 'C-3', 'E-3', 'G-3']
>>> h1.key = 'CM'
>>> [str(p) for p in h1.pitches]
['D-2', 'F-2', 'A-2', 'C-3', 'E-3', 'G-3']
```
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 GeneralNote: lyric, quarterLength

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

Harmony methods

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

```>>> from music21 import *
>>> hd = harmony.ChordStepModification('add', 4)
>>> h = harmony.ChordSymbol()
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 GeneralNote: addLyric(), augmentOrDiminish(), getGrace(), hasLyrics(), insertLyric()

## ChordSymbol¶

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

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.chordKind
'minor'
>>> cs.root()
<music21.pitch.Pitch C>
>>> cs.bass()
<music21.pitch.Pitch E->
```

The second approach to creating a Chord Symbol object, by passing a regular expression (this list is not exhaustive):

```>>> symbols = ['', 'm', '+', 'dim', '7',
...            'M7', 'm7', 'dim7', '7+', 'm7b5', #half-diminished
...            'mM7', '6', 'm6', '9', 'Maj9', 'm9',
...            '11', 'Maj11', 'm11', '13',
...            'Maj13', 'm13', 'sus2', 'sus4',
...            'N6', 'It+6', 'Fr+6', 'Gr+6', 'pedal',
...            'power', 'tristan', '/E', 'm7/E-', 'add2',
...            '7omit3',]
>>> for s in symbols:
...     chordSymbolName = 'C' + s
...     h = harmony.ChordSymbol(chordSymbolName)
...     pitchNames = [str(p) for p in h.pitches]
...     print "%-10s%s" % (chordSymbolName, "[" + (', '.join(pitchNames)) + "]")
C         [C3, E3, G3]
Cm        [C3, E-3, G3]
C+        [C3, E3, G#3]
Cdim      [C3, E-3, G-3]
C7        [C3, E3, G3, B-3]
CM7       [C3, E3, G3, B3]
Cm7       [C3, E-3, G3, B-3]
Cdim7     [C3, E-3, G-3, B--3]
C7+       [C3, E3, G#3, B-3]
Cm7b5     [C3, E-3, G-3, B-3]
CmM7      [C3, E-3, G3, B3]
C6        [C3, E3, G3, A3]
Cm6       [C3, E-3, G3, A3]
C9        [C3, E3, G3, B-3, D4]
CMaj9     [C3, E3, G3, B3, D4]
Cm9       [C3, E-3, G3, B-3, D4]
C11       [C2, E2, G2, B-2, D3, F3]
CMaj11    [C2, E2, G2, B2, D3, F3]
Cm11      [C2, E-2, G2, B-2, D3, F3]
C13       [C2, E2, G2, B-2, D3, F3, A3]
CMaj13    [C2, E2, G2, B2, D3, F3, A3]
Cm13      [C2, E-2, G2, B-2, D3, F3, A3]
Csus2     [C3, D3, G3]
Csus4     [C3, F3, G3]
CN6       [C3, D-3, E3, G-3]
CIt+6     [C3, F#3, A-3]
CFr+6     [C3, D3, F#3, A-3]
CGr+6     [C3, E-3, F#3, A-3]
Cpedal    [C3]
Cpower    [C3, G3]
Ctristan  [C3, D#3, F#3, A#3]
C/E       [E3, G3, C4]
Cm7/E-    [E-3, G3, B-3, C4]
Cadd2     [C3, D3, E3, G3]
C7omit3   [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)

```>>> [str(p) for p in harmony.ChordSymbol('C35b7b9#11b13').pitches]
['C3', 'D-3', 'E3', 'F#3', 'G3', 'A-3', 'B-3']
⁠
>>> [str(p) for p in harmony.ChordSymbol('C35911').pitches]
['C3', 'D3', 'E3', 'F3', 'G3']
```

to prevent ambiguity in notation....

...and in accordance with the rest of music21, if a root or bass is flat, the ‘-‘ must be used, and NOT ‘b’. However, alterations and chord abreviations are specified normally with the ‘b’ and ‘#’ signs.

```>>> [str(p) for p in harmony.ChordSymbol('D-35').pitches]
['D-3', 'F3', 'A-3']
>>> [str(p) for p in harmony.ChordSymbol('Db35').pitches]
['D3', 'F3', 'A3']
>>> [str(p) for p in harmony.ChordSymbol('D,35b7b9#11b13').pitches]
['D3', 'E-3', 'F#3', 'G#3', 'A3', 'B-3', 'C4']
>>> harmony.ChordSymbol('Am').pitches
[<music21.pitch.Pitch A2>, <music21.pitch.Pitch C3>, <music21.pitch.Pitch E3>]
>>> harmony.ChordSymbol('A-m').pitches
[<music21.pitch.Pitch A-2>, <music21.pitch.Pitch C-3>, <music21.pitch.Pitch E-3>]
>>> harmony.ChordSymbol('A-m').pitches
[<music21.pitch.Pitch A-2>, <music21.pitch.Pitch C-3>, <music21.pitch.Pitch E-3>]
>>> harmony.ChordSymbol('F-dim7').pitches
[<music21.pitch.Pitch F-2>, <music21.pitch.Pitch A--2>, <music21.pitch.Pitch C--3>, <music21.pitch.Pitch E---3>]
```

And now, and example of parsing in the wild:

```>>> s = corpus.parse('leadsheet/fosterBrownHair')
>>> [[str(c.name) for c in c.pitches] for c in s.flat.getElementsByClass(harmony.ChordSymbol)[0:5]]
[['F', 'A', 'C'], ['B', 'B-', 'D', 'F'], ['F', 'A', 'C'], ['C', 'E', 'G'], ['F', 'A', 'C']]
```

ChordSymbol attributes

Attributes without Documentation: chordKind, chordKindStr

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, xPosition, id, sites, groups, hideObjectOnPrint

ChordSymbol properties

ChordSymbol methods

findFigure()

return the chord symbol figure associated with this chord. This method tries to deduce what information it can from the provided pitches.

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

Thanks to Norman Schmidt for code sample and helping fix a bug

```>>> s = corpus.parse('leadsheet/fosterBrownHair.xml')
>>> s = s.parts[0].getElementsByClass(stream.Measure)
>>> for m in s[12:17]:
...   c = m.getElementsByClass(harmony.ChordSymbol)
...   if(len(c)):
...     chord = c[0].figure
...     print chord.replace('-','b')
...   else:
...     print 'n.c.'
F
G7
C
C
C
```
inversionIsValid(inversion)

returns true if the provided inversion 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 GeneralNote: addLyric(), augmentOrDiminish(), getGrace(), hasLyrics(), insertLyric()

## 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