This Chapter of the MEI Guidelines is based on the older MEI v3 release. It may contradict the current state of the MEI specifications as documented in the Elements, Attribute Classes, Model Classes, Data Types and Macro Groups sections. The Community is currently working to update these Guidelines. Of course, help is greatly appreciated. In case you would like to contribute, please reach out to us.
This chapter describes the elements, models, and attributes that are part of the MEI.shared module. The shared module contains declarations that are common to two or more other modules.
Typically, the following elements are available for the representation of the outermost structure of an MEI document:
A typical MEI document contains an mei element, which in turn contains metadata, represented by an meiHead element, and the musical text itself, represented by a music element. The meiHead element, formally declared in the MEI.header module, is described in chapter The MEI Header.
Other variations on this basic form are also available for the representation of:
Inclusion of MEI encodings (partial or complete) inside Text Encoding Initiative (TEI) documents is covered in the TEI Guidelines at http://www.tei-c.org/release/doc/tei-p5-doc/en/html/FT.html#FTNM and by the TEI Music Special Interest Group at http://www.tei-c.org/SIG/Music/twm/index.html.
MEI texts may be regarded either as unitary; that is, forming an organic whole, or as composite; that is, consisting of several components which are in some important sense independent of each other. The distinction is not always entirely obvious. For example, a collection of songs might be regarded as a single item in some circumstances, or as a number of distinct items in others. In such borderline cases, the encoder must choose whether to treat the text as unitary or composite; each option may have advantages and disadvantages.
Whether unitary or composite, the musical text is marked with the music tag and may contain front matter, a body, and back matter. In unitary texts, the body is tagged using the body element; in composite texts, however, where the textual body consists of a series of subordinate musical texts or other groups, it is tagged with the group element. The overall structure of any musical text, unitary or composite, is thus defined by the following elements:
Critical editions and collections of works often contain extensive text, such as a title page, table of contents, an introductory essay, commentary, biographical sketch, index, etc. These textual items may appear in either the front or back elements. The front and back elements, available only when the MEI.text module is activated, are described more fully in chapter Text in MEI.
The overall structure of a single musical text is:
The top-level structure of a composite musical text made up of two unitary musical texts is:
The group element may be used to represent a collection of independent musical texts which is to be regarded as a single unit for processing or other purposes. It is provided to simplify the encoding of collections, anthologies, and cyclic works. It can also be used to record the potentially complex internal structure of corpora, covered more fully in chapter Musical Corpora.
Examples of composite texts which may be represented using the group element include anthologies and other collections. The presence of common front matter referring to the whole collection, possibly in addition to front matter relating to each individual musical text, is a good indication that a given musical text might usefully be encoded in this way.
For example, the overall structure of a collection of songs might be encoded as follows:
A group of musical texts may contain other unitary and grouped texts:
The group element may be used to encode any kind of collection in which the constituents are regarded by the encoder as works in their own right, such as ad hoc single- or multiple-composer collections or anthologies of works not originally conceived of as a single composition.
This section describes sub-division of the body of a musical text. Front and back matter are described in chapter Text in MEI.
The body of a unitary musical text may contain one or more discrete, linear segments. The names commonly used for these structural subdivisions vary with the genre, style, and time period of the music, or even at the whim of the author, editor, or publisher. For example, a major subdivision of a symphony is generally referred to as a ‘movement’. An opera, on the other hand, is usually organized into ‘acts’ and then further by ‘scenes’. All such divisions are treated as occurrences of the same neutrally-named element, with a @type attribute used to categorize them independently of their hierarchic level.
The following element is used to identify musical subdivisions. As a member of the class att.typed, the mdiv element has attributes which can be used to classify it according to a two-tier hierarchy.
To accommodate “divisions within divisions”, an mdiv element may contain additional mdiv sub-elements nested to any level required. For example, the encoding of a multi-movement work, such as a symphony, frequently have the following structure:
while dramatic works, such as Verdi’s opera, Il Trovatore, often exhibit a more deeply-nested structure:
Conventionally, in performance the musical structures represented by mdiv elements are separated by pauses; however, attacca, attacca subito, seque, or similar terms are sometimes used at the end of an mdiv to indicate that the next mdiv should begin immediately after the conclusion of the current one. These terms have no effect, however, on the logical segmentation of musical content using mdiv elements.
The mdiv element may contain one or both of two possible views: score and parts.
The score element represents notation in which all the parts of an ensemble are arranged on vertically aligned staves, while the parts element collects the individually notated parts for each performer or group of performers. The explicit encoding of these two ‘views’ is necessary because it is not always possible or desirable to automatically derive one view from the other. In addition, separating scores and parts can eliminate a great deal of markup complexity.
The score and parts elements may also be employed to accommodate different methods of organizing the markup – with no particular presentation implied. In this case, software may render a collection of parts as a score or a score as a collection of parts.
A part is effectively a small-scale score, allowing all the encoding features of a full score, such as multiple staves, performance directives, and so on. A group of part element is useful for encoding performing parts when there is no score, such as in early music part books; when the parts have non-aligning bar lines; when different layout features, such as page turns, are needed for the score and parts; or for accommodating software that requires part-by-part encoding.
Please note that part elements in MEI are not an indication of voice leading or staff grouping. Voice leading can be encoded using the @next attribute, available on all the members of the model.model.eventLike class. The staffGrp element handles grouping of staves in the score context.
In both score and part views, the scoreDef element is used to describe logical characteristics of the encoded music, such as key signature, the sounding key (as opposed to the notated key signature), meter, etc., and visual features, such as page size, staff groupings and display labels, etc. The staffGrp elements within scoreDef and the order of staffDef elements inside staffGrp should follow the score order of the source for the encoding.
section elements are often used as a scoping mechanism for clef signs, key and meter signatures, as well as metronome, tempo, and expression markings. Using section elements can help to minimize the need for backward scanning to establish context when the starting point for access is not at the beginning of the score. section elements may also be used for other user-defined, i.e., analytical or editorial, purposes and may therefore be arbitrarily nested to any desired level.
Within section elements, several methods of organization are possible, depending upon the notational style of the source material and the encoder’s needs. For example, when the MEI.cmn module is used, the default organization is measure-by-measure, with staff and layer sub-elements within each measure. Further discussion of CMN notation is continued in chapter Repertoire: Common Music Notation.
However, staff-by-staff organization is more appropriate for music without measures and is provided when either the MEI.mensural or MEI.neumes module is employed. Coverage of mensural notation is provided in chapter Repertoire: Mensural Notation, while Repertoire: Neume Notation describes neumatic notation.
It must be noted that, when both the MEI.cmn and MEI.mensural modules are available, it is possible to encode CMN notation without using measure elements; that is, staff-by-staff organization may be used and the ends of measures marked using barLine elements.
In certain circumstances, this approach may be preferable for reproduction of the visual layout of the music. However, the simultaneous use of the
Typically, MEI follows the order of sections as they appear in the document being encoded. When performance requires a different order, for instance in the case of D.C. and D.S. directives, the following element may be used to define the performance order.
In the following example, expansion is used to indicate how the notated sections should be ordered in a “through-composed” rendition, for example for machine performance or analysis. The plist attribute contains an ordered list of identifiers of descendant section, ending, lem, or rdg elements. The sequence of values in the plist attribute indicates that the section labelled ‘A’ comes first, then the section labelled ‘B’, followed by the ‘A’ section again. This mechanism must be specified independently of any textual directives, such as “Da capo” or “D.S. al Fine”, that may be present in the document.
This section lists the elements defined in the shared module that are available within the music element.
The following elements are provided for the capture of scores and parts:
The character of elements specifying one or more score or staff parameters, such as meter and key signature, clefs, etc., is that of a milestone; that is, they affect all subsequent material until a following redefinition. A scoreDef element, which may affect more than just one staff, is allowed only within score, part and section elements, whereas staffDef is allowed only within staffGrp, staff and layer. A staffDef nested inside a staff must bear the same value for its @n attribute as its parent staff and may thus not affect other staves.
The actual use of these elements depends on the repertoire and historical context of the source material. For details on their use in Common Western Notation, please refer to chapter Defining Score Parameters for CMN.
The elements below are used to capture the logical organization of musical notation:
The actual use of the staff and layer elements depends on the repertoire and historical context of the source material. For details on their use in Common Western Notation, please refer to chapter The Role of the Measure Element. For mensural notation, see chapter Music Data Organization, and for neumatic notation, chapter Repertoire: Neume Notation.
The basic features of music notation are represented by the following elements:
The characteristics of stems on notes and chords are indicated by means of attributes found in the att.stems class.
Because they can occur in the context of a stream of events on the staff, some elements which are used in other contexts are also treated as events. For example, in addition to being used to define the initial clef of a staff, the clef element can also be used to indicate a clef change.
Key signatures and clefs as well as intra-staff changes to these musical parameters are treated as events.
Measure separators, i.e., bar lines, and custos signs are also considered to be events.
The following elements are regarded as events primarily because they sometimes occur independently of any associated notes, rests, or chords, especially in mensural and neume repertoires.
The following elements provide control over the horizontal spacing of notational events, such as notes, chords, rests, etc.:
In this context, the term ‘space’ is used to mean whitespace that is required to meaningfully align multiple voices in a multi-voice texture. In DARMS these were referred to as ‘push codes’. The space element is most often used when a new voice appears on a staff mid-measure.
The space element may also be used to align material that crosses staves.
‘Space’ can be thought of as another kind of event. In fact, some refer to this concept as an ‘invisible rest’.
While ‘space’ is meaningful, ‘padding’ is non-essential whitespace that is used to shift the position of the events which follow.
The pad element is provided in order to capture software-dependent placement information when it is desirable to do so. Unless the MEI file will be used as an intermediate file format, this is usually not necessary.
Expression marks are instructions in the form of words, abbreviations, or symbols that convey aspects of performance that cannot be expressed purely through the musical notation.
All of the following elements can be considered text directives; however, MEI uses the dir element specifically for words, abbreviations, numbers, or symbols specifying or suggesting the manner of performance that are not encoded elsewhere using the more specific elements of tempo and dynam.
Examples of directives include text strings such as ‘affettuoso’, fingering numbers, or music symbols such as segno and coda symbols or fermatas over a bar line. Directives can be control elements. That is, they can linked via their attributes to other events. The starting point of the directive may be indicated by either a tstamp, tstamp.ges, tstamp.real or startid attribute, while the ending point may be recorded by either a tstamp2, dur, dur.ges or endid attribute. It is a semantic error not to specify a starting point attribute.
Tempo marks are indications through words, abbreviations, or specific metronome settings of the speed at which a piece of music is to be performed. Both instantaneous and continuous tempo markings may be encoded using this element.
Dynamics, or dynamic marks, are terms, abbreviations, and symbols that indicate the specific degrees of volume of a note, phrase, or section of music, e.g., “piano”, “forte”. Transitions from one volume level to another, e.g., “crescendo”, “diminuendo”, are also specified through dynamic marks.
Phrase marks are curved lines placed over or under notes to delineate short sections of a work that represent a unified melodic idea, analogous to a phrase in literature.
MEI maintains a distinction between phrase marks and slurs, the latter being curved lines over or under a sequence of notes indicating they are to be performed using a particular playing/singing technique, notes that should be taken in a single breath by wind instruments or played by string instruments using a single stroke of the bow. Often, a slur also indicates that the affected notes should be played in a legato manner.
Even so, it is common for both of these concepts to be referred to generically as “slurs”. Therefore, unless one is encoding music from a repertoire in which this distinction is important, the slur element should be preferred over phrase.
Ornaments are formulae of embellishment that can be realized by adding supplementary notes to one or more notes of the melody.
MEI provides a generic element for encoding an ornament symbol that is not a mordent, turn, or trill. For those common CMN ornaments, please refer to Common Music Notation Ornaments.
Ornaments can be represented as textual strings (e.g. with a Unicode symbol) or with a user defined symbol. Ornaments can be control elements. That is, they be can linked via their attributes to other events. It is a semantic error not to specify a starting point attribute with either @tstamp or @startid.
The following attributes, provided by the att.common attribute class, are available on nearly all elements in an MEI encoding. They provide the means to identify, label, and access elements in MEI-encoded files.
The value of the @xml:id attribute serves as an identifier for an element and its content. Its value must be unique in the context of the current document and must conform to the definition of an XML Name provided by the W3C Recommendation at http://www.w3.org/TR/xml/#NT-Name. Suggestions for constructing an ID value can be found at http://www.w3.org/TR/xml/#sec-suggested-names.
The @xml:id attribute may take values similar to the following:
This is an example of an incorrectly-formulated @xml:id value:
The @label and @n attributes both serve a labeling function; however, they differ in the values they allow. The @n attribute must be a single token, while @label may contain a string value that includes spaces. This makes @label useful for the capture of free-text labels, but a name or number specified with @n may be easier to process.
When a reference to an external entity is not a complete URI, the @xml:base attribute can record a value against which it can be resolved into a complete, or absolute, location.
The value of @xml:base can be inherited from an ancestor. In the following example, the values of the graphic elements’ @target attribute can be completed by the xml:base value specified for the facsimile element:
See http://www.w3.org/TR/xmlbase/ for more details on xml:base.
This chapter describes the elements, model classes, and attribute classes that are part of the MEI.usersymbols module.
The module described in this chapter makes available the following components:
No attribute classes are defined in this module.
The usersymbols module defines the following model classes:
The elements provided by the usersymbols module may be used in two ways:
For this purpose, it provides three elements as graphic primitives, line, curve and anchoredText. Anywhere these elements are allowed, the symbol element can be used as well. The symbol element facilitates the re-use of symbols that were defined by symbolDef elements.
The symbolDef element uses SVG markup or the aforementioned graphic primitives to describe a symbol. A symbol definition may also use symbols defined by other symbolDef elements by employing the symbol element.
The graphics primitives and symbols can be used directly in the music to describe text and lines on a purely graphical level, without implying a specific logical meaning. If possible, however, more meaningful elements should be used. This means for example, “a tempo” or “da capo” should in general not be put inside anchoredText. Instead, tempo and dir should be used. Likewise, slurs and ties should be encoded using their respective elements, not using curve, and for glissandi, gliss should be used instead of line.
An example usage for line is the visualization of voice leading, which is not covered by a specific MEI element.
Usersymbols can define the rendition of different elements in two ways. Some elements, for example dir and tempo, can have user symbol elements as content. In the following example, the content of dir is used to provide pictograms of percussion instruments.
A number of elements can point to an internally-defined symbol for rendering using the @altsym attribute.
Externally-defined symbols may be referenced using a @glyphname or @glyphnum attribute. Both attributes refer to Standard Music Font Layout (SMuFL) characters. Other character sets must be treated as internally-defined character sets.
MEI uses the classic axis directions where the x-axis points from left to right and the y-axis points from bottom up. (This is compatible with PostScript’s axis orientation, while SVG’s y-axis points in the opposite direction.)
There are two types of units used by MEI: Staff units (data.MEASUREMENT) and units of the output coordinate system. Units of the output coordinate system can be translated to physical real world distances by means of the @vu.height and @page.scale of a scoreDef element. Real world units are multiplied by the value of @page.scale to get the corresponding value in output coordinate units.
If an element is scaled using the @scale attribute, the actual size of the units changes accordingly.
An element may be positioned using either absolute or relative coordinates. If absolute start point coordinates are specified using @x/@y coordinates (or their relatives @x2/@y2 for endpoints) they take precedence over relative positions specified by @ho/@vo/@to (or @startho/@startvo/@startto). Analogously, @x2/@y2 override @endho@endvo/@endto.
If @to/@startto/@endto attributes are used, the start or end point is x-aligned with the indicated timestamp.
If relative start coordinates (@ho/@vo or @startho/@startvo) are used, the origin of the coordinate system to be used for the start point is the first one found by the following search schema:
The start point is offset from this origin by the value of the start coordinates (@ho/@vo or @startho/@startvo), using staff units.
Analogously, the endpoint is determined using end coordinates (@endho/@endvo). If @endid is specified, it takes precedence over @startid.
Examples of origins are:
When they are referenced by symbol or @altsym, the origin of the context, i.e. the referencing symbol, is used. If neither absolute nor relative coordinates are specified, determining visually suitable start and end points for @line and @curve attributes is left to the rendering application. A value of 0 is not always assumed for absent relative coordinates. A typical example where a rendering application may not choose the origins of absent relative start and end coordinates to be the start point as well is the line connecting two notes in the above Schumann example.
If neither a @bezier nor @bulge attribute is present, the renderer determines a suitable shape. However, if @curvedir is present, the curve must respect the curvature direction specified there.
The attributes @bezier and @bulge define the shape of a curve in two different ways. If both are present, a rendering application may choose either one. They override @curvedir.
@bezier defines the inner control points of a cubic Bézier curve, i.e., a Bézier curve with two inner control points. The coordinates are given by a space separated list, first x and y offsets for the first control point, then x and y offsets for the second one. The x and y offsets are given in staff units (or inside the context of symbolDef in abstract units). The offsets for the first inner control point are relative to the start point, the ones for the second inner control point are relative to the end point.
The @bulge attribute allows specification of the curve shape by a number of interpolation points. The interpolation points are given by their distance from the line connecting the start and end point. The distance values are stored as a space separated list.
The interpolation points are calculated as follows: If @bulge provides n distance values, the connection line is divided into n+1 subsegments of equal length. The interpolation points are found by drawing a perpendicular line of the respective length at each subsegment joint. Positive distance values are drawn to the left of the connection line (left when traveling from start to end), negative ones to the right.
The interpolation algorithm used by the rendering application is implementation dependent.
The @form attribute of lines may take the following values:
These attribute values are only qualitative. Actual dash length and dot and dash spacing are implementation dependent.
The @width attribute may take the following values:
These values are also qualitative, however, they are also relative. That is, ‘narrow’ is the default value, ‘medium’ is twice as wide as ‘narrow’, and ‘wide’ is twice as wide as ‘medium’.
In addition to these textual values, the width attribute may contain a numeric value and an optional unit value, “2mm” for example. If the unit value is not provided, staff interline units are presumed.
The @lstartsym and @lendsym attributes name the symbol that may start and/or end a line, while @lstartsymsize and @lendsymsize indicate the relative size of the symbol using a numeric value in the range from 1 to 9.
The usersymbols module does not currently support continuous composite lines or filled areas. As mentioned above, the rendition of lines is highly implementation dependent. Coordinate system transforms are restricted to scaling using @scale.
2.1. Structural Elements 2.1.1. Document Elements 2.1.2. Music Element 2.2. Shared Musical Elements 2.2.1. Score and Parts 2.2.2. Staves and Layers 2.2.3. Basic Music Events 2.2.4. Other events 2.2.5. Expression Marks 2.3. Common Attributes 2.4. User-defined Symbols 2.4.1. Overview of the User Symbols Module 2.4.2. Uses of the Usersymbols Module 2.4.3. Positioning and Coordinates 2.4.4. Line Rendition 2.4.5. Limitations 8.1.2. Text Rendition