.. _moduleTinyNotation:

music21.tinyNotation
====================

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

.. module:: music21.tinyNotation


tinyNotation is a simple way of specifying single line melodies
that uses a notation somewhat similar to Lilypond but with WAY fewer
options.  It was originally developed to notate trecento (medieval Italian)
music, but it is pretty useful for a lot of short examples, so we have
made it a generally supported music21 format


N.B.: TinyNotation is not meant to expand to cover every single case.  Instead
it is meant to be subclassable to extend to the cases *your* project needs.
See for instance the harmony examples in HarmonyStream and HarmonyNote
or the Trecento specific examples in trecento/cadencebook.py


Here are the most important rules:

1. Note names are: a,b,c,d,e,f,g and r for rest
2. Flats, sharps, and naturals are notated as #,- (not b), and (if needed) n.
   If the accidental is above the staff (i.e., editorial), enclose it in
   parentheses: (#), etc.  Make sure that flats in the key signatures are
   explicitly specified.
3. Note octaves are specified as follows::

     CC to BB = from C below bass clef to second-line B in bass clef
     C to B = from bass clef C to B below middle C.
     c  to b = from middle C to the middle of treble clef
     c' to b' = from C in treble clef to B above treble clef

   Octaves below and above these are specified by further doublings of
   letter (CCC) or apostrophes (c'') -- this is one of the note name
   standards found in many music theory books.
4. After the note name, a number may be placed indicating the note
   length: 1 = whole note, 2 = half, 4 = quarter, 8 = eighth, 16 = sixteenth.
   etc.  If the number is omitted then it is assumed to be the same
   as the previous note.  I.e., c8 B c d  is a string of eighth notes.
5. After the number, a ~ can be placed to show a tie to the next note.
   A "." indicates a dotted note.  (If you are entering
   data via Excel or other spreadsheet, be sure that "capitalize the
   first letter of sentences" is turned off under "Tools->AutoCorrect,"
   otherwise the next letter will be capitalized, and the octave will
   be screwed up.)
6. For triplets use this notation:  `trip{c4 d8}`  indicating that these
   two notes both have "3s" over them.  For 4 in the place of 3,
   use `quad{c16 d e8}`.  No other tuplets are supported.


Again, see the :class:`~music21.tinyNotation.HarmonyStream` (below) and
trecento.cadencebook examples
to see how to make TinyNotation useful for your own needs.

(Currently, final notes with fermatas (or any very long final note),
take 0 for the note length.  But expect this to disappear from the
TinyNotation specification soon, as it's too Trecento specific.)




TinyNotationNote
----------------



.. class:: TinyNotationNote(stringRep=None, storedDict={})


    Class defining a single note in TinyNotation.  The "note" attribute
    returns a :class:`~music21.note.Note` object.


    See docs for :class:`~music21.tinyNotation.TinyNotationStream` for
    usage.


    Simple example:




    >>> from music21 import *
    >>> tnN = tinyNotation.TinyNotationNote("c8")
    >>> m21Note = tnN.note
    >>> m21Note
    <music21.note.Note C>
    >>> m21Note.octave
    4
    >>> m21Note.duration
    <music21.duration.Duration 0.5>


    Very complex example:




    >>> tnN = tinyNotation.TinyNotationNote("AA-4.~=aflat_hel-")
    >>> m21Note = tnN.note
    >>> m21Note.name
    'A-'
    >>> m21Note.octave
    2
    >>> m21Note.lyric
    'hel'
    >>> m21Note.id
    'aflat'



    The optional third element is a dictionary of stored information
    from previous notes that might affect parsing of this note:




    >>> storedDict = {}
    >>> storedDict['lastNoteTied'] = True
    >>> storedDict['inTrip'] = True
    >>> tnN = tinyNotation.TinyNotationNote("d''#4", storedDict)
    >>> tnN.note.tie
    <music21.tie.Tie stop>
    >>> tnN.note.duration.quarterLength
    0.6666666...




    **TinyNotationNote** **attributes**

        .. attribute:: storedDict

            A replacement for dictionaries that behave a bit more like perl hashes.
            No more KeyErrors. The difference between DefaultHash and defaultdict is that the
            Dict values come first in the definition and that default can be set to
            None (which it is) or to any object.

            If you want a factory that makes hashes with a particular different default, use:

                falsehash = lambda h = None: common.DefaultHash(h, default = False)
                a = falsehash({"A": falsehash(), "B": falsehash()})
                print(a["A"]["hi"]) # returns False

            there's probably a way to use this to create a data structure
            of arbitrary dimensionality, though it escapes this author.

            if callDefault is True then the default is called:

                common.DefaultHash(default = list, callDefault = True)

            will create a new List for each element



        Attributes without Documentation: `debug`, `stringRep`

    **TinyNotationNote** **properties**

        .. attribute:: note

            No documentation.


    **TinyNotationNote** **methods**

        .. method:: customNotationMatch(m21NoteObject, stringRep, storedDict)

            No documentation.


        .. method:: customPitchMatch(stringRep, storedDict)


            method to create a note object in sub classes of tiny notation.
            Should return a Note-like object or None



        .. method:: getDots(stringRep, noteObj)


            Subclassable method to set the dots attributes of
            the duration object.

            It is subclassed in music21.trecento.cadencebook.TrecentoNote
            where double dots are redefined as referring to multiply by
            2.25 (according to a practice used by some Medieval musicologists).




TinyNotationStream
------------------

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

.. class:: TinyNotationStream(stringRep='', timeSignature=None)


    A TinyNotationStream takes in a string representation
    similar to Lilypond format
    but simplified somewhat and an optional time signature
    string (or TimeSignature object).


    Example in 3/4:



    >>> from music21 import *
    >>> stream1 = tinyNotation.TinyNotationStream("3/4 E4 r f# g=lastG trip{b-8 a g} c4~ c")
    >>> stream1.show('text')
    {0.0} <music21.meter.TimeSignature 3/4>
    {0.0} <music21.note.Note E>
    {1.0} <music21.note.Rest rest>
    {2.0} <music21.note.Note F#>
    {3.0} <music21.note.Note G>
    {4.0} <music21.note.Note B->
    {4.33333333333} <music21.note.Note A>
    {4.66666666667} <music21.note.Note G>
    {5.0} <music21.note.Note C>
    {6.0} <music21.note.Note C>
    ⁠ 
    >>> stream1.getElementById("lastG").step
    'G'
    >>> stream1.notesAndRests[1].isRest
    True
    >>> stream1.notesAndRests[0].octave
    3
    >>> stream1.notes[-2].tie.type
    'start'
    >>> stream1.notes[-1].tie.type
    'stop'



    **TinyNotationStream** **attributes**

        Attributes without Documentation: `stringRep`

        Attributes inherited from :class:`~music21.stream.Stream`: :attr:`~music21.stream.Stream.isMeasure`, :attr:`~music21.stream.Stream.isStream`, :attr:`~music21.stream.Stream.isFlat`, :attr:`~music21.stream.Stream.autoSort`, :attr:`~music21.stream.Stream.isSorted`, :attr:`~music21.stream.Stream.flattenedRepresentationOf`

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

    **TinyNotationStream** **properties**

        Properties inherited from :class:`~music21.stream.Stream`: :attr:`~music21.stream.Stream.notes`, :attr:`~music21.stream.Stream.pitches`, :attr:`~music21.stream.Stream.atSoundingPitch`, :attr:`~music21.stream.Stream.beat`, :attr:`~music21.stream.Stream.beatDuration`, :attr:`~music21.stream.Stream.beatStr`, :attr:`~music21.stream.Stream.beatStrength`, :attr:`~music21.stream.Stream.derivationChain`, :attr:`~music21.stream.Stream.derivationMethod`, :attr:`~music21.stream.Stream.derivesFrom`, :attr:`~music21.stream.Stream.duration`, :attr:`~music21.stream.Stream.elements`, :attr:`~music21.stream.Stream.finalBarline`, :attr:`~music21.stream.Stream.flat`, :attr:`~music21.stream.Stream.highestOffset`, :attr:`~music21.stream.Stream.highestTime`, :attr:`~music21.stream.Stream.isGapless`, :attr:`~music21.stream.Stream.lowestOffset`, :attr:`~music21.stream.Stream.metadata`, :attr:`~music21.stream.Stream.midiFile`, :attr:`~music21.stream.Stream.musicxml`, :attr:`~music21.stream.Stream.mx`, :attr:`~music21.stream.Stream.notesAndRests`, :attr:`~music21.stream.Stream.offsetMap`, :attr:`~music21.stream.Stream.rootDerivation`, :attr:`~music21.stream.Stream.seconds`, :attr:`~music21.stream.Stream.secondsMap`, :attr:`~music21.stream.Stream.semiFlat`, :attr:`~music21.stream.Stream.sorted`, :attr:`~music21.stream.Stream.spannerBundle`, :attr:`~music21.stream.Stream.spanners`, :attr:`~music21.stream.Stream.variants`, :attr:`~music21.stream.Stream.voices`

        Properties inherited from :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.activeSite`, :attr:`~music21.base.Music21Object.classes`, :attr:`~music21.base.Music21Object.derivationHierarchy`, :attr:`~music21.base.Music21Object.isGrace`, :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`

    **TinyNotationStream** **methods**

        .. method:: getNote(stringRep, storedDict={})


            called out so as to be subclassable, returns a
            :class:`~music21.tinyNotation.TinyNotationNote` object



        Methods inherited from :class:`~music21.stream.Stream`: :meth:`~music21.stream.Stream.append`, :meth:`~music21.stream.Stream.insert`, :meth:`~music21.stream.Stream.insertAndShift`, :meth:`~music21.stream.Stream.transpose`, :meth:`~music21.stream.Stream.augmentOrDiminish`, :meth:`~music21.stream.Stream.scaleOffsets`, :meth:`~music21.stream.Stream.scaleDurations`, :meth:`~music21.stream.Stream.activateVariants`, :meth:`~music21.stream.Stream.addGroupForElements`, :meth:`~music21.stream.Stream.allPlayingWhileSounding`, :meth:`~music21.stream.Stream.analyze`, :meth:`~music21.stream.Stream.attachIntervalsBetweenStreams`, :meth:`~music21.stream.Stream.attachMelodicIntervals`, :meth:`~music21.stream.Stream.attributeCount`, :meth:`~music21.stream.Stream.bestClef`, :meth:`~music21.stream.Stream.chordify`, :meth:`~music21.stream.Stream.expandRepeats`, :meth:`~music21.stream.Stream.explode`, :meth:`~music21.stream.Stream.extendDuration`, :meth:`~music21.stream.Stream.extendDurationAndGetBoundaries`, :meth:`~music21.stream.Stream.extendTies`, :meth:`~music21.stream.Stream.extractContext`, :meth:`~music21.stream.Stream.findConsecutiveNotes`, :meth:`~music21.stream.Stream.findGaps`, :meth:`~music21.stream.Stream.flattenUnnecessaryVoices`, :meth:`~music21.stream.Stream.getClefs`, :meth:`~music21.stream.Stream.getElementAfterElement`, :meth:`~music21.stream.Stream.getElementAfterOffset`, :meth:`~music21.stream.Stream.getElementAtOrAfter`, :meth:`~music21.stream.Stream.getElementAtOrBefore`, :meth:`~music21.stream.Stream.getElementBeforeElement`, :meth:`~music21.stream.Stream.getElementBeforeOffset`, :meth:`~music21.stream.Stream.getElementById`, :meth:`~music21.stream.Stream.getElementByObjectId`, :meth:`~music21.stream.Stream.getElementsByClass`, :meth:`~music21.stream.Stream.getElementsByGroup`, :meth:`~music21.stream.Stream.getElementsByOffset`, :meth:`~music21.stream.Stream.getElementsNotOfClass`, :meth:`~music21.stream.Stream.getInstrument`, :meth:`~music21.stream.Stream.getInstruments`, :meth:`~music21.stream.Stream.getKeySignatures`, :meth:`~music21.stream.Stream.getOffsetByElement`, :meth:`~music21.stream.Stream.getOverlaps`, :meth:`~music21.stream.Stream.getSimultaneous`, :meth:`~music21.stream.Stream.getTimeSignatures`, :meth:`~music21.stream.Stream.groupCount`, :meth:`~music21.stream.Stream.groupElementsByOffset`, :meth:`~music21.stream.Stream.hasElement`, :meth:`~music21.stream.Stream.hasElementByObjectId`, :meth:`~music21.stream.Stream.hasElementOfClass`, :meth:`~music21.stream.Stream.hasMeasures`, :meth:`~music21.stream.Stream.hasPartLikeStreams`, :meth:`~music21.stream.Stream.hasVoices`, :meth:`~music21.stream.Stream.haveAccidentalsBeenMade`, :meth:`~music21.stream.Stream.haveBeamsBeenMade`, :meth:`~music21.stream.Stream.index`, :meth:`~music21.stream.Stream.insertAtNativeOffset`, :meth:`~music21.stream.Stream.insertIntoNoteOrChord`, :meth:`~music21.stream.Stream.internalize`, :meth:`~music21.stream.Stream.invertDiatonic`, :meth:`~music21.stream.Stream.isSequence`, :meth:`~music21.stream.Stream.isTwelveTone`, :meth:`~music21.stream.Stream.isWellFormedNotation`, :meth:`~music21.stream.Stream.makeAccidentals`, :meth:`~music21.stream.Stream.makeBeams`, :meth:`~music21.stream.Stream.makeChords`, :meth:`~music21.stream.Stream.makeImmutable`, :meth:`~music21.stream.Stream.makeMeasures`, :meth:`~music21.stream.Stream.makeMutable`, :meth:`~music21.stream.Stream.makeNotation`, :meth:`~music21.stream.Stream.makeRests`, :meth:`~music21.stream.Stream.makeTies`, :meth:`~music21.stream.Stream.makeTupletBrackets`, :meth:`~music21.stream.Stream.makeVoices`, :meth:`~music21.stream.Stream.measure`, :meth:`~music21.stream.Stream.measureOffsetMap`, :meth:`~music21.stream.Stream.measureTemplate`, :meth:`~music21.stream.Stream.measures`, :meth:`~music21.stream.Stream.melodicIntervals`, :meth:`~music21.stream.Stream.mergeElements`, :meth:`~music21.stream.Stream.metronomeMarkBoundaries`, :meth:`~music21.stream.Stream.pitchAttributeCount`, :meth:`~music21.stream.Stream.playingWhenAttacked`, :meth:`~music21.stream.Stream.plot`, :meth:`~music21.stream.Stream.pop`, :meth:`~music21.stream.Stream.quantize`, :meth:`~music21.stream.Stream.realizeOrnaments`, :meth:`~music21.stream.Stream.recurse`, :meth:`~music21.stream.Stream.remove`, :meth:`~music21.stream.Stream.removeByClass`, :meth:`~music21.stream.Stream.removeByNotOfClass`, :meth:`~music21.stream.Stream.repeatAppend`, :meth:`~music21.stream.Stream.repeatInsert`, :meth:`~music21.stream.Stream.replace`, :meth:`~music21.stream.Stream.restoreActiveSites`, :meth:`~music21.stream.Stream.setDerivation`, :meth:`~music21.stream.Stream.setupSerializationScaffold`, :meth:`~music21.stream.Stream.shiftElements`, :meth:`~music21.stream.Stream.showVariantAsOssialikePart`, :meth:`~music21.stream.Stream.simultaneousAttacks`, :meth:`~music21.stream.Stream.sliceAtOffsets`, :meth:`~music21.stream.Stream.sliceByBeat`, :meth:`~music21.stream.Stream.sliceByGreatestDivisor`, :meth:`~music21.stream.Stream.sliceByQuarterLengths`, :meth:`~music21.stream.Stream.sort`, :meth:`~music21.stream.Stream.splitAtQuarterLength`, :meth:`~music21.stream.Stream.splitByClass`, :meth:`~music21.stream.Stream.storeAtEnd`, :meth:`~music21.stream.Stream.stripTies`, :meth:`~music21.stream.Stream.teardownSerializationScaffold`, :meth:`~music21.stream.Stream.toSoundingPitch`, :meth:`~music21.stream.Stream.toWrittenPitch`, :meth:`~music21.stream.Stream.transferOffsetToElements`, :meth:`~music21.stream.Stream.trimPlayingWhileSounding`, :meth:`~music21.stream.Stream.unwrapWeakref`, :meth:`~music21.stream.Stream.voicesToParts`, :meth:`~music21.stream.Stream.wrapWeakref`

        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.splitByQuarterLengths`, :meth:`~music21.base.Music21Object.unfreezeIds`, :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`


HarmonyStream
-------------

Inherits from: :class:`~music21.tinyNotation.TinyNotationStream`, :class:`~music21.stream.Stream`, :class:`~music21.base.Music21Object`, :class:`~music21.base.JSONSerializer`

.. class:: HarmonyStream(stringRep='', timeSignature=None)


    HarmonyStream provides an
    example of subclassing :class:`~music21.tinyNotation.TinyNotationStream`
    to include harmonies and lyrics encoded in a simple format.



    >>> from music21 import *
    ⁠ 
    >>> michelle = "c2*F*_Mi- c_chelle r4*B-m7* d-_ma A-2_belle "
    >>> michelle += "G4*E-*_these c_are A-_words G_that "
    >>> michelle += "F*Ddim*_go A-_to- Bn_geth- A-_er"



    >>> hns = tinyNotation.HarmonyStream(michelle, "4/4")
    >>> ns = hns.notesAndRests
    >>> ns[0].step
    'C'
    >>> ns[0].editorial.misc['harmony']
    'F'
    >>> ns[0].lyric # note that hyphens are removed
    'Mi'
    >>> ns[2].isRest
    True
    >>> ns[5].name
    'G'
    >>> ns[7].name
    'A-'





HarmonyNote
-----------

Inherits from: :class:`~music21.tinyNotation.TinyNotationNote`

.. class:: HarmonyNote(stringRep=None, storedDict={})



