.. _moduleAbc.base:

music21.abc.base
================

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

.. module:: music21.abc.base


Objects and resources for processing ABC data.

ABC conversion from a file or URL to a :class:`~music21.stream.Stream` is available through the music21 converter module's :func:`~music21.converter.parse` function.



>>> from music21 import *
>>> abcScore = converter.parse('/users/ariza/myScore.abc')


Low level ABC conversion is facilitated by the objects in this module and :func:`music21.abc.translate.abcToStreamScore`.




.. function:: mergeLeadingMetaData(barHandlers)

    Given a list of ABCHandlerBar, ruturn a list of ABCHandlerBar objects, where leading metadata is merged, if possible, with the bar data following.

    This consolidates all metadata in bar-like entities.



ABCFile
-------



.. class:: ABCFile()


    ABC File access




    **ABCFile** **methods**

        .. method:: close()

            No documentation.


        .. method:: extractReferenceNumber(strSrc, number)

            Extract a single reference number from many defined in a file. This permits loading a single work from a collection/opus without parsing the entire file.



        .. method:: open(filename)

            Open a file for reading



        .. method:: openFileLike(fileLike)

            Assign a file-like object, such as those provided by StringIO, as an open file object.



            >>> fileLikeOpen = StringIO.StringIO()



        .. method:: read(number=None)

            Read a file. Note that this calls readstring, which processes all tokens.

            If `number` is given, a work number will be extracted if possible.



        .. method:: readstr(strSrc, number=None)

            Read a string and process all Tokens. Returns a ABCHandler instance.




ABCHandler
----------



