.. _modulePitch:

music21.pitch
=============

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

.. module:: music21.pitch


Classes and functions for creating and manipulating pitches, pitch-space, and accidentals.
Used extensively by note.py8




.. function:: convertCentsToAlterAndCents(shift)

    Given any floating point value, split into accidental and microtone components.



    >>> from music21 import *
    >>> pitch.convertCentsToAlterAndCents(125)
    (1, 25.0)
    >>> pitch.convertCentsToAlterAndCents(-75)
    (-0.5, -25.0)
    >>> pitch.convertCentsToAlterAndCents(-125)
    (-1, -25.0)
    >>> pitch.convertCentsToAlterAndCents(-200)
    (-2, 0.0)
    >>> pitch.convertCentsToAlterAndCents(235)
    (2.5, -15.0)



.. function:: convertFqToPs(fq)

    Utility conversion; does not process internals.
    Converts a frequency in Hz into a midiNote number.
    Assumes A4 = 440 Hz


    >>> convertFqToPs(440)
    69.0
    >>> convertFqToPs(261.62556530059862)
    60.0



.. function:: convertHarmonicToCents(value)

    Given a harmonic number, return the total number shift in cents assuming 12 tone equal temperament.



    >>> convertHarmonicToCents(8)
    3600
    >>> [convertHarmonicToCents(x) for x in [5, 6, 7, 8]]
    [2786, 3102, 3369, 3600]
    >>> [convertHarmonicToCents(x) for x in [16, 17, 18, 19]]
    [4800, 4905, 5004, 5098]
    ⁠ 
    >>> [convertHarmonicToCents(x) for x in range(1, 33)]
    [0, 1200, 1902, 2400, 2786, 3102, 3369, 3600, 3804, 3986, 4151, 4302, 4441, 4569, 4688, 4800, 4905, 5004, 5098, 5186, 5271, 5351, 5428, 5502, 5573, 5641, 5706, 5769, 5830, 5888, 5945, 6000]


    Works with subHarmonics as well by specifying them as either 1/x or negative numbers.
    note that -2 is the first subharmonic, since -1 == 1:



    >>> [convertHarmonicToCents(1.0/x) for x in [1, 2, 3, 4]]
    [0, -1200, -1902, -2400]
    >>> [convertHarmonicToCents(x) for x in [-1, -2, -3, -4]]
    [0, -1200, -1902, -2400]

    So the fifth subharmonic of the 7th harmonic (remember floating point division for Python 2.x!),
    which is C2->C3->G3->C4->E4->G4->B\`4 --> B\`3->E\`3->B\`2->G-\`2



    >>> convertHarmonicToCents(7.0/5.0)
    583
    >>> convertHarmonicToCents(7.0) - convertHarmonicToCents(5.0)
    583



.. function:: convertNameToPitchClass(pitchName)

    Utility conversion: from a pitch name to a pitch class integer between 0 and 11.



    >>> convertNameToPitchClass('c4')
    0
    >>> convertNameToPitchClass('c#')
    1
    >>> convertNameToPitchClass('d-')
    1
    >>> convertNameToPitchClass('e--')
    2
    >>> convertNameToPitchClass('b2##')
    1



.. function:: convertNameToPs(pitchName)

    Utility conversion: from a pitch name to a pitch space number (floating point MIDI pitch values).



    >>> from music21 import *
    >>> pitch.convertNameToPs('c4')
    60.0
    >>> pitch.convertNameToPs('c2#')
    37.0
    >>> pitch.convertNameToPs('d7-')
    97.0
    >>> pitch.convertNameToPs('e1--')
    26.0
    >>> pitch.convertNameToPs('b2##')
    49.0
    >>> pitch.convertNameToPs('c~4')
    60.5



.. function:: convertPitchClassToNumber(ps)

    Given a pitch class or pitch class value,
    look for strings. If a string is found,
    replace it with the default pitch class representation.



    >>> from music21 import *
    >>> pitch.convertPitchClassToNumber(3)
    3
    >>> pitch.convertPitchClassToNumber('a')
    10
    >>> pitch.convertPitchClassToNumber('B')
    11
    >>> pitch.convertPitchClassToNumber('3')
    3



.. function:: convertPitchClassToStr(pc)

    Given a pitch class number, return a string.



    >>> convertPitchClassToStr(3)
    '3'
    >>> convertPitchClassToStr(10)
    'A'



.. function:: convertPsToFq(ps)

    Utility conversion; does not process internals.

    Converts a midiNote number to a frequency in Hz.
    Assumes A4 = 440 Hz




    >>> from music21 import *
    >>> pitch.convertPsToFq(69)
    440.0
    >>> str(pitch.convertPsToFq(60))
    '261.625565301'
    >>> str(pitch.convertPsToFq(2))
    '9.17702399742'
    >>> str(pitch.convertPsToFq(135))
    '19912.1269582'



.. function:: convertPsToOct(ps)

    Utility conversion; does not process internals.
    Converts a midiNote number to an octave number.
    Assume C4 middle C, so 60 returns 4


    >>> [convertPsToOct(59), convertPsToOct(60), convertPsToOct(61)]
    [3, 4, 4]
    >>> [convertPsToOct(12), convertPsToOct(0), convertPsToOct(-12)]
    [0, -1, -2]
    >>> convertPsToOct(135)
    10



.. function:: convertPsToStep(ps)

    Utility conversion; does not process internal representations.

    Takes in a pitch space floating-point value or a MIDI note number (Assume C4 middle C, so 60 returns 4).

    Returns a tuple of Step, an Accidental object, and a Microtone object or None.



    >>> convertPsToStep(60)
    ('C', <accidental natural>, (+0c), 0)
    >>> convertPsToStep(66)
    ('F', <accidental sharp>, (+0c), 0)
    >>> convertPsToStep(67)
    ('G', <accidental natural>, (+0c), 0)
    >>> convertPsToStep(68)
    ('G', <accidental sharp>, (+0c), 0)
    >>> convertPsToStep(-2)
    ('B', <accidental flat>, (+0c), 0)
    ⁠ 
    >>> convertPsToStep(60.5)
    ('C', <accidental half-sharp>, (+0c), 0)
    >>> convertPsToStep(61.5)
    ('C', <accidental one-and-a-half-sharp>, (+0c), 0)
    >>> convertPsToStep(62)
    ('D', <accidental natural>, (+0c), 0)
    >>> convertPsToStep(62.5)
    ('D', <accidental half-sharp>, (+0c), 0)
    >>> convertPsToStep(135)
    ('E', <accidental flat>, (+0c), 0)
    >>> convertPsToStep(70)
    ('B', <accidental flat>, (+0c), 0)
    >>> convertPsToStep(70.5)
    ('B', <accidental half-flat>, (+0c), 0)



.. function:: convertStepToPs(step, oct, acc=None, microtone=None)

    Utility conversion; does not process internals.
    Takes in a note name string, octave number, and optional
    Accidental object.

    Returns a pitch space value as a floating point MIDI note number.



    >>> from music21 import *
    >>> pitch.convertStepToPs('c', 4, pitch.Accidental('sharp'))
    61.0
    >>> pitch.convertStepToPs('d', 2, pitch.Accidental(-2))
    36.0
    >>> pitch.convertStepToPs('b', 3, pitch.Accidental(3))
    62.0
    >>> pitch.convertStepToPs('c', 4, pitch.Accidental('half-flat'))
    59.5



Pitch
-----

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

.. class:: Pitch(name=None, **keywords)


    An object for storing pitch values.
    All values are represented internally as a
    scale step (self.step), and octave and an
    accidental object. In addition, pitches know their
    pitch space representation (self.ps); altering any
    of the first three changes the pitch space (ps) representation.
    Similarly, altering the .ps representation
    alters the first three.


    Two Pitches are equal if they represent the same
    pitch and are spelled the same.  A Pitch is greater
    than another Pitch if its pitchSpace is greater than
    the other.  Thus C##4 > D-4.




    Create a Pitch.

    Optional parameter name should include a step and accidental character(s)

    it can also include an octave number ("C#4", "B--3", etc.) so long
    as it's 0 or higher.



    >>> from music21 import *
    >>> p1 = pitch.Pitch('a#')
    >>> p1
    A#
    >>> p2 = pitch.Pitch(3)
    >>> p2
    E-


    This is B-double flat in octave 3, not B- in octave -3.




    >>> p3 = pitch.Pitch("B--3")
    >>> p3.accidental
    <accidental double-flat>
    >>> p3.octave
    3


    Just about everything can be specified in keywords too:




    >>> p4 = pitch.Pitch(name = 'C', accidental = '#', octave = 7, microtone = -30)
    >>> p4.fullName
    'C7-sharp (-30c)'





    **Pitch** **attributes**

        Attributes without Documentation: `fundamental`, `implicitAccidental`, `defaultOctave`

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

    **Pitch** **properties**

        .. attribute:: name


            Gets or sets the name (pitch name with accidental but
            without octave) of the Pitch.




            >>> from music21 import *
            >>> p = pitch.Pitch()
            >>> p.name = 'C#'
            >>> p.implicitAccidental
            False
            >>> p.ps = 61
            >>> p.implicitAccidental
            True
            >>> p.name
            'C#'
            >>> p.ps = 58
            >>> p.name
            'B-'
            ⁠ 
            >>> p.name = 'C#'
            >>> p.implicitAccidental
            False




        .. attribute:: nameWithOctave


            Return or set the pitch name with an octave designation.
            If no octave as been set, no octave value is returned.



            >>> from music21 import *
            >>> gSharp = pitch.Pitch('G#4')
            >>> gSharp.nameWithOctave
            'G#4'
            ⁠ 
            >>> dFlatFive = pitch.Pitch()
            >>> dFlatFive.step = 'D'
            >>> dFlatFive.accidental = pitch.Accidental('flat')
            >>> dFlatFive.octave = 5
            >>> dFlatFive.nameWithOctave
            'D-5'
            >>> dFlatFive.nameWithOctave = 'C#6'
            >>> dFlatFive.name
            'C#'
            >>> dFlatFive.octave
            6


            N.B. -- it's generally better to set the name and octave separately, especially
            since you may at some point encounter very low pitches such as "A octave -1", which
            will be interpreted as "A-flat, octave 1".  Our crude setting algorithm also does
            not support octaves above 9.



            >>> lowA = pitch.Pitch()
            >>> lowA.name = 'A'
            >>> lowA.octave = -1
            >>> lowA.nameWithOctave
            'A-1'
            >>> lowA.nameWithOctave = lowA.nameWithOctave
            >>> lowA.name
            'A-'
            >>> lowA.octave
            1



        .. attribute:: step

            The diatonic name of the note; i.e. does not give the
            accidental or octave.  Is case insensitive.




            >>> from music21 import *
            >>> a = pitch.Pitch('B-3')
            >>> a.step
            'B'
            ⁠ 
            >>> a.step = "c"
            >>> a.nameWithOctave
            'C-3'


            Giving a name with an accidental raises a PitchException.
            Use .name instead.



            >>> from music21 import *
            >>> b = pitch.Pitch('E4')
            >>> b.step = "E-"
            Traceback (most recent call last):
            PitchException: Cannot make a step out of 'E-'



        .. attribute:: pitchClass


            Returns or sets the integer value for the pitch, 0-11, where C=0,
            C#=1, D=2...B=11. Can be set using integers (0-11) or 'A' or 'B'
            for 10 or 11.




            >>> from music21 import *
            >>> a = pitch.Pitch('a3')
            >>> a.pitchClass
            9
            >>> dis = pitch.Pitch('d3')
            >>> dis.pitchClass
            2
            >>> dis.accidental = pitch.Accidental("#")
            >>> dis.pitchClass
            3
            >>> dis.pitchClass = 11
            >>> dis.pitchClass
            11
            >>> dis.name
            'B'



        .. attribute:: octave


            Returns or sets the octave of the note.
            Setting the octave
            updates the pitchSpace attribute.



            >>> from music21 import *
            ⁠ 
            >>> a = pitch.Pitch('g')
            >>> a.octave is None
            True
            >>> a.implicitOctave
            4
            >>> a.ps  ## will use implicitOctave
            67.0
            >>> a.name
            'G'



            >>> a.octave = 14
            >>> a.octave
            14
            >>> a.implicitOctave
            14
            >>> a.name
            'G'
            >>> a.ps
            187.0



        .. attribute:: midi


            Get or set a pitch value in MIDI.
            MIDI pitch values are like ps values (pitchSpace) rounded to
            the nearest integer; while the ps attribute will accommodate floats.




            >>> from music21 import *
            >>> c = pitch.Pitch('C4')
            >>> c.midi
            60
            >>> c.midi =  23.5
            >>> c.midi
            24


            Note that like ps (pitchSpace), MIDI notes do not distinguish between
            sharps and flats, etc.




            >>> dSharp = pitch.Pitch('D#4')
            >>> dSharp.midi
            63
            >>> eFlat = pitch.Pitch('E-4')
            >>> eFlat.midi
            63


            Midi values are constrained to the space 0-127.  Higher or lower
            values will be transposed octaves to fit in this space.





            >>> veryHighFHalfFlat = pitch.Pitch("F")
            >>> veryHighFHalfFlat.octave = 12
            >>> veryHighFHalfFlat.accidental = pitch.Accidental('half-flat')
            >>> veryHighFHalfFlat
            F`12
            >>> veryHighFHalfFlat.ps
            160.5
            >>> veryHighFHalfFlat.midi
            125




            >>> notAsHighNote = pitch.Pitch()
            >>> notAsHighNote.ps = veryHighFHalfFlat.midi
            >>> notAsHighNote
            F9



            Note that the conversion of improper midi values to proper
            midi values is done before assigning .ps:




            >>> a = pitch.Pitch()
            >>> a.midi = -10
            >>> a.midi
            2
            >>> a.ps
            2.0
            >>> a.implicitAccidental
            True



        .. attribute:: german


            Read-only attribute. Returns the name
            of a Pitch in the German system
            (where B-flat = B, B = H, etc.)
            (Microtones and Quartertones raise an error).  Note that
            Ases is used instead of the also acceptable Asas.




            >>> from music21 import *
            >>> print pitch.Pitch('B-').german
            B
            >>> print pitch.Pitch('B').german
            H
            >>> print pitch.Pitch('E-').german
            Es
            >>> print pitch.Pitch('C#').german
            Cis
            >>> print pitch.Pitch('A--').german
            Ases
            >>> p1 = pitch.Pitch('C')
            >>> p1.accidental = pitch.Accidental('half-sharp')
            >>> p1.german
            Traceback (most recent call last):
            PitchException: Es geht nicht "german" zu benutzen mit Microtoenen.  Schade!


            Note these rarely used pitches:




            >>> print pitch.Pitch('B--').german
            Heses
            >>> print pitch.Pitch('B#').german
            His



        .. attribute:: french


            Read-only attribute. Returns the name
            of a Pitch in the French system
            (where A = la, B = si, B-flat = si bémol, C-sharp = do dièse, etc.)
            (Microtones and Quartertones raise an error).  Note that
            do is used instead of the also acceptable ut.




            >>> from music21 import *
            >>> print pitch.Pitch('B-').french
            si bémol
            >>> print pitch.Pitch('B').french
            si
            >>> print pitch.Pitch('E-').french
            mi bémol
            >>> print pitch.Pitch('C#').french
            do dièse
            >>> print pitch.Pitch('A--').french
            la double bémol
            >>> p1 = pitch.Pitch('C')
            >>> p1.accidental = pitch.Accidental('half-sharp')
            >>> p1.french
            Traceback (most recent call last):
            PitchException: On ne peut pas utiliser les microtones avec "french." Quelle Dommage!



        .. attribute:: spanish


            Read-only attribute. Returns the name
            of a Pitch in Spanish
            (Microtones and Quartertones raise an error).




            >>> from music21 import *
            >>> print pitch.Pitch('B-').spanish
            si bèmol
            >>> print pitch.Pitch('E-').spanish
            mi bèmol
            >>> print pitch.Pitch('C#').spanish
            do sostenido
            >>> print pitch.Pitch('A--').spanish
            la doble bèmol
            >>> p1 = pitch.Pitch('C')
            >>> p1.accidental = pitch.Accidental('half-sharp')
            >>> p1.spanish
            Traceback (most recent call last):
            PitchException: Unsupported accidental type.


            Note these rarely used pitches:




            >>> print pitch.Pitch('B--').spanish
            si doble bèmol
            >>> print pitch.Pitch('B#').spanish
            si sostenido



        .. attribute:: italian


            Read-only attribute. Returns the name
            of a Pitch in the Italian system
            (F-sharp is fa diesis, C-flat is do bemolle, etc.)
            (Microtones and Quartertones raise an error).




            >>> from music21 import *
            >>> print pitch.Pitch('B-').italian
            si bemolle
            >>> print pitch.Pitch('B').italian
            si
            >>> print pitch.Pitch('E-9').italian
            mi bemolle
            >>> print pitch.Pitch('C#').italian
            do diesis
            >>> print pitch.Pitch('A--4').italian
            la doppio bemolle
            >>> p1 = pitch.Pitch('C')
            >>> p1.accidental = pitch.Accidental('half-sharp')
            >>> p1.italian
            Traceback (most recent call last):
            PitchException: Incompatible with quarter-tones


            Note these rarely used pitches:




            >>> print pitch.Pitch('E####').italian
            mi quadruplo diesis
            >>> print pitch.Pitch('D---').italian
            re triplo bemolle



        .. attribute:: dutch


            Read-only attribute. Returns the name
            of a Pitch in the German system
            (where B-flat = B, B = H, etc.)
            (Microtones and Quartertones raise an error).




            >>> from music21 import *
            >>> print pitch.Pitch('B-').dutch
            Bes
            >>> print pitch.Pitch('B').dutch
            B
            >>> print pitch.Pitch('E-').dutch
            Es
            >>> print pitch.Pitch('C#').dutch
            Cis
            >>> print pitch.Pitch('A--').dutch
            Ases
            >>> p1 = pitch.Pitch('C')
            >>> p1.accidental = pitch.Accidental('half-sharp')
            >>> p1.dutch
            Traceback (most recent call last):
            PitchException: Quarter-tones not supported



        .. attribute:: accidental


            Stores an optional accidental object contained within the
            Pitch object.  This might return None, which is different
            than a natural accidental:




            >>> from music21 import *
            >>> a = pitch.Pitch('E-')
            >>> a.accidental.alter
            -1.0
            >>> a.accidental.modifier
            '-'
            ⁠ 
            >>> b = pitch.Pitch('C4')
            >>> b.accidental is None
            True
            >>> b.accidental = pitch.Accidental('natural')
            >>> b.accidental is None
            False
            >>> b.accidental
            <accidental natural>



            >>> b = pitch.Pitch('C4')
            >>> b.accidental = 1.5
            >>> b
            C#4(+50c)
            >>> b.accidental = 1.65
            >>> b
            C#~4(+15c)
            >>> b.accidental = 1.95
            >>> b
            C##4(-5c)



        .. attribute:: alter

            Return the pitch alteration as a numeric value, where 1 is the space of one half step and all base pitch values are given by step alone. Thus, the alter value combines the pitch change suggested by the Accidental and the Microtone combined.



            >>> from music21 import *
            >>> p = pitch.Pitch('g#4')
            >>> p.alter
            1.0
            >>> p.microtone = -25 # in cents
            >>> p.alter
            0.75



        .. attribute:: diatonicNoteNum


            Returns (or takes) an integer that uniquely identifies the
            diatonic version of a note, that is ignoring accidentals.
            The number returned is the diatonic interval above C0 (the lowest C on
            a Boesendorfer Imperial Grand), so G0 = 5, C1 = 8, etc.
            Numbers can be negative for very low notes.

            C4 (middleC) = 29, C#4 = 29, C##4 = 29, D-4 = 30, D4 = 30, etc.



            >>> from music21 import *
            >>> c = pitch.Pitch('c4')
            >>> c.diatonicNoteNum
            29
            >>> c = pitch.Pitch('c#4')
            >>> c.diatonicNoteNum
            29
            >>> d = pitch.Pitch('d--4')
            >>> d.accidental.name
            'double-flat'
            >>> d.diatonicNoteNum
            30
            >>> lowc = pitch.Pitch('c1')
            >>> lowc.diatonicNoteNum
            8
            ⁠ 
            >>> b = pitch.Pitch()
            >>> b.step = "B"
            >>> b.octave = -1
            >>> b.diatonicNoteNum
            0
            >>> c = pitch.Pitch("C")
            >>> c.diatonicNoteNum  #implicitOctave
            29



            >>> lowDSharp = pitch.Pitch("C#7") # start high !!!
            >>> lowDSharp.diatonicNoteNum = 9  # move low
            >>> lowDSharp.octave
            1
            >>> lowDSharp.name
            'D#'



        .. attribute:: freq440


            Gets the frequency of the note as if it's in an equal temperment
            context where A4 = 440hz.  The same as .frequency so long
            as no other temperments are currently being used.


            Since we don't have any other temperament objects as
            of alpha 7, this is the same as .frequency always.




        .. attribute:: frequency


            The frequency property gets or sets the frequency of
            the pitch in hertz.
            If the frequency has not been overridden, then
            it is computed based on A440Hz and equal temperament



            >>> from music21 import *
            >>> a = pitch.Pitch()
            >>> a.frequency = 440.0
            >>> a.frequency
            440.0
            >>> a.name
            'A'
            >>> a.octave
            4
            >>> a.frequency = 450.0 # microtones are captured
            >>> a
            A~4(-11c)




        .. attribute:: fullName


            Return the most complete representation of this Pitch,
            providing name, octave, accidental, and any
            microtonal adjustments.



            >>> from music21 import *
            >>> p = pitch.Pitch('A-3')
            >>> p.microtone = 33.33
            >>> p.fullName
            'A3-flat (+33c)'
            ⁠ 
            >>> p = pitch.Pitch('A`7')
            >>> p.fullName
            'A7-half-flat'



        .. attribute:: implicitOctave


            Returns the octave of the Pitch, or defaultOctave if
            octave was never set. To set an octave, use .octave.
            Default octave is usually 4.



        .. attribute:: microtone


            Sets the microtone object contained within the
            Pitch object. Microtones must be supplied in cents.



            >>> from music21 import *
            >>> p = pitch.Pitch('E4-')
            >>> p.microtone.cents == 0
            True
            >>> p.ps
            63.0
            >>> p.microtone = 33 # adjustment in cents
            >>> p
            E-4(+33c)
            >>> (p.name, p.nameWithOctave) # these representations are unchanged
            ('E-', 'E-4')
            >>> p.microtone = '(-12c' # adjustment in cents
            >>> p
            E-4(-12c)
            >>> p.microtone = pitch.Microtone(-30)
            >>> p
            E-4(-30c)




        .. attribute:: musicxml

            Provide a complete MusicXML representation. Presently, this is based on



        .. attribute:: mx

            No documentation.


        .. attribute:: pitchClassString


            Returns or sets a string representation of the pitch class,
            where integers greater than 10 are replaced by A and B,
            respectively. Can be used to set pitch class by a
            string representation as well (though this is also
            possible with :attr:`~music21.pitch.Pitch.pitchClass`.




            >>> from music21 import *
            >>> a = pitch.Pitch('a3')
            >>> a.pitchClassString = 'B'
            >>> a.pitchClass
            11
            >>> a.pitchClassString
            'B'



        .. attribute:: ps


            The ps property permits getting and setting
            a pitch space value, a floating point number
            representing pitch space, where 60.0 is C4, middle C,
            61.0 is C#4 or D-4, and floating point values are
            microtonal tunings (.01 is equal to one cent), so
            a quarter-tone sharp above C5 is 72.5.

            Note that the choice of 60.0 for C4 makes it identical
            to the integer value of 60 for .midi, but .midi
            does not allow for microtones and is limited to 0-127
            while .ps allows for notes before midi 0 or above midi 127.




            >>> from music21 import *
            >>> a = pitch.Pitch("C4")
            >>> a.ps
            60.0


            Changing the ps value for
            A will change the step and octave:




            >>> a.ps = 45
            >>> a
            A2
            >>> a.ps
            45.0


            Notice that ps 61 represents both
            C# and D-flat.  Thus "implicitAccidental"
            will be true after setting our pitch to 61:




            >>> a.ps = 61
            >>> a
            C#4
            >>> a.ps
            61.0
            >>> a.implicitAccidental
            True


            Microtones are allowed, as are extreme ranges:




            >>> b = pitch.Pitch('B9')
            >>> b.accidental = pitch.Accidental('half-flat')
            >>> b
            B`9
            >>> b.ps
            130.5




        .. attribute:: stepWithOctave


            Returns the pitch step (F, G, etc) with
            octave designation. If no octave has been set,
            no octave value is returned.



            >>> from music21 import *
            >>> a = pitch.Pitch('G#4')
            >>> a.stepWithOctave
            'G4'




            >>> a = pitch.Pitch('A#')
            >>> a.stepWithOctave
            'A'




        .. attribute:: unicodeName

            Return the pitch name in a unicode encoding.



        .. attribute:: unicodeNameWithOctave

            Return the pitch name with octave with unicode accidental symbols, if available.



        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`

    **Pitch** **methods**

        .. method:: convertMicrotonesToQuarterTones(inPlace=True)

            Convert any Microtones available to quarter tones, if possible.



            >>> from music21 import *
            >>> p = pitch.Pitch('g3')
            >>> p.microtone = 78
            >>> p
            G3(+78c)
            >>> p.convertMicrotonesToQuarterTones(inPlace=True)
            >>> p
            G#3(-22c)
            ⁠ 
            >>> p = pitch.Pitch('d#3')
            >>> p.microtone = 46
            >>> p
            D#3(+46c)
            >>> p.convertMicrotonesToQuarterTones(inPlace=True)
            >>> p
            D#~3(-4c)



            >>> p = pitch.Pitch('f#2')
            >>> p.microtone = -38
            >>> p.convertMicrotonesToQuarterTones(inPlace=True)
            >>> p
            F~2(+12c)




        .. method:: convertQuarterTonesToMicrotones(inPlace=True)

            Convert any quarter tone Accidentals to Microtones.



            >>> from music21 import *
            >>> p = pitch.Pitch('G#~')
            >>> p, p.microtone
            (G#~, (+0c))
            >>> p.convertQuarterTonesToMicrotones(inPlace=True)
            >>> p.ps
            68.5
            >>> p, p.microtone
            (G#(+50c), (+50c))
            ⁠ 
            >>> p = pitch.Pitch('A`')
            >>> p, p.microtone
            (A`, (+0c))
            >>> x = p.convertQuarterTonesToMicrotones(inPlace=False)
            >>> x, x.microtone
            (A(-50c), (-50c))
            >>> p, p.microtone
            (A`, (+0c))



        .. method:: getAllCommmonEnharmonics(alterLimit=2)

            Return all common unique enharmonics for a pitch, or those that do not involve more than two accidentals.



            >>> from music21 import *
            >>> p = pitch.Pitch('c#3')
            >>> p.getAllCommmonEnharmonics()
            [D-3, B##2]
            >>> p = pitch.Pitch('g-6')
            >>> p.getAllCommmonEnharmonics()
            [F#6, E##6]
            >>> p.getAllCommmonEnharmonics(alterLimit=3)
            [A---6, F#6, E##6]



        .. method:: getCentShiftFromMidi()

            Get cent deviation of this pitch from MIDI pitch.



            >>> from music21 import *
            >>> p = pitch.Pitch('c~4')
            >>> p.midi # midi values automatically round up
            61
            >>> p.getCentShiftFromMidi()
            50
            >>> p = pitch.Pitch('c#4')
            >>> p.microtone = -25
            >>> p.getCentShiftFromMidi()
            -25
            ⁠ 
            >>> p = pitch.Pitch('c#~4')
            >>> p.getCentShiftFromMidi()
            50
            >>> p.microtone = 3
            >>> p.getCentShiftFromMidi()
            53



            >>> p = pitch.Pitch('c`4') # quarter tone flat
            >>> p.getCentShiftFromMidi()
            -50
            >>> p.microtone = 3
            >>> p.getCentShiftFromMidi()
            -47



        .. method:: getEnharmonic(inPlace=False)


            Returns a new Pitch that is the(/an) enharmonic equivalent of this Pitch.


            N.B.: n1.name == getEnharmonic(getEnharmonic(n1)).name is not necessarily true.
            For instance:

                getEnharmonic(E##) => F#; getEnharmonic(F#) => G-

                getEnharmonic(A--) => G; getEnharmonic(G) => F##


            However, for all cases not involving double sharps or flats
            (and even many that do), getEnharmonic(getEnharmonic(n)) = n


            For the most ambiguous cases, it's good to know that these are the enharmonics:

                   C <-> B#, D <-> C##, E <-> F-; F <-> E#, G <-> F##, A <-> B--, B <-> C-


            However, isEnharmonic() for A## and B certainly returns true.




            >>> from music21 import *
            >>> p = pitch.Pitch('d#')
            >>> p.getEnharmonic()
            E-
            >>> p = pitch.Pitch('e-8')
            >>> p.getEnharmonic()
            D#8


            Other tests:




            >>> pitch.Pitch('c-3').getEnharmonic()
            B2
            >>> pitch.Pitch('e#2').getEnharmonic()
            F2
            >>> pitch.Pitch('f#2').getEnharmonic()
            G-2
            >>> pitch.Pitch('c##5').getEnharmonic()
            D5
            >>> pitch.Pitch('g3').getEnharmonic()
            F##3
            >>> pitch.Pitch('B7').getEnharmonic()
            C-8


            Octaveless Pitches remain octaveless:




            >>> p = pitch.Pitch('a-')
            >>> p.getEnharmonic()
            G#
            >>> p = pitch.Pitch('B#')
            >>> p.getEnharmonic()
            C




        .. method:: getHarmonic(number)

            Return a Pitch object representing the harmonic found above this Pitch.



            >>> from music21 import *
            >>> p = pitch.Pitch('a4')
            >>> p.getHarmonic(2)
            A5
            >>> p.getHarmonic(3)
            E6(+2c)
            >>> p.getHarmonic(4)
            A6
            >>> p.getHarmonic(5)
            C#7(-14c)
            >>> p.getHarmonic(6)
            E7(+2c)
            >>> p.getHarmonic(7)
            F#~7(+19c)
            >>> p.getHarmonic(8)
            A7




            >>> p2 = p.getHarmonic(2)
            >>> p2
            A5
            >>> p2.fundamental
            A4
            >>> p2.transpose('p5', inPlace=True)
            >>> p2
            E6
            >>> p2.fundamental
            E5


            Or we can iterate over a list of the next 8 odd harmonics:




            >>> for i in [9,11,13,15,17,19,21,23]:
            ...     print p.getHarmonic(i),
            B7(+4c) D~8(+1c) F~8(-9c) G#8(-12c) B-8(+5c) C9(-2c) C#~9(+21c) E`9(-22c)


            Microtonally adjusted notes also generate harmonics:




            >>> q = pitch.Pitch('C4')
            >>> q.microtone = 10
            >>> q.getHarmonic(2)
            C5(+10c)
            >>> q.getHarmonic(3)
            G5(+12c)


            The fundamental is stored with the harmonic.




            >>> h7 = pitch.Pitch("A4").getHarmonic(7)
            >>> h7
            F#~7(+19c)
            >>> h7.fundamental
            A4
            >>> h7.harmonicString()
            '7thH/A4'
            >>> h7.harmonicString('A3')
            '14thH/A3'




            >>> h2 = h7.getHarmonic(2)
            >>> h2
            F#~8(+19c)
            >>> h2.fundamental
            F#~7(+19c)
            >>> h2.fundamental.fundamental
            A4
            >>> h2.transpose(-24, inPlace=True)
            >>> h2
            F#~6(+19c)
            >>> h2.fundamental.fundamental
            A2




        .. method:: getHigherEnharmonic(inPlace=False)

            Returns a Pitch enharmonic note that a dim-second above the current note.



            >>> from music21 import *
            >>> p1 = pitch.Pitch('C#3')
            >>> p2 = p1.getHigherEnharmonic()
            >>> p2
            D-3
            ⁠ 
            >>> p1 = pitch.Pitch('C#3')
            >>> p1.getHigherEnharmonic(inPlace=True)
            >>> p1
            D-3



            The method even works for certain CRAZY enharmonics




            >>> p3 = pitch.Pitch('D--3')
            >>> p4 = p3.getHigherEnharmonic()
            >>> p4
            E----3


            But not for things that are just utterly insane:




            >>> p4.getHigherEnharmonic()
            Traceback (most recent call last):
            AccidentalException: -5 is not a supported accidental type




        .. method:: getLowerEnharmonic(inPlace=False)


            returns a Pitch enharmonic note that is a diminished second
            below the current note

            If `inPlace` is set to true, changes the current Pitch.




            >>> from music21 import *
            >>> p1 = pitch.Pitch('C-3')
            >>> p2 = p1.getLowerEnharmonic()
            >>> p2
            B2
            ⁠ 
            >>> p1 = pitch.Pitch('C#3')
            >>> p1.getLowerEnharmonic(inPlace=True)
            >>> p1
            B##2



        .. method:: getMidiPreCentShift()

            If pitch bend will be used to adjust MIDI values, the given pitch values for microtones should go to the nearest non-microtonal pitch value, not rounded up or down. This method is used in MIDI output generation.



            >>> from music21 import *
            >>> p = pitch.Pitch('c~4')
            >>> p.getMidiPreCentShift()
            60
            >>> p = pitch.Pitch('c#4')
            >>> p.getMidiPreCentShift()
            61
            >>> p.microtone = 65
            >>> p.getMidiPreCentShift()
            61
            >>> p.getCentShiftFromMidi()
            65



        .. method:: getStringHarmonic(chordIn)

            Given a chord, determines whether the chord constitutes a string harmonic and then
            returns a new chord with the proper sounding pitch added.




            >>> from music21 import *
            >>> n1 = note.Note('d3')
            >>> n2 = note.Note('g3')
            >>> n2.notehead = 'diamond'
            >>> n2.noteheadFill = 'no'
            >>> p1 = pitch.Pitch('d3')
            >>> harmChord = chord.Chord([n1, n2])
            >>> harmChord.quarterLength = 1
            >>> newChord = p1.getStringHarmonic(harmChord)
            >>> newChord.quarterLength = 1
            >>> pitchList = newChord.pitches
            >>> pitchList
            [D3, G3, D5]



        .. method:: harmonicAndFundamentalFromPitch(target)

            Given a Pitch that is a plausible target for a fundamental, return the harmonic number and a potentially shifted fundamental that describes this Pitch.



            >>> from music21 import *
            >>> pitch.Pitch('g4').harmonicAndFundamentalFromPitch('c3')
            (3, C3(-2c))




        .. method:: harmonicAndFundamentalStringFromPitch(fundamental)

            Given a Pitch that is a plausible target for a fundamental, return the harmonic number and a potentially shifted fundamental that describes this Pitch. Return a string representation.



            >>> from music21 import *
            >>> pitch.Pitch('g4').harmonicAndFundamentalStringFromPitch('c3')
            '3rdH/C3(-2c)'
            ⁠ 
            >>> pitch.Pitch('c4').harmonicAndFundamentalStringFromPitch('c3')
            '2ndH/C3'



            >>> p = pitch.Pitch('c4')
            >>> p.microtone = 20 # raise 20
            >>> p.harmonicAndFundamentalStringFromPitch('c3')
            '2ndH/C3(+20c)'
            ⁠ 
            >>> p.microtone = -20 # lower 20
            >>> p.harmonicAndFundamentalStringFromPitch('c3')
            '2ndH/C3(-20c)'



            >>> p = pitch.Pitch('c4')
            >>> f = pitch.Pitch('c3')
            >>> f.microtone = -20
            >>> p.harmonicAndFundamentalStringFromPitch(f)
            '2ndH/C3'
            >>> f.microtone = +20
            >>> p.harmonicAndFundamentalStringFromPitch(f)
            '2ndH/C3'
            ⁠ 
            >>> p = pitch.Pitch('A4')
            >>> p.microtone = 69
            >>> p.harmonicAndFundamentalStringFromPitch('c2')
            '7thH/C2'



            >>> p = pitch.Pitch('A4')
            >>> p.harmonicAndFundamentalStringFromPitch('c2')
            '7thH/C2(-69c)'




        .. method:: harmonicFromFundamental(fundamental)


            Given another Pitch as a fundamental, find the harmonic
            of that pitch that is equal to this Pitch.


            Returns a tuple of harmonic number and the number of cents that
            the first Pitch object would have to be shifted to be the exact
            harmonic of this fundamental.


            Microtones applied to the fundamental are irrelevant,
            as the fundamental may be microtonally shifted to find a match to this Pitch.


            Example: G4 is the third harmonic of C3, albeit 2 cents flatter than
            the true 3rd harmonic.




            >>> from music21 import *
            >>> p = pitch.Pitch('g4')
            >>> f = pitch.Pitch('c3')
            >>> p.harmonicFromFundamental(f)
            (3, 2.0)
            >>> p.microtone = p.harmonicFromFundamental(f)[1] # adjust microtone
            >>> int(f.getHarmonic(3).frequency) == int(p.frequency)
            True



            The shift from B-5 to the 7th harmonic of C3 is more substantial
            and likely to be noticed by the audience.  To make p the 7th harmonic
            it'd have to be lowered by 31 cents.  Note that the
            second argument is a float, but because the default rounding of
            music21 is to the nearest cent, the .0 is not a significant digit.
            I.e. it might be more like 31.3 cents.




            >>> p = pitch.Pitch('B-5')
            >>> f = pitch.Pitch('C3')
            >>> p.harmonicFromFundamental(f)
            (7, -31.0)




        .. method:: harmonicString(fundamental=None)


            Return a string representation of a harmonic equivalence.


            N.B. this has nothing to do with what string a string player
            would use to play the harmonic on.  (Perhaps should be
            renamed).





            >>> from music21 import *
            >>> pitch.Pitch('g4').harmonicString('c3')
            '3rdH(-2c)/C3'




            >>> pitch.Pitch('c4').harmonicString('c3')
            '2ndH/C3'




            >>> p = pitch.Pitch('c4')
            >>> p.microtone = 20 # raise 20
            >>> p.harmonicString('c3')
            '2ndH(+20c)/C3'




            >>> p.microtone = -20 # lower 20
            >>> p.harmonicString('c3')
            '2ndH(-20c)/C3'




            >>> p = pitch.Pitch('c4')
            >>> f = pitch.Pitch('c3')
            >>> f.microtone = -20
            >>> p.harmonicString(f)
            '2ndH(+20c)/C3(-20c)'
            >>> f.microtone = +20
            >>> p.harmonicString(f)
            '2ndH(-20c)/C3(+20c)'




            >>> p = pitch.Pitch('A4')
            >>> p.microtone = 69
            >>> p.harmonicString('c2')
            '7thH/C2'




            >>> p = pitch.Pitch('A4')
            >>> p.harmonicString('c2')
            '7thH(-69c)/C2'



        .. method:: inheritDisplay(other)

            Inherit display properties from another Pitch, including those found on the Accidental object.



            >>> from music21 import *
            ⁠ 
            >>> a = pitch.Pitch('c#')
            >>> a.accidental.displayType = 'always'
            >>> b = pitch.Pitch('c-')
            >>> b.inheritDisplay(a)
            >>> b.accidental.displayType
            'always'




        .. method:: isEnharmonic(other)

            Return True if other is an enharmonic equivalent of self.



            >>> from music21 import *
            >>> p1 = pitch.Pitch('C#3')
            >>> p2 = pitch.Pitch('D-3')
            >>> p3 = pitch.Pitch('D#3')
            >>> p1.isEnharmonic(p2)
            True
            >>> p2.isEnharmonic(p1)
            True
            >>> p3.isEnharmonic(p1)
            False



        .. method:: isTwelveTone()


            Return True if this Pitch is
            one of the twelve tones available on a piano
            keyboard. Returns False if it instead
            has a non-zero microtonal adjustment or
            has a quarter tone accidental.




            >>> from music21 import *
            >>> p = pitch.Pitch('g4')
            >>> p.isTwelveTone()
            True
            >>> p.microtone = -20
            >>> p.isTwelveTone()
            False




            >>> p2 = pitch.Pitch('g~4')
            >>> p2.isTwelveTone()
            False



        .. method:: setAccidentalDisplay(value=None)

            If this Pitch has an accidental, set its displayStatus, which can be True, False, or None.



            >>> from music21 import *
            ⁠ 
            >>> a = pitch.Pitch('a')
            >>> past = [pitch.Pitch('a#'), pitch.Pitch('c#'), pitch.Pitch('c')]
            >>> a.updateAccidentalDisplay(past, cautionaryAll=True)
            >>> a.accidental, a.accidental.displayStatus
            (<accidental natural>, True)
            >>> a.setAccidentalDisplay(None)
            >>> a.accidental, a.accidental.displayStatus
            (<accidental natural>, None)



        .. method:: simplifyEnharmonic(inPlace=False, mostCommon=False)


            Returns a new Pitch (or sets the current one if inPlace is True)
            that is either the same as the current pitch or has fewer
            sharps or flats if possible.  For instance, E# returns F,
            while A# remains A# (i.e., does not take into account that B- is
            more common than A#).  Useful to call if you ever have an
            algorithm that might take your piece far into the realm of
            double or triple flats or sharps.


            If mostCommon is set to true, then the most commonly used
            enharmonic spelling is chosen (that is, the one that appears
            first in key signatures as you move away from C on the circle
            of fifths).  Thus G-flat becomes F#, A# becomes B-flat,
            D# becomes E-flat, D-flat becomes C#, G# and A-flat are left
            alone.


            TODO: should be called automatically after ChromaticInterval
            transpositions.




            >>> from music21 import *
            >>> p1 = pitch.Pitch("B#5")
            >>> p1.simplifyEnharmonic().nameWithOctave
            'C6'
            ⁠ 
            >>> p2 = pitch.Pitch("A#2")
            >>> p2.simplifyEnharmonic(inPlace = True)
            >>> p2
            A#2



            >>> p3 = pitch.Pitch("E--3")
            >>> p4 = p3.transpose(interval.Interval('-A5'))
            >>> p4.simplifyEnharmonic()
            F#2


            Setting mostCommon = True simplifies enharmonics
            even further.




            >>> pList = [pitch.Pitch("A#4"), pitch.Pitch("B-4"), pitch.Pitch("G-4"), pitch.Pitch("F#4")]
            >>> [p.simplifyEnharmonic(mostCommon = True) for p in pList]
            [B-4, B-4, F#4, F#4]





            Note that pitches with implicit octaves retain their implicit octaves.
            This might change the pitch space for B#s and C-s.




            >>> pList = [pitch.Pitch("B"), pitch.Pitch("C#"), pitch.Pitch("G"), pitch.Pitch("A--")]
            >>> [p.simplifyEnharmonic() for p in pList]
            [B, C#, G, G]




            >>> pList = [pitch.Pitch("C-"), pitch.Pitch("B#")]
            >>> [p.ps for p in pList]
            [59.0, 72.0]
            >>> [p.simplifyEnharmonic().ps for p in pList]
            [71.0, 60.0]




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

            Transpose the pitch 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.



            >>> from music21 import *
            >>> aPitch = pitch.Pitch('g4')
            >>> bPitch = aPitch.transpose('m3')
            >>> bPitch
            B-4
            >>> aInterval = interval.Interval(-6)
            >>> bPitch = aPitch.transpose(aInterval)
            >>> bPitch
            C#4
            ⁠ 
            >>> aPitch
            G4
            >>> aPitch.transpose(aInterval, inPlace=True)
            >>> aPitch
            C#4



        .. method:: transposeAboveTarget(target, minimize=False)

            Given a source Pitch, shift it up octaves until it is above the target. Note: this manipulates src inPlace.

            If `minimize` is True, a pitch above the the target will move down to the nearest octave.



            >>> from music21 import *
            >>> pitch.Pitch('d2').transposeAboveTarget(pitch.Pitch('e4'))
            D5
            >>> # if already above the target, make no change
            >>> pitch.Pitch('d7').transposeAboveTarget(pitch.Pitch('e2'))
            D7
            >>> # accept the same pitch
            >>> pitch.Pitch('d2').transposeAboveTarget(pitch.Pitch('d8'))
            D8
            ⁠ 
            >>> # if minimize is True, we go the closest position
            >>> pitch.Pitch('d#8').transposeAboveTarget(pitch.Pitch('d2'), minimize=True)
            D#2
            >>> pitch.Pitch('d7').transposeAboveTarget(pitch.Pitch('e2'), minimize=True)
            D3
            >>> pitch.Pitch('d0').transposeAboveTarget(pitch.Pitch('e2'), minimize=True)
            D3




        .. method:: transposeBelowTarget(target, minimize=False)

            Given a source Pitch, shift it down octaves until it is below the target. Note: this manipulates src inPlace.

            If `minimize` is True, a pitch below the the target will move up to the nearest octave.



            >>> from music21 import *
            >>> pitch.Pitch('g5').transposeBelowTarget(pitch.Pitch('c#4'))
            G3
            >>> # if already below the target, make no change
            >>> pitch.Pitch('g#3').transposeBelowTarget(pitch.Pitch('c#6'))
            G#3
            >>> # accept the same pitch
            >>> pitch.Pitch('g#8').transposeBelowTarget(pitch.Pitch('g#1'))
            G#1
            ⁠ 
            >>> pitch.Pitch('g#2').transposeBelowTarget(pitch.Pitch('f#8'))
            G#2
            >>> pitch.Pitch('g#2').transposeBelowTarget(pitch.Pitch('f#8'), minimize=True)
            G#7
            >>> pitch.Pitch('f#2').transposeBelowTarget(pitch.Pitch('f#8'), minimize=True)
            F#8



        .. method:: updateAccidentalDisplay(pitchPast=[], pitchPastMeasure=[], alteredPitches=[], cautionaryPitchClass=True, cautionaryAll=False, overrideStatus=False, cautionaryNotImmediateRepeat=True, lastNoteWasTied=False)


            Given an ordered list of Pitch objects in `pitchPast`,
            determine if this pitch's Accidental object needs
            to be created or updated with a natural or other cautionary accidental.


            Changes to this Pitch object's Accidental object are made in-place.

            `pitchPast` is a list of pitches preceeding this pitch

            `pitchPastMeasure` is a list of pitches preceeding this pitch but in a previous measure

            The `alteredPitches` list supplies pitches from a :class:`~music21.key.KeySignature` object using the :attr:`~music21.key.KeySignature.alteredPitches` property.


            If `cautionaryPitchClass` is True, comparisons to past accidentals
            are made regardless of register. That is, if a past sharp is found two
            octaves above a present natural, a natural sign is still displayed.
            Note that this has nothing to do with whether a sharp (not in the key signature)
            is found in a different octave from the same note in a different octave.  The
            sharp must always be displayed.


            If `overrideStatus` is True, this method will ignore any current
            `displayStatus` stetting found on the Accidental. By default this
            does not happen. If `displayStatus` is set to None, the
            Accidental's `displayStatus` is set.


            If `cautionaryNotImmediateRepeat` is True, cautionary accidentals will be displayed
            for an altered pitch even if that pitch had already been displayed as altered (unless
            it's an immediate repetition).


            If `lastNoteWasTied` is True then this note will be treated as immediately following a tie.




            >>> from music21 import *
            ⁠ 
            >>> a = pitch.Pitch('a')
            >>> past = [pitch.Pitch('a#'), pitch.Pitch('c#'), pitch.Pitch('c')]
            >>> a.updateAccidentalDisplay(past, cautionaryAll=True)
            >>> a.accidental, a.accidental.displayStatus
            (<accidental natural>, True)



            >>> b = pitch.Pitch('a')
            >>> past = [pitch.Pitch('a#'), pitch.Pitch('c#'), pitch.Pitch('c')]
            >>> b.updateAccidentalDisplay(past) # should add a natural
            >>> b.accidental, b.accidental.displayStatus
            (<accidental natural>, True)
            ⁠ 
            >>> a4 = pitch.Pitch('a4')
            >>> past = [pitch.Pitch('a#3'), pitch.Pitch('c#'), pitch.Pitch('c')]
            >>> # will not add a natural because match is pitchSpace
            >>> a4.updateAccidentalDisplay(past, cautionaryPitchClass=False)
            >>> a4.accidental == None
            True




        Methods inherited from :class:`~music21.base.Music21Object`: :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.getContextAttr`, :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.searchActiveSiteByAttr`, :meth:`~music21.base.Music21Object.setContextAttr`, :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`


Accidental
----------

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

.. class:: Accidental(specifier='natural')


    Accidental class, representing the symbolic and numerical representation of pitch deviation from a pitch name (e.g., G, B).

    Two accidentals are considered equal if their names are equal.

    Accidentals have three defining attributes: a name, a modifier, and an alter.
    For microtonal specifications, the name and modifier are the same except in
    the case of half-sharp, half-flat, one-and-a-half-flat, and one-and-a-half-sharp.

    Accidentals up to quadruple-sharp and quadruple-flat are allowed.

    Natural-sharp etc. (for canceling a previous flat) are not yet supported.




    >>> from music21 import *
    >>> a = pitch.Accidental('sharp')
    >>> a.name, a.alter, a.modifier
    ('sharp', 1.0, '#')




    **Accidental** **attributes**

        .. attribute:: displayLocation

            Location of accidental: "normal", "above", "below".


        .. attribute:: displaySize

            Size in display: "cue", "large", or a percentage.


        .. attribute:: displayStyle

            Style of display: "parentheses", "bracket", "both".


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

    **Accidental** **properties**

        .. attribute:: name

            A string name of the Accidental, such as "sharp" or
            "double-flat".


        .. attribute:: modifier

            A string symbol used to modify the pitch name, such as "#" or
            "-" for sharp and flat, respectively.


        .. attribute:: alter

            A signed decimal representing the number of half-steps shifted
            by this Accidental, such as 1.0 for a sharp and -.5 for a quarter tone flat.


        .. attribute:: displayStatus

            Determines if this Accidental is to be displayed; can be None (for not set), True, or False.


        .. attribute:: displayType


            Returns or sets the display type of the accidental

            "normal" (default) displays it if it is the first in measure,
            or is needed to contradict a previous accidental, etc.

            other valid terms:
            "always", "never", "unless-repeated" (show always unless
            the immediately preceding note is the same), "even-tied"
            (stronger than always: shows even if it is tied to the
            previous note)



        .. attribute:: fullName

            Return the most complete representation of this Accidental.



            >>> from music21 import *
            >>> a = pitch.Accidental('double-flat')
            >>> a.fullName
            'double-flat'

            Note that non-standard microtones are converted to standard ones



            >>> a = pitch.Accidental('quarter-flat')
            >>> a.fullName
            'half-flat'




        .. attribute:: mx

            From music21 to MusicXML



            >>> from music21 import *
            >>> a = pitch.Accidental()
            >>> a.set('half-sharp')
            >>> a.alter == .5
            True
            >>> mxAccidental = a.mx
            >>> mxAccidental.get('content')
            'quarter-sharp'



        .. attribute:: unicode


            Return a unicode representation of this accidental or the best ascii representation
            if that is not possible.



        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`

    **Accidental** **methods**

        .. method:: set(name)


            Provide a value to the Accidental. Strings values, numbers, and Lilypond
            Abbreviations are all accepted.



            >>> from music21 import *
            >>> a = pitch.Accidental()
            >>> a.set('sharp')
            >>> a.alter == 1
            True
            ⁠ 
            >>> a = pitch.Accidental()
            >>> a.set(2)
            >>> a.modifier == "##"
            True



            >>> a = pitch.Accidental()
            >>> a.set(2.0)
            >>> a.modifier == "##"
            True
            ⁠ 
            >>> a = pitch.Accidental('--')
            >>> a.alter
            -2.0



        .. method:: inheritDisplay(other)

            Given another Accidental object, inherit all the display properites
            of that object.

            This is needed when transposing Pitches: we need to retain accidental display properties.



            >>> from music21 import *
            >>> a = pitch.Accidental('double-flat')
            >>> a.displayType = 'always'
            >>> b = pitch.Accidental('sharp')
            >>> b.inheritDisplay(a)
            >>> b.displayType
            'always'



        .. method:: isTwelveTone()

            Return a boolean if this Accidental describes a twelve-tone pitch.



            >>> from music21 import *
            >>> a = pitch.Accidental('~')
            >>> a.isTwelveTone()
            False
            ⁠ 
            >>> a = pitch.Accidental('###')
            >>> a.isTwelveTone()
            True




        Methods inherited from :class:`~music21.base.Music21Object`: :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.getContextAttr`, :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.searchActiveSiteByAttr`, :meth:`~music21.base.Music21Object.setContextAttr`, :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`


Microtone
---------

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

.. class:: Microtone(centsOrString=0)


    The Microtone object defines a pitch transformation above
    or below a standard Pitch and its Accidental.



    >>> from music21 import *
    >>> m = pitch.Microtone(20)
    >>> m.cents
    20
    >>> m.alter
    0.2...
    >>> m
    (+20c)


    Microtones can be shifted according to the harmonic. Here we take the 3rd
    harmonic of the previous microtone



    >>> m.harmonicShift = 3
    >>> m
    (+20c+3rdH)
    >>> m.cents
    1922
    >>> m.alter
    19.2...


    Microtonal changes can be positive or negative.
    Both Positive and negative numbers can optionally be placed in parentheses
    Negative numbers in parentheses still need the minus sign.




    >>> m = pitch.Microtone('(-33.333333)')
    >>> m
    (-33c)
    >>> m = pitch.Microtone('33.333333')
    >>> m
    (+33c)


    Note that we round the display of microtones to the nearest cent,
    but we keep the exact alteration in both .cents and .alter:



    >>> m.cents
    33.333...
    >>> m.alter
    0.3333...



    **Microtone** **properties**

        .. attribute:: alter

            Return the microtone value in accidental alter values.



        .. attribute:: cents

            Return the microtone value in cents.
            This is not a settable property. To set the value in cents,
            simply use that value as a creation argument.



        .. attribute:: harmonicShift

            Set or get the harmonic shift, altering the microtone



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

    **Microtone** **methods**

        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`


