.. _moduleMusedata.base:

music21.musedata.base
=====================

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

.. module:: music21.musedata.base


Objects and resources for processing MuseData.

MuseData 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('d:/data/musedata/myScore.stage2')

Low level MuseData conversion is facilitated by the objects in this module and :func:`music21.musedata.translate.museDataToStreamScore`.




MuseDataWork
------------



.. class:: MuseDataWork()

    A work might consist of one ore more files.



    **MuseDataWork** **attributes**

        Attributes without Documentation: `files`

    **MuseDataWork** **methods**

        .. method:: addFile(fp)

            Open and read this file path as



        .. method:: addString(str)

            Add a string representation acting like a part file



            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)




        .. method:: getParts()

            Get all parts contained in all files associated with this work. A list of MuseDataPart objects that were created in a MuseDataFile.




MuseDataDirectory
-----------------



.. class:: MuseDataDirectory(dirOrList)

    This class manages finding musedata files stored in a directory, comparing file names and examining sub directories to determine which files are parts.

    Once found, a MuseDataWork, or a list of paths, can be returned

    A directory, or a list of file path stubs, such as that obtained within a zip file, can both be provided



    **MuseDataDirectory** **methods**

        .. method:: getPaths(group=None)

            Return sorted paths for a group, or None



        .. method:: isMusedataFile(fp)

            No documentation.



MuseDataFile
------------



.. class:: MuseDataFile()

    A MuseDataFile file may describe one or more MuseDataPart; a Score might need multiple files for complete definition. A MuseDataFile object can be created from a string.

    When read, one or more MuseDataPart objects are created and stored on self.parts.



    **MuseDataFile** **attributes**

        Attributes without Documentation: `parts`, `file`, `filename`

    **MuseDataFile** **methods**

        .. method:: close()

            No documentation.


        .. method:: open(fp)

            No documentation.


        .. method:: read()

            No documentation.


        .. method:: readstr(str)

            Read a string, dividing it into individual parts.




MuseDataMeasure
---------------



.. class:: MuseDataMeasure(src=[], parent=None)

    A MuseDataMeasure is an abstraction of the data contained within a measure definitions.

    This needs to be an object to gracefully handle the following cases. Some Measures do not have any notes, for example, and the end of encoding where a final bar line is defined. Some measures do not have numbers or barlin definitions, such as pickup notes. Some measures define barline characteristics. Backup and forward presumably only is contained within a measure.



    **MuseDataMeasure** **attributes**

        Attributes without Documentation: `src`, `parent`, `stage`

    **MuseDataMeasure** **methods**

        .. method:: getBarObject()

            Return a configured music21 bar object. This can be used with the current Measure or applied to a previous Measure.



        .. method:: getMeasureObject()

            Return a configured music21 :class:`~music21.stream.Measure`.



        .. method:: getRecords()

            Return a lost of all records stored in this measure as MuseDataRecord.



        .. method:: hasNotes()

            Return True of if this Measure return Notes



        .. method:: hasVoices()

            Return True of if this Measure defines one or more 'back' indication.

            Note: this does not instantiate MuseDataRecord instances.




MuseDataMeasureIterator
-----------------------



.. class:: MuseDataMeasureIterator(src, boundaries, parent)

    Create MuseDataMeasure objects on demand, in order



    **MuseDataMeasureIterator** **methods**

        .. method:: next()

            No documentation.



MuseDataPart
------------