.. class:: ABCHandler()


    **ABCHandler** **properties**

        .. attribute:: tokens

            Get or set tokens for this Handler



    **ABCHandler** **methods**

        .. method:: definesMeasures()

            Return True if this token structure defines Measures in a normal Measure form.



            >>> from music21 import *
            >>> abcStr = 'M:6/8\nL:1/8\nK:G\nV:1 name="Whistle" snm="wh"\nB3 A3 | G6 | B3 A3 | G6 ||\nV:2 name="violin" snm="v"\nBdB AcA | GAG D3 | BdB AcA | GAG D6 ||\nV:3 name="Bass" snm="b" clef=bass\nD3 D3 | D6 | D3 D3 | D6 ||'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> True == ah.definesMeasures()
            True
            ⁠ 
            >>> abcStr = 'M:6/8\nL:1/8\nK:G\nB3 A3 G6 B3 A3 G6'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> False == ah.definesMeasures()
            True




        .. method:: definesReferenceNumbers()

            Return True if this token structure defines more than 1 reference number.



            >>> from music21 import *
            >>> abcStr = 'X:5\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> ah.definesReferenceNumbers() # only one returns false
            False
            ⁠ 
            >>> from music21 import *
            >>> abcStr = 'X:5\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||\nX:6\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> ah.definesReferenceNumbers() # only one returns false
            True



        .. method:: getReferenceNumber()

            If tokens are processed, get the first reference number defined.



            >>> from music21 import *
            >>> abcStr = 'X:5\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> ah.getReferenceNumber()
            '5'



        .. method:: getTitle()

            If tokens are processed, get the first title tag. Used for testing.



        .. method:: hasNotes()

            If tokens are processed, return True of ABCNote or ABCChord classes are defined



            >>> from music21 import *
            >>> abcStr = 'M:6/8\nL:1/8\nK:G\n'
            >>> ah1 = abc.ABCHandler()
            >>> junk = ah1.process(abcStr)
            >>> ah1.hasNotes()
            False
            >>> abcStr = 'M:6/8\nL:1/8\nK:G\nc1D2'
            >>> ah2 = abc.ABCHandler()
            >>> junk = ah2.process(abcStr)
            >>> ah2.hasNotes()
            True



        .. method:: process(strSrc)

            No documentation.


        .. method:: splitByMeasure()

            Divide a token list by Measures, also defining start and end bars of each Measure.

            If a component does not have notes, leave as an empty bar. This is often done with leading metadata.

            Returns a list of ABCHandlerBar instances. The first usually defines only Metadata



        .. method:: splitByReferenceNumber()

            Split tokens by reference numbers.

            Returns a dictionary of ABCHandler instances, where the reference number is used to access the music. If no reference numbers are defined, the tune is available under the dictionary entry None.



            >>> from music21 import *
            >>> abcStr = 'X:5\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> len(ah)
            14
            >>> ahDict = ah.splitByReferenceNumber()
            >>> len(ahDict[5].tokens)
            14



        .. method:: splitByVoice()

            Given a processed token list, look for voices. If voices exist, split into parts: common metadata, then next voice, next voice, etc.

            Each part is returned as a ABCHandler instance.



            >>> from music21 import *
            >>> abcStr = 'M:6/8\nL:1/8\nK:G\nV:1 name="Whistle" snm="wh"\nB3 A3 | G6 | B3 A3 | G6 ||\nV:2 name="violin" snm="v"\nBdB AcA | GAG D3 | BdB AcA | GAG D6 ||\nV:3 name="Bass" snm="b" clef=bass\nD3 D3 | D6 | D3 D3 | D6 ||'
            >>> ah = abc.ABCHandler()
            >>> junk = ah.process(abcStr)
            >>> tokenColls = ah.splitByVoice()
            >>> tokenColls[0]
            <music21.abc.base.ABCHandler object at 0x...>
            ⁠ 
            >>> [t.src for t in tokenColls[0].tokens] # common headers are first
            ['M:6/8', 'L:1/8', 'K:G']
            >>> # then each voice
            >>> [t.src for t in tokenColls[1].tokens]
            ['V:1 name="Whistle" snm="wh"', 'B3', 'A3', '|', 'G6', '|', 'B3', 'A3', '|', 'G6', '||']
            >>> [t.src for t in tokenColls[2].tokens]
            ['V:2 name="violin" snm="v"', 'B', 'd', 'B', 'A', 'c', 'A', '|', 'G', 'A', 'G', 'D3', '|', 'B', 'd', 'B', 'A', 'c', 'A', '|', 'G', 'A', 'G', 'D6', '||']
            >>> [t.src for t in tokenColls[3].tokens]
            ['V:3 name="Bass" snm="b" clef=bass', 'D3', 'D3', '|', 'D6', '|', 'D3', 'D3', '|', 'D6', '||']

            Then later the metadata can be merged at the start of each voice...



            >>> mergedTokens = tokenColls[0] + tokenColls[1]
            >>> mergedTokens
            <music21.abc.base.ABCHandler object at 0x...>
            >>> [t.src for t in mergedTokens.tokens]
            ['M:6/8', 'L:1/8', 'K:G', 'V:1 name="Whistle" snm="wh"', 'B3', 'A3', '|', 'G6', '|', 'B3', 'A3', '|', 'G6', '||']





        .. method:: tokenProcess()

            Process all token objects. First, call preParse(), then do cointext assignments, then call parse().



        .. method:: tokenize(strSrc)

            Walk the abc string, creating ABC objects along the way.

            This may be called separately from process(), in the case
            that pre/post parse processing is not needed.




ABCHandlerBar
-------------

Inherits from: :class:`~music21.abc.base.ABCHandler`

.. class:: ABCHandlerBar()

    A Handler specialized for storing bars. All left and right bars are collected and assigned to attributes.



    **ABCHandlerBar** **attributes**

        Attributes without Documentation: `leftBarToken`, `rightBarToken`

    **ABCHandlerBar** **properties**

        Properties inherited from :class:`~music21.abc.base.ABCHandler`: :attr:`~music21.abc.base.ABCHandler.tokens`

    **ABCHandlerBar** **methods**

        Methods inherited from :class:`~music21.abc.base.ABCHandler`: :meth:`~music21.abc.base.ABCHandler.definesMeasures`, :meth:`~music21.abc.base.ABCHandler.definesReferenceNumbers`, :meth:`~music21.abc.base.ABCHandler.getReferenceNumber`, :meth:`~music21.abc.base.ABCHandler.getTitle`, :meth:`~music21.abc.base.ABCHandler.hasNotes`, :meth:`~music21.abc.base.ABCHandler.process`, :meth:`~music21.abc.base.ABCHandler.splitByMeasure`, :meth:`~music21.abc.base.ABCHandler.splitByReferenceNumber`, :meth:`~music21.abc.base.ABCHandler.splitByVoice`, :meth:`~music21.abc.base.ABCHandler.tokenProcess`, :meth:`~music21.abc.base.ABCHandler.tokenize`


