.. _moduleMetadata:

music21.metadata
================

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

.. module:: music21.metadata

Classes and functions for creating and processing metadata associated with scores, works, and fragments, such as titles, movements, authors, publishers, and regions.

The :class:`~music21.metadata.Metadata` object is the main public interface to metadata components. A Metadata object can be added to a Stream and used to set common score attributes, such as title and composer. A Metadata object found at offset zero can be accessed through a Stream's :attr:`~music21.stream.Stream.metadata` property.

The following example creates a :class:`~music21.stream.Stream` object, adds a :class:`~music21.note.Note` object, and configures and adds the :attr:`~music21.metadata.Metadata.title` and :attr:`~music21.metadata.Metadata.composer` properties of a Metadata object.



>>> from music21 import *
>>> s = stream.Stream()
>>> s.append(note.Note())
>>> s.insert(metadata.Metadata())
>>> s.metadata.title = 'title'
>>> s.metadata.composer = 'composer'
>>> s.show()




.. image:: images/moduleMetadata-01.*
        :width: 600






.. function:: abbreviationToRole(value)

    Get ROLE_ABBREVIATIONS as string-like attributes, used for Contributors.



    >>> from music21 import *
    >>> metadata.abbreviationToRole('com')
    'composer'
    >>> metadata.abbreviationToRole('lib')
    'librettist'
    >>> for id in metadata.ROLE_ABBREVIATIONS:
    ...    post = metadata.abbreviationToRole(id)



.. function:: abbreviationToWorkId(value)

    Get work id abbreviations.



    >>> from music21 import *
    >>> metadata.abbreviationToWorkId('otl')
    'title'
    >>> for id in metadata.WORK_ID_ABBREVIATIONS:
    ...    post = metadata.abbreviationToWorkId(id)



.. function:: errorToSymbol(value)

    Convert an error string (appoximate, uncertain) into a symbol.



    >>> from music21 import *
    >>> metadata.errorToSymbol('approximate')
    '~'
    >>> metadata.errorToSymbol('uncertain')
    '?'



.. function:: roleToAbbreviation(value)

    Get a role id from a string representation.



    >>> from music21 import *
    >>> metadata.roleToAbbreviation('composer')
    'com'
    >>> for n in metadata.ROLES:
    ...     post = metadata.roleToAbbreviation(n)



.. function:: workIdToAbbreviation(value)

    Get a role id from a string representation.



    >>> from music21 import *
    >>> metadata.workIdToAbbreviation('localeOfComposition')
    'opc'
    >>> for n in metadata.WORK_IDS:
    ...     post = metadata.workIdToAbbreviation(n)



Text
----

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

.. class:: Text(data='', language=None)

    One unit of text data: a title, a name, or some other text data. Store the string and a language name or code. This object can be used and/or subclassed for a variety for of text storage.







    >>> from music21 import *
    >>> td = metadata.Text('concerto in d', 'en')
    >>> str(td)
    'concerto in d'



    **Text** **properties**

        .. attribute:: language

            Set the language of the Text stored within.



            >>> from music21 import *
            >>> t = metadata.Text('my text')
            >>> t.language = 'en'
            >>> t.language
            'en'



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

    **Text** **methods**

        .. method:: getNormalizedArticle()

            Return a string representation with normalized articles.



            >>> from music21 import *
            >>> td = metadata.Text('Ale is Dear, The', 'en')
            >>> str(td)
            'Ale is Dear, The'
            >>> td.getNormalizedArticle()
            'The Ale is Dear'
            ⁠ 
            >>> td.language = 'de'
            >>> td.getNormalizedArticle()
            'Ale is Dear, The'



        .. method:: jsonAttributes()

            Define all attributes of this object that should be JSON serialized for storage and re-instantiation. Attributes that name basic Python objects or :class:`~music21.base.JSONSerializer` subclasses, or dictionaries or lists that contain Python objects or :class:`~music21.base.JSONSerializer` subclasses, can be provided.



        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


Date
----

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