.. class:: MuseDataPart(src=[], stage=None)

    A MuseData part is defined by collection of lines



    **MuseDataPart** **attributes**

        Attributes without Documentation: `src`, `stage`

    **MuseDataPart** **methods**

        .. method:: getClefObject(voice=1)

            Return a music21 clef object based on a two character clef definition.



            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)
            >>> mdw.getParts()[0].getClefObject().sign
            'C'



        .. method:: getDirective()

            The directive field is generally used to store tempo indications.This indication, however, is frequently not provided.



            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = musedata.MuseDataWork()
            >>> mdw.addString(testFiles.hwv56_movement1_17)
            >>> mdw.getParts()[3].getDirective()
            'Largo e piano'



        .. method:: getDivisionsPerQuarterNote()




            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)
            >>> mdw.getParts()[0].getDivisionsPerQuarterNote()
            4
            >>> mdw.getParts()[0].getDivisionsPerQuarterNote()
            4
            >>> mdw.getParts()[1].getDivisionsPerQuarterNote()
            8
            ⁠ 
            >>> mdw = musedata.MuseDataWork()
            >>> mdw.addString(testFiles.bachContrapunctus1_part1)
            >>> mdw.getParts()[0].getDivisionsPerQuarterNote()
            4.0



        .. method:: getGroupMembershipNumber(membership='score')




            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)
            >>> mdw.getParts()[0].getGroupMembershipNumber()
            1
            >>> mdw.getParts()[1].getGroupMembershipNumber()
            2
            >>> mdw.getParts()[2].getGroupMembershipNumber()
            3
            ⁠ 
            >>> mdw = musedata.MuseDataWork()
            >>> mdw.addString(testFiles.bachContrapunctus1_part2)
            >>> mdw.getParts()[0].getGroupMembershipNumber()
            '2'
            >>> mdw = musedata.MuseDataWork()
            >>> mdw.addString(testFiles.bachContrapunctus1_part1)
            >>> mdw.getParts()[0].getGroupMembershipNumber()
            '1'



        .. method:: getGroupMemberships()




            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)
            >>> mdw.getParts()[0].getGroupMemberships()
            ['score']



        .. method:: getGroupMembershipsTotal(membership='score')




            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)
            >>> mdw.getParts()[0].getGroupMembershipsTotal()
            3
            ⁠ 
            >>> mdw = musedata.MuseDataWork()
            >>> mdw.addString(testFiles.bachContrapunctus1_part2)
            >>> mdw.getParts()[0].getGroupMembershipsTotal()
            4



        .. method:: getKeySignature()




            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)
            >>> mdw.getParts()[0].getKeySignature()
            <music21.key.KeySignature of 3 flats>
            ⁠ 
            >>> mdw = musedata.MuseDataWork()
            >>> mdw.addString(testFiles.bachContrapunctus1_part1)
            >>> mdw.getParts()[0].getKeySignature()
            <music21.key.KeySignature of 1 flat>



        .. method:: getMeasures()

            Return a list of all measures stored in this part as MuseDataMeasure objects.



        .. method:: getMovementNumber()




            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = musedata.MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)
            >>> mdw.getParts()[0].getMovementNumber()
            '3'
            ⁠ 
            >>> mdw = musedata.MuseDataWork()
            >>> mdw.addString(testFiles.bachContrapunctus1_part2)
            >>> mdw.getParts()[0].getMovementNumber()
            '1'



        .. method:: getMovementTitle()




            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)
            >>> mdw.getParts()[0].getMovementTitle()
            'Aria'



        .. method:: getPartName()




            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)
            >>> mdw.getParts()[0].getPartName()
            'Viola Solo'
            >>> mdw.getParts()[1].getPartName()
            'TENORE'



        .. method:: getSource()




            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = musedata.MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)
            >>> mdw.getParts()[0].getSource()
            'Bach Gesellschaft i'
            ⁠ 
            >>> mdw = musedata.MuseDataWork()
            >>> mdw.addString(testFiles.bachContrapunctus1_part2)
            >>> mdw.getParts()[0].getSource()
            'Bach Gesellschaft xxv,1'



        .. method:: getTimeSignatureObject()




            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)
            >>> mdw.getParts()[0].getTimeSignatureObject()
            <music21.meter.TimeSignature 3/4>



        .. method:: getTranspositionIntervalObject()

            If this part defines a transposition, return a corresponding Interval object.



            >>> from music21 import *
            >>> fp1 = os.path.join(common.getSourceFilePath(), 'musedata', 'testPrimitive', 'test01', '01.md')
            >>> fp2 = os.path.join(common.getSourceFilePath(), 'musedata', 'testPrimitive', 'test01', '02.md')
            >>> mdw = MuseDataWork()
            >>> mdw.addFile(fp1)
            >>> mdw.addFile(fp2)
            >>> mdw.getParts()[0].getTranspositionIntervalObject()
            <music21.interval.Interval m-3>



        .. method:: getWorkNumber()




            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = musedata.MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)
            >>> mdw.getParts()[0].getWorkNumber()
            '5'
            ⁠ 
            >>> mdw = musedata.MuseDataWork()
            >>> mdw.addString(testFiles.bachContrapunctus1_part2)
            >>> mdw.getParts()[0].getWorkNumber()
            '1080'



        .. method:: getWorkTitle()




            >>> from music21 import *
            >>> from music21.musedata import testFiles
            >>> mdw = MuseDataWork()
            >>> mdw.addString(testFiles.bach_cantata5_mvmt3)
            >>> mdw.getParts()[0].getWorkTitle()
            'Wo soll ich fliehen hin'
            ⁠ 
            >>> mdw = musedata.MuseDataWork()
            >>> mdw.addString(testFiles.bachContrapunctus1_part2)
            >>> mdw.getParts()[0].getWorkTitle()
            '381'



        .. method:: update()

            After setting the source string, this method must be called to configure the _measureNumberToLine method and set additional attributes.




MuseDataRecord
--------------