ABCBar
------

Inherits from: :class:`~music21.abc.base.ABCToken`

.. class:: ABCBar(src)


    **ABCBar** **methods**

        .. method:: getBarObject()

            Return a music21 bar object



            >>> from music21 import *
            >>> ab = abc.ABCBar('|:')
            >>> ab.parse()
            >>> post = ab.getBarObject()



        .. method:: isRegular()

            Return True if this is a regular, single, light bar line.



            >>> from music21 import *
            >>> ab = abc.ABCBar('|')
            >>> ab.parse()
            >>> ab.isRegular()
            True



        .. method:: isRepeat()

            No documentation.


        .. method:: isRepeatBracket()

            Return true if this defines a repeat bracket for an alternate ending




            >>> from music21 import *
            >>> ab = abc.ABCBar('[2')
            >>> ab.parse()
            >>> ab.isRepeat()
            False
            >>> ab.isRepeatBracket()
            2



        .. method:: parse()


            Assign the bar-type based on the source string.



            >>> from music21 import *
            ⁠ 
            >>> ab = abc.ABCBar('|')
            >>> ab.parse()
            >>> ab.barType
            'barline'
            >>> ab.barStyle
            'regular'



            >>> ab = abc.ABCBar('||')
            >>> ab.parse()
            >>> ab.barType
            'barline'
            >>> ab.barStyle
            'light-light'
            ⁠ 
            >>> ab = abc.ABCBar('|:')
            >>> ab.parse()
            >>> ab.barType
            'repeat'
            >>> ab.barStyle
            'heavy-light'
            >>> ab.repeatForm
            'start'



        Methods inherited from :class:`~music21.abc.base.ABCToken`: :meth:`~music21.abc.base.ABCToken.preParse`, :meth:`~music21.abc.base.ABCToken.stripComment`


ABCBrokenRhythmMarker
---------------------

Inherits from: :class:`~music21.abc.base.ABCToken`

.. class:: ABCBrokenRhythmMarker(src)



ABCChord
--------

Inherits from: :class:`~music21.abc.base.ABCNote`, :class:`~music21.abc.base.ABCToken`

.. class:: ABCChord(src)


    A representation of an ABC Chord, which contains within its delimiters individual notes.

    A subclass of ABCNote.





ABCMetadata
-----------

Inherits from: :class:`~music21.abc.base.ABCToken`