.. class:: Date(*args, **keywords)

    A single date value, specified by year, month, day, hour, minute, and second. Note that this class has been created, instead of using Python's datetime, to provide greater flexibility for processing unconventional dates, ancient dates, dates with error, and date ranges.

    The :attr:`~music21.metadata.Date.datetime` property can be used to retrieve a datetime object when necessary.

    Additionally, each value can be specified as `uncertain` or `approximate`; if None, assumed to be certain.

    Data objects are fundamental components of :class:`~music21.metadata.DateSingle` and related subclasses that represent single dates and date ranges.







    >>> from music21 import *
    >>> a = metadata.Date(year=1843, yearError='approximate')
    >>> a.year
    1843
    >>> a.yearError
    'approximate'
    ⁠ 
    >>> a = metadata.Date(year='1843?')
    >>> a.yearError
    'uncertain'




    **Date** **attributes**

        Attributes without Documentation: `attrStrFormat`, `minuteError`, `monthError`, `hour`, `hourError`, `dayError`, `attrNames`, `month`, `second`, `secondError`, `yearError`, `year`, `day`, `minute`

    **Date** **properties**

        .. attribute:: datetime

            Get a datetime object from a metadata.Date() object



            >>> from music21 import *
            >>> a = metadata.Date(year=1843, month=3, day=3)
            >>> str(a)
            '1843/03/03'
            >>> a.datetime
            datetime.datetime(1843, 3, 3, 0, 0)

            Lack of a required date element raises an exception:



            >>> a = metadata.Date(year=1843, month=3)
            >>> str(a)
            '1843/03/--'
            >>> a.datetime
            Traceback (most recent call last):
            ...
            TypeError: Required argument 'day' (pos 3) not found



        .. attribute:: hasError

            Return True if any data points have error defined.



            >>> from music21 import *
            >>> a = metadata.Date(year=1843, month=3, day=3, dayError='approximate')
            >>> a.hasError
            True
            >>> b = metadata.Date(year=1843, month=3, day=3, minute=3)
            >>> b.hasError
            False



        .. attribute:: hasTime

            Return True if any time elements are defined.



            >>> from music21 import *
            >>> a = metadata.Date(year=1843, month=3, day=3)
            >>> a.hasTime
            False
            >>> b = metadata.Date(year=1843, month=3, day=3, minute=3)
            >>> b.hasTime
            True



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

    **Date** **methods**

        .. method:: jsonAttributes()

            Define all attributes of this object that should be JSON serialized for storage and re-instantiation. Attributes that name basic Python objects or :class:`~music21.base.JSONSerializer` subclasses, or dictionaries or lists that contain Python objects or :class:`~music21.base.JSONSerializer` subclasses, can be provided.



        .. method:: load(value)

            Load values by string, datetime object, or Date object.



            >>> from music21 import *
            >>> a = metadata.Date(year=1843, month=3, day=3)
            >>> b = metadata.Date()
            >>> b.load(a)
            >>> b.year
            1843



        .. method:: loadDatetime(dt)

            Load time data from a datetime object.



            >>> from music21 import *
            >>> import datetime
            >>> dt = datetime.datetime(2005, 02, 01)
            >>> dt
            datetime.datetime(2005, 2, 1, 0, 0)
            ⁠ 
            >>> m21mdDate = metadata.Date()
            >>> m21mdDate.loadDatetime(dt)
            >>> str(m21mdDate)
            '2005/02/01'



        .. method:: loadOther(other)

            Load values based on another Date object:



            >>> from music21 import *
            >>> a = metadata.Date(year=1843, month=3, day=3)
            >>> b = metadata.Date()
            >>> b.loadOther(a)
            >>> b.year
            1843



        .. method:: loadStr(str)

            Load a string date representation.

            Assume year/month/day/hour:minute:second



            >>> from music21 import *
            >>> d = metadata.Date()
            >>> d.loadStr('3030?/12~/?4')
            >>> d.month, d.monthError
            (12, 'approximate')
            >>> d.year, d.yearError
            (3030, 'uncertain')
            >>> d.month, d.monthError
            (12, 'approximate')
            >>> d.day, d.dayError
            (4, 'uncertain')
            ⁠ 
            >>> d = metadata.Date()
            >>> d.loadStr('1834/12/4/4:50:32')
            >>> d.minute, d.second
            (50, 32)




        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