.. class:: MuseDataRecord(src='', parent=None)

    Object for extracting data from a Note or other related record, or a single line of musedata data.



    **MuseDataRecord** **attributes**

        Attributes without Documentation: `src`, `parent`, `stage`

    **MuseDataRecord** **methods**

        .. method:: getArticulationObjects()

            Return a list of 0 or more music21 Articulation objects



            >>> from music21 import *
            >>> mdr = music21.musedata.MuseDataRecord('C4    12        e     u  [      .p')
            >>> mdr.getArticulationObjects()
            [<music21.articulations.Staccato>]
            ⁠ 
            >>> mdr = music21.musedata.MuseDataRecord('C4    12        e     u  [      .p>')
            >>> mdr.getArticulationObjects()
            [<music21.articulations.Staccato>, <music21.articulations.Accent>]




        .. method:: getBeams()

            Return complete span of characters defining beams.



            >>> from music21 import *
            >>> mdr = music21.musedata.MuseDataRecord('E2     1        s     u  =')
            >>> mdr.getBeams()
            '='
            >>> mdr = music21.musedata.MuseDataRecord('E2     1        s     u  ]')
            >>> mdr.getBeams()
            ']'
            >>> mdr = music21.musedata.MuseDataRecord('E2     4        q     u')
            >>> mdr.getBeams() == None
            True




        .. method:: getDots()

            No documentation.


        .. method:: getDynamicObjects()

            Return a list of 0 or more music21 Dyanmic objects



            >>> from music21 import *
            >>> mdr = music21.musedata.MuseDataRecord('C5    12        e     u         ff')
            >>> mdr.getDynamicObjects()
            [<music21.dynamics.Dynamic ff >]
            ⁠ 
            >>> mdr = music21.musedata.MuseDataRecord('E4    48        h     u        (pp')
            >>> mdr.getDynamicObjects()
            [<music21.dynamics.Dynamic pp >]




        .. method:: getExpressionObjects()

            Return a list of 0 or more music21 Articulation objects



            >>> from music21 import *
            >>> mdr = music21.musedata.MuseDataRecord('C4    12        e     u  [      t')
            >>> mdr.getExpressionObjects()
            [<music21.expressions.Trill>]
            ⁠ 
            >>> mdr = music21.musedata.MuseDataRecord('C4    12        e     u  [      .p>F')
            >>> mdr.getExpressionObjects()
            [<music21.expressions.Fermata>]




        .. method:: getLyrics()

            Return lyrics as a list.



            >>> from music21 import *
            >>> mdr = music21.musedata.MuseDataRecord('D4     2        e     u                    con-')
            >>> mdr.stage = 2
            >>> mdr.getLyrics()
            ['con-']



        .. method:: getPitchObject()

            Get the Pitch object defined by this record. This may be a note, chord, or grace pitch.



            >>> from music21 import *
            >>> mdr = music21.musedata.MuseDataRecord('Ef4    1        s     d  ==')
            >>> p = mdr.getPitchObject()
            >>> p.nameWithOctave
            'E-4'
            >>> mdr = music21.musedata.MuseDataRecord('F#4    1        s #   d  ==')
            >>> p = mdr.getPitchObject()
            >>> p.nameWithOctave
            'F#4'
            >>> p.accidental.displayStatus
            True



        .. method:: getQuarterLength(divisionsPerQuarterNote=None)




            >>> from music21 import *
            >>> mdr = music21.musedata.MuseDataRecord('Ef4    1        s     d  ==')
            >>> mdr.getQuarterLength(4)
            0.25
            ⁠ 
            >>> mdr = music21.musedata.MuseDataRecord('Ef4    6        s     d  ==')
            >>> mdr.getQuarterLength(4)
            1.5



            >>> mdr = music21.musedata.MuseDataRecord('back   4')
            >>> mdr.getQuarterLength(4)
            1.0



        .. method:: getType()

            No documentation.


        .. method:: hasCautionaryAccidental()

            Return a boolean if this note has a cautionary accidental.



            >>> from music21 import *
            >>> mdr = music21.musedata.MuseDataRecord('F5     3        t n   d  ==[   (+')
            >>> mdr.hasCautionaryAccidental()
            True
            ⁠ 
            >>> mdr = music21.musedata.MuseDataRecord('C4    12        e     u  [')
            >>> mdr.hasCautionaryAccidental()
            False




        .. method:: isBack()




            >>> mdr = music21.musedata.MuseDataRecord('back   4')
            >>> mdr.isBack()
            True



        .. method:: isChord()

            Chords are specified as additional note records following a main chord tone. The blank space defines this as chord tone.



        .. method:: isCueOrGrace()

            No documentation.


        .. method:: isNote()

            No documentation.


        .. method:: isRest()

            Return a boolean if this record is a rest.



            >>> from music21 import *
            >>> mdr = music21.musedata.MuseDataRecord('D4     1        s     d  ]]')
            >>> mdr.isRest()
            False
            >>> mdr = music21.musedata.MuseDataRecord('measure 1       A')
            >>> mdr.isRest()
            False




        .. method:: isTied()

            Return a boolean if this record is tied.



            >>> from music21 import *
            >>> mdr = music21.musedata.MuseDataRecord('D4     8-       h     d        -')
            >>> mdr.isTied()
            True
            ⁠ 
            >>> from music21 import *
            >>> mdr = music21.musedata.MuseDataRecord('C4     1        s     u  [[')
            >>> mdr.isTied()
            False




MuseDataRecordIterator
----------------------



.. class:: MuseDataRecordIterator(src, parent)

    Create MuseDataRecord objects on demand, in order



    **MuseDataRecordIterator** **methods**

        .. method:: next()

            No documentation.