.. class:: ABCMetadata(src='')


    **ABCMetadata** **attributes**

        Attributes without Documentation: `tag`, `data`

        Attributes inherited from :class:`~music21.abc.base.ABCToken`: :attr:`~music21.abc.base.ABCToken.src`

    **ABCMetadata** **methods**

        .. method:: getClefObject()

            Extract any clef parameters stored in the key metadata token. Assume that a clef definition suggests a transposition. Return both the Clef and the transposition.



            >>> from music21 import *
            >>> am = abc.ABCMetadata('K:Eb Lydian')
            >>> am.preParse()
            >>> am._getKeySignatureParameters()
            (-2, 'lydian')




        .. method:: getDefaultQuarterLength()

            If there is a quarter length representation available, return it as a floating point value



            >>> from music21 import *
            >>> am = abc.ABCMetadata('L:1/2')
            >>> am.preParse()
            >>> am.getDefaultQuarterLength()
            2.0
            ⁠ 
            >>> am = abc.ABCMetadata('L:1/8')
            >>> am.preParse()
            >>> am.getDefaultQuarterLength()
            0.5



            >>> am = abc.ABCMetadata('M:C|')
            >>> am.preParse()
            >>> am.getDefaultQuarterLength()
            0.5
            ⁠ 
            >>> am = abc.ABCMetadata('M:2/4')
            >>> am.preParse()
            >>> am.getDefaultQuarterLength()
            0.25



            >>> am = abc.ABCMetadata('M:6/8')
            >>> am.preParse()
            >>> am.getDefaultQuarterLength()
            0.5




        .. method:: getKeySignatureObject()


            Return a music21 :class:`~music21.key.KeySignature`
            object for this metadata tag.



            >>> from music21 import *
            >>> am = abc.ABCMetadata('K:G')
            >>> am.preParse()
            >>> ks = am.getKeySignatureObject()
            >>> ks
            <music21.key.KeySignature of 1 sharp>



        .. method:: getMetronomeMarkObject()

            Extract any tempo parameters stored in a tmepo metadata token.



            >>> from music21 import *
            >>> am = abc.ABCMetadata('Q: "Allegro" 1/4=120')
            >>> am.preParse()
            >>> am.getMetronomeMarkObject()
            <music21.tempo.MetronomeMark Allegro Quarter=120.0>
            ⁠ 
            >>> am = abc.ABCMetadata('Q: 3/8=50 "Slowly"')
            >>> am.preParse()
            >>> am.getMetronomeMarkObject()
            <music21.tempo.MetronomeMark Slowly Dotted Quarter=50.0>



            >>> am = abc.ABCMetadata('Q:1/2=120')
            >>> am.preParse()
            >>> am.getMetronomeMarkObject()
            <music21.tempo.MetronomeMark animato Half=120.0>
            ⁠ 
            >>> am = abc.ABCMetadata('Q:1/4 3/8 1/4 3/8=40')
            >>> am.preParse()
            >>> am.getMetronomeMarkObject()
            <music21.tempo.MetronomeMark grave Whole tied to Quarter (5.0 total QL)=40.0>



            >>> am = abc.ABCMetadata('Q:90')
            >>> am.preParse()
            >>> am.getMetronomeMarkObject()
            <music21.tempo.MetronomeMark maestoso Quarter=90.0>




        .. method:: getTimeSignatureObject()


            Return a music21 :class:`~music21.meter.TimeSignature`
            object for this metadata tag.



            >>> from music21 import *
            >>> am = abc.ABCMetadata('M:2/2')
            >>> am.preParse()
            >>> ts = am.getTimeSignatureObject()
            >>> ts
            <music21.meter.TimeSignature 2/2>



        .. method:: isComposer()

            Returns True if the tag is "C" for composer, False otherwise.



        .. method:: isDefaultNoteLength()

            Returns True if the tag is "L", False otherwise.



        .. method:: isKey()

            Returns True if the tag is "K", False otherwise. Note that in some cases a Key will encode clef information.



        .. method:: isMeter()

            Returns True if the tag is "M" for meter, False otherwise.



        .. method:: isOrigin()

            Returns True if the tag is "O" for origin, False otherwise. This value is set in the Metadata `localOfComposition` of field.



        .. method:: isReferenceNumber()

            Returns True if the tag is "X", False otherwise.



            >>> from music21 import *
            >>> x = abc.ABCMetadata('X:5')
            >>> x.preParse()
            >>> x.tag
            'X'
            >>> x.isReferenceNumber()
            True



        .. method:: isTempo()

            Returns True if the tag is "Q" for tempo, False otherwise.



        .. method:: isTitle()

            Returns True if the tag is "T" for title, False otherwise.



        .. method:: isVoice()

            Returns True if the tag is "V", False otherwise.



        .. method:: parse()

            No documentation.


        .. method:: preParse()


            Called before contextual adjustments and needs
            to have access to data.  Divides a token into
            .tag (a single capital letter or w) and .data representations.



            >>> from music21 import *
            >>> x = abc.ABCMetadata('T:tagData')
            >>> x.preParse()
            >>> x.tag
            'T'
            >>> x.data
            'tagData'



        Methods inherited from :class:`~music21.abc.base.ABCToken`: :meth:`~music21.abc.base.ABCToken.stripComment`


ABCNote
-------

Inherits from: :class:`~music21.abc.base.ABCToken`