DateSingle
----------

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

.. class:: DateSingle(data='', relevance='certain')

    Store a date, either as certain, approximate, or uncertain relevance.

    The relevance attribute is limited within each DateSingle subclass depending on
    the design of the class. Alternative relevance types should be configured as other DateSingle subclasses.






    >>> from music21 import *
    >>> dd = metadata.DateSingle('2009/12/31', 'approximate')
    >>> str(dd)
    '2009/12/31'
    >>> dd.relevance
    'approximate'
    ⁠ 
    >>> dd = metadata.DateSingle('1805/3/12', 'uncertain')
    >>> str(dd)
    '1805/03/12'



    **DateSingle** **attributes**

        Attributes without Documentation: `isSingle`

    **DateSingle** **properties**

        .. attribute:: datetime

            Get a datetime object.



            >>> from music21 import *
            >>> a = metadata.DateSingle('1843/03/03')
            >>> str(a)
            '1843/03/03'
            >>> a.datetime
            datetime.datetime(1843, 3, 3, 0, 0)
            ⁠ 
            >>> a = metadata.DateSingle('1843/03')
            >>> str(a)
            '1843/03/--'



        .. attribute:: relevance

            No documentation.


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

    **DateSingle** **methods**

        .. method:: jsonAttributes()

            Define all attributes of this object that should be JSON serialized for storage and re-instantiation. Attributes that name basic Python objects or :class:`~music21.base.JSONSerializer` subclasses, or dictionaries or lists that contain Python objects or :class:`~music21.base.JSONSerializer` subclasses, can be provided.



        .. method:: jsonComponentFactory(idStr)

            No documentation.


        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


DateRelative
------------

Inherits from: :class:`~music21.metadata.DateSingle`, :class:`~music21.base.JSONSerializer`

.. class:: DateRelative(data='', relevance='after')

    Store a relative date, sometime prior or sometime after






    >>> from music21 import *
    >>> dd = metadata.DateRelative('2009/12/31', 'prior')
    >>> str(dd)
    '2009/12/31'
    ⁠ 
    >>> dd = metadata.DateRelative('2009/12/31', 'certain')
    Traceback (most recent call last):
    MetadataException: relevance value is not supported by this object: certain




DateBetween
-----------

Inherits from: :class:`~music21.metadata.DateSingle`, :class:`~music21.base.JSONSerializer`

.. class:: DateBetween(data=[], relevance='between')

    Store a relative date, sometime between two dates






    >>> from music21 import *
    >>> dd = metadata.DateBetween(['2009/12/31', '2010/1/28'])
    >>> str(dd)
    '2009/12/31 to 2010/01/28'
    ⁠ 
    >>> dd = metadata.DateBetween(['2009/12/31', '2010/1/28'], 'certain')
    Traceback (most recent call last):
    MetadataException: relevance value is not supported by this object: certain




DateSelection
-------------

Inherits from: :class:`~music21.metadata.DateSingle`, :class:`~music21.base.JSONSerializer`

.. class:: DateSelection(data='', relevance='or')

    Store a selection of dates, or a collection of dates that might all be possible






    >>> from music21 import *
    >>> dd = metadata.DateSelection(['2009/12/31', '2010/1/28', '1894/1/28'], 'or')
    >>> str(dd)
    '2009/12/31 or 2010/01/28 or 1894/01/28'
    ⁠ 
    >>> dd = metadata.DateSelection(['2009/12/31', '2010/1/28'], 'certain')
    Traceback (most recent call last):
    MetadataException: relevance value is not supported by this object: certain




Contributor
-----------

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

