.. _moduleKey:

music21.key
===========

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

.. module:: music21.key

This module defines objects for representing key signatures as well as key
areas. The :class:`~music21.key.KeySignature` is used in
:class:`~music21.stream.Measure` objects for defining notated key signatures.

The :class:`~music21.key.Key` object is a fuller representation not just of
a key signature but also of the key of a region.




.. function:: convertKeyStringToMusic21KeyString(textString)


    Utility function to change strings in the form of "Eb" to
    "E-" (for E-flat major) and leaves alone proper music21 strings
    (like "E-" or "f#").  A little bit complex because of parsing
    bb as B-flat minor and Bb as B-flat major.




    >>> from music21 import *
    >>> key.convertKeyStringToMusic21KeyString('Eb')
    'E-'
    >>> key.convertKeyStringToMusic21KeyString('f#')
    'f#'
    >>> key.convertKeyStringToMusic21KeyString('bb')
    'b-'
    >>> key.convertKeyStringToMusic21KeyString('Bb')
    'B-'
    >>> key.convertKeyStringToMusic21KeyString('b#')
    'b#'
    >>> key.convertKeyStringToMusic21KeyString('c')
    'c'



.. function:: pitchToSharps(value, mode=None)

    Given a pitch or :class:`music21.pitch.Pitch` object,
    return the number of sharps found in that mode.

    The `mode` parameter can be 'major', 'minor', or most
    of the common church/jazz modes ('dorian', 'mixolydian', etc.)
    including Locrian.

    If `mode` is omitted or not found, the default mode is major.

    (extra points to anyone who can find the earliest reference to
    the Locrian mode in print.  David Cohen and I (MSC) have been
    looking for this for years).



    >>> from music21 import *
    ⁠ 
    >>> key.pitchToSharps('c')
    0
    >>> key.pitchToSharps('c', 'minor')
    -3
    >>> key.pitchToSharps('a', 'minor')
    0
    >>> key.pitchToSharps('d')
    2
    >>> key.pitchToSharps('e-')
    -3
    >>> key.pitchToSharps('a')
    3
    >>> key.pitchToSharps('e', 'minor')
    1
    >>> key.pitchToSharps('f#', 'major')
    6
    >>> key.pitchToSharps('g-', 'major')
    -6
    >>> key.pitchToSharps('c#')
    7
    >>> key.pitchToSharps('g#')
    8
    >>> key.pitchToSharps('e', 'dorian')
    2
    >>> key.pitchToSharps('d', 'dorian')
    0
    >>> key.pitchToSharps('g', 'mixolydian')
    0
    >>> key.pitchToSharps('e-', 'lydian')
    -2
    >>> key.pitchToSharps('e-', 'lydian')
    -2
    >>> key.pitchToSharps('a', 'phrygian')
    -1
    >>> key.pitchToSharps('e', 'phrygian')
    0
    >>> key.pitchToSharps('f#')
    6
    >>> key.pitchToSharps('f-')
    -8
    >>> key.pitchToSharps('f--')
    -15
    >>> key.pitchToSharps('f--', 'locrian')
    -20

    But quarter tones don't work:



    >>> key.pitchToSharps('C~')
    Traceback (most recent call last):
    KeyException: Cannot determine sharps for quarter-tone keys! silly!




.. function:: sharpsToPitch(sharpCount)

    Given a number a positive/negative number of sharps, return a Pitch
    object set to the appropriate major key value.



    >>> from music21 import *
    >>> key.sharpsToPitch(1)
    G
    >>> key.sharpsToPitch(1)
    G
    >>> key.sharpsToPitch(2)
    D
    >>> key.sharpsToPitch(-2)
    B-
    >>> key.sharpsToPitch(-6)
    G-

    Note that these are :class:`music21.pitch.Pitch` objects not just names:



    >>> k1 = key.sharpsToPitch(6)
    >>> k1
    F#
    >>> k1.step
    'F'
    >>> k1.accidental
    <accidental sharp>



KeySignature
------------

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