.. class:: ABCNote(src='')


    A model of an ABCNote.

    General usage requires multi-pass processing. After being tokenized,
    each ABCNote needs a number of attributes updates. Attributes to
    be updated after tokenizing, and based on the linear sequence of
    tokens: `inBar`, `inBeam` (not used), `inSlur` (not used), `inGrace` (not used),
    `activeDefaultQuarterLength`, `brokenRhythmMarker`, and
    `activeKeySignature`.

    The `chordSymbols` list stores one or more chord symbols (ABC calls
    these guitar chords) associated with this note. This attribute is
    updated when parse() is called.



    **ABCNote** **attributes**

        Attributes without Documentation: `brokenRhythmMarker`, `quarterLength`, `activeKeySignature`, `inGrace`, `chordSymbols`, `inBeam`, `pitchName`, `inSlur`, `activeTuplet`, `inBar`, `isRest`, `accidentalDisplayStatus`, `activeDefaultQuarterLength`

        Attributes inherited from :class:`~music21.abc.base.ABCToken`: :attr:`~music21.abc.base.ABCToken.src`

    **ABCNote** **methods**

        .. method:: parse(forceDefaultQuarterLength=None, forceKeySignature=None)

            No documentation.


        Methods inherited from :class:`~music21.abc.base.ABCToken`: :meth:`~music21.abc.base.ABCToken.preParse`, :meth:`~music21.abc.base.ABCToken.stripComment`


ABCToken
--------



.. class:: ABCToken(src='')


    ABC processing works with a multi-pass procedure. The first pass
    breaks the data stream into a list of ABCToken objects. ABCToken
    objects are specialized in subclasses.

    The multi-pass procedure is conducted by an ABCHandler object.
    The ABCHandler.tokenize() method breaks the data stream into
    ABCToken objects. The :meth:`~music21.abc.base.ABCHandler.tokenProcess` method first
    calls the :meth:`~music21.abc.base.ABCToken.preParse` method on each token, then does contextual
    adjustments to all tokens, then calls :meth:`~music21.abc.base.ABCToken.parse` on all tokens.

    The source ABC string itself is stored in self.src




    **ABCToken** **attributes**

        Attributes without Documentation: `src`

    **ABCToken** **methods**

        .. method:: parse()


            Dummy method that reads self.src and loads attributes.
            It is called after contextual adjustments.

            It is designed to be subclassed or overridden.



        .. method:: preParse()


            Dummy method that is called before contextual adjustments.
            Designed to be subclassed or overridden.



        .. method:: stripComment(strSrc)


            removes ABC-style comments from a string:



            >>> from music21 import *
            >>> ao = abc.ABCToken()
            >>> ao.stripComment('asdf')
            'asdf'
            >>> ao.stripComment('asdf%234')
            'asdf'
            >>> ao.stripComment('asdf  %     234')
            'asdf  '
            >>> ao.stripComment('[ceg]% this chord appears 50% more often than other chords do')
            '[ceg]'




ABCTuplet
---------

Inherits from: :class:`~music21.abc.base.ABCToken`

.. class:: ABCTuplet(src)


    ABCTuplet tokens always precede the notes they describe.

    In ABCHandler.tokenProcess(), rhythms are adjusted.




    **ABCTuplet** **methods**

        .. method:: updateNoteCount(durationActual=None, durationNormal=None)

            Update the note count of notes that are affected by this tuplet.



        .. method:: updateRatio(keySignatureObj=None)

            Cannot be called until local meter context is established



            >>> from music21 import *
            >>> at = abc.ABCTuplet('(3')
            >>> at.updateRatio()
            >>> at.numberNotesActual, at.numberNotesNormal
            (3, 2)
            ⁠ 
            >>> at = abc.ABCTuplet('(5')
            >>> at.updateRatio()
            >>> at.numberNotesActual, at.numberNotesNormal
            (5, 2)



            >>> at = abc.ABCTuplet('(5')
            >>> at.updateRatio(meter.TimeSignature('6/8'))
            >>> at.numberNotesActual, at.numberNotesNormal
            (5, 3)



        Methods inherited from :class:`~music21.abc.base.ABCToken`: :meth:`~music21.abc.base.ABCToken.parse`, :meth:`~music21.abc.base.ABCToken.preParse`, :meth:`~music21.abc.base.ABCToken.stripComment`