.. class:: Contributor(*args, **keywords)

    A person that contributed to a work. Can be a composer, lyricist,
    arranger, or other type of contributor.
    In MusicXML, these are "creator" elements.






    >>> from music21 import *
    >>> td = metadata.Contributor(role='composer', name='Chopin, Fryderyk')
    >>> td.role
    'composer'
    >>> td.name
    'Chopin, Fryderyk'
    >>> td.relevance
    'contributor'




    **Contributor** **attributes**

        Attributes without Documentation: `relevance`

    **Contributor** **properties**

        .. attribute:: mx

            Return a mxCreator object based on this object.



            >>> from music21 import *
            >>> md = metadata.Metadata()
            >>> md.composer = 'frank'
            >>> mxCreator = md._contributors[0].mx
            >>> mxCreator.get('charData')
            'frank'
            >>> mxCreator.get('type')
            'composer'



        .. attribute:: name

            Returns the text name, or the first of many names entered.



            >>> from music21 import *
            >>> td = metadata.Contributor(role='composer', names=['Chopin, Fryderyk', 'Chopin, Frederick'])
            >>> td.name
            'Chopin, Fryderyk'
            >>> td.names
            ['Chopin, Fryderyk', 'Chopin, Frederick']




        .. attribute:: names

            Returns all names in a list.



            >>> from music21 import *
            >>> td = metadata.Contributor(role='composer', names=['Chopin, Fryderyk', 'Chopin, Frederick'])
            >>> td.names
            ['Chopin, Fryderyk', 'Chopin, Frederick']



        .. attribute:: role


            The role is what part this Contributor plays in the work.
            Both full roll strings and roll abbreviations may be used.



            >>> from music21 import *
            >>> td = metadata.Contributor()
            >>> td.role = 'composer'
            >>> td.role
            'composer'
            >>> td.role = 'lor'
            >>> td.role
            'orchestrator'



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

    **Contributor** **methods**

        .. method:: age()

            Calculate the age at death of the Contributor, returning a datetime.timedelta object.



            >>> from music21 import *
            >>> a = metadata.Contributor(name='Beethoven, Ludwig van', role='composer', birth='1770/12/17', death='1827/3/26')
            >>> a.role
            'composer'
            >>> a.age()
            datetime.timedelta(20552)
            >>> str(a.age())
            '20552 days, 0:00:00'
            >>> a.age().days / 365
            56



        .. method:: jsonAttributes()

            Define all attributes of this object that should be JSON serialized for storage and re-instantiation. Attributes that name basic Python objects or :class:`~music21.base.JSONSerializer` subclasses, or dictionaries or lists that contain Python objects or :class:`~music21.base.JSONSerializer` subclasses, can be provided.



        .. method:: jsonComponentFactory(idStr)

            No documentation.


        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


Metadata
--------

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

