.. _moduleHarmony:

music21.harmony
===============

.. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED. Edit the .py file directly

.. module:: music21.harmony


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




.. function:: realizeChordSymbolDurations(piece)

    Returns Music21 score object 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.



    >>> 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.TrebleClef>
    {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.TrebleClef>
    {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.TrebleClef>
    {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: :class:`~music21.base.Music21Object`, :class:`~music21.base.JSONSerializer`

.. class:: 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', inversion=1, duration=4.0)
    >>> p
    <music21.harmony.ChordSymbol C/E>

    Harmony objects in music21 are special types of chords. Although on a page of music they exist as symbols
    rather than notes, musicians consider them to be chords. Thus, harmony objects in music21 are not a subclass
    of Chord, although they do contain a chord object within them and all of the methods of class chord can
    be used to operate directly on the harmony object. NB - h.root() is analogous to calling h.chord.root()

    For example,



    >>> 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 :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.classSortOrder`, :attr:`~music21.base.Music21Object.hideObjectOnPrint`, :attr:`~music21.base.Music21Object.id`, :attr:`~music21.base.Music21Object.isSpanner`, :attr:`~music21.base.Music21Object.isStream`, :attr:`~music21.base.Music21Object.groups`

    **Harmony** **properties**

        .. attribute:: XMLbass


            Get or set the XMLbass of the Harmony as a :class:`~music21.pitch.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



        .. attribute:: 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



        .. attribute:: XMLroot


            Get or set the XMLroot attribute of the Harmony as a :class:`~music21.pitch.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



        .. attribute:: chord


            Get or set the chord object of this harmony object. The chord object will
            be returned with the realized pitches as an attribute. The user could
            override these pitches by manually setting the chord.pitches.





        .. attribute:: chordTablesAddress

            directly references :attr:`music21.chord.Chord.chordTablesAddress`


        .. attribute:: color

            directly references :attr:`music21.chord.Chord.color`


        .. attribute:: commonName

            directly references :attr:`music21.chord.Chord.commonName`


        .. attribute:: duration

            directly references :attr:`music21.chord.Chord.duration`


        .. attribute:: fifth

            directly references :attr:`music21.chord.Chord.fifth`


        .. attribute:: 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 :meth:`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 :meth:`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'



        .. attribute:: forteClass

            directly references :attr:`music21.chord.Chord.forteClass`


        .. attribute:: forteClassNumber

            directly references :attr:`music21.chord.Chord.forteClassNumber`


        .. attribute:: forteClassTn

            directly references :attr:`music21.chord.Chord.forteClassTn`


        .. attribute:: forteClassTnI

            directly references :attr:`music21.chord.Chord.forteClassTnI`


        .. attribute:: fullName

            directly references :attr:`music21.chord.Chord.fullName`


        .. attribute:: hasZRelation

            directly references :attr:`music21.chord.Chord.hasZRelation`


        .. attribute:: intervalVector

            directly references :attr:`music21.chord.Chord.intervalVector`


        .. attribute:: intervalVectorString

            directly references :attr:`music21.chord.Chord.intervalVectorString`


        .. attribute:: isPrimeFormInversion

            directly references :attr:`music21.chord.Chord.isPrimeFormInversion`


        .. attribute:: midiEvents

            directly references :attr:`music21.chord.Chord.midiEvents`


        .. attribute:: midiFile

            directly references :attr:`music21.chord.Chord.midiFile`


        .. attribute:: multisetCardinality

            directly references :attr:`music21.chord.Chord.multisetCardinality`


        .. attribute:: normalForm

            directly references :attr:`music21.chord.Chord.normalForm`


        .. attribute:: normalFormString

            directly references :attr:`music21.chord.Chord.normalFormString`


        .. attribute:: orderedPitchClasses

            directly references :attr:`music21.chord.Chord.orderedPitchClasses`


        .. attribute:: orderedPitchClassesString

            directly references :attr:`music21.chord.Chord.orderedPitchClassesString`


        .. attribute:: pitchClassCardinality

            directly references :attr:`music21.chord.Chord.pitchClassCardinality`


        .. attribute:: pitchClasses

            directly references :attr:`music21.chord.Chord.pitchClasses`


        .. attribute:: pitchNames

            directly references :attr:`music21.chord.Chord.pitchNames`


        .. attribute:: pitchedCommonName

            directly references :attr:`music21.chord.Chord.pitchedCommonName`


        .. attribute:: pitches

            directly references :attr:`music21.chord.Chord.pitches`


        .. attribute:: primeForm

            directly references :attr:`music21.chord.Chord.primeForm`


        .. attribute:: primeFormString

            directly references :attr:`music21.chord.Chord.primeFormString`


        .. attribute:: quality

            directly references :attr:`music21.chord.Chord.quality`


        .. attribute:: romanNumeral


            Get or set the romanNumeral numeral function of the Harmony as a :class:`~music21.romanNumeral.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>




        .. attribute:: scaleDegrees

            directly references :attr:`music21.chord.Chord.scaleDegrees`


        .. attribute:: seventh

            directly references :attr:`music21.chord.Chord.seventh`


        .. attribute:: third

            directly references :attr:`music21.chord.Chord.third`


        .. attribute:: tie

            directly references :attr:`music21.chord.Chord.tie`


        .. attribute:: volume

            directly references :attr:`music21.chord.Chord.volume`


        Properties inherited from :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.activeSite`, :attr:`~music21.base.Music21Object.beat`, :attr:`~music21.base.Music21Object.beatDuration`, :attr:`~music21.base.Music21Object.beatStr`, :attr:`~music21.base.Music21Object.beatStrength`, :attr:`~music21.base.Music21Object.classes`, :attr:`~music21.base.Music21Object.derivationHierarchy`, :attr:`~music21.base.Music21Object.measureNumber`, :attr:`~music21.base.Music21Object.offset`, :attr:`~music21.base.Music21Object.priority`, :attr:`~music21.base.Music21Object.seconds`

        Properties inherited from :class:`~music21.base.JSONSerializer`: :attr:`~music21.base.JSONSerializer.json`

    **Harmony** **methods**

        .. method:: addChordStepModification(degree)

            Add a harmony degree specification to this Harmony as a :class:`~music21.harmony.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




        .. method:: annotateIntervals(inPlace=True, stripSpecifiers=True, sortPitches=True)

            directly calls :meth:`~music21.chord.Chord.annotateIntervals`


        .. method:: areZRelations(other)

            directly calls :meth:`~music21.chord.Chord.areZRelations`


        .. method:: bass(newbass=0)

            directly calls :meth:`~music21.chord.Chord.bass`


        .. method:: canBeDominantV()

            directly calls :meth:`~music21.chord.Chord.canBeDominantV`


        .. method:: canBeTonic()

            directly calls :meth:`~music21.chord.Chord.canBeTonic`


        .. method:: closedPosition(forceOctave=None, inPlace=False)

            directly calls :meth:`~music21.chord.Chord.closedPosition`


        .. method:: containsSeventh()

            directly calls :meth:`~music21.chord.Chord.containsSeventh`


        .. method:: containsTriad()

            directly calls :meth:`~music21.chord.Chord.containsTriad`


        .. method:: findFigure()

            No documentation.


        .. method:: findRoot()

            directly calls :meth:`~music21.chord.Chord.findRoot`


        .. method:: getChordStep(chordStep, testRoot=None)

            directly calls :meth:`~music21.chord.Chord.getChordStep`


        .. method:: getChordStepModifications()

            Return all harmony degrees as a list.



        .. method:: getColor(pitchTarget)

            directly calls :meth:`~music21.chord.Chord.getColor`


        .. method:: getDegrees()

            Return list of all the degrees associated with the pitches of the Harmony Chord



            >>> from music21 import *
            >>> h = harmony.ChordSymbol('Dm7/F')
            >>> h.getDegrees()
            ['1', '-3', '5', '-7']



        .. method:: getNotehead(p)

            directly calls :meth:`~music21.chord.Chord.getNotehead`


        .. method:: getPitchesAndDegrees()

            pitchesAndDegrees is the compiled list of the pitches in the chord and their
            respective degrees (with alterations, a '-' for flat, a '#' for sharp, and an 'A'
            for altered. It is a list of lists of two units, the pitch and the degree. The list is
            not ordered.



            >>> from music21 import *
            >>> h = harmony.ChordSymbol('CMaj7')
            >>> h.getPitchesAndDegrees()
            [[C3, '1'], [E3, '3'], [G3, '5'], [B3, '7']]
            ⁠ 
            >>> h = harmony.ChordSymbol('Dm7/Fomit5')
            >>> h.getPitchesAndDegrees()
            [[D4, '1'], [F3, '-3'], [C4, '-7']]



            >>> h = harmony.ChordSymbol('Dm7/F')
            >>> h.getPitchesAndDegrees()
            [[D4, '1'], [F3, '-3'], [A3, '5'], [C4, '-7']]



        .. method:: getStemDirection(p)

            directly calls :meth:`~music21.chord.Chord.getStemDirection`


        .. method:: getTie(p)

            directly calls :meth:`~music21.chord.Chord.getTie`


        .. method:: getVolume(p)

            directly calls :meth:`~music21.chord.Chord.getVolume`


        .. method:: getZRelation()

            directly calls :meth:`~music21.chord.Chord.getZRelation`


        .. method:: hasAnyRepeatedDiatonicNote(testRoot=None)

            directly calls :meth:`~music21.chord.Chord.hasAnyRepeatedDiatonicNote`


        .. method:: hasComponentVolumes()

            directly calls :meth:`~music21.chord.Chord.hasComponentVolumes`


        .. method:: hasRepeatedChordStep(chordStep, testRoot=None)

            directly calls :meth:`~music21.chord.Chord.hasRepeatedChordStep`


        .. method:: intervalFromChordStep(chordStep, testRoot=None)

            directly calls :meth:`~music21.chord.Chord.intervalFromChordStep`


        .. method:: inversion()

            directly calls :meth:`~music21.chord.Chord.inversion`


        .. method:: inversionName()

            directly calls :meth:`~music21.chord.Chord.inversionName`


        .. method:: isAugmentedSixth()

            directly calls :meth:`~music21.chord.Chord.isAugmentedSixth`


        .. method:: isAugmentedTriad()

            directly calls :meth:`~music21.chord.Chord.isAugmentedTriad`


        .. method:: isConsonant()

            directly calls :meth:`~music21.chord.Chord.isConsonant`


        .. method:: isDiminishedSeventh()

            directly calls :meth:`~music21.chord.Chord.isDiminishedSeventh`


        .. method:: isDiminishedTriad()

            directly calls :meth:`~music21.chord.Chord.isDiminishedTriad`


        .. method:: isDominantSeventh()

            directly calls :meth:`~music21.chord.Chord.isDominantSeventh`


        .. method:: isFalseDiminishedSeventh()

            directly calls :meth:`~music21.chord.Chord.isFalseDiminishedSeventh`


        .. method:: isFrenchAugmentedSixth()

            directly calls :meth:`~music21.chord.Chord.isFrenchAugmentedSixth`


        .. method:: isGermanAugmentedSixth()

            directly calls :meth:`~music21.chord.Chord.isGermanAugmentedSixth`


        .. method:: isHalfDiminishedSeventh()

            directly calls :meth:`~music21.chord.Chord.isHalfDiminishedSeventh`


        .. method:: isIncompleteMajorTriad()

            directly calls :meth:`~music21.chord.Chord.isIncompleteMajorTriad`


        .. method:: isIncompleteMinorTriad()

            directly calls :meth:`~music21.chord.Chord.isIncompleteMinorTriad`


        .. method:: isItalianAugmentedSixth(restrictDoublings=False)

            directly calls :meth:`~music21.chord.Chord.isItalianAugmentedSixth`


        .. method:: isMajorTriad()

            directly calls :meth:`~music21.chord.Chord.isMajorTriad`


        .. method:: isMinorTriad()

            directly calls :meth:`~music21.chord.Chord.isMinorTriad`


        .. method:: isSeventh()

            directly calls :meth:`~music21.chord.Chord.isSeventh`


        .. method:: isSwissAugmentedSixth()

            directly calls :meth:`~music21.chord.Chord.isSwissAugmentedSixth`


        .. method:: isTriad()

            directly calls :meth:`~music21.chord.Chord.isTriad`


        .. method:: removeRedundantPitchClasses(inPlace=True)

            directly calls :meth:`~music21.chord.Chord.removeRedundantPitchClasses`


        .. method:: removeRedundantPitchNames(inPlace=True)

            directly calls :meth:`~music21.chord.Chord.removeRedundantPitchNames`


        .. method:: removeRedundantPitches(inPlace=True)

            directly calls :meth:`~music21.chord.Chord.removeRedundantPitches`


        .. method:: root(newroot=False)

            directly calls :meth:`~music21.chord.Chord.root`


        .. method:: seekChordTablesAddress()

            directly calls :meth:`~music21.chord.Chord.seekChordTablesAddress`


        .. method:: semitonesFromChordStep(chordStep, testRoot=None)

            directly calls :meth:`~music21.chord.Chord.semitonesFromChordStep`


        .. method:: setColor(value, pitchTarget=None)

            directly calls :meth:`~music21.chord.Chord.setColor`


        .. method:: setNotehead(nh, pitchTarget)

            directly calls :meth:`~music21.chord.Chord.setNotehead`


        .. method:: setStemDirection(stem, pitchTarget)

            directly calls :meth:`~music21.chord.Chord.setStemDirection`


        .. method:: setTie(t, pitchTarget)

            directly calls :meth:`~music21.chord.Chord.setTie`


        .. method:: setVolume(vol, pitchTarget=None)

            directly calls :meth:`~music21.chord.Chord.setVolume`


        .. method:: sortAscending(inPlace=False)

            directly calls :meth:`~music21.chord.Chord.sortAscending`


        .. method:: sortChromaticAscending()

            directly calls :meth:`~music21.chord.Chord.sortChromaticAscending`


        .. method:: sortDiatonicAscending(inPlace=False)

            directly calls :meth:`~music21.chord.Chord.sortDiatonicAscending`


        .. method:: sortFrequencyAscending()

            directly calls :meth:`~music21.chord.Chord.sortFrequencyAscending`


        .. method:: transpose(value, inPlace=False)

            directly calls :meth:`~music21.chord.Chord.transpose`


        Methods inherited from :class:`~music21.base.Music21Object`: :meth:`~music21.base.Music21Object.searchActiveSiteByAttr`, :meth:`~music21.base.Music21Object.getContextAttr`, :meth:`~music21.base.Music21Object.setContextAttr`, :meth:`~music21.base.Music21Object.addContext`, :meth:`~music21.base.Music21Object.addLocation`, :meth:`~music21.base.Music21Object.addLocationAndActiveSite`, :meth:`~music21.base.Music21Object.freezeIds`, :meth:`~music21.base.Music21Object.getAllContextsByClass`, :meth:`~music21.base.Music21Object.getCommonSiteIds`, :meth:`~music21.base.Music21Object.getCommonSites`, :meth:`~music21.base.Music21Object.getContextByClass`, :meth:`~music21.base.Music21Object.getOffsetBySite`, :meth:`~music21.base.Music21Object.getSiteIds`, :meth:`~music21.base.Music21Object.getSites`, :meth:`~music21.base.Music21Object.getSpannerSites`, :meth:`~music21.base.Music21Object.hasContext`, :meth:`~music21.base.Music21Object.hasSpannerSite`, :meth:`~music21.base.Music21Object.isClassOrSubclass`, :meth:`~music21.base.Music21Object.mergeAttributes`, :meth:`~music21.base.Music21Object.next`, :meth:`~music21.base.Music21Object.previous`, :meth:`~music21.base.Music21Object.purgeLocations`, :meth:`~music21.base.Music21Object.removeLocationBySite`, :meth:`~music21.base.Music21Object.removeLocationBySiteId`, :meth:`~music21.base.Music21Object.removeNonContainedLocations`, :meth:`~music21.base.Music21Object.setOffsetBySite`, :meth:`~music21.base.Music21Object.show`, :meth:`~music21.base.Music21Object.splitAtDurations`, :meth:`~music21.base.Music21Object.splitAtQuarterLength`, :meth:`~music21.base.Music21Object.splitByQuarterLengths`, :meth:`~music21.base.Music21Object.unfreezeIds`, :meth:`~music21.base.Music21Object.unwrapWeakref`, :meth:`~music21.base.Music21Object.wrapWeakref`, :meth:`~music21.base.Music21Object.write`

        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonAttributes`, :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


ChordStepModification
---------------------



.. class:: ChordStepModification(modType=None, degree=None, interval=None)

    ChordStepModification objects define the specification of harmony degree alterations, subtractions, or additions,
    used in :class:`~music21.harmony.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 XML DOCUMENTATION
       http://www.google.com/codesearch#AHKd_kdk32Q/trunk/musicXML/dtd/direction.mod&q=Chord%20Symbols%20package:http://bmml%5C.googlecode%5C.com&l=530
       The degree element is used to add, alter, or subtract
       individual notes in the chord. The degree-value element
       is a number indicating the degree of the chord (1 for
       the root, 3 for third, etc). The degree-alter element
       is like the alter element in notes: 1 for sharp, -1 for
       flat, etc. The degree-type element can be add, alter, or
       subtract. If the degree-type is alter or subtract, the
       degree-alter is relative to the degree already in the
       chord based on its kind element. If the degree-type is
       add, the degree-alter is relative to a dominant chord
       (major and perfect intervals except for a minor
       seventh). The print-object attribute can be used to
       keep the degree from printing separately when it has
       already taken into account in the text attribute of
       the kind element. The plus-minus attribute is used to
       indicate if plus and minus symbols should be used
       instead of sharp and flat symbols to display the degree
       alteration; it is no by default. The degree-value and
       degree-type text attributes specify how the value and
       type of the degree should be displayed.

       A harmony of kind "other" can be spelled explicitly by
       using a series of degree elements together with a root.
       -->

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

        .. attribute:: 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




        .. attribute:: interval


            Get or set the alteration of this degree as a :class:`~music21.interval.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>



        .. attribute:: 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




ChordSymbol
-----------

Inherits from: :class:`~music21.harmony.Harmony`, :class:`~music21.base.Music21Object`, :class:`~music21.base.JSONSerializer`

.. class:: 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.

    When a Chord Symbol object is instantiated, it creates a 'chord' property, which is the chord
    representation of the Chord Symbol object. This chord is of :class:`~music21.chord.Chord` and
    can be manipulated in the same was as any other chord object. However, when you access the chord
    attribute of the Chord Symbol, the pitches associated with that chord symbol are realized. This is true
    for both Chord Symbol objects instantiated from music xml and directly with music21.

    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, E3, 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]




    **ChordSymbol** **attributes**

        Attributes without Documentation: `XMLkindStr`, `XMLkind`

        Attributes inherited from :class:`~music21.harmony.Harmony`: :attr:`~music21.harmony.Harmony.chordStepModifications`

        Attributes inherited from :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.classSortOrder`, :attr:`~music21.base.Music21Object.hideObjectOnPrint`, :attr:`~music21.base.Music21Object.id`, :attr:`~music21.base.Music21Object.isSpanner`, :attr:`~music21.base.Music21Object.isStream`, :attr:`~music21.base.Music21Object.groups`

    **ChordSymbol** **properties**

        Properties inherited from :class:`~music21.harmony.Harmony`: :attr:`~music21.harmony.Harmony.XMLbass`, :attr:`~music21.harmony.Harmony.XMLinversion`, :attr:`~music21.harmony.Harmony.XMLroot`, :attr:`~music21.harmony.Harmony.chord`, :attr:`~music21.harmony.Harmony.chordTablesAddress`, :attr:`~music21.harmony.Harmony.color`, :attr:`~music21.harmony.Harmony.commonName`, :attr:`~music21.harmony.Harmony.duration`, :attr:`~music21.harmony.Harmony.fifth`, :attr:`~music21.harmony.Harmony.figure`, :attr:`~music21.harmony.Harmony.forteClass`, :attr:`~music21.harmony.Harmony.forteClassNumber`, :attr:`~music21.harmony.Harmony.forteClassTn`, :attr:`~music21.harmony.Harmony.forteClassTnI`, :attr:`~music21.harmony.Harmony.fullName`, :attr:`~music21.harmony.Harmony.hasZRelation`, :attr:`~music21.harmony.Harmony.intervalVector`, :attr:`~music21.harmony.Harmony.intervalVectorString`, :attr:`~music21.harmony.Harmony.isPrimeFormInversion`, :attr:`~music21.harmony.Harmony.midiEvents`, :attr:`~music21.harmony.Harmony.midiFile`, :attr:`~music21.harmony.Harmony.multisetCardinality`, :attr:`~music21.harmony.Harmony.normalForm`, :attr:`~music21.harmony.Harmony.normalFormString`, :attr:`~music21.harmony.Harmony.orderedPitchClasses`, :attr:`~music21.harmony.Harmony.orderedPitchClassesString`, :attr:`~music21.harmony.Harmony.pitchClassCardinality`, :attr:`~music21.harmony.Harmony.pitchClasses`, :attr:`~music21.harmony.Harmony.pitchNames`, :attr:`~music21.harmony.Harmony.pitchedCommonName`, :attr:`~music21.harmony.Harmony.pitches`, :attr:`~music21.harmony.Harmony.primeForm`, :attr:`~music21.harmony.Harmony.primeFormString`, :attr:`~music21.harmony.Harmony.quality`, :attr:`~music21.harmony.Harmony.romanNumeral`, :attr:`~music21.harmony.Harmony.scaleDegrees`, :attr:`~music21.harmony.Harmony.seventh`, :attr:`~music21.harmony.Harmony.third`, :attr:`~music21.harmony.Harmony.tie`, :attr:`~music21.harmony.Harmony.volume`

        Properties inherited from :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.activeSite`, :attr:`~music21.base.Music21Object.beat`, :attr:`~music21.base.Music21Object.beatDuration`, :attr:`~music21.base.Music21Object.beatStr`, :attr:`~music21.base.Music21Object.beatStrength`, :attr:`~music21.base.Music21Object.classes`, :attr:`~music21.base.Music21Object.derivationHierarchy`, :attr:`~music21.base.Music21Object.measureNumber`, :attr:`~music21.base.Music21Object.offset`, :attr:`~music21.base.Music21Object.priority`, :attr:`~music21.base.Music21Object.seconds`

        Properties inherited from :class:`~music21.base.JSONSerializer`: :attr:`~music21.base.JSONSerializer.json`

    **ChordSymbol** **methods**

        .. method:: 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 actually pitches rather than numeric degrees



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



        .. method:: 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 :class:`~music21.harmony.Harmony`: :meth:`~music21.harmony.Harmony.addChordStepModification`, :meth:`~music21.harmony.Harmony.annotateIntervals`, :meth:`~music21.harmony.Harmony.areZRelations`, :meth:`~music21.harmony.Harmony.bass`, :meth:`~music21.harmony.Harmony.canBeDominantV`, :meth:`~music21.harmony.Harmony.canBeTonic`, :meth:`~music21.harmony.Harmony.closedPosition`, :meth:`~music21.harmony.Harmony.containsSeventh`, :meth:`~music21.harmony.Harmony.containsTriad`, :meth:`~music21.harmony.Harmony.findRoot`, :meth:`~music21.harmony.Harmony.getChordStep`, :meth:`~music21.harmony.Harmony.getChordStepModifications`, :meth:`~music21.harmony.Harmony.getColor`, :meth:`~music21.harmony.Harmony.getDegrees`, :meth:`~music21.harmony.Harmony.getNotehead`, :meth:`~music21.harmony.Harmony.getPitchesAndDegrees`, :meth:`~music21.harmony.Harmony.getStemDirection`, :meth:`~music21.harmony.Harmony.getTie`, :meth:`~music21.harmony.Harmony.getVolume`, :meth:`~music21.harmony.Harmony.getZRelation`, :meth:`~music21.harmony.Harmony.hasAnyRepeatedDiatonicNote`, :meth:`~music21.harmony.Harmony.hasComponentVolumes`, :meth:`~music21.harmony.Harmony.hasRepeatedChordStep`, :meth:`~music21.harmony.Harmony.intervalFromChordStep`, :meth:`~music21.harmony.Harmony.inversion`, :meth:`~music21.harmony.Harmony.inversionName`, :meth:`~music21.harmony.Harmony.isAugmentedSixth`, :meth:`~music21.harmony.Harmony.isAugmentedTriad`, :meth:`~music21.harmony.Harmony.isConsonant`, :meth:`~music21.harmony.Harmony.isDiminishedSeventh`, :meth:`~music21.harmony.Harmony.isDiminishedTriad`, :meth:`~music21.harmony.Harmony.isDominantSeventh`, :meth:`~music21.harmony.Harmony.isFalseDiminishedSeventh`, :meth:`~music21.harmony.Harmony.isFrenchAugmentedSixth`, :meth:`~music21.harmony.Harmony.isGermanAugmentedSixth`, :meth:`~music21.harmony.Harmony.isHalfDiminishedSeventh`, :meth:`~music21.harmony.Harmony.isIncompleteMajorTriad`, :meth:`~music21.harmony.Harmony.isIncompleteMinorTriad`, :meth:`~music21.harmony.Harmony.isItalianAugmentedSixth`, :meth:`~music21.harmony.Harmony.isMajorTriad`, :meth:`~music21.harmony.Harmony.isMinorTriad`, :meth:`~music21.harmony.Harmony.isSeventh`, :meth:`~music21.harmony.Harmony.isSwissAugmentedSixth`, :meth:`~music21.harmony.Harmony.isTriad`, :meth:`~music21.harmony.Harmony.removeRedundantPitchClasses`, :meth:`~music21.harmony.Harmony.removeRedundantPitchNames`, :meth:`~music21.harmony.Harmony.removeRedundantPitches`, :meth:`~music21.harmony.Harmony.root`, :meth:`~music21.harmony.Harmony.seekChordTablesAddress`, :meth:`~music21.harmony.Harmony.semitonesFromChordStep`, :meth:`~music21.harmony.Harmony.setColor`, :meth:`~music21.harmony.Harmony.setNotehead`, :meth:`~music21.harmony.Harmony.setStemDirection`, :meth:`~music21.harmony.Harmony.setTie`, :meth:`~music21.harmony.Harmony.setVolume`, :meth:`~music21.harmony.Harmony.sortAscending`, :meth:`~music21.harmony.Harmony.sortChromaticAscending`, :meth:`~music21.harmony.Harmony.sortDiatonicAscending`, :meth:`~music21.harmony.Harmony.sortFrequencyAscending`, :meth:`~music21.harmony.Harmony.transpose`

        Methods inherited from :class:`~music21.base.Music21Object`: :meth:`~music21.base.Music21Object.searchActiveSiteByAttr`, :meth:`~music21.base.Music21Object.getContextAttr`, :meth:`~music21.base.Music21Object.setContextAttr`, :meth:`~music21.base.Music21Object.addContext`, :meth:`~music21.base.Music21Object.addLocation`, :meth:`~music21.base.Music21Object.addLocationAndActiveSite`, :meth:`~music21.base.Music21Object.freezeIds`, :meth:`~music21.base.Music21Object.getAllContextsByClass`, :meth:`~music21.base.Music21Object.getCommonSiteIds`, :meth:`~music21.base.Music21Object.getCommonSites`, :meth:`~music21.base.Music21Object.getContextByClass`, :meth:`~music21.base.Music21Object.getOffsetBySite`, :meth:`~music21.base.Music21Object.getSiteIds`, :meth:`~music21.base.Music21Object.getSites`, :meth:`~music21.base.Music21Object.getSpannerSites`, :meth:`~music21.base.Music21Object.hasContext`, :meth:`~music21.base.Music21Object.hasSpannerSite`, :meth:`~music21.base.Music21Object.isClassOrSubclass`, :meth:`~music21.base.Music21Object.mergeAttributes`, :meth:`~music21.base.Music21Object.next`, :meth:`~music21.base.Music21Object.previous`, :meth:`~music21.base.Music21Object.purgeLocations`, :meth:`~music21.base.Music21Object.removeLocationBySite`, :meth:`~music21.base.Music21Object.removeLocationBySiteId`, :meth:`~music21.base.Music21Object.removeNonContainedLocations`, :meth:`~music21.base.Music21Object.setOffsetBySite`, :meth:`~music21.base.Music21Object.show`, :meth:`~music21.base.Music21Object.splitAtDurations`, :meth:`~music21.base.Music21Object.splitAtQuarterLength`, :meth:`~music21.base.Music21Object.splitByQuarterLengths`, :meth:`~music21.base.Music21Object.unfreezeIds`, :meth:`~music21.base.Music21Object.unwrapWeakref`, :meth:`~music21.base.Music21Object.wrapWeakref`, :meth:`~music21.base.Music21Object.write`

        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonAttributes`, :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


