These are the public methods for the MEI module.
To convert a string with MEI markup into music21 objects, use MeiToM21Converter.convertFromString().
In the future, most of the functions in this module should be moved to a separate, import-only module, so that functions for writing music21-to-MEI will fit nicely.
Simple “How-To”
Use MeiToM21Converter to convert a string to a set of music21 objects. In the future, the M21ToMeiConverter class will convert a set of music21 objects into a string with an MEI document.
>>> meiString = """<?xml version="1.0" encoding="UTF-8"?>
... <mei xmlns="http://www.music-encoding.org/ns/mei" meiversion="2013">
... <music>
... <score>
... <scoreDef meter.count="6" meter.unit="8">
... <staffGrp>
... <staffDef n="1" clef.shape="F" clef.line="4"/>
... </staffGrp>
... </scoreDef>
... <section>
... <scoreDef key.sig="1f" key.mode="major"/>
... <measure n="1">
... <staff n="1">
... <layer n="1">
... <beam>
... <note pname="E" oct="3" dur="8" artic="stacc"/>
... <note pname="E" oct="3" dur="8"/>
... <note pname="E" oct="3" dur="8"/>
... </beam>
... <chord dur="4" dots="1">
... <note pname="F" oct="2"/>
... <note pname="A" oct="2" accid="f"/>
... </chord>
... </layer>
... </staff>
... </measure>
... </section>
... </score>
... </music>
... </mei>
... """
>>> from music21 import *
>>> conv = mei.MeiToM21Converter(meiString)
>>> result = conv.run()
>>> type(result)
<class 'music21.stream.Score'>
Terminology
This module’s documentation adheres to the following terminology regarding XML documents, using this snippet, <note pname="C"/> as an example:
Because Python also uses “attributes,” an XML attribute is always preceded by an “at sign,” as in @pname, whereas a Python attribute is set as pname.
Ignored Elements
The following elements are not yet imported, though you might expect they would be:
Where Elements Are Processed
Most elements are processed in functions called tagFromElement(), where “tag” is replaced by the element’s tag name (e.g., staffDefFromElement() for <staffDef> elements). These functions convert from a Python xml.etree.ElementTree.Element object to the appropriate music21 object.
However, certain elements are processed primarily in another way, by “private” functions that are not documented in this API. Rather than converting an Element object into a music21 object, these functions modify the MEI document tree by adding instructions for the tagFromElement() functions. The elements processed by private functions include:
Whereas you can expect functions like clefFromElement() to convert a <clef> into a Clef with no loss of information. Because we cannot provide a simple one-to-one conversion for slurs, ties, and tuplets, we have kept their conversion functions “private,” to emphasize the fact that you must use the MeiToM21Converter to process them properly.
Guidelines for Encoders
While we aim for the best possible compatibility, the MEI specification is very large. The following guidelines will help you produce a file that this MEI-to-music21 module will import correctly and in the most efficient way. These should not necessarily be considered recommendations when using MEI in any other context.
List of Supported Elements
Alphabetical list of the elements currently supported by this module:
To know which MEI attributes are known to import correctly, read the documentation for the relevant element. For example, to know whether the @color attribute on a <note> element is supported, read the “Attributes/Elements Implemented” section of the noteFromElement() documentation.
<accid> Records a temporary alteration to the pitch of a note.
In MEI 2013: pg.248 (262 in PDF) (MEI.shared module)
Returns: | A string indicating the music21 representation of this accidental. |
---|
Examples
Unlike most of the ___FromElement() functions, this does not return any music21 object—just a string. Accidentals up to triple-sharp and triple-flat are supported.
>>> from xml.etree import ElementTree as ET
>>> from music21 import *
>>> meiSnippet = """<accid accid="s" xmlns="http://www.music-encoding.org/ns/mei"/>"""
>>> meiSnippet = ET.fromstring(meiSnippet)
>>> mei.base.accidFromElement(meiSnippet)
'#'
>>> meiSnippet = """<accid accid="tf" xmlns="http://www.music-encoding.org/ns/mei"/>"""
>>> meiSnippet = ET.fromstring(meiSnippet)
>>> mei.base.accidFromElement(meiSnippet)
'---'
Attributes/Elements Implemented:
Attributes/Elements in Testing: none
Attributes not Implemented:
att.common (@label, @n, @xml:base) (att.id (@xml:id))
att.facsimile (@facs)
att.typography (@fontfam, @fontname, @fontsize, @fontstyle, @fontweight)
att.accid.log (@func)
(att.controlevent
- (att.plist (@plist, @evaluate))
- (att.timestamp.musical (@tstamp))
- (att.timestamp.performed (@tstamp.ges, @tstamp.real))
- (att.staffident (@staff)) (att.layerident (@layer)))
att.accid.vis (all)
att.accid.gesatt.accid.anl (all)
Contained Elements not Implemented: none
<artic> An indication of how to play a note or chord.
In MEI 2013: pg.259 (273 in PDF) (MEI.shared module)
Returns: | A list of Articulation objects. |
---|
Examples
This function is normally called by, for example, noteFromElement(), to determine the Articulation objects that will be assigned to the articulations attribute.
>>> from xml.etree import ElementTree as ET
>>> from music21 import *
>>> meiSnippet = """<artic artic="acc" xmlns="http://www.music-encoding.org/ns/mei"/>"""
>>> meiSnippet = ET.fromstring(meiSnippet)
>>> mei.base.articFromElement(meiSnippet)
[<music21.articulations.Accent>]
A single <artic> element may indicate many Articulation objects.
>>> meiSnippet = """<artic artic="acc ten" xmlns="http://www.music-encoding.org/ns/mei"/>"""
>>> meiSnippet = ET.fromstring(meiSnippet)
>>> mei.base.articFromElement(meiSnippet)
[<music21.articulations.Accent>, <music21.articulations.Tenuto>]
Attributes Implemented:
Attributes/Elements in Testing: none
Attributes not Implemented:
att.common (@label, @n, @xml:base) (att.id (@xml:id))
att.facsimile (@facs)
att.typography (@fontfam, @fontname, @fontsize, @fontstyle, @fontweight)
att.artic.log
(att.controlevent
- (att.plist (@plist, @evaluate))
- (att.timestamp.musical (@tstamp))
- (att.timestamp.performed (@tstamp.ges, @tstamp.real))
- (att.staffident (@staff))
- (att.layerident (@layer)))
att.artic.vis (all)
att.artic.gesatt.artic.anl (all)
Contained Elements not Implemented: none
In MEI 2013: pg.264 (278 in PDF) (MEI.cmn module)
Parameters: | elem (Element) – The <beam> element to process. |
---|---|
Returns: | An iterable of all the objects contained within the <beam> container. |
Return type: | list of Music21Object |
Example
Here, three Note objects are beamed together. Take note that the function returns a list of three objects, none of which is a Beam or similar.
>>> from xml.etree import ElementTree as ET
>>> from music21 import *
>>> meiSnippet = """<beam xmlns="http://www.music-encoding.org/ns/mei">
... <note pname='A' oct='7' dur='8'/>
... <note pname='B' oct='7' dur='8'/>
... <note pname='C' oct='6' dur='8'/>
... </beam>"""
>>> meiSnippet = ET.fromstring(meiSnippet)
>>> result = mei.base.beamFromElement(meiSnippet)
>>> isinstance(result, list)
True
>>> len(result)
3
>>> result[0].pitch.nameWithOctave
'A7'
>>> result[0].beams
<music21.beam.Beams <music21.beam.Beam 1/start>>
>>> result[1].pitch.nameWithOctave
'B7'
>>> result[1].beams
<music21.beam.Beams <music21.beam.Beam 1/continue>>
>>> result[2].pitch.nameWithOctave
'C6'
>>> result[2].beams
<music21.beam.Beams <music21.beam.Beam 1/stop>>
Attributes/Elements Implemented:
Attributes/Elements Ignored:
Attributes/Elements in Testing: none
Attributes not Implemented:
att.common (@label, @n, @xml:base)
att.facsimile (@facs)
att.beam.log
(att.event
- (att.timestamp.musical (@tstamp))
- (att.timestamp.performed (@tstamp.ges, @tstamp.real))
- (att.staffident (@staff))
- (att.layerident (@layer)))
(att.beamedwith (@beam.with))
att.beam.vis (all)
att.beam.gesatt.beam.anl (all)
Contained Elements not Implemented:
<chord> is a simultaneous sounding of two or more notes in the same layer with the same duration.
In MEI 2013: pg.280 (294 in PDF) (MEI.shared module)
Attributes/Elements Implemented:
@xml:id (or id), an XML id (submitted as the Music21Object “id”)
<note> contained within
@dur, from att.duration.musical: (via _qlDurationFromAttr())
@dots, from att.augmentdots: [0..4]
@artic and <artic>
@tie, (many of “[i|m|t]”)
@slur, (many of “[i|m|t][1-6]”)
duration is 0 because we ignore the question of which neighbouring note to borrow time from)
Attributes/Elements in Testing: none
Attributes not Implemented:
att.common (@label, @n, @xml:base)
att.facsimile (@facs)
att.chord.log
(att.event
- (att.timestamp.musical (@tstamp))
- (att.timestamp.performed (@tstamp.ges, @tstamp.real))
- (att.staffident (@staff))
- (att.layerident (@layer)))
(att.fermatapresent (@fermata))
(att.syltext (@syl))
(att.chord.log.cmn
- (att.tupletpresent (@tuplet))
- (att.beamed (@beam))
- (att.lvpresent (@lv))
- (att.ornam (@ornam)))
att.chord.vis (all)
att.chord.ges
- (att.articulation.performed (@artic.ges))
- (att.duration.performed (@dur.ges))
- (att.instrumentident (@instr))
- (att.chord.ges.cmn (att.graced (@grace, @grace.time))) <– partially implemented
att.chord.anl (all)
Contained Elements not Implemented:
<clef> Indication of the exact location of a particular note on the staff and, therefore, the other notes as well.
In MEI 2013: pg.284 (298 in PDF) (MEI.shared module)
Attributes/Elements Implemented:
Attributes/Elements Ignored:
Attributes/Elements in Testing: none
Attributes not Implemented:
att.common (@label, @n, @xml:base)
att.event
- (att.timestamp.musical (@tstamp))
- (att.timestamp.performed (@tstamp.ges, @tstamp.real))
- (att.staffident (@staff))
- (att.layerident (@layer))
att.facsimile (@facs)
att.clef.anl (all)
att.clef.vis (all)
Contained Elements not Implemented: none
Returns 1 no matter what is passed in.
<dot> Dot of augmentation or division.
In MEI 2013: pg.304 (318 in PDF) (MEI.shared module)
Returns: | 1 |
---|---|
Return type: | int |
Attributes/Elements Implemented: none
Attributes/Elements in Testing: none
Attributes not Implemented:
Elements not Implemented: none
<instrDef> (instrument definition)—MIDI instrument declaration.
In MEI 2013: pg.344 (358 in PDF) (MEI.midi module)
Returns: | An Instrument |
---|
Attributes/Elements Implemented:
Attributes/Elements in Testing: none
Attributes/Elements Ignored:
Attributes not Implemented:
Contained Elements not Implemented: none
<layer> An independent stream of events on a staff.
In MEI 2013: pg.353 (367 in PDF) (MEI.shared module)
Note
The Voice object’s id attribute must be set properly in order to ensure continuity of voices between measures. If the elem does not have an @n attribute, you can set one with the overrideN parameter in this function. If you provide a value for overrideN, it will be used instead of the elemn object’s @n attribute.
Because improperly-set id attributes nearly guarantees errors in the imported Score, either overrideN or @n must be specified.
Parameters: |
|
---|---|
Returns: | A Voice with the objects found in the provided Element. |
Return type: | |
Raises : | MeiAttributeError if neither overrideN nor @n are specified. |
Attributes/Elements Implemented:
Attributes Ignored:
Attributes/Elements in Testing: none
Attributes not Implemented:
Contained Elements not Implemented:
<measure> Unit of musical time consisting of a fixed number of note-values of a given type, as determined by the prevailing meter, and delimited in musical notation by two bar lines.
In MEI 2013: pg.365 (379 in PDF) (MEI.cmn module)
Parameters: |
|
---|---|
Returns: | A dictionary where keys are the @n attributes for <staff> tags found in this <measure>, and values are Measure objects that should be appended to the Part instance with the value’s @n attributes. |
Return type: | dict of music21.stream.Measure |
Note
When the right barline is set to 'rptboth' in MEI, it requires adjusting the left barline of the following <measure>. If this happens, the Repeat object is assigned to the 'next @left' key in the returned dictionary.
Attributes/Elements Implemented:
Attributes Ignored:
Attributes/Elements in Testing: none
Attributes not Implemented:
Contained Elements not Implemented:
<note> is a single pitched event.
In MEI 2013: pg.382 (396 in PDF) (MEI.shared module)
Note
If set, the @accid.ges attribute is always imported as the music21 Accidental for this note. We assume it corresponds to the accidental implied by a key signature.
Attributes/Elements Implemented:
@accid and <accid>
@accid.ges for key signatures
@pname, from att.pitch: [a–g]
@oct, from att.octave: [0..9]
@dur, from att.duration.musical: (via _qlDurationFromAttr())
@dots: [0..4], and <dot> contained within
@xml:id (or id), an XML id (submitted as the Music21Object “id”)
@artic and <artic>
@tie, (many of “[i|m|t]”)
@slur, (many of “[i|m|t][1-6]”)
duration is 0 because we ignore the question of which neighbouring note to borrow time from)
Attributes/Elements in Testing: none
Attributes not Implemented:
att.common (@label, @n, @xml:base)
att.facsimile (@facs)
att.note.log
(att.event
- (att.timestamp.musical (@tstamp))
- (att.timestamp.performed (@tstamp.ges, @tstamp.real))
- (att.staffident (@staff))
- (att.layerident (@layer)))
(att.fermatapresent (@fermata))
(att.syltext (@syl))
(att.note.log.cmn
- (att.tupletpresent (@tuplet))
- (att.beamed (@beam))
- (att.lvpresent (@lv))
- (att.ornam (@ornam)))
(att.note.log.mensural (@lig))
att.note.vis (all)
att.note.ges
(@oct.ges, @pname.ges, @pnum)
att.articulation.performed (@artic.ges))
(att.duration.performed (@dur.ges))
(att.instrumentident (@instr))
(att.note.ges.cmn (@gliss)
- (att.graced (@grace, @grace.time))) <– partially implemented
(att.note.ges.mensural (att.duration.ratio (@num, @numbase)))
(att.note.ges.tablature (@tab.fret, @tab.string))
att.note.anl (all)
Contained Elements not Implemented:
<space> A placeholder used to fill an incomplete measure, layer, etc. most often so that the combined duration of the events equals the number of beats in the measure.
In MEI 2013: pg.440 (455 in PDF) (MEI.shared module)
<mSpace/> A measure containing only empty space in any meter.
In MEI 2013: pg.377 (391 in PDF) (MEI.cmn module)
This is a function wrapper for spaceFromElement().
Note
If the <mSpace> element does not have a @dur attribute, it will have the default duration of 1.0. This must be fixed later, so the Space object returned from this method is given the m21wasMRest attribute, set to True.
<rest/> is a non-sounding event found in the source being transcribed
In MEI 2013: pg.424 (438 in PDF) (MEI.shared module)
Attributes/Elements Implemented:
Attributes/Elements in Testing: none
Attributes not Implemented:
att.common (@label, @n, @xml:base)
att.facsimile (@facs)
att.rest.log
(att.event
- (att.timestamp.musical (@tstamp))
- (att.timestamp.performed (@tstamp.ges, @tstamp.real))
- (att.staffident (@staff))
- (att.layerident (@layer)))
(att.fermatapresent (@fermata))
- (att.tupletpresent (@tuplet))
- (att.rest.log.cmn (att.beamed (@beam)))
att.rest.vis (all)
att.rest.ges (all)
att.rest.anl (all)
Contained Elements not Implemented: none
<mRest/> Complete measure rest in any meter.
In MEI 2013: pg.375 (389 in PDF) (MEI.cmn module)
This is a function wrapper for restFromElement().
Note
If the <mRest> element does not have a @dur attribute, it will have the default duration of 1.0. This must be fixed later, so the Rest object returned from this method is given the m21wasMRest attribute, set to True.
<score> Full score view of the musical content.
In MEI 2013: pg.430 (444 in PDF) (MEI.shared module)
Parameters: |
|
---|---|
Returns: | A completed Score object. |
Attributes/Elements Implemented:
Attributes Ignored:
Attributes/Elements in Testing:
Attributes not Implemented:
att.common (@label, @n, @xml:base) (att.id (@xml:id))
att.declaring (@decls)
att.typed (@type, @subtype)
(att.alignment (@when)))
Contained Elements not Implemented:
<section> Segment of music data.
In MEI 2013: pg.432 (446 in PDF) (MEI.shared module)
Note
The parameters and return values are exactly the same for sectionFromElement() and sectionScoreCore(), so refer to the latter function’s documentation for more information.
Attributes/Elements Implemented:
Attributes Ignored:
Attributes/Elements in Testing:
Attributes not Implemented:
att.common (@n, @xml:base) (att.id (@xml:id))
att.declaring (@decls)
att.facsimile (@facs)
att.typed (@type, @subtype)
att.pointing (@xlink:actuate, @xlink:role, @xlink:show, @target, @targettype, @xlink:title)
att.section.vis (@restart)
(att.alignment (@when)))
Contained Elements not Implemented:
<scoreDef> Container for score meta-information.
In MEI 2013: pg.431 (445 in PDF) (MEI.shared module)
This function returns a dictionary with objects that may relate to the entire score, to all parts at a particular moment, or only to a specific part at a particular moment. The dictionary keys determine the object’s scope. If the key is...
While the multi-part objects will be held in a list, the single-part objects will be in a dict like that returned by staffDefFromElement().
Note that it is the caller’s responsibility to determine the right action if there are conflicting objects in the returned dictionary.
For example:
>>> meiDoc = """<?xml version="1.0" encoding="UTF-8"?>
... <scoreDef meter.count="3" meter.unit="4" xmlns="http://www.music-encoding.org/ns/mei">
... <staffGrp><staffDef n="1" label="Clarinet"/></staffGrp>
... </scoreDef>
... """
>>> from music21 import *
>>> from xml.etree import ElementTree as ET
>>> scoreDef = ET.fromstring(meiDoc)
>>> result = mei.base.scoreDefFromElement(scoreDef)
>>> len(result)
3
>>> result['1']
{'instrument': <music21.instrument.Instrument 1: Clarinet: Clarinet>}
>>> result['all-part objects']
[<music21.meter.TimeSignature 3/4>]
>>> result['whole-score objects']
[]
Parameters: | elem (Element) – The <scoreDef> element to process. |
---|---|
Returns: | Objects from the <scoreDef>, as described above. |
Return type: | dict |
Attributes/Elements Implemented:
Attributes/Elements in Testing: None
Attributes not Implemented:
att.common (@label, @n, @xml:base) (att.id (@xml:id))
att.scoreDef.log
(att.cleffing.log (@clef.shape, @clef.line, @clef.dis, @clef.dis.place))
(att.duration.default (@dur.default, @num.default, @numbase.default))
(att.keySigDefault.log (@key.sig.mixed))
(att.octavedefault (@octave.default))
(att.transposition (@trans.diat, @trans.semi))
(att.scoreDef.log.cmn (att.beaming.log (@beam.group, @beam.rests)))
(att.scoreDef.log.mensural
- (att.mensural.log (@mensur.dot, @mensur.sign, @mensur.slash, @proport.num, @proport.numbase)
- (att.mensural.shared (@modusmaior, @modusminor, @prolatio, @tempus))))
att.scoreDef.vis (all)
att.scoreDef.ges (all)
att.scoreDef.anl (none exist)
Contained Elements not Implemented:
<staff> A group of equidistant horizontal lines on which notes are placed in order to represent pitch or a grouping element for individual ‘strands’ of notes, rests, etc. that may or may not actually be rendered on staff lines; that is, both diastematic and non-diastematic signs.
In MEI 2013: pg.444 (458 in PDF) (MEI.shared module)
Parameters: | elem (Element) – The <staff> element to process. |
---|---|
Returns: | The Voice classes corresponding to the <layer> tags in elem. |
Return type: | list of music21.stream.Voice |
Attributes/Elements Implemented:
Attributes Ignored:
Attributes/Elements in Testing: none
Attributes not Implemented:
Contained Elements not Implemented:
<staffDef> Container for staff meta-information.
In MEI 2013: pg.445 (459 in PDF) (MEI.shared module)
Returns: | A dict with various types of metadata information, depending on what is specified in this <staffDef> element. Read below for more information. |
---|---|
Return type: | dict |
Possible Return Values
The contents of the returned dictionary depend on the contents of the <staffDef> element. The dictionary keys correspond to types of information. Possible keys include:
Examples
This <staffDef> only returns a single item.
>>> meiDoc = """<?xml version="1.0" encoding="UTF-8"?>
... <staffDef n="1" label="Clarinet" xmlns="http://www.music-encoding.org/ns/mei"/>
... """
>>> from music21 import *
>>> from xml.etree import ElementTree as ET
>>> staffDef = ET.fromstring(meiDoc)
>>> result = mei.base.staffDefFromElement(staffDef)
>>> len(result)
1
>>> result
{'instrument': <music21.instrument.Instrument 1: Clarinet: Clarinet>}
>>> result['instrument'].partId
'1'
>>> result['instrument'].partName
'Clarinet'
This <staffDef> returns many objects.
>>> meiDoc = """<?xml version="1.0" encoding="UTF-8"?>
... <staffDef n="2" label="Tuba" key.pname="B" key.accid="f" key.mode="major"
... xmlns="http://www.music-encoding.org/ns/mei">
... <clef shape="F" line="4"/>
... </staffDef>
... """
>>> from music21 import *
>>> from xml.etree import ElementTree as ET
>>> staffDef = ET.fromstring(meiDoc)
>>> result = mei.base.staffDefFromElement(staffDef)
>>> len(result)
3
>>> result['instrument']
<music21.instrument.Instrument 2: Tuba: Tuba>
>>> result['clef']
<music21.clef.BassClef>
>>> result['key']
<music21.key.Key of B- major>
Attributes/Elements Implemented:
Attributes/Elements Ignored:
Attributes/Elements in Testing: none
Attributes not Implemented:
att.common (@n, @xml:base) (att.id (@xml:id))
att.declaring (@decls)
att.staffDef.log
(att.duration.default (@dur.default, @num.default, @numbase.default))
(att.octavedefault (@octave.default))
(att.staffDef.log.cmn (att.beaming.log (@beam.group, @beam.rests)))
(att.staffDef.log.mensural
- (att.mensural.log (@mensur.dot, @mensur.sign, @mensur.slash, @proport.num, @proport.numbase)
- (att.mensural.shared (@modusmaior, @modusminor, @prolatio, @tempus))))
att.staffDef.vis (all)
att.staffDef.ges (all)
att.staffDef.anl (none exist)
Contained Elements not Implemented:
<staffGrp> A group of bracketed or braced staves.
In MEI 2013: pg.448 (462 in PDF) (MEI.shared module)
For now, this function is merely a container-processor-thing for <staffDef> elements contained in this <staffGrp> element given as the “elem” argument. That is, the function does not yet create the brackets/braces and labels expected of a staff group.
Parameters: | elem (Element) – The <staffGrp> element to process. |
---|---|
Returns: | Dictionary where keys are the @n attribute on a contained <staffDef>, and values are the result of calling staffDefFromElement() with that <staffDef>. |
Attributes/Elements Implemented:
Attributes/Elements in Testing: none
Attributes not Implemented:
att.common (@label, @n, @xml:base) (att.id (@xml:id))
att.declaring (@decls)
att.facsimile (@facs)
att.staffGrp.vis (@barthru)
- (att.labels.addl (@label.abbr))
- (att.staffgroupingsym (@symbol))
- (att.visibility (@visible))
att.staffGrp.ges (att.instrumentident (@instr))
Contained Elements not Implemented:
<tuplet> A group of notes with “irregular” (sometimes called “irrational”) rhythmic values, for example, three notes in the time normally occupied by two or nine in the time of five.
In MEI 2013: pg.473 (487 in PDF) (MEI.cmn module)
Parameters: | elem (Element) – The <tuplet> element to process. |
---|---|
Returns: | An iterable of all the objects contained within the <tuplet> container. |
Return type: | tuple of Music21Object |
Attributes/Elements Implemented:
Attributes/Elements in Testing: none
Attributes not Implemented:
att.common (@label, @n, @xml:base) (att.id (@xml:id))
att.facsimile (@facs)
att.tuplet.log
(att.event
- (att.timestamp.musical (@tstamp))
- (att.timestamp.performed (@tstamp.ges, @tstamp.real))
- (att.staffident (@staff))
- (att.layerident (@layer)))
(att.beamedwith (@beam.with))
(att.augmentdots (@dots))
(att.duration.additive (@dur))
(att.startendid (@endid) (att.startid (@startid)))
att.tuplet.vis (all)
att.tuplet.ges (att.duration.performed (@dur.ges))
att.tuplet.anl (all)
Contained Elements not Implemented:
If relevant, add a slur to an obj (object) that was created from an elem (element).
Parameters: |
|
---|---|
Returns: | Whether at least one slur was added. |
Return type: | bool |
A Note about Importing Slurs
Because of how the MEI format specifies slurs, the strategy required for proper import to music21 is not obvious. There are two ways to specify a slur:
Caution
If an elem has an @m21SlurStart or @m21SlurEnd attribute that refer to an object not found in the slurBundle, the slur is silently dropped.
Find the @n values for all <staffDef> elements in a <score> element. This assumes that every MEI <staff> corresponds to a music21 Part.
Parameters: | scoreElem – The <score> Element in which to find the part names. |
---|---|
Returns: | All the unique @n values associated with a part in the <score>. |
Return type: | tuple of str |
Example
>>> meiDoc = """<?xml version="1.0" encoding="UTF-8"?>
... <score xmlns="http://www.music-encoding.org/ns/mei">
... <scoreDef>
... <staffGrp>
... <staffDef n="1" clef.shape="G" clef.line="2"/>
... <staffDef n="2" clef.shape="F" clef.line="4"/>
... </staffGrp>
... </scoreDef>
... <section>
... <!-- ... some music ... -->
... <staffDef n="2" clef.shape="C" clef.line="4"/>
... <!-- ... some music ... -->
... </section>
... </score>"""
>>> import xml.etree.ElementTree as ETree
>>> from music21 import *
>>> meiDoc = ETree.fromstring(meiDoc)
>>> mei.base.allPartsPresent(meiDoc)
('1', '2')
Even though there are three <staffDef> elements in the document, there are only two unique @n attributes. The second appearance of <staffDef> with @n=”2” signals a change of clef on that same staff—not that there is a new staff.
Beam some things together. The function beams every object that has a beams attribute, leaving the other objects unmodified.
Parameters: | things (iterable of Music21Object) – An iterable of things to beam together. |
---|---|
Returns: | someThings with relevant objects beamed together. |
Return type: | same as someThings |
From a list of objects with mixed type, find the “id” of the music21.stream.Voice instance.
Parameters: | fromThese (list) – A list of objects of any type, at least one of which must be a Voice instance. |
---|---|
Returns: | The id of the Voice instance. |
Raises : | RuntimeError if zero or many Voice objects are found. |
Given a base duration and a number of dots, create a Duration instance with the appropriate quarterLength value.
Parameters: |
|
---|---|
Returns: | A Duration corresponding to the fully-augmented value. |
Return type: |
Examples
>>> from music21 import *
>>> from fractions import Fraction
>>> mei.base.makeDuration(base=2.0, dots=0).quarterLength # half note, no dots
2.0
>>> mei.base.makeDuration(base=2.0, dots=1).quarterLength # half note, one dot
3.0
>>> mei.base.makeDuration(base=2, dots=2).quarterLength # 'base' can be an int or float
3.5
>>> mei.base.makeDuration(2.0, 10).quarterLength # you want ridiculous dots? Sure...
3.998046875
>>> mei.base.makeDuration(0.33333333333333333333, 0).quarterLength # works with fractions too
Fraction(1, 3)
>>> mei.base.makeDuration(Fraction(1, 3), 1).quarterLength
0.5
Produce metadata objects for all the metadata stored in the MEI header.
Parameters: | fromThis (Element) – The MEI file’s root tag. |
---|---|
Returns: | Metadata objects that hold the metadata stored in the MEI header. |
Return type: | sequence of music21.metadata.Metadata and RichMetadata. |
Given a string with an @xml:id to search for, remove a leading octothorpe, if present.
>>> from music21.mei.base import removeOctothorpe
>>> removeOctothorpe('110a923d-a13a-4a2e-b85c-e1d438e4c5d6')
'110a923d-a13a-4a2e-b85c-e1d438e4c5d6'
>>> removeOctothorpe('#e46cbe82-95fc-4522-9f7a-700e41a40c8e')
'e46cbe82-95fc-4522-9f7a-700e41a40c8e'
Safely build a Pitch from a string.
When Pitch.__init__() is given an empty string, it raises a PitchException. This function instead returns a default Pitch instance.
Parameters: |
|
---|---|
Returns: | A Pitch with the appropriate properties. |
Return type: |
Scale the duration of some objects by a ratio indicated by a tuplet. The elem must have the @m21TupletNum and @m21TupletNumbase attributes set, and optionally the @m21TupletSearch or @m21TupletType attributes.
The @m21TupletNum and @m21TupletNumbase attributes should be equal to the @num and @numbase values of the <tuplet> or <tupletSpan> that indicates this tuplet.
The @m21TupletSearch attribute, whose value must either be 'start' or 'end', is required when a <tupletSpan> does not include a @plist attribute. It indicates that the importer must “search” for a tuplet near the end of the import process, which involves scaling the durations of all objects discvoered between those with the “start” and “end” search values.
The @m21TupletType attribute is set directly as the type attribute of the music21 object’s Tuplet object. If @m21TupletType is not set, the @tuplet attribute will be consulted. Note that this attribute is ignored if the @m21TupletSearch attribute is present, since the type will be set later by the tuplet-finding algorithm.
Note
Objects without a duration attribute will be skipped silently, unless they will be given the @m21TupletSearch attribute.
Parameters: |
|
---|---|
Returns: | objs with scaled durations. |
Return type: | (list of) Music21Object |
This function is the “core” of both sectionFromElement() and scoreFromElement(), since both elements are treated quite similarly (though not identically). It’s a separate and shared function to reduce code duplication and increase ease of testing. It’s a “public” function to help spread the burden of API documentation complexity: while the parameters and return values are described in this function, the compliance with the MEI Guidelines is described in both sectionFromElement() and scoreFromElement(), as expected.
Required Parameters
Parameters: |
|
---|
Optional Keyword Parameters
The following parameters are all optional, and must be specified as a keyword argument (i.e., you specify the parameter name before its value).
Parameters: |
|
---|---|
Returns: | Four-tuple with a dictionary of results, the new value of activeMeter, the new value of nextMeasureLeft, and the new value of backupMeasureNum. |
Return type: | (dict, TimeSignature, Barline, int) |
Return Value
In short, it’s parsed, activeMeter, nextMeasureLeft, backupMeasureNum.
a list of all the Measure objects in that part, as found in this <section> or <score>.
<section> or <score>.
of the first Measure found in the next <section>. This will almost always be None.
<measure> elements found in this <score> or <section>.
A MeiToM21Converter instance manages the conversion of an MEI document into music21 objects.
If theDocument does not have <mei> as the root element, the class raises an MeiElementError. If theDocument is not a valid XML file, the class raises an MeiValidityError.
Parameters: | theDocument (str) – A string containing an MEI document. |
---|---|
Raises : | MeiElementError when the root element is not <mei> |
Raises : | MeiValidityError when the MEI file is not valid XML. |
MeiToM21Converter methods
Run conversion of the internal MEI document to produce a music21 object.
Returns: | A Stream subclass, depending on the MEI document. |
---|---|
Return type: | music21.stream.Stream |