.. class:: Metadata(*args, **keywords)

    Metadata represent data for a work or fragment,
    including title, composer, dates, and other relevant information.

    Metadata is a :class:`~music21.base.Music21Object` subclass,
    meaing that it can be positioned on a Stream by offset and
    have a :class:`~music21.duration.Duration`.

    In many cases, each Stream will have a single Metadata
    object at the zero offset position.






    >>> from music21 import *
    >>> md = metadata.Metadata(title='Concerto in F')
    >>> md.title
    'Concerto in F'




    >>> md = Metadata(otl='Concerto in F') # can use abbreviations
    >>> md.title
    'Concerto in F'
    >>> md.setWorkId('otl', 'Rhapsody in Blue')
    >>> md.otl
    'Rhapsody in Blue'
    >>> md.title
    'Rhapsody in Blue'



    **Metadata** **attributes**

        .. attribute:: classSortOrder

            Property which returns an number (int or otherwise)
            depending on the class of the Music21Object that
            represents a priority for an object based on its class alone --
            used as a tie for stream sorting in case two objects have the
            same offset and priority.  Lower numbers are sorted to the left
            of higher numbers.  For instance, Clef, KeySignature, TimeSignature
            all come (in that order) before Note.

            All undefined classes have classSortOrder of 20 -- same as note.Note



            >>> from music21 import *
            >>> tc = clef.TrebleClef()
            >>> tc.classSortOrder
            0
            >>> ks = key.KeySignature(3)
            >>> ks.classSortOrder
            1


            New classes can define their own default classSortOrder



            >>> class ExampleClass(base.Music21Object):
            ...     classSortOrderDefault = 5
            ...
            >>> ec1 = ExampleClass()
            >>> ec1.classSortOrder
            5



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

    **Metadata** **properties**

        .. attribute:: alternativeTitle

            Get or set the alternative title.



            >>> from music21 import *
            >>> md = metadata.Metadata(popularTitle='Eroica')
            >>> md.alternativeTitle = 'Heroic Symphony'
            >>> md.alternativeTitle
            'Heroic Symphony'




        .. attribute:: composer

            Get or set the composer of this work. More than one composer may be specified.

            The composer attribute does not live in Metadata, but creates a :class:`~music21.metadata.Contributor` object in the Metadata object.



            >>> from music21 import *
            >>> md = metadata.Metadata(title='Third Symphony', popularTitle='Eroica', composer='Beethoven, Ludwig van')
            >>> md.composer
            'Beethoven, Ludwig van'



        .. attribute:: composers

            Get a list of all :class:`~music21.metadata.Contributor` objects defined as composer of this work.



        .. attribute:: date

            Get or set the date of this work as one of the following date objects: :class:`~music21.metadata.DateSingle`, :class:`~music21.metadata.DateRelative`, :class:`~music21.metadata.DateBetween`,  :class:`~music21.metadata.DateSelection`,



            >>> from music21 import *
            >>> md = metadata.Metadata(title='Third Symphony', popularTitle='Eroica', composer='Beethoven, Ludwig van')
            >>> md.date = '2010'
            >>> md.date
            '2010/--/--'
            ⁠ 
            >>> md.date = metadata.DateBetween(['2009/12/31', '2010/1/28'])
            >>> md.date
            '2009/12/31 to 2010/01/28'



        .. attribute:: localeOfComposition

            Get or set the locale of composition, or origin, of the work.



        .. attribute:: movementName

            Get or set the movement title.



        .. attribute:: movementNumber

            Get or set the movement number.



        .. attribute:: mx

            Return a mxScore object, to be merged or used in final musicxml output



        .. attribute:: number

            Get or set the number of the work.



        .. attribute:: opusNumber

            Get or set the opus number.



        .. attribute:: title

            Get the title of the work, or the next-matched title string available from a related parameter fields.



            >>> from music21 import *
            >>> md = metadata.Metadata(title='Third Symphony')
            >>> md.title
            'Third Symphony'
            ⁠ 
            >>> md = metadata.Metadata(popularTitle='Eroica')
            >>> md.title
            'Eroica'



            >>> md = metadata.Metadata(title='Third Symphony', popularTitle='Eroica')
            >>> md.title
            'Third Symphony'
            >>> md.popularTitle
            'Eroica'
            >>> md.otp
            'Eroica'



        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`

    **Metadata** **methods**

        .. method:: addContributor(c)

            Assign a :class:`~music21.metadata.Contributor` object to this Metadata.



            >>> from music21 import *
            >>> md = metadata.Metadata(title='Third Symphony')
            >>> c = metadata.Contributor()
            >>> c.name = 'Beethoven, Ludwig van'
            >>> c.role = 'composer'
            >>> md.addContributor(c)
            >>> md.composer
            'Beethoven, Ludwig van'
            >>> md.composer = 'frank'
            >>> md.composers
            ['Beethoven, Ludwig van', 'frank']



        .. method:: getContributorsByRole(value)

            Return a :class:`~music21.metadata.Contributor` if defined for a provided role.



            >>> from music21 import *
            >>> md = metadata.Metadata(title='Third Symphony')
            ⁠ 
            >>> c = metadata.Contributor()
            >>> c.name = 'Beethoven, Ludwig van'
            >>> c.role = 'composer'
            >>> md.addContributor(c)
            >>> cList = md.getContributorsByRole('composer')
            >>> cList[0].name
            'Beethoven, Ludwig van'


            Some musicxml files have contributors with no role defined.
            To get these contributors, search for getContributorsByRole(None).
            N.B. upon output to MusicXML, music21 gives these contributors
            the generic role of "creator"



            >>> c2 = metadata.Contributor()
            >>> c2.name = 'Beth Hadley'
            >>> md.addContributor(c2)
            >>> noRoleList = md.getContributorsByRole(None)
            >>> len(noRoleList)
            1
            >>> noRoleList[0].role
            >>> noRoleList[0].name
            'Beth Hadley'




        .. method:: jsonAttributes()

            Define all attributes of this object that should be JSON serialized for storage and re-instantiation. Attributes that name basic Python objects or :class:`~music21.base.JSONSerializer` subclasses, or dictionaries or lists that contain Python objects or :class:`~music21.base.JSONSerializer` subclasses, can be provided.



        .. method:: jsonComponentFactory(idStr)

            No documentation.


        .. method:: search(query, field=None)

            Search one or all fields with a query, given either as a string or a regular expression match.



            >>> from music21 import *
            >>> md = metadata.Metadata()
            >>> md.composer = 'Beethoven, Ludwig van'
            >>> md.title = 'Third Symphony'
            ⁠ 
            >>> md.search('beethoven', 'composer')
            (True, 'composer')
            >>> md.search('beethoven', 'compose')
            (True, 'composer')
            >>> md.search('frank', 'composer')
            (False, None)
            >>> md.search('frank')
            (False, None)



            >>> md.search('third')
            (True, 'title')
            >>> md.search('third', 'composer')
            (False, None)
            >>> md.search('third', 'title')
            (True, 'title')
            ⁠ 
            >>> md.search('third|fourth')
            (True, 'title')
            >>> md.search('thove(.*)')
            (True, 'composer')




        .. method:: setWorkId(idStr, value)

            Directly set a workd id, given either as a full string name or as a three character abbreviation. The following work id abbreviations and their full id string are given as follows. In many cases the Metadata object support properties for convenient access to these work ids.

            Id abbreviations and strings: otl / title, otp / popularTitle, ota / alternativeTitle, opr / parentTitle, oac / actNumber, osc / sceneNumber, omv / movementNumber, omd / movementName, ops / opusNumber, onm / number, ovm / volume, ode / dedication, oco / commission, gtl / groupTitle, gaw / associatedWork, gco / collectionDesignation, txo / textOriginalLanguage, txl / textLanguage, ocy / countryOfComposition, opc / localeOfComposition.



            >>> from music21 import *
            >>> md = metadata.Metadata(title='Quartet')
            >>> md.title
            'Quartet'
            >>> md.setWorkId('otl', 'Trio')
            >>> md.title
            'Trio'
            >>> md.setWorkId('sdf', None)
            Traceback (most recent call last):
            MetadataException: no work id available with id: sdf




        Methods inherited from :class:`~music21.base.Music21Object`: :meth:`~music21.base.Music21Object.searchActiveSiteByAttr`, :meth:`~music21.base.Music21Object.getContextAttr`, :meth:`~music21.base.Music21Object.setContextAttr`, :meth:`~music21.base.Music21Object.addContext`, :meth:`~music21.base.Music21Object.addLocation`, :meth:`~music21.base.Music21Object.addLocationAndActiveSite`, :meth:`~music21.base.Music21Object.freezeIds`, :meth:`~music21.base.Music21Object.getAllContextsByClass`, :meth:`~music21.base.Music21Object.getCommonSiteIds`, :meth:`~music21.base.Music21Object.getCommonSites`, :meth:`~music21.base.Music21Object.getContextByClass`, :meth:`~music21.base.Music21Object.getOffsetBySite`, :meth:`~music21.base.Music21Object.getSiteIds`, :meth:`~music21.base.Music21Object.getSites`, :meth:`~music21.base.Music21Object.getSpannerSites`, :meth:`~music21.base.Music21Object.hasContext`, :meth:`~music21.base.Music21Object.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.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.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


