Previous topic

music21.medren

Next topic

music21.metadata.bundles

Table Of Contents

Table Of Contents

This Page

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 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 metadata property.

The following example creates a Stream object, adds a Note object, and configures and adds the title and composer properties of a Metadata object.

>>> s = stream.Stream()
>>> s.append(note.Note())
>>> s.insert(metadata.Metadata())
>>> s.metadata.title = 'title'
>>> s.metadata.composer = 'composer'
>>> s.show()
../_images/moduleMetadata-01.png

Metadata

class music21.metadata.Metadata(*args, **keywords)

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

Metadata is a Music21Object subclass, meaing that it can be positioned on a Stream by offset and have a Duration.

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

>>> from music21 import metadata
>>> md = metadata.Metadata(title='Concerto in F')
>>> md.title
'Concerto in F'
>>> md = metadata.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 bases

Metadata read-only properties

Metadata.composers

Get a list of all Contributor objects defined as composer of this work.

Read-only properties inherited from Music21Object:

Metadata read/write properties

Metadata.alternativeTitle

Get or set the alternative title.

>>> from music21 import metadata
>>> md = metadata.Metadata(popularTitle='Eroica')
>>> md.alternativeTitle = 'Heroic Symphony'
>>> md.alternativeTitle
'Heroic Symphony'
Metadata.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 Contributor object in the Metadata object.

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

Get or set the date of this work as one of the following date objects:

DateSingle, DateRelative, DateBetween, DateSelection,

>>> from music21 import metadata
>>> 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'
Metadata.localeOfComposition

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

Metadata.movementName

Get or set the movement title.

Note that a number of pieces from various MusicXML datasets have the piece title as the movement title. For instance, the Bach Chorales, since they are technically movements of larger cantatas.

Metadata.movementNumber

Get or set the movement number.

Metadata.number

Get or set the number of the work.

TODO: Explain what this means...

Metadata.opusNumber

Get or set the opus number.

Metadata.title

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

>>> from music21 import metadata
>>> 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'

Read/write properties inherited from Music21Object:

Metadata methods

static Metadata.abbreviationToWorkId(abbreviation)

Get work id abbreviations.

>>> from music21 import metadata
>>> metadata.Metadata.abbreviationToWorkId('otl')
'title'
>>> for id in metadata.Metadata.workIdAbbreviationDict.keys():
...    result = metadata.Metadata.abbreviationToWorkId(id)
...
Metadata.addContributor(c)

Assign a Contributor object to this Metadata.

>>> from music21 import metadata
>>> 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']
Metadata.getContributorsByRole(value)

Return a Contributor if defined for a provided role.

>>> from music21 import metadata
>>> 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'
Metadata.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 metadata
>>> md = metadata.Metadata()
>>> md.composer = 'Beethoven, Ludwig van'
>>> md.title = 'Third Symphony'
>>> md.search(
...     'beethoven',
...     field='composer',
...     )
(True, 'composer')

Note how the incomplete field name in the following example is still matched:

>>> md.search(
...     'beethoven',
...     field='compose',
...     )
(True, 'composer')
>>> md.search(
...     'frank',
...     field='composer',
...     )
(False, None)
>>> md.search('frank')
(False, None)
>>> md.search('third')
(True, 'title')
>>> md.search(
...     'third',
...     field='composer',
...     )
(False, None)
>>> md.search(
...     'third',
...     field='title',
...     )
(True, 'title')
>>> md.search('third|fourth')
(True, 'title')
>>> md.search('thove(.*)')
(True, 'composer')
Metadata.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 metadata
>>> 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
static Metadata.workIdToAbbreviation(value)

Get a work abbreviation from a string representation.

>>> from music21 import metadata
>>> metadata.Metadata.workIdToAbbreviation('localeOfComposition')
'opc'
>>> for n in metadata.Metadata.workIdAbbreviationDict.values():
...     result = metadata.Metadata.workIdToAbbreviation(n)
...

Methods inherited from Music21Object:

Metadata instance variables

Metadata.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

>>> m21o = base.Music21Object()
>>> m21o.classSortOrder
20
>>> 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
Metadata.groups

An instance of a Group object which describes arbitrary Groups that this object belongs to.

Metadata.hideObjectOnPrint

if set to True will not print upon output (only used in MusicXML output at this point and Lilypond for notes, chords, and rests).

Metadata.id

A unique identification string (not to be confused with the default .id() method.

Metadata.isSpanner

Boolean value for quickly identifying Spanner objects (False by default).

Metadata.isStream

Boolean value for quickly identifying Stream objects (False by default).

Metadata.isVariant

Boolean value for quickly identifying Variant objects (False by default).

Metadata.xPosition

if set, defines the display x-position from the start of the container (in musicxml “tenths” by default)

Instance variables inherited from Music21Object:

RichMetadata

class music21.metadata.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 metadata
>>> richMetadata = metadata.RichMetadata(title='Concerto in F')
>>> richMetadata.title
'Concerto in F'
>>> from music21 import key
>>> richMetadata.keySignatureFirst = key.KeySignature(-1)
>>> 'keySignatureFirst' in richMetadata._searchAttributes
True

RichMetadata bases

RichMetadata read-only properties

Read-only properties inherited from Metadata:

Read-only properties inherited from Music21Object:

RichMetadata read/write properties

Read/write properties inherited from Metadata:

Read/write properties inherited from Music21Object:

RichMetadata methods

RichMetadata.merge(other, favorSelf=False)

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

>>> from music21 import metadata
>>> md = metadata.Metadata(title='Concerto in F')
>>> md.title
'Concerto in F'
>>> richMetadata = metadata.RichMetadata()
>>> richMetadata.merge(md)
>>> richMetadata.title
'Concerto in F'
RichMetadata.update(streamObj)

Given a Stream object, update attributes with stored objects.

Methods inherited from Metadata:

Methods inherited from Music21Object:

RichMetadata instance variables

RichMetadata.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

>>> m21o = base.Music21Object()
>>> m21o.classSortOrder
20
>>> 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
RichMetadata.groups

An instance of a Group object which describes arbitrary Groups that this object belongs to.

RichMetadata.hideObjectOnPrint

if set to True will not print upon output (only used in MusicXML output at this point and Lilypond for notes, chords, and rests).

RichMetadata.id

A unique identification string (not to be confused with the default .id() method.

RichMetadata.isSpanner

Boolean value for quickly identifying Spanner objects (False by default).

RichMetadata.isStream

Boolean value for quickly identifying Stream objects (False by default).

RichMetadata.isVariant

Boolean value for quickly identifying Variant objects (False by default).

RichMetadata.xPosition

if set, defines the display x-position from the start of the container (in musicxml “tenths” by default)

Instance variables inherited from Metadata:

Instance variables inherited from Music21Object: