.. _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. 


.. 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:: keyFromString(strKey)

    Given a string representing a key, return the appropriate Key object. 

.. 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.) but not Locrian yet. If `mode` is omitted, 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 

    

.. 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)


    

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

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

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

            returns the Lilypond representation of a KeySignature object 

            >>> from music21 import *
            >>> d = key.KeySignature(-1)
            >>> d.mode = 'minor'
            >>> print d.lily
            \key d \minor 
            Major is assumed: 
            >>> fsharp = key.KeySignature(6)
            >>> print fsharp.lily
            \key fis \major 

        .. 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.measureNumber`, :attr:`~music21.base.Music21Object.offset`, :attr:`~music21.base.Music21Object.priority`

        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.searchParentByAttr`, :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.mergeAttributes`, :meth:`~music21.base.Music21Object.purgeLocations`, :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. EXPERIMENTAL 

    

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

    

    **Key** **attributes**

        Attributes without Documentation: `correlationCoefficient`, `tonic`, `alternateInterpretations`

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

        Attributes inherited from :class:`~music21.scale.ConcreteScale`: :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.hideObjectOnPrint`, :attr:`~music21.base.Music21Object.id`

    **Key** **properties**

        Properties inherited from :class:`~music21.key.KeySignature`: :attr:`~music21.key.KeySignature.alteredPitches`, :attr:`~music21.key.KeySignature.lily`, :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.measureNumber`, :attr:`~music21.base.Music21Object.offset`, :attr:`~music21.base.Music21Object.priority`

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

    **Key** **methods**

        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.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`

        Methods inherited from :class:`~music21.base.Music21Object`: :meth:`~music21.base.Music21Object.searchParentByAttr`, :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.mergeAttributes`, :meth:`~music21.base.Music21Object.purgeLocations`, :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`