Copyright
---------



.. class:: Copyright(*args, **keywords)

    An object representation of copyright.




Creator
-------

Inherits from: :class:`~music21.metadata.Contributor`, :class:`~music21.base.JSONSerializer`

.. class:: Creator(*args, **keywords)

    A person that created a work. Can be a composer, lyricist, arranger, or other type of contributor. In MusicXML, these are "creator" elements.






    >>> from music21 import *
    >>> td = metadata.Creator(role='composer', name='Chopin, Fryderyk')
    >>> td.role
    'composer'
    >>> td.name
    'Chopin, Fryderyk'
    >>> td.relevance
    'creator'




Imprint
-------



.. class:: Imprint(*args, **keywords)

    An object representation of imprint, or publication.




MetadataBundle
--------------

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

.. class:: MetadataBundle(name='default')

    An object that provides access to, searches within, and storage and loading of multiple Metadata objects.

    Additionally, multiple MetadataBundles can be merged for additional processing



    **MetadataBundle** **properties**

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

    **MetadataBundle** **methods**

        .. method:: addFromPaths(pathList)

            Parse and store metadata from numerous files.

            If any files cannot be loaded, they file paths will be collected in a list.



            >>> from music21 import *
            >>> mb = metadata.MetadataBundle()
            >>> mb.addFromPaths(corpus.getWorkList('bwv66.6'))
            []
            >>> len(mb._storage)
            1



        .. method:: corpusPathToKey(fp, number=None)

            Given a file path or corpus path, return the meta-data path



            >>> from music21 import *
            >>> mb = metadata.MetadataBundle()
            >>> mb.corpusPathToKey('bach/bwv1007/prelude').endswith('bach_bwv1007_prelude')
            True
            >>> mb.corpusPathToKey('/beethoven/opus59no1/movement1.xml').endswith('beethoven_opus59no1_movement1_xml')
            True



        .. method:: jsonAttributes()

            Define all attributes of this object that should be JSON serialized for storage and re-instantiation. Attributes that name basic Python objects or :class:`~music21.base.JSONSerializer` subclasses, or dictionaries or lists that contain Python objects or :class:`~music21.base.JSONSerializer` subclasses, can be provided.



        .. method:: jsonComponentFactory(idStr)

            No documentation.


        .. method:: read(fp=None)

            Load self from the file path suggested by the _name of this MetadataBundle



        .. method:: search(query, field=None, extList=None)

            Perform search, on all stored metadata, permit regular expression matching.

            Return pairs of file paths and work numbers, or None



            >>> from music21 import *
            >>> mb = metadata.MetadataBundle()
            >>> mb.addFromPaths(corpus.getWorkList('ciconia'))
            []
            >>> mb.updateAccessPaths(corpus.getWorkList('ciconia'))
            >>> post = mb.search('cicon', 'composer')
            >>> len(post[0])
            2
            >>> post = mb.search('cicon', 'composer', extList=['.krn'])
            >>> len(post) # no files in this format
            0
            >>> post = mb.search('cicon', 'composer', extList=['.xml'])
            >>> len(post)
            1



        .. method:: updateAccessPaths(pathList)

            For each stored Metatadata object, create an entry for a complete, local file path that returns this.

            The `pathList` parameter is a list of all file paths on the users local system.



            >>> from music21 import *
            >>> mb = metadata.MetadataBundle()
            >>> mb.addFromPaths(corpus.getWorkList('bwv66.6'))
            []
            >>> len(mb._accessPaths)
            0
            >>> mb.updateAccessPaths(corpus.getWorkList('bwv66.6'))
            >>> len(mb._accessPaths)
            1



        .. method:: write()

            Write the JSON storage of all Metadata or RichMetadata contained in this object.



        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