.. class:: KeySignature(sharps=None, mode=None)


    A KeySignature object specifies the signature to be used for a piece; it takes
    in zero, one, or two arguments.  The first argument is an int giving the number of sharps,
    or if negative the number of flats.  The second argument (deprecated -- do not use)
    specifies the mode of the piece ('major', 'minor', or None for unknown).

    If you are starting with the name of a key, see the :class:`~music21.key.Key` object.



    >>> from music21 import *
    ⁠ 
    >>> A = key.KeySignature(3)
    >>> A
    <music21.key.KeySignature of 3 sharps>



    >>> Eflat = key.KeySignature(-3)
    >>> Eflat
    <music21.key.KeySignature of 3 flats>


    If you want to get a real Key, then use the :class:`~music21.key.Key` object instead:



    >>> illegal = key.KeySignature('c#')
    Traceback (most recent call last):
    KeySignatureException: Cannot get a KeySignature from this "number" of sharps: "c#"; did you mean to use a key.Key() object instead?
    ⁠ 
    >>> legal = key.Key('c#')
    >>> legal.sharps
    4
    >>> legal
    <music21.key.Key of c# minor>



    **KeySignature** **attributes**

        .. attribute:: classSortOrder

            Property which returns an number (int or otherwise)
            depending on the class of the Music21Object that
            represents a priority for an object based on its class alone --
            used as a tie for stream sorting in case two objects have the
            same offset and priority.  Lower numbers are sorted to the left
            of higher numbers.  For instance, Clef, KeySignature, TimeSignature
            all come (in that order) before Note.

            All undefined classes have classSortOrder of 20 -- same as note.Note



            >>> from music21 import *
            >>> tc = clef.TrebleClef()
            >>> tc.classSortOrder
            0
            >>> ks = key.KeySignature(3)
            >>> ks.classSortOrder
            1


            New classes can define their own default classSortOrder



            >>> class ExampleClass(base.Music21Object):
            ...     classSortOrderDefault = 5
            ...
            >>> ec1 = ExampleClass()
            >>> ec1.classSortOrder
            5



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

    **KeySignature** **properties**

        .. attribute:: alteredPitches


            Return a list of music21.pitch.Pitch objects that are altered by this
            KeySignature. That is, all Pitch objects that will receive an accidental.



            >>> from music21 import *
            ⁠ 
            >>> a = key.KeySignature(3)
            >>> a.alteredPitches
            [F#, C#, G#]
            >>> b = key.KeySignature(1)
            >>> b.alteredPitches
            [F#]



            >>> c = key.KeySignature(9)
            >>> c.alteredPitches
            [F#, C#, G#, D#, A#, E#, B#, F##, C##]
            ⁠ 
            >>> d = key.KeySignature(-3)
            >>> d.alteredPitches
            [B-, E-, A-]



            >>> e = key.KeySignature(-1)
            >>> e.alteredPitches
            [B-]
            ⁠ 
            >>> f = key.KeySignature(-6)
            >>> f.alteredPitches
            [B-, E-, A-, D-, G-, C-]



            >>> g = key.KeySignature(-8)
            >>> g.alteredPitches
            [B-, E-, A-, D-, G-, C-, F-, B--]



        .. attribute:: mode

            Get or set the mode.



        .. attribute:: mx

            Returns a musicxml.KeySignature object



            >>> a = KeySignature(3)
            >>> a.sharps = -3
            >>> mxKey = a.mx
            >>> mxKey.get('fifths')
            -3



        .. attribute:: pitchAndMode

            Returns a a two value list containing
            a :class:`music21.pitch.Pitch` object that
            names this key and the value of :attr:`~music21.key.KeySignature.mode`.



            >>> from music21 import *
            ⁠ 
            >>> key.KeySignature(-7).pitchAndMode
            (C-, None)
            >>> key.KeySignature(-6).pitchAndMode
            (G-, None)
            >>> key.KeySignature(-3).pitchAndMode
            (E-, None)
            >>> key.KeySignature(0).pitchAndMode
            (C, None)
            >>> key.KeySignature(1).pitchAndMode
            (G, None)
            >>> csharp = key.KeySignature(4)
            >>> csharp.mode = "minor"
            >>> csharp.pitchAndMode
            (C#, 'minor')
            >>> csharpPitch = csharp.pitchAndMode[0]
            >>> csharpPitch.accidental
            <accidental sharp>



        .. attribute:: sharps

            Get or set the number of sharps.



        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.duration`, :attr:`~music21.base.Music21Object.isGrace`, :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`

    **KeySignature** **methods**

        .. method:: accidentalByStep(step)


            Given a step (C, D, E, F, etc.) return the accidental
            for that note in this key (using the natural minor for minor)
            or None if there is none.



            >>> from music21 import *
            ⁠ 
            >>> g = key.KeySignature(1)
            >>> g.accidentalByStep("F")
            <accidental sharp>
            >>> g.accidentalByStep("G")



            >>> f = KeySignature(-1)
            >>> bbNote = note.Note("B-5")
            >>> f.accidentalByStep(bbNote.step)
            <accidental flat>


            Fix a wrong note in F-major:




            >>> wrongBNote = note.Note("B#4")
            >>> if f.accidentalByStep(wrongBNote.step) != wrongBNote.accidental:
            ...    wrongBNote.accidental = f.accidentalByStep(wrongBNote.step)
            >>> wrongBNote
            <music21.note.Note B->


            Set all notes to the correct notes for a key using the
            note's Key Context.  Before:




            >>> from music21 import *
            >>> s1 = stream.Stream()
            >>> s1.append(key.KeySignature(4))  # E-major or C-sharp-minor
            >>> s1.append(note.HalfNote("C"))
            >>> s1.append(note.HalfNote("E-"))
            >>> s1.append(key.KeySignature(-4)) # A-flat-major or F-minor
            >>> s1.append(note.WholeNote("A"))
            >>> s1.append(note.WholeNote("F#"))
            >>> s1.show()






            .. image:: images/keyAccidentalByStep_Before.*
                    :width: 400



            After:




            >>> for n in s1.notes:
            ...    n.accidental = n.getContextByClass(key.KeySignature).accidentalByStep(n.step)
            >>> s1.show()






            .. image:: images/keyAccidentalByStep.*
                    :width: 400








        .. method:: getScale()

            Return a scale that is representative of this key.



            >>> from music21 import *
            >>> ks = key.KeySignature(3)
            >>> ks
            <music21.key.KeySignature of 3 sharps>
            >>> ks.getScale()
            <music21.scale.MajorScale A major>



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


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



            >>> a = KeySignature(2)
            >>> a.pitchAndMode
            (D, None)
            >>> b = a.transpose('p5')
            >>> b.pitchAndMode
            (A, None)
            >>> b.sharps
            3
            >>> c = b.transpose('-m2')
            >>> c.pitchAndMode
            (G#, None)
            >>> c.sharps
            8
            ⁠ 
            >>> d = c.transpose('-a3')
            >>> d.pitchAndMode
            (E-, None)
            >>> d.sharps
            -3



        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.hasSite`, :meth:`~music21.base.Music21Object.hasSpannerSite`, :meth:`~music21.base.Music21Object.hasVariantSite`, :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.purgeOrphans`, :meth:`~music21.base.Music21Object.purgeUndeclaredIds`, :meth:`~music21.base.Music21Object.removeLocationBySite`, :meth:`~music21.base.Music21Object.removeLocationBySiteId`, :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`


Key
---

Inherits from: :class:`~music21.key.KeySignature`, :class:`~music21.scale.DiatonicScale`, :class:`~music21.scale.ConcreteScale`, :class:`~music21.scale.Scale`, :class:`~music21.base.Music21Object`, :class:`~music21.base.JSONSerializer`

.. class:: Key(tonic=None, mode=None)


    Note that a key is a sort of hypothetical/conceptual object.
    It probably has a scale (or scales) associated with it and a KeySignature,
    but not necessarily.



    >>> from music21 import *
    >>> cm = key.Key('c')  # cminor.
    >>> cm
    <music21.key.Key of c minor>
    >>> cm.sharps
    -3
    >>> cm.pitchFromDegree(3)
    E-4
    >>> cm.pitchFromDegree(7)
    B-4
    ⁠ 
    >>> Csharpmaj = key.Key('C#')
    >>> Csharpmaj
    <music21.key.Key of C# major>
    >>> Csharpmaj.sharps
    7



    >>> Fflatmaj = key.Key('F-')
    >>> Fflatmaj
    <music21.key.Key of F- major>
    >>> Fflatmaj.sharps
    -8
    >>> Fflatmaj.accidentalByStep('B')
    <accidental double-flat>



    **Key** **attributes**

        Attributes without Documentation: `correlationCoefficient`, `alternateInterpretations`

        Attributes inherited from :class:`~music21.key.KeySignature`: :attr:`~music21.key.KeySignature.classSortOrder`

        Attributes inherited from :class:`~music21.scale.ConcreteScale`: :attr:`~music21.scale.ConcreteScale.tonic`, :attr:`~music21.scale.ConcreteScale.boundRange`

        Attributes inherited from :class:`~music21.scale.Scale`: :attr:`~music21.scale.Scale.type`

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

    **Key** **properties**

        Properties inherited from :class:`~music21.key.KeySignature`: :attr:`~music21.key.KeySignature.alteredPitches`, :attr:`~music21.key.KeySignature.mode`, :attr:`~music21.key.KeySignature.mx`, :attr:`~music21.key.KeySignature.pitchAndMode`, :attr:`~music21.key.KeySignature.sharps`

        Properties inherited from :class:`~music21.scale.DiatonicScale`: :attr:`~music21.scale.DiatonicScale.musicxml`

        Properties inherited from :class:`~music21.scale.ConcreteScale`: :attr:`~music21.scale.ConcreteScale.abstract`, :attr:`~music21.scale.ConcreteScale.chord`, :attr:`~music21.scale.ConcreteScale.isConcrete`, :attr:`~music21.scale.ConcreteScale.name`, :attr:`~music21.scale.ConcreteScale.pitches`

        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.duration`, :attr:`~music21.base.Music21Object.isGrace`, :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`

    **Key** **methods**

        .. method:: tonalCertainty(method='correlationCoefficient', *args, **keywords)

            Provide a measure of tonal ambiguity for Key determined with one of many methods.

            The `correlationCoefficient` assumes that the alternateInterpretations list has been filled from the use of a KeyWeightKeyAnalysis subclass.



        Methods inherited from :class:`~music21.key.KeySignature`: :meth:`~music21.key.KeySignature.accidentalByStep`, :meth:`~music21.key.KeySignature.getScale`, :meth:`~music21.key.KeySignature.transpose`

        Methods inherited from :class:`~music21.scale.DiatonicScale`: :meth:`~music21.scale.DiatonicScale.getDominant`, :meth:`~music21.scale.DiatonicScale.getLeadingTone`, :meth:`~music21.scale.DiatonicScale.getParallelMajor`, :meth:`~music21.scale.DiatonicScale.getParallelMinor`, :meth:`~music21.scale.DiatonicScale.getRelativeMajor`, :meth:`~music21.scale.DiatonicScale.getRelativeMinor`, :meth:`~music21.scale.DiatonicScale.getTonic`

        Methods inherited from :class:`~music21.scale.ConcreteScale`: :meth:`~music21.scale.ConcreteScale.derive`, :meth:`~music21.scale.ConcreteScale.deriveByDegree`, :meth:`~music21.scale.ConcreteScale.deriveRanked`, :meth:`~music21.scale.ConcreteScale.findMissing`, :meth:`~music21.scale.ConcreteScale.getChord`, :meth:`~music21.scale.ConcreteScale.getDegreeMaxUnique`, :meth:`~music21.scale.ConcreteScale.getPitches`, :meth:`~music21.scale.ConcreteScale.getScalaStorage`, :meth:`~music21.scale.ConcreteScale.getScaleDegreeAndAccidentalFromPitch`, :meth:`~music21.scale.ConcreteScale.getScaleDegreeFromPitch`, :meth:`~music21.scale.ConcreteScale.intervalBetweenDegrees`, :meth:`~music21.scale.ConcreteScale.isNext`, :meth:`~music21.scale.ConcreteScale.match`, :meth:`~music21.scale.ConcreteScale.next`, :meth:`~music21.scale.ConcreteScale.pitchFromDegree`, :meth:`~music21.scale.ConcreteScale.pitchesFromScaleDegrees`, :meth:`~music21.scale.ConcreteScale.romanNumeral`, :meth:`~music21.scale.ConcreteScale.show`, :meth:`~music21.scale.ConcreteScale.solfeg`, :meth:`~music21.scale.ConcreteScale.tune`, :meth:`~music21.scale.ConcreteScale.write`

        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.hasSite`, :meth:`~music21.base.Music21Object.hasSpannerSite`, :meth:`~music21.base.Music21Object.hasVariantSite`, :meth:`~music21.base.Music21Object.isClassOrSubclass`, :meth:`~music21.base.Music21Object.mergeAttributes`, :meth:`~music21.base.Music21Object.previous`, :meth:`~music21.base.Music21Object.purgeLocations`, :meth:`~music21.base.Music21Object.purgeOrphans`, :meth:`~music21.base.Music21Object.purgeUndeclaredIds`, :meth:`~music21.base.Music21Object.removeLocationBySite`, :meth:`~music21.base.Music21Object.removeLocationBySiteId`, :meth:`~music21.base.Music21Object.setOffsetBySite`, :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`

        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`