RichMetadata
------------

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

.. class:: RichMetadata(*args, **keywords)

    RichMetadata adds to Metadata information about the contents of the Score
    it is attached to. TimeSignature, KeySignature and related analytical is stored.
    RichMetadata are generally only created in the process of creating stored JSON metadata.






    >>> from music21 import *
    >>> rmd = metadata.RichMetadata(title='Concerto in F')
    >>> rmd.title
    'Concerto in F'
    >>> rmd.keySignatureFirst = key.KeySignature(-1)
    >>> 'keySignatureFirst' in rmd._searchAttributes
    True



    **RichMetadata** **attributes**

        Attributes without Documentation: `timeSignatures`, `tempos`, `keySignatureFirst`, `keySignatures`, `noteCount`, `ambitus`, `tempoFirst`, `pitchHighest`, `timeSignatureFirst`, `quarterLength`, `pitchLowest`

        Attributes inherited from :class:`~music21.metadata.Metadata`: :attr:`~music21.metadata.Metadata.classSortOrder`

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

    **RichMetadata** **properties**

        Properties inherited from :class:`~music21.metadata.Metadata`: :attr:`~music21.metadata.Metadata.alternativeTitle`, :attr:`~music21.metadata.Metadata.composer`, :attr:`~music21.metadata.Metadata.composers`, :attr:`~music21.metadata.Metadata.date`, :attr:`~music21.metadata.Metadata.localeOfComposition`, :attr:`~music21.metadata.Metadata.movementName`, :attr:`~music21.metadata.Metadata.movementNumber`, :attr:`~music21.metadata.Metadata.mx`, :attr:`~music21.metadata.Metadata.number`, :attr:`~music21.metadata.Metadata.opusNumber`, :attr:`~music21.metadata.Metadata.title`

        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`

    **RichMetadata** **methods**

        .. method:: jsonAttributes()

            Define all attributes of this object that should be JSON serialized for storage and re-instantiation. Attributes that name basic Python objects or :class:`~music21.base.JSONSerializer` subclasses, or dictionaries or lists that contain Python objects or :class:`~music21.base.JSONSerializer` subclasses, can be provided.



        .. method:: jsonComponentFactory(idStr)

            No documentation.


        .. method:: merge(other, favorSelf=False)

            Given another Metadata or RichMetadata object, combine
            all attributes and return a new object.



            >>> from music21 import *
            >>> md = metadata.Metadata(title='Concerto in F')
            >>> md.title
            'Concerto in F'
            >>> rmd = metadata.RichMetadata()
            >>> rmd.merge(md)
            >>> rmd.title
            'Concerto in F'



        .. method:: update(streamObj)

            Given a Stream object, update attributes with stored objects.



        Methods inherited from :class:`~music21.metadata.Metadata`: :meth:`~music21.metadata.Metadata.addContributor`, :meth:`~music21.metadata.Metadata.getContributorsByRole`, :meth:`~music21.metadata.Metadata.search`, :meth:`~music21.metadata.Metadata.setWorkId`

        Methods inherited from :class:`~music21.base.Music21Object`: :meth:`~music21.base.Music21Object.searchActiveSiteByAttr`, :meth:`~music21.base.Music21Object.getContextAttr`, :meth:`~music21.base.Music21Object.setContextAttr`, :meth:`~music21.base.Music21Object.addContext`, :meth:`~music21.base.Music21Object.addLocation`, :meth:`~music21.base.Music21Object.addLocationAndActiveSite`, :meth:`~music21.base.Music21Object.freezeIds`, :meth:`~music21.base.Music21Object.getAllContextsByClass`, :meth:`~music21.base.Music21Object.getCommonSiteIds`, :meth:`~music21.base.Music21Object.getCommonSites`, :meth:`~music21.base.Music21Object.getContextByClass`, :meth:`~music21.base.Music21Object.getOffsetBySite`, :meth:`~music21.base.Music21Object.getSiteIds`, :meth:`~music21.base.Music21Object.getSites`, :meth:`~music21.base.Music21Object.getSpannerSites`, :meth:`~music21.base.Music21Object.hasContext`, :meth:`~music21.base.Music21Object.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.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.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